Skip to content

Instantly share code, notes, and snippets.

@KageDesu

KageDesu/treasureChestPluginGuide.md

Created December 26, 2024 16:59
Show Gist options
  • Save KageDesu/fb29ba6d328a04461ada175f7780bb1b to your computer and use it in GitHub Desktop.
Save KageDesu/fb29ba6d328a04461ada175f7780bb1b to your computer and use it in GitHub Desktop.
Download ZIP
Treasure Chest Plugin guide
Raw
treasureChestPluginGuide.md

Treasure Chest Plugin Guide

chests

Author: Pheonix KageDesu
Target: RPG Maker MZ / MV
Website: KD Workshop

Overview

  • Treasure Chest Plugin is a plugin that allows you to create a treasure chest event that can be opened by the player.
  • The plugin allows you to set the contents of the chest. You can configurate content: random items, weapons, armors, and gold. Set conditions and amount range.
  • The plugin allows you to set the background image of the chest. You can set different images for different chests.
  • Chest will store the content that you set. If player don't take all content, it will be stored in the chest. After closing the chest, player can return and take remaining content.
  • You can use script call for adding content to existing chest, remove chest, clear it or check if chest is empty.

How to Use

Plugin Command

Note: Plugin command allowed only for RPG Maker MZ

  • Create Treasure Chest: PKD_TreasureChest -> Treasure Chest

PluginCommandMZ

  • Remove Treasure Chest: PKD_TreasureChest -> Remove Chest

Script Call

Note: Script call allowed for RPG Maker MZ and MV

Script calls for opening chest:

Note: You can use this script call only inside event.
Note: All script call starts with this. prefix.

  • this.prepareChest(); - prepare chest (for this event) for opening and adding content. Required. You must call this script call before adding content to chest.

  • this.putGoldToChest(amount, chance, condition); - add gold to chest. Amount - number of gold. Chance - chance to add gold. Condition - condition for adding gold.

Condition can be boolean or string. If condition is string, it will be evaluated as script.

Examples:

this.putGoldToChest(100, 100, true); // add 100 gold to chest with 100% chance

this.putGoldToChest(100, 100, "$gameParty.gold() < 1000"); // add 100 gold to chest if player have less than 1000 gold

Examples, using variables:

this.putGoldToChest($gameVariables.value(1), 100, true); // add gold from variable 1 to chest with 100% chance

this.putGoldToChest($gameVariables.value(1), 100, "$gameParty.gold() < 1000"); // add gold from variable 1 to chest if player have less than 1000 gold

this.putGoldToChest($gameVariables.value(1), $gameVariables.value(2), true); // add gold from variable 1 to chest with chance from variable 2

  • this.putWeaponToChest(weaponId, amount, chance, condition); - add weapon to chest. WeaponId - id of weapon. Chance - chance to add weapon. Condition - condition for adding weapon. Amount - number of weapons.

  • this.putArmorToChest(armorId, amount, chance, condition); - add armor to chest. ArmorId - id of armor. Chance - chance to add armor. Condition - condition for adding armor. Amount - number of armors.

  • this.putItemToChest(itemId, amount, chance, condition); - add item to chest. ItemId - id of item. Chance - chance to add item. Condition - condition for adding item. Amount - number of items.

  • this.setBackgroundForChest(imageName); - set background image for chest. ImageName - name of image from img/PKD_TreasureChest folder.

  • this.removeChestAfterClose(); - remove chest after closing. Optional. If you want to remove chest (from memory) after opening, you must call this script call. This allows you to create one-time chests.

  • this.openChest(); - open chest and show content. Required. You must call this script call after adding content to chest. For opening chest.

  • this.clearChest(); - remove all content from chest (from memory). If player open chest again, all content will be added again.

  • this.isChestHaveItems(); - check if chest have items. Return boolean. You can use this script call in conditional branch. If chest not be opened (or prepared), it will return false.

Chest configuration example: ScriptCalls(any)

Script calls API:

Note: You can use this script call anywhere.

  • RemoveTreasureChest(mapId, eventId); - remove chest from map. MapId - id of map. EventId - id of event.

  • RemoveAllTreasureChests(); - remove all chests from all maps.

  • RemoveTreasureChestsForMapId(mapId); - remove all chests from map. MapId - id of map. Use this if player never return to map. For optimization.

  • RemoveTreasureChestsOnCurrentMap(); - remove all chests from current map. Use this if player never return to map. For optimization.

  • IsTreasureChestExists(mapId, eventId); - check if chest exists. MapId - id of map. EventId - id of event. Return boolean. Return true if chest exists, even if chest is empty.

  • GetTreasureChestItemsLeftCount(mapId, eventId); - get count of items left in chest. MapId - id of map. EventId - id of event. Return number. Return 0 if chest not exists or empty.

  • TakeAllFromTreasureChest(mapId, eventId); - take all items from chest. MapId - id of map. EventId - id of event. Give all items from chest to player. If chest not exists or empty, nothing will be given. Chest will be empty after this.

  • ClearItemsInTreasureChest(mapId, eventId); - clear all items from chest. MapId - id of map. EventId - id of event. Remove all items from chest. But chest will be still exists.

  • PutWeaponToTreasureChest(mapId, eventId, weaponId); - add weapon to chest. MapId - id of map. EventId - id of event. WeaponId - id of weapon. Amount is 1.

  • PutArmorToTreasureChest(mapId, eventId, armorId); - add armor to chest. MapId - id of map. EventId - id of event. ArmorId - id of armor. Amount is 1.

  • PutItemToTreasureChest(mapId, eventId, itemId, amount); - add item to chest. MapId - id of map. EventId - id of event. ItemId - id of item. Amount - number of items.

  • PutGoldToTreasureChest(mapId, eventId, amount); - add gold to chest. MapId - id of map. EventId - id of event. Amount - number of gold.

Additional Settings for Items/Armor/Weapons

  • Use custom image instead of default Icon for items, weapons, armors. You can set image for item in note field. Use <imageForChest:imageName> tag. ImageName - name of image from img/pictures folder.

  • Use custom pick up sound effect for items, weapons, armors. You can set sound for item in note field. Use <pickFromChestSE:seName> tag. SeName - name of sound effect from audio/se folder.

Plugin Customization

Plugin Parameters

  • Plugin have parameters for customization.

Visual Customization

  • Plugin visuals based on NUI

  • You can modify the appearance of the treasure chest by editing the .json files located in: data\PKD_TreasueChest\ (all files starting with NUI_).

  • Images are stored in the img\PKD_TreasueChest\ folder. You can replace these images with your.

Enjoy the plugin!

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