Keyring (Standalone Release) - jondevarthur/feraltrainer GitHub Wiki

A simple plugin that lets you define keys (or a similar item that only needs a binary owned / not owned check) in the game's internal data rather than defining them all in Items.txt just to clog up your Key Items.

Script Calls

  • keyringAdd("identifier","Display Name","image","description") - adds a key to your keyring.
    • Will also update existing keys if you pass an identifier the player already has.
      • As an example, keyringAdd("unknownkey","??? Key","key_unknown","What is this?") will add a mystery key.
      • When it's owner is revealed, you can use keyringAdd("unknownkey","Clefable's Key","key_Clefable","This Key was used by Clefable to open the Black Door.") to reflect the story update.
      • You can pass -1 for name and image, and omit the description, to leave fields the same - for example, keyringAdd("unknownkey","Clefable's Strange Key",-1) would leave the key the same except for the name.
    • keyringAdd("identifier") is also valid - this will pull the name and image from either a match in PREDEFINED_KEYS below or the default values.
  • keyringRemove("identifier") - removes that key from your keyring. This cannot be undone; it must be added again as if brand new.
  • keyringOwned?("identifier") - returns true or false depending on whether the key is owned by the player. If you add "true" after the identifier ( keyringOwned?("identifier",true) ), it will delete the key after doing the check - mainly used for simple key checks where the key is consumed after using, only if you'd like to simplify things.
  • keyringEverOwned?("identifier") - returns true or false if they key has ever been owned by the player, regardless of whether it is currently in their possession.
  • keyringOpen - opens the keyring screen.

Added Values

  • $PokemonGlobal.krKeyring - your keys are stored in here as a readable array, if you know what you're doing.
  • $PokemonGlobal.krKeytrail - stores an array of just the key identifiers you have ever given the player, should you want to check if e.g. a key has been obtained and then removed.

This is mostly for puzzle use case purposes, but also lets you both 'use up' keys and only manage doors with self-switches if necessary.

Settings

  • DEFAULT_BG - Located in Graphics/UI/pluginKeyring/backgrounds/. A custom background will be checked for in /backgrounds/ using the image name of the key, this will be used if that cannot be found.
  • WINDOWSKIN - Overrides the Windowskin when generating the list of keys. Set to "default" to use your player's current in-game windowskin. Located in the default windowskin folder, these will be the "choice" format images by default (i.e. menu skins, not message skins).
  • MESSAGESKIN - Overrides the Windowskin when generating the description of keys. Set to "default" to use your player's current in-game message skin. Located in the default windowskin folder, these will be the "speech" format images by default.
  • DEFAULT_KEYNAME - Fallback used in case of error. Should theoretically never actually end up being used in game.
  • DEFAULT_KEYGRAPHIC - Used if a given key graphic does not exist. All images of keys are kept in Graphics/UI/pluginKeyring/keyimages/. If you don't want to use key images, just set this to a blank, 1x1 transparent image.
  • DEFAULT_DESCRIPTION - Used if no description is available.
  • IMAGESTYLE - In the format [Style, X modifier, Y modifier]. Styles are:
    • 0 - "absolute" style. Places the key image at coordinate 0,0 (top-left), modified by the X and Y values given.
    • 1 - "relative" style. Centers the key image horizontally at halfway between the left-edge of the screen and the left-edge of the key list windowbox, and halfway down the screen vertically, both modified by the X and Y value given.
  • NOKEYS_TEXT - text to show if the player has no keys but attempts to open the keyring.
  • SORTING - your keyring will be sorted every time you add a new record by one of three methods:
    • 0 = no sorting, will just be the order they were added
    • 1 = sort by Display Name
    • 2 = sort by identifier
    • 3 = sort by display name, then image (for grouping kinds of keys by visual)
  • PREDEFINED_KEYS - an array of arrays to predefine keys. If you put a record here in the format ["identifier","Display Name","image","description"], you can quickly call it by just specifying keyringAdd("identifier") rather than all three fields. Multiple must be separated by i.e. [ [],[],[] ]. Note that all values must be "wrapped in quote marks".

Default Menu Handlers

Default examples are added for the three main methods of accessing this menu - Pause Menu, Pokegear Menu and Item (UseFromBag). If you don't wish to use either the Pause or Pokegear Menu options, change the appropriate part of the "condition" line to { next false },. The UseFromBag handler will activate by default when using an item called [KEYRING] in items.txt - a default PBS file called items_keyring.txt is provided to show the optimal settings for this item. It should be a FieldUse = Direct item and, ideally, an unsellable KeyItem.

Files

\Graphics\UI\pluginKeyring

  • \keyimages\ contains all images of keys.
  • \backgrounds\ contains all background images. For a specific background for a specific key, name your background the same as the image of the key.

\PBS\items_keyring.txt

  • Provided mostly as an example of how to set up a bag item to work with the UseFromBag handler.

\Plugins[JDA]Keyring

  • Contains the plugin files.

Tips and Tricks

  • You can forgo using images entirely by simply setting a blank image as the default key image and then placing no keys in the images folder.