Loot Box System Plugin Guide

loot_box_system_plugin_guide.md

PKD Loot Box Plugin Guide

Author: Pheonix KageDesu
RPG Maker Versions: MZ, MV
URL: https://kdworkshop.net/loot-box-system

---

Overview

PKD Loot Box adds a configurable loot box / chest opening scene with a spinning reward carousel.

• Loot boxes are configured in plugin parameters.
• Each loot box can contain items, weapons, armors, gold, and common event rewards.
• Each reward has a roll weight, so you can control reward chances.
• The spin scene, sounds, reward icons, and UI layout can be customized.
• The plugin uses NUI JSON files for interface layout and animation settings.

---

Installation

1. Place the plugin in your project's js/plugins folder.
2. Enable PKD_LootBox in the RPG Maker Plugin Manager.
3. Make sure the project contains the resource folders:
   • data/PKD_LootBox
   • img/PKD_LootBox
4. If you use custom reward icons from pictures, place them in:
   • img/pictures
5. If you use custom sound effects, place them in:
   • audio/se

---

Creating A Loot Box

Loot boxes are configured in the plugin parameter Loot Boxes (lootBoxesList).

Each entry in this list is a LootBoxConfig structure.

LootBoxConfig

• ID (id): unique loot box ID. You will use this ID when opening the loot box in game.
• Background Image (backgroundImageName): optional background image from img/PKD_LootBox.
  • If empty, the plugin uses Default Background Image (spinBackgroundImageName).
• Rewards (rewards): list of rewards that can be rolled from this loot box.

Example loot box ID:

test

You can open it with:

OpenLootBoxSpin("test");

---

Setting Up Rewards

Each reward is a LootRewardConfig structure.

Reward Fields

• ID (id): optional unique reward ID. If empty, the plugin generates one automatically.
• Kind (kind): reward type.
  • item
  • weapon
  • armor
  • gold
  • event
• Data ID (dataId): database ID for item, weapon, or armor rewards.
  • Use 0 for gold and common event rewards.
• Amount (amount): amount of items or gold to give.
• Weight (weight): roll weight. Higher value means higher chance.
• Card Back Image (rarity): optional card back image from img/PKD_LootBox.
• Custom Icon Image (customIcon): optional reward icon image from img/pictures.
• Custom Name (customName): optional display name for the reward.
• Common Event ID (commonEventId): common event to reserve when kind is event.
• Custom SE (customSE): optional sound effect from audio/se played when this reward is selected.

Reward Examples

Item reward:

kind: item
dataId: 7
amount: 3
weight: 60

Weapon reward:

kind: weapon
dataId: 1
amount: 1
weight: 40

Gold reward:

kind: gold
dataId: 0
amount: 500
weight: 15

Common event reward:

kind: event
dataId: 0
amount: 1
weight: 15
commonEventId: 1
customName: Level Up!
customIcon: scroll_06_t
rarity: epic

---

Reward Chances

The plugin uses reward weights to choose the result.

Example:

• Potion weight: 60
• Sword weight: 30
• Gold weight: 10

Total weight is 100, so the approximate chances are:

• Potion: 60%
• Sword: 30%
• Gold: 10%

Weights do not need to add up to 100. The plugin compares each reward weight against the total weight.

---

Opening A Loot Box In Game

Use a Script event command:

OpenLootBoxSpin("lootBoxId");

Replace lootBoxId with the ID from the Loot Boxes plugin parameter.

Example:

OpenLootBoxSpin("test");

If the ID is not found, the plugin writes a warning to the console and does not open the scene.

---

Customization Through Plugin Parameters

Loot Box Database

• Loot Boxes (lootBoxesList): all configured loot boxes and their rewards.

Spin Scene Settings

• Default Background Image (spinBackgroundImageName): default scene background from img/PKD_LootBox.
• Spin Duration (spinDuration): main spin duration in frames.
• Win Index Min (spinWinIndexMin): minimum carousel index where the winning reward is placed.
• Win Index Random Range (spinWinIndexRandomRange): random extra range added to the winning index.
• Extra Trailing Items (spinTrailingItemsExtra): extra visual items created after the winning reward.
• Minimum Item Scale (spinMinScale): scale for items far from the carousel center.
• Maximum Item Scale (spinMaxScale): scale for items near the carousel center.
• Item Gap (spinBaseGap): base gap between carousel items.
• Fast Stop Duration (spinFastStopDuration): skip button fast-stop duration in frames.
• Close Delay (spinTakeRewardCloseDelay): delay in milliseconds before closing the scene after taking the reward.
• Refresh Interval (spinPostCreateRefreshInterval): short binding refresh interval after scene creation.
• Refresh Count (spinPostCreateRefreshCount): number of refresh ticks after scene creation.
• Focus Animation Duration (spinFocusAnimationDuration): final reward focus animation duration.
• Focus Scale Bonus (spinFocusScaleBonus): extra scale for the winning reward during focus animation.
• Other Items Scale Multiplier (spinFocusOtherScaleMultiplier): scale multiplier for non-winning rewards during focus animation.
• Focus Lift (spinFocusLift): vertical lift of the winning reward in pixels.
• Side Spread (spinFocusSideSpread): horizontal spread of surrounding rewards in pixels.

Sound Settings

• Spin Tick SE (spinTickSE): SE played when the carousel center changes.
• Spin Finish SE (spinFinishSE): default SE played when the final reward is selected.

Reward Visual Settings

• Gold Default Icon (goldRewardDefaultIcon): default picture icon for gold rewards.
• Common Event Default Icon (commonEventRewardDefaultIcon): default picture icon for common event rewards.

---

Reward Visuals And Sound Priority

Each reward can be customized directly in the loot box parameters:

• rarity: card back image from img/PKD_LootBox
• customIcon: icon image from img/pictures
• customSE: reward sound effect from audio/se

Database items, weapons, and armors can also use notetags:

<lbBack:rare>
<lbIcon:potion_big>
<lbSE:Item3>

Priority Rules

Direct reward settings have higher priority than notetags.

Card back image priority:

1. Reward rarity
2. Database object notetag <lbBack:imageName>
3. Default card back common

Reward icon priority:

1. Reward customIcon
2. Database object notetag <lbIcon:imageName>
3. Database icon index for items, weapons, and armors
4. Default icon for gold or common event rewards

Reward sound priority:

1. Reward customSE
2. Database object notetag <lbSE:seName>
3. Plugin parameter Spin Finish SE (spinFinishSE)

Notes:

• Notetags are used only for database-backed rewards: items, weapons, and armors.
• Gold and common event rewards do not have database objects, so use customIcon, customName, and customSE for them.
• Image names should be written without file extension.
• Sound effect names should be written without file extension.

---

NUI Interface Customization

The loot box interface is built with NUI JSON layout files.

⚠️ Only the default NUI interface is available in the BASIC version of the plugin.

Note: You need a PRO version to use custom NUI layouts.

Main files:

• data/PKD_LootBox/NUI_LootBoxCarouselScene.json
• data/PKD_LootBox/NUI_LootBoxCarouselItem.json

You can edit these .json files to customize:

• scene layout
• button images and positions
• background element
• reward name frame
• carousel item layout
• text positions and styles
• finish animations
• image bindings

Images used by the default interface are stored in:

img/PKD_LootBox

Finish Animations

NUI_LootBoxCarouselScene.json can contain finishupAnimations constants.

The scene reads animation groups by element ID:

• button
• nameText
• items
• reward
• background

These animation rules are applied when the player takes the reward.

---

Practical Setup Checklist

1. Add or verify images in img/PKD_LootBox.
2. Add optional custom reward icons in img/pictures.
3. Add optional reward SE files in audio/se.
4. Open Plugin Manager and edit Loot Boxes (lootBoxesList).
5. Create a loot box and set its unique ID.
6. Add rewards to the loot box.
7. Set reward kind, dataId, amount, and weight.
8. Optionally set rarity, customIcon, customName, customSE, or commonEventId.
9. Open the loot box with:

OpenLootBoxSpin("yourLootBoxId");

---

Quick Example

Create a loot box with ID:

forest_chest

Add rewards:

Potion:
kind = item
dataId = 7
amount = 3
weight = 60

Iron Sword:
kind = weapon
dataId = 1
amount = 1
weight = 20

Gold:
kind = gold
dataId = 0
amount = 500
weight = 20

Open it from an event with Script:

OpenLootBoxSpin("forest_chest");

Optional database item notetags:

<lbBack:rare>
<lbIcon:potion_big>
<lbSE:Item3>

⚠️ If the reward itself has rarity, customIcon, or customSE, those values override the notetags.