KageDesu/simpleLorebookGuide.md

Simple Lorebook Plugin Guide

Author: Pheonix KageDesu
RPG Maker Versions: MZ, MV
URL: https://kdworkshop.net/simple-lorebook

Overview

Simple Lorebook is a data-driven lore / codex menu.

Lore entries are configured in plugin parameters (Lore Database).
Each entry can have multiple text variants, images, an optional SE audio, and unlock conditions.
In RPG Maker MZ you can control entries via Plugin Commands.
In RPG Maker MV/MZ you can control entries via global API script calls.

How To Use

Installation and Setup

Installation: Download the plugin and place it in your RPG Maker project's js/plugins folder.
Activation: Open the Plugin Manager in RPG Maker and activate the Simple Lorebook plugin.
Configuration: Customize the plugin parameters to suit your game's needs.

Notes:

Make sure your project also contains the plugin resource folders:
- data\PKD_SimpleLorebook
- img\PKD_SimpleLorebook
If you use the default UI, these folders contain the NUI layout/config and images.

Creating Lore Entries

Lore entries are configured in the plugin parameter Lore Database (loreDatabase).

Each element is a LoreEntry structure:

Title Text (titleText): entry title shown in the list.
Text Variants (textVariants): an array of texts (each is a Note field).
- The plugin uses an internal current text index to choose which variant to show.
- Tip: you can store multiple versions (e.g. short/long, before/after some plot point).
Image Set (imageSet): images for this entry.
- Cover Image (cover): file from img/pictures.
- Illustration Image (illustration): file from img/pictures.
- Note: the current implementation uses only cover and illustration.
Audio File Name (audioFileName): optional SE file from audio/se.
Unlock Conditions (unlockConditions): array of conditions that must be met.
Require All Conditions (requireAllConditions):
- true: all conditions must be met.
- false: any one condition is enough.
Style Name (relatedToStyleName): optional. Lore entry will be displayed in lorebook only with the specified style. If empty, the default style will be used.

Unlock conditions (structure LoreCondition):

Type (type): variable / switch / item
Variable: set variableId and expectedValue (condition is met when variable value is >= expectedValue).
Switch: set switchId (condition is met when switch is ON).
Item: set itemId (condition is met when the party has the item).

If unlockConditions is empty, the entry is considered unlockable immediately.

Opening the Lorebook

You have multiple ways to open the lorebook:

Main Menu option (MZ/MV)
- Enable Add Lorebook To Main Menu (isAddLorebookMenuOption).
- Set Lorebook Menu Option Title (lorebookMenuOptionTitle).
Plugin Command (MZ only): OpenLorebook
Script Call (MZ and MV): OpenLorebook()

Control Lorebook Entries

Plugin Commands (RPG Maker MZ only)

All commands use Lore Entry Index (entryIndex) as a 1-based index (1 = first entry in the database).

Open Lorebook
- Command: OpenLorebook
Change Lore Entry Text Index
- Command: ChangeLoreEntryTextIndex
- Args:
  - entryIndex (number, min 1)
  - newTextIndex (number, min 1)
Set New Audio For Lore Entry
- Command: SetNewAudioForLoreEntry
- Args:
  - entryIndex (number, min 1)
  - seFilename (file from audio/se)
Set New Cover Image For Lore Entry
- Command: SetNewCoverImageForLoreEntry
- Args:
  - entryIndex (number, min 1)
  - imageFilename (file from img/pictures)
Set New Illustration Image For Lore Entry
- Command: SetNewIllustrationImageForLoreEntry
- Args:
  - entryIndex (number, min 1)
  - imageFilename (file from img/pictures)
Set Entry Hidden State
- Command: SetEntryHiddenState
- Args:
  - entryIndex (number, min 1)
  - hidden (boolean): true = hide, false = show

API Script calls (MZ and MV)

The plugin exposes global functions on window, so you can call them from Script events.

Entry indexing:

entryIndex is 1-based (same as plugin commands).
newTextIndex is 1-based (same as plugin commands).

Available calls:

OpenLorebook()
OpenLorebookWithCustomStyle(styleName)
ChangeLoreEntryTextIndex(entryIndex, newTextIndex)
SetNewAudioForLoreEntry(entryIndex, seFilename)
SetNewCoverImageForLoreEntry(entryIndex, imageFilename)
SetNewIllustrationImageForLoreEntry(entryIndex, imageFilename)
SetEntryHiddenState(entryIndex, hidden)

These calls modify the entry state (text variant / images / audio / hidden flag) at runtime.

Examples:

// Change the text variant of the first lore entry to the second variant
ChangeLoreEntryTextIndex(1, 2);
// Set a new cover image for the third lore entry
SetNewCoverImageForLoreEntry(3, "new_cover_image");
// Hide the fifth lore entry
SetEntryHiddenState(5, true);

Plugin Parameters (Reference)

Custom Styles To Load (customStylesToLoad): array of CustomStyle folder names (for NUI-based lorebook customization).
Lore Database (loreDatabase): array of LoreEntry structures.
Open Lorebook SE (openLorebookSE): SE played when opening the lorebook (file from audio/se).
Lore Audio Play Delay (loreAudioPlayDelay): delay (seconds) before playing entry audio. Default 0.5.
Show Locked Entries (showLockedEntries): show locked entries in the list. Default true.
Sort By Unlock Order (isSortByUnlockOrder): keep entries sorted by the order they were unlocked. Default true.
Input Mode Type (inputModeType):
- 0 = Show Entries On Hover
- 1 = Activate Each Entry
Description Text Format Settings (descriptionTextFormatSettings): rich text styling settings.
- fontFace (string, empty = default)
- fontSize (number)
- textColor (HEX)
- outlineColor (HEX)
- lineHeight (-1 = default)
- padding (-1 = default)
- bottomArrowMargin (number, margin for the "more text" arrow when description is too long)
- topArrowMargin (number, margin for the "more text" arrow when description is too long)
Add Lorebook To Main Menu (isAddLorebookMenuOption): adds a menu command. Default true.
Lorebook Menu Option Title (lorebookMenuOptionTitle): title for the menu command. Default Lorebook.
Custom Style Menu Options (customStyleMenuOptions): array of menu options for opening the lorebook with a specific custom style. Each option has:
- styleName (string, name of the custom style folder)
- displayName (string, title for the menu command)

Custom Styles

Create a folder with any name inside data\PKD_SimpleLorebook\custom_styles (e.g. example).
Place the files NUI_LorebookGridItem.json and NUI_Scene_SimpleLorebook.json inside that folder — they will be applied when the lorebook is opened with the matching style. You can copy these files from data\PKD_SimpleLorebook and modify them as needed.
Add the folder name (e.g. example) to the Custom Styles To Load (customStylesToLoad) array in the plugin parameters. This step is required so the files are loaded into game memory.
Open the lorebook using OpenLorebookWithCustomStyle("example") to apply the custom style from the example folder. In RPG Maker MZ, you can also use the dedicated plugin command OpenLorebookWithCustomStyle, which accepts the style name as an argument.
In a lore entry's Style Name (relatedToStyleName) parameter, specify a style name to make that entry visible only when the lorebook is opened with that style. If left empty, the entry will appear only when the lorebook is opened with the default style.
Optional. Plugin parameter Custom Style Menu Options (customStyleMenuOptions) allows you to add menu options for opening the lorebook with a specific custom style. Each option has a styleName field, which should match the name of the custom style folder. When the player selects that menu option, the lorebook will open with the corresponding custom style.

Customization

Plugin based on NUI system, which allows for easy customization of the lorebook menu.
You can customize the appearance of the lorebook menu by modifying the .json files in the data\PKD_SimpleLorebook folder.
All the images used in the lorebook menu are stored in the img\PKD_SimpleLorebook folder. You can replace these images with your own to change the look of the lorebook.

Additional configurations for resolutions

The plugin comes with two ready-made configurations for different resolutions. For default one (816x624) and any bigger and special for 720p only.
Check folders data\PKD_SimpleLorebook\For720pOnly and data\PKD_SimpleLorebook\ForDeafult816x624andAny for the configurations.
To use a configuration, simply copy the contents of the desired configuration folder into your project's data\PKD_SimpleLorebook folder, replacing any existing files.