Skip to content

Instantly share code, notes, and snippets.

@KageDesu

KageDesu/simpleLorebookGuide.md

Created December 24, 2025 14:14
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save KageDesu/ff89f970c931e477605cc9b63f48ddaf to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save KageDesu/ff89f970c931e477605cc9b63f48ddaf to your computer and use it in GitHub Desktop.
Download ZIP
Simple Lorebook Plugin Guide
Raw
simpleLorebookGuide.md

Simple Lorebook Plugin Guide

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

simpleLoreBook2

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

  1. Installation: Download the plugin and place it in your RPG Maker project's js/plugins folder.
  2. Activation: Open the Plugin Manager in RPG Maker and activate the Simple Lorebook plugin.
  3. 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).

loreEntryPP

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.

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)

pluginCommands

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()
  • 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)

  • 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)
  • Add Lorebook To Main Menu (isAddLorebookMenuOption): adds a menu command. Default true.
  • Lorebook Menu Option Title (lorebookMenuOptionTitle): title for the menu command. Default Lorebook.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment