- Joined
- Jan 27, 2017
- Messages
- 226
- Reaction score
- 262
- First Language
- Portuguese
- Primarily Uses
- RMMV
TAA_BookMenu - v1.6.7
Created by taaspider
Terms of Use
Any plugins developed by taaspider are free for use for both commercial and noncommercial RPG Maker games, unless specified otherwise. Just remember to credit "taaspider".
Redistribution of parts or the whole of taaspider plugins is forbidden (which also includes reposting), unless it comes from the official website (linked within the post). You are allowed to edit and change the plugin code for your own use, but you're definitely not allowed to sell or reuse any part of the code as your own. Although not required to use my plugins, a free copy of your game would be nice!
Introduction
When we create a game, we usually create a whole new world rich in lore and details, and want to make it all available to the players, so that they can understand every single detail we develop. However, just dumping it all in lengthy dialogues usually bore and scare most of the players, who will simply give up on your world.
A common alternative used by many AAA games is to minimize dialogue and exposition, and provide additional details through in-game books.
This plugin aims to provide just that for your game: a book menu where the player can read up additional lore when he feels up to it. You can place books throughout your game, providing a bit more of context for hungry players as they progress, and keeping exposition to a minimum.
Features
Screenshots
How to Use
WARNING: This plugin requires RPG Maker MV 1.5.0 or above! Please make sure your RPG Maker MV software is up to date before using this plugin.
First of, download the plugin here. There's a bunch of parameters that allows you to customize each of the scenes (the detached book window and the book menu). The plugin's help section describe most which are not self explanatory, try taking a look there if you feel lost.
One important thing though... you have to set up your books before you can call them inside your game. There's two ways of doing that: inside the Plugin Manager itself or using external JSON files. The plugin can only work with one of this methods at a time, so you need to chose which one you want at the "DataSource Type" parameter. I'll enclose the instructions for each case in spoiler tags below to make it more readable.
You can also test the plugin using my sample demo project. It was built with MV, but you can open it with MZ as well (just open the game.rmmzproject file and you're good to go).
Demo
This is the first plugin I'm sharing, but I don't intend it to be the last. So, I've built a little demo showing how this one works, and will update it in the future with new releases. You can download the demo project here.
Notes
Credit and Thanks
Created by taaspider
Terms of Use
Any plugins developed by taaspider are free for use for both commercial and noncommercial RPG Maker games, unless specified otherwise. Just remember to credit "taaspider".
Redistribution of parts or the whole of taaspider plugins is forbidden (which also includes reposting), unless it comes from the official website (linked within the post). You are allowed to edit and change the plugin code for your own use, but you're definitely not allowed to sell or reuse any part of the code as your own. Although not required to use my plugins, a free copy of your game would be nice!
Introduction
When we create a game, we usually create a whole new world rich in lore and details, and want to make it all available to the players, so that they can understand every single detail we develop. However, just dumping it all in lengthy dialogues usually bore and scare most of the players, who will simply give up on your world.
A common alternative used by many AAA games is to minimize dialogue and exposition, and provide additional details through in-game books.
This plugin aims to provide just that for your game: a book menu where the player can read up additional lore when he feels up to it. You can place books throughout your game, providing a bit more of context for hungry players as they progress, and keeping exposition to a minimum.
Features
- Creates a main menu command gathering books the player discovers throughout your world, letting them read whenever they want;
- Allows the dev to call a detached window and show the contents of a book outside the menu;
- Input your game books into the engine using either the Plugin Manager or an external JSON file;
- Compatibility with multilanguage plugins that uses multiple external files for text;
- Allows the dev to setup background images for both scenes separately, with options to use different images for each window or a single image for everything;
- Allows you to include inline images along with the book text. The image can be used with its original size, or proportionally resized through a special escape code.
- Use inline trailing images to give a nice finishing touch to your books!
- Scroll book text by cliking (PC) or touching (mobile) the arrows or swyping up and down;
- Have book contents change as the game progresses;
- Mark newly added or recently changed books in the book menu so your player knows when there's new information available;
Screenshots
How to Use
WARNING: This plugin requires RPG Maker MV 1.5.0 or above! Please make sure your RPG Maker MV software is up to date before using this plugin.
First of, download the plugin here. There's a bunch of parameters that allows you to customize each of the scenes (the detached book window and the book menu). The plugin's help section describe most which are not self explanatory, try taking a look there if you feel lost.
One important thing though... you have to set up your books before you can call them inside your game. There's two ways of doing that: inside the Plugin Manager itself or using external JSON files. The plugin can only work with one of this methods at a time, so you need to chose which one you want at the "DataSource Type" parameter. I'll enclose the instructions for each case in spoiler tags below to make it more readable.
You can also test the plugin using my sample demo project. It was built with MV, but you can open it with MZ as well (just open the game.rmmzproject file and you're good to go).
There's two main parameters to configure:
The Id is used only to order the books under each category. If you leave all Ids equal (0), the plugin will use the order it reads the books from the editor (usually the order you input them).
Title Color is an optional parameter that allows you to set a custom color ONLY on the title section of the scene. So that it will appear with the default color on the list section of the menu, and the custom color on the title window. If you want a custom color on both windows just use color escape codes.
If you want a book to have a custom background (overriding the global settings), just select an image for the "Custom Background" parameters. Leave it blank to go with the global background settings.
Version 1.6.0 Update: The "Variabl Text List" parameter has been included so you can define a list of text chunks that can be added to your book as the game progresses. This chunks can be added in any order, depending on how plugin comands are used. The "Visible Text List" parameter determines which text chunk indexes are loaded by default when the book is added to the player library.
- Category Order: List your book categories in the order you wish them to appear in the menu command. If you don't wish to display categories, input at least one entry here and choose to hide categories in the Menu List Window options;
- Books: Here you'll have to list all the books you want to make available to the player. Each book have the following attributes:
- Title
- Title Color
- Text
- Variable Text List
- Visible Text List
- Category
- Id
- Custom Background
- Custom Background Mode
The Id is used only to order the books under each category. If you leave all Ids equal (0), the plugin will use the order it reads the books from the editor (usually the order you input them).
Title Color is an optional parameter that allows you to set a custom color ONLY on the title section of the scene. So that it will appear with the default color on the list section of the menu, and the custom color on the title window. If you want a custom color on both windows just use color escape codes.
If you want a book to have a custom background (overriding the global settings), just select an image for the "Custom Background" parameters. Leave it blank to go with the global background settings.
Version 1.6.0 Update: The "Variabl Text List" parameter has been included so you can define a list of text chunks that can be added to your book as the game progresses. This chunks can be added in any order, depending on how plugin comands are used. The "Visible Text List" parameter determines which text chunk indexes are loaded by default when the book is added to the player library.
In this case, there's a bunch more parameters to configure. But first, let's establish the file format the plugin expects to find:
A few important notes:
This plugin has a default compatibility with localization plugins, like Iavra's Localization Core, for example). Plugins like this work with multiple external files, one for each language. If you want to use this feature, choose "Type" "Localization File" and point the plugin to one of the language files (any of them, it doesn't matter which), and configure "Localization Escape Code" accordingly, so that this plugin can build the placeholder tag for you.
If you're not using a localization plugin and just want to load books from a JSON file, choose "Dedicated File" and ignore the "Localization Escape Code" parameter.
{
"library": {
"categories": [
"Category 1",
"Category 2",
...
"Category N"
],
"books": {
"title1": {
"title": "Book Title",
"titleColor": 1,
"text": "Book's content.",
"textArray": [
"if you want your book text to change throughout the game",
"add all text chunks inside this array"
],
"visibleTexts": [
0
],
"category": 0,
"id": 0,
"customBg": "File Name",
"customBgMode": 11
},
"title2": {
...
},
...,
"titleN": {
...
}
}
}
}
A few important notes:
- The "category" tag must be a number, referencing the category index in the "categories" array;
- The "id" tag is used to control the ordering of books in the list window. It must be a number, but it can also be omitted and the plugin will define the order according to the order it reads the books from the file (usually the order they're placed);
- titleColor is an optional parameter that allows you to set a custom color ONLY on the title section of the scene. So that it will appear with the default color on the list section of the menu, and the custom color on the title window. If you want a custom color on both windows just use color escape codes.
- textArray has been included in version 1.6.0. It allows you to enter multiple text chunks that can be loaded separately inside the book using plugin commands. If you want your book contents to change as the game progresses, each set of text should be listed as an entry inside this array.
- visibleTexts has also been included in version 1.6.0. It determine which textArray indexes will be displayed by default when the book is first read. For backwards compatibility reasons, if the "text" tag is present it will automatically become index 0 of "textArray" when the game boots.
- Each book must have an unique key tag. This tag will be used by most of the plugin available commands (its the "title1", "title2", ..., "titleN" references above);
- customBg and customBgMode are optional, use them only when you want the book to have a custom background image. If you want it to go with the default background settings, just omit the parameters or set customBg to an empty string ("");
- customBgMode must be an integer. It is read bitwise by the plugin, so long story short, use one of the following values:
- 5: Detached Text Window Only
- 6: Menu Text Window Only
- 7: All Text Window Only
- 9: Detached Title + Text Window
- 10: Menu Title + Text Window
- 11: All Title + Text Window
- Category List: Specify the path to the array object containing the list of categories you'll use. You need at least one category, so if you do not wish to show categories in the book menu create at least one entry and use it for every book, them hide categories in the Menu List Window parameters. In our little example above, it would be "library.categories";
- Root Context Object: The path where we'll find our book objects. Again, in our example it would be "library.books";
- Title/Text/Category/Id Object: The name of the object inside each book holding its name, text, category and Id;
- Undefined Category: If per any chance the plugin fails to recognize the category text, place a default text to show in its place;
This plugin has a default compatibility with localization plugins, like Iavra's Localization Core, for example). Plugins like this work with multiple external files, one for each language. If you want to use this feature, choose "Type" "Localization File" and point the plugin to one of the language files (any of them, it doesn't matter which), and configure "Localization Escape Code" accordingly, so that this plugin can build the placeholder tag for you.
If you're not using a localization plugin and just want to load books from a JSON file, choose "Dedicated File" and ignore the "Localization Escape Code" parameter.
The plugin gives a lot of options for you to setup background images on both scenes. Configurations are kept separate for each one, so you can set different backgrounds for each scene if you wish.
All images must be in png format and located in the img/pictures folder. The parameters to config each type of background image is shared by all possible options.
A warning though, the plugin won't manipulate, stretch or shrink images. It will only place the images as they are. It's up to you to provide images on the right size.
Apart from choosing the images, you must also inform the plugin how you want it to present them. Options are a little different between scenes because the Menu Scene has an additional window (the list window), but the logic is the same. Here's a few things you should know:
All images must be in png format and located in the img/pictures folder. The parameters to config each type of background image is shared by all possible options.
A warning though, the plugin won't manipulate, stretch or shrink images. It will only place the images as they are. It's up to you to provide images on the right size.
Apart from choosing the images, you must also inform the plugin how you want it to present them. Options are a little different between scenes because the Menu Scene has an additional window (the list window), but the logic is the same. Here's a few things you should know:
- If you set it up as "None", the plugin will paint a black background, with no image;
- If you set "Default Map Print", it will keep the base class default, which is using a print screen from the map the player is located;
- If you set "Full Background Image", the image will be place as a background for the whole screen, regardless of the size of your windows;
- There's a bunch of options saying "Multiple Images", and then a combo highlighted between parenthesis, like "Title + Text", "Title / Text + List", for example. The dash sign (/) means the windows will share a single image, while the plus sign (+) means it will use a different image;
- The option "Single Image" will set the same image across all windows in the scene. If the scene takes the whole screen, it will work exactly as the "Full Background Image". If not, it will be placed as best as possible to cover all windows on the scene, and nothing more;
- There are also options to allow you to combine different configurations, so you can customize the background to your liking!
The escape code %img("filename") can be used to include an image along with the book text in its original size (or resized to fit into window, see next section). The plugin will always look for images in PNG format in the pictures folder.
You can also include optional parameters to force the plugin to resize the image to your liking: % img("filename", width, height) (again, no space between % and img). The code parameters width and height are percentile numbers. For instance, if you want the image to be displayed in half its original size use % img("filename", 50, 50).
Ex.: %img("Sword", 50, 50)
%img("Sword", 40, 20)
You can also include inline trailing images at the beginning of text lines in the book text. This can add a nice finishing touch to your books. To use this feature, include the proper escape code: %in_img("filename"). You can use the same options to resize the trailing image as with the common image tag (ex.: %in_img("filename", 10, 10).
One additional note: images are loaded into memory asynchronously. Which means the plugin won't wait for it to be ready to show the book's text. If, however, the image finishes loading and the screen is already showing your book's text it will be automatically updated. In other words, slower machines may see the book load without the image, just to see the screen automatically update a few seconds later including it.
EDIT: Beginning on version 1.4.1, a new parameter was included (Inline Image Preloading), which when turned on triggers the plugin to try and preload inline images whenever a book is highlighted on the book list, before text is loaded. The goal is try to prevent the behavior described above. However, image loading is still asynchronous. Even though the plugin will try to preload it, depending on your specs and image size you can still experience images loading after the text.
You can also include optional parameters to force the plugin to resize the image to your liking: % img("filename", width, height) (again, no space between % and img). The code parameters width and height are percentile numbers. For instance, if you want the image to be displayed in half its original size use % img("filename", 50, 50).
Ex.: %img("Sword", 50, 50)
%img("Sword", 40, 20)
You can also include inline trailing images at the beginning of text lines in the book text. This can add a nice finishing touch to your books. To use this feature, include the proper escape code: %in_img("filename"). You can use the same options to resize the trailing image as with the common image tag (ex.: %in_img("filename", 10, 10).
One additional note: images are loaded into memory asynchronously. Which means the plugin won't wait for it to be ready to show the book's text. If, however, the image finishes loading and the screen is already showing your book's text it will be automatically updated. In other words, slower machines may see the book load without the image, just to see the screen automatically update a few seconds later including it.
EDIT: Beginning on version 1.4.1, a new parameter was included (Inline Image Preloading), which when turned on triggers the plugin to try and preload inline images whenever a book is highlighted on the book list, before text is loaded. The goal is try to prevent the behavior described above. However, image loading is still asynchronous. Even though the plugin will try to preload it, depending on your specs and image size you can still experience images loading after the text.
OpenBookMenu
- Triggers the book menu to be displayed.
ReadBook key <true|false>
- Replace key with the book tag, if using a JSON file as datasource, or the book title if using Plugin Manager. If the key contains blank spaces between words, you need to remove them in the plugin command call. This will mark the book as read (if it isn't already) and display the detached book window with the book contents.
Optionally, you can add a second argument that tells if the book will be marked as read or not (true or false). If the argument is left blank, the book is marked as read.
Examples:
ReadBook bookJsonTag
ReadBook PluginManagerTitle (instead of "Plugin Manager Title")
ReadBook bookJsonTag false
LibraryData Menu Hide
LibraryData Menu Show
- Use this commands to hide / show the book menu from the main menu list.
LibraryData Menu Enable
LibraryData Menu Disable
- Use this commands to enable / disable the book menu at the main menu list.
LibraryData Learn Book key
LibraryData Forget Book key
- Use this commands to make the player learn / forget books without opening the detached book window. Replace 'key' with the book tag, if using a JSON File as datasource, or the book title if using the Plugin Manager. If the key contains blank spaces between words, you need to remove them in the plugin command call.
LibraryData Learn Books key1 key2 key3 ... keyN
LibraryData Forget Books key1 key2 key3 ... keyN
- Similar to the previous command, but this can be used to make the player learn / forget many books at once.
LibraryData Learn Category categoryName
LibraryData Forget Category categoryName
- Use this commands to make the player learn / forget all books from a specific category. Replace 'categoryName' with the category name (if it contains blank spaces, you need to remove them in the plugin command call)
LibraryData ShowCategories on
LibraryData ShowCategories off
- Use this to show / hide categories in the list window menu.
LibraryData UnreadBooks hide
LibraryData UnreadBooks show
- Use this to hide / show books not read by the player in the book list window.
LibraryData TitleBar hide
LibraryData TitleBar show
- Use this to hide / show the title bar on the detached book window.
LibraryData Reset All
- Reload the whole book list and books read. It might be useful when testing your game.
LibraryData Reset BookList
- Reload all book data from your datasource, but keeps the list of books read. This should be used carefully, as changing category/books names, order, or ids, can be game breaking. It may be useful for testing, but I recommend caution if it is to be used on your released game.
LibraryData Reset BooksRead
- Reload the list of books read, making the player forget all books read.
LibraryData Preload on
LibraryData Preload true
- Enables preloading of book inline images when loading from menu view.
LibraryData Preload off
LibraryData Preload false
- Disables preloading of book inline images when loading from menu view.
LibraryData Preload book bookKey
- Forces the plugin to preload the book reference by bookKey inline images. Useful to prepare for scenes where a detached scene may be triggered. Works best if triggered a few seconds before the scene.
LibraryData TextUpdate key Add index
LibraryData TextUpdate key Add index At position
- Changes visible text for the book key adding the text array of index 'index'. If "At position" is present, the text is added at the designated array position. Both index and position can reference a variable value by using the v[n] pattern, where n is the variable number.
LibraryData TextUpdate key Remove index
LibraryData TextUpdate key Remove At position
- Changes visible text for the book key removing the text array of index 'index'. You can also remove by the text position in the visible text array. Both index and position can reference a variable value by using the v[n] pattern, where n is the variable number.
LibraryData TextUpdate key Replace index
- Changes visible text for the book key removing all visible text entries and adding back only the specified index.
LibraryData TextUpdate key Clear
- Clear all visible text for the book key.
- Triggers the book menu to be displayed.
ReadBook key <true|false>
- Replace key with the book tag, if using a JSON file as datasource, or the book title if using Plugin Manager. If the key contains blank spaces between words, you need to remove them in the plugin command call. This will mark the book as read (if it isn't already) and display the detached book window with the book contents.
Optionally, you can add a second argument that tells if the book will be marked as read or not (true or false). If the argument is left blank, the book is marked as read.
Examples:
ReadBook bookJsonTag
ReadBook PluginManagerTitle (instead of "Plugin Manager Title")
ReadBook bookJsonTag false
LibraryData Menu Hide
LibraryData Menu Show
- Use this commands to hide / show the book menu from the main menu list.
LibraryData Menu Enable
LibraryData Menu Disable
- Use this commands to enable / disable the book menu at the main menu list.
LibraryData Learn Book key
LibraryData Forget Book key
- Use this commands to make the player learn / forget books without opening the detached book window. Replace 'key' with the book tag, if using a JSON File as datasource, or the book title if using the Plugin Manager. If the key contains blank spaces between words, you need to remove them in the plugin command call.
LibraryData Learn Books key1 key2 key3 ... keyN
LibraryData Forget Books key1 key2 key3 ... keyN
- Similar to the previous command, but this can be used to make the player learn / forget many books at once.
LibraryData Learn Category categoryName
LibraryData Forget Category categoryName
- Use this commands to make the player learn / forget all books from a specific category. Replace 'categoryName' with the category name (if it contains blank spaces, you need to remove them in the plugin command call)
LibraryData ShowCategories on
LibraryData ShowCategories off
- Use this to show / hide categories in the list window menu.
LibraryData UnreadBooks hide
LibraryData UnreadBooks show
- Use this to hide / show books not read by the player in the book list window.
LibraryData TitleBar hide
LibraryData TitleBar show
- Use this to hide / show the title bar on the detached book window.
LibraryData Reset All
- Reload the whole book list and books read. It might be useful when testing your game.
LibraryData Reset BookList
- Reload all book data from your datasource, but keeps the list of books read. This should be used carefully, as changing category/books names, order, or ids, can be game breaking. It may be useful for testing, but I recommend caution if it is to be used on your released game.
LibraryData Reset BooksRead
- Reload the list of books read, making the player forget all books read.
LibraryData Preload on
LibraryData Preload true
- Enables preloading of book inline images when loading from menu view.
LibraryData Preload off
LibraryData Preload false
- Disables preloading of book inline images when loading from menu view.
LibraryData Preload book bookKey
- Forces the plugin to preload the book reference by bookKey inline images. Useful to prepare for scenes where a detached scene may be triggered. Works best if triggered a few seconds before the scene.
LibraryData TextUpdate key Add index
LibraryData TextUpdate key Add index At position
- Changes visible text for the book key adding the text array of index 'index'. If "At position" is present, the text is added at the designated array position. Both index and position can reference a variable value by using the v[n] pattern, where n is the variable number.
LibraryData TextUpdate key Remove index
LibraryData TextUpdate key Remove At position
- Changes visible text for the book key removing the text array of index 'index'. You can also remove by the text position in the visible text array. Both index and position can reference a variable value by using the v[n] pattern, where n is the variable number.
LibraryData TextUpdate key Replace index
- Changes visible text for the book key removing all visible text entries and adding back only the specified index.
LibraryData TextUpdate key Clear
- Clear all visible text for the book key.
$gameSystem.isShowBookMenu()
- Test if the book menu should be shown at the main menu.
$gameSystem.isBookMenuEnabled()
- Test if the book menu should be enabled at the main menu.
$gameSystem.isBookCategoriesVisible()
- Test if the books categories are visible in the list window.
$gameSystem.isUnreadBooksHidden()
- Check if books not found by the player are shown at the list menu.
$gameSystem.getTotalBooks()
- Return the total number of books in the game.
$gameSystem.getTotalBooksRead()
- Return the number of books the player has found.
$gameSystem.getTotalBooksFromCategory(category)
- Replace "category" with the category name, regardless of the datasource type selected. This will return the total number of books under this category. Remove blank spaces in the category name, if any.
Example: $gameSystem.getTotalBooksFromCategory("History");
$gameSystem.getTotalBooksReadFromCategory(category)
- Replace "category" with the category name, regardless of the datasource type selected. This will return the total number of books from the specified category that has already been read by the player. Remove blank spaces in the category name, if any.
Example: $gameSystem.getTotalBooksReadFromCategory("History");
$gameSystem.isBookRead(bookKey)
- "bookKey" should be replaced by the book tag, if you're using a JSON file as your datasource, or the book title (minus blank spaces) if you're using Plugin Manager. This will return true if the player has already read the book, or false if he didn't.
Examples:
$gameSystem.isBookRead("bookJsonTag");
$gameSystem.isBookRead("PluginManagerTitle");
$gameSystem.isBookPassageKnown(bookKey, index)
- This command returns true if the specified index is included in the visible text list for the given book. index refers to the text chunk index inside the Text List Object. For backwards compatibility purposes, whenever the "Text" parameter is present it will be automatically assigned to index zero.
Examples:
$gameSystem.isBookPassageKnown("Version1.6.0", 1);
$gameSystem.resetLibrary()
- Reload the whole book list and books read. It might be useful when testing your game.
$gameSystem.resetLibraryBookList()
- Reload all book data from your datasource, but keeps the list of books read. This should be used carefully, as changing category/books names, order, or ids, can be game breaking. It maybe useful for testing, but I recommend caution if it is to be used on your released game.
$gameSystem.resetLibraryBooksRead()
- Reload the list of books read, making the player forget all books read.
$gameSystem.createExportDummy()
- Creates a dummy map with 1 tile and an event with commands to show every inline image called from within books. This is a useful tool to run just before exporting your game. This dummy map prevents inline images to be deleted when selecting the option to exclude unused files. The command will always create a new map with a high index (last map id + 1). To see the dummy map you'll need to close and reopen the editor.
- Test if the book menu should be shown at the main menu.
$gameSystem.isBookMenuEnabled()
- Test if the book menu should be enabled at the main menu.
$gameSystem.isBookCategoriesVisible()
- Test if the books categories are visible in the list window.
$gameSystem.isUnreadBooksHidden()
- Check if books not found by the player are shown at the list menu.
$gameSystem.getTotalBooks()
- Return the total number of books in the game.
$gameSystem.getTotalBooksRead()
- Return the number of books the player has found.
$gameSystem.getTotalBooksFromCategory(category)
- Replace "category" with the category name, regardless of the datasource type selected. This will return the total number of books under this category. Remove blank spaces in the category name, if any.
Example: $gameSystem.getTotalBooksFromCategory("History");
$gameSystem.getTotalBooksReadFromCategory(category)
- Replace "category" with the category name, regardless of the datasource type selected. This will return the total number of books from the specified category that has already been read by the player. Remove blank spaces in the category name, if any.
Example: $gameSystem.getTotalBooksReadFromCategory("History");
$gameSystem.isBookRead(bookKey)
- "bookKey" should be replaced by the book tag, if you're using a JSON file as your datasource, or the book title (minus blank spaces) if you're using Plugin Manager. This will return true if the player has already read the book, or false if he didn't.
Examples:
$gameSystem.isBookRead("bookJsonTag");
$gameSystem.isBookRead("PluginManagerTitle");
$gameSystem.isBookPassageKnown(bookKey, index)
- This command returns true if the specified index is included in the visible text list for the given book. index refers to the text chunk index inside the Text List Object. For backwards compatibility purposes, whenever the "Text" parameter is present it will be automatically assigned to index zero.
Examples:
$gameSystem.isBookPassageKnown("Version1.6.0", 1);
$gameSystem.resetLibrary()
- Reload the whole book list and books read. It might be useful when testing your game.
$gameSystem.resetLibraryBookList()
- Reload all book data from your datasource, but keeps the list of books read. This should be used carefully, as changing category/books names, order, or ids, can be game breaking. It maybe useful for testing, but I recommend caution if it is to be used on your released game.
$gameSystem.resetLibraryBooksRead()
- Reload the list of books read, making the player forget all books read.
$gameSystem.createExportDummy()
- Creates a dummy map with 1 tile and an event with commands to show every inline image called from within books. This is a useful tool to run just before exporting your game. This dummy map prevents inline images to be deleted when selecting the option to exclude unused files. The command will always create a new map with a high index (last map id + 1). To see the dummy map you'll need to close and reopen the editor.
Touch/Click support allows the player to scroll book text by clicking the up/down arrows (when visible) or by touching/clicking and swyping up and down the book text.This parameter has three possible values:
The text window must be activated for this feature to be available. Simply highlighting the book (which loads the text) in the book menu is not enough. The book must be selected with 'ok' to activate this feature.
- Disable: completely disables Touch/Click support;
- Up/Down Arrows Only: Enables support only for scrolling by clicking / touching on the up/down arrows;
- Full Support: Enables support for scrolling using the up/down arrows and by touch/click and dragging up and down.
The text window must be activated for this feature to be available. Simply highlighting the book (which loads the text) in the book menu is not enough. The book must be selected with 'ok' to activate this feature.
Demo
This is the first plugin I'm sharing, but I don't intend it to be the last. So, I've built a little demo showing how this one works, and will update it in the future with new releases. You can download the demo project here.
Notes
- This plugin does not implement wordwrap, as it is widely available with a bunch of free plugins out there. I won't be reinventing the wheel, so I highly recommend using one of those. I, for instance, use Yanfly's Message Core;
- This plugin creates almost everything it uses, so it is unlikely that any compatibility issues arises. Anyway, I've tested it out with most of Yanfly's plugins and found no issues;
- I don't know how many around here go through the trouble of using multi language plugins like me, but I've built this plugin to make those people lives easier. You can set it up so that it reads the books data directly from one of your JSON language files, and just reference the key tag of each book in the plugin commands. The plugin will take care of using placeholders to make sure the right language is used. I've tested it out with Iavra's Localization Core, but it should work with any plugin of this kind if there are JSON files involved;
Credit and Thanks
- A huge thanks to CodeBreakerZ and his tutorial videos, which really helped me begin to understand the engine default scripts and how I could slowly start bringing my ideas to life. Although I know my way through coding, I'm not an expert in Javascript and had no idea where to start messing with the engine before his videos;
- Also, I probably would have taken ages longer to find my way through the default code without studing a few of Yanfly's plugins. So... really... thank you for your hard work, and keep flooding ourselves with amazing free plugins. A lot of things I dreamed of building back at the XP ages are now available thanks to you.
- A special thanks to Pie4aPie for suggesting the trailing images feature. That was a nice addition to the plugin!
- Another thanks for Solar_Flare for the feedback and pointing out a few enhancements for version 1.4.1 and 1.4.2.
- A special thanks to DarkSearinox92, who provided me with a ton of feedbacks and helped me test version 1.5.0 fixes and peformance enhancements!
- If you're using another plugin to provide wordwrap, it may be disrupted when using inline images. It happens because in order to allow inline images I have to break down book input, and I treat each text and image section separately. So, the wordwrap tag included at the beginning of the text is lost when there's one or more inline images. The workaround for that is to simply manually include a wordwrap tag after an inline image tag if you're going to continue the book's text.
For example, using Yanfly's wordwrap tag: '<WordWrap>Initial text.%img("Sword")<WordWrap>Text after image.' - If using the Plugin Manager as source and a book text is left with an empty the game can break if you try to access the book. As I see no use on loading a book without any text, I'm not planning on failsafe that for now.
- Version 1.6.7:
- Fixed a bug that would cause categories added after a save file not to be recognized by the plugin when the game was loaded, and a book in that category was marked as read.
- Added compatibility with the engine encrypt images feature for both MV and MZ.
- Version 1.6.6:
- Fixed a bug that would cause a game crash if new categories are added and the player tries to learn a book from them after loading a game saved before those categories were created;
- Fixed a bug that would cause a book created after a save file to not be displayed correctly when the save was loaded.
- Version 1.6.5:
- Fixed a bug that could prevent inline images from being correctly loaded when used;
- Version 1.6.4:
- Fixed a bug that would cause the game to crash at boot trying to load the visible texts array from a JSON library;
- Added compatibility to Luna's Engine, through an additional compatibility module (TAA_BookMenu_CompatLunaEngine);
- Version 1.6.3:
- Fixed a bug that would cause the text window to not be properly positioned in the detached scene if it is not placed directly below the title window;
- Version 1.6.2:
- Fixed a compatibility bug with CGMV_Toast;
- Version 1.6.1:
- Fixed a bug that could cause a custom window skin to not be loaded correctly the first time a scene is activated;
- Changed the code to prevent crashes when background image parameters are not set correctly;
- Version 1.6.0:
- Changed method that checks if image file exists before trying to load so it can work properly on web and mobile deployments;
- Fixed vertical alignment of item names in the book menu list;
- Added a new parameter to enable / disable checking if files exists before loading;
- Added a new feature to allow book text to change with plugin commands. New plugin parameters were added to allow including a list of texts and a list of visible texts. All changes were implemented to have backwards compatibility;
- Added a "new" indicator for books learned / changed and not yet read in the book menu. This marking can be done with a static text, an icon or a picture. All settings for this feature are located under the Menu List Window parameter;
- Version 1.5.2:
- Fixed a bug that caused a Full Background image to have right and bottom borders cut off with MZ;
- Fixed a bug that caused any combinations of Full Background / Default Map Print with menu background images to fail (only the full background would appear);
- Fixed a bug that could cause crashes with deployed projects (failure to load image files);
- Added a new background setting for both scenes: Map Print + Full Background. This allows the use of transparencies with the full background image without having borders around it;
- Version 1.5.1:
- Fixed an issue with window layers on MZ, which could cause incompatibility with other plugins;
- Fixed a bug with the plugin command to learn all books from a category when books didn't have sequential ids (like having books with ids 1, 4, 10 instead of 1, 2 and 3). It would mess with category book count in the menu scene;
- Version 1.5.0:
- Added MZ compatibility;
- Reworked a few functions, enhancing performance a bit;
- Discontinued the parameter "Text Windows WordWrap Fix", as it is no longer needed (found a better solution);
- Added support to home/end keys into the book text window, allowing quick navigation to the start or end of your book text;
- Added some steps to validate runtime images (inline images and custom backgrounds) exists before trying to load them. This way the game won't crash if it tries to load an image that is not available in the filesystem;
- Added a plugin command to force inline image preloading of a specific book;
- Revised and enhanced detached scene book performance when inline images are present;
- Fixed an issue with hide categories plugin command;
- Added a parameter to allow a custom folder for inline images, making it easier to copy them to an exported project (since default export with exclude unused files don't consider such files);
- Added a few scrolling parameters;
- Version 1.4.2:
- Added the parameter 'Load Before Title', allowing to hold game load until all books are loaded to memory, or running it asynchronously (as it was with previous versions)
- Fixed an issue with book counting when Hide Unread Books is disabled
- Version 1.4.1:
- Added a parameter to the ReadBook command, to allow a book to be read in the detached window without marking it as read. Simply call the plugin command as follows: ReadBook <BookName> false
- Added a fix to prevent errors when loading save files created before the plugin was enabled in the plugin manager;
- Changed how save files are handled, so that only books read are stored (not the whole library). This will make save files lighter. As a result, the "Reset Book List On Load" parameter was removed (book list will always be reset on load, as only books read are saved);
- Added a "@require 1" to each image background parameter, so that the editor will know to keep them when exporting with the exclude unused options enabled. Thanks to Solar_Flare for pointing it out;
- Added the script call $gameSystem.createExportDummy() to create a dummy event calling a show picture for each inline image. This is a tool to be used just before exporting your game, so that "exclude unused files" won't delete inline images;
- Changed the function used to load the library from DataManager.createGameObjects to DataManager.loadDatabase;
- Version 1.4.0:
- Fixed arrows not showing in the text window when scrolling;
- Fixed clipping text on text window when using wordwrapping plugins (enable 'Text Windows WordWrap Fix' to activate it);
- Fixed Auto Place, Enable and Show menu parameters;
- Added native plugin support to touch/click and drag scrolling, and scrolling by clicking/touching the up/down arrows. Touch/click support can also be disabled (total or partially) using the 'Native Touch/Click Support' parameter;
- Version 1.3.7:
- Added a handler to allow closing the detached window when pressing 'ok' as well as 'cancel';
- Fixed the black text window issue on large books with lots of line breaks;
- Version 1.3.6:
- Added the 'Load Closed Categories' parameter to allow categories to be automatically closed when loading the plugin menu. If set to NO, the plugin will retain previous behavior of always showing every category open
- Version 1.3.5:
- Included parameters that an be used to reset or keep book list on game load. If set to reset, New books created into the selected datasource will be loaded into the game, otherwise it will keep the list of books previously loaded by that save. Similarly, there's another new parameter that allows you to reset or remember books read on game load. Which means you can set the plugin to make it so all books listed on the book menu are forgotten, or remembered on game load;
- Added script calls and plugin commands to reset the whole library, only the book list, and only books read (forget all books found);
- Version 1.3.4:
- Added new feature to allow trailing inline images into book texts
- Fixed bug with text padding not being applied to book text
- Fixed an issue when using RS_MessageAlign that caused the first line to
not be aligned correctly
- Version 1.3.3:
- Fixed bug that caused odd window behavior when two or more books in a row had custom backgrounds.
- Fixed bugs that interfered with windowskin and window opacity parameters
Option added to set a custom color for book titles only in the title section. When in book menu, it will appear with default color in the list section while using the custom color in the title section. Use escape codes if you the same color on both sections. - Included a small fix so that the first item on the list is automatically selected when the Book Menu is loaded.
- Fixed an issue when using inline images along with wordwrap
- Version 1.3.2:
- Fixed compatibility with MOG_MenuCursor (and probably with most plugins that creates a new layer over the scene as long as it stays over the WindowLayer).
- Version 1.3.1:
- Added a custom log function to help me debug future issues;
- Fixed compatibility issues with Olivia_StateTooltipDisplay Plugin.
- Version 1.3.0:
- Fixed a bug caused by the custom background change of the previous version that could cause the game to crash when opening a book with no custom background;
- Reworked the Window_BookText prototype to allow inline images to be included along with a book text.
- Version 1.2.0:
- Included a new feature allowing books to have custom background images that override the default ones. It comes with options to use the custom images on the detached scene only, menu scene only, or both. The image can also be set to cover only the text window or title + text windows.
- Version 1.1.0:
- Reorganized all aliases inside an object, to make them easier to track down;
- Included the possibility to customize scene backgrounds with images. The Detached Scene and Menu Scene have different configurations, so that they can have different backgrounds if the dev wishes.
- Version 1.0.1: Fixed mouse wheel scrolling, that wasn't working as expected;
- Version 1.0: First release!
Last edited: