Map Inventory Plugin Guide

mapInventoryPluginGuide.md

Map Inventory Plugin - Guide

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

---

Table of Contents

1. Overview
2. Installation
3. Getting Started
4. Core Features
5. Plugin Commands
6. Script Calls
7. Database Note Tags
8. Advanced Features
   • Visual Chests
   • Player Storage
   • Hot Bar (Hot Cells)
   • Items Weight System
   • Item Quality System
   • Custom Item Types
   • Images as Item Icons
   • Random Loot System
9. Customization
10. Support

---

Overview

Map Inventory is a powerful plugin that adds a new interactive grid-based inventory system with visual icons for RPG Maker MV and MZ. It allows players to manage their items directly on the map, providing a more immersive and modern gaming experience.

Important Notes

⚠️ Compatibility

• This plugin is designed to work with mouse input
• Since version 1.5, PKD_MapInventory.js supports both RPG Maker MV and MZ
• Visual settings are stored in data/PKD_MapInventorySettings.json
• By default, the map inventory doesn't play sound effects when opened (configurable via the .json settings file)
• This plugin is not compatible with the Alpha ABS Plugin (Alpha ABS already includes its own inventory system)
• MZ uses a different plugin command system than MV. For MZ, use the script calls provided in this guide

---

Installation

Follow these steps to install the PKD Map Inventory plugin:

Step 1: Extract Files

Extract all files from the downloaded archive.

Step 2: Copy Required Folders

Copy the data and img folders and paste them into your project's root directory.

Step 3: Copy Plugin File

Copy PKD_MapInventory.js and paste it into YourProjectFolder/js/plugins/

Step 4: Load Plugin

Open the Plugin Manager in RPG Maker and add the plugin to your project.

Step 5: Test Your Game

Run a playtest to verify the installation was successful. Press the "I" key (default) to open the inventory.

---

Getting Started

Opening the Inventory

By default, you can open the Map Inventory by pressing the "I" key on your keyboard. This key binding can be changed in the plugin parameters.

Basic Controls

• Left Click - Select and drag items
• Right Click - Use item or equip/unequip
• Mouse Wheel - Scroll through item information
• Drag & Drop - Move items between slots

Customizing Categories

You can hide specific item categories by editing the settings file located at data/PKD_MapInventorySettings.json.

To hide a category:

1. Set the category you want to hide to false in the JSON file
2. Adjust the position values of remaining categories to keep them centered

Equipment Statistics Table

When you hover over equipment (weapons or armor) and scroll with the mouse wheel, you'll see the Equipment Statistics Table. This table can display either:

• Full stats of the equipment
• Only the stats provided by that equipment

The Equipment Statistics Table behaves differently depending on:

• Whether you have a single hero or the entire party
• Whether the item is equipped or unequipped

---

Core Features

Inventory Interface

The Map Inventory provides a visual grid where items are displayed with their icons. Players can:

• Drag and drop items to reorganize
• See item quantities at a glance
• View detailed item descriptions
• Equip weapons and armor directly
• Use items without entering battle

Item Selection Mode

Since update 2.3, you can select not only Items from Inventory via Select Item event command, but also weapons or armor.

Use these script calls right before the Select Item event command:

MI_SetSelectModeW();  // Select weapon
MI_SetSelectModeA();  // Select equipment (armor)

After selection is done or inventory is closed, the select mode returns to default (Items).

Actor-Specific Items

Since update 2.3, you can create items/weapons/equipment only for certain actor usage.

Add <iOnlyForActor:X> to item/weapon/armor Note section, where X is the Actor ID who can use this item or equip this weapon/armor.

Inventory Button

The plugin includes a screen button that can be controlled via script calls:

MIButtonMove(x, y);              // Move button to position
MIButtonVisibility(true/false);  // Show/hide button
MIButtonState(true/false);       // Enable/disable button
MIButtonReset();                 // Reset to default settings

---

Plugin Commands

RPG Maker MV Commands

OpenMapInventory - Open map inventory

--- PRO ONLY ---

MapUserChest - Open player storage chest

VisualChest NAME ICON - Open visual chest
    NAME - chest name (optional)
    ICON - custom icon image from img\pMapInventory (optional)
    Examples:
        VisualChest
        VisualChest SomeChest
        VisualChest SomeChest MyIcon

VisualChestStored NAME - Open visual chest that keeps items

VisualChestStored NAME TYPE - Open visual chest for specific item types
    Example: VisualChestStored Ammunition Ammo|Grenade
    Use <aItemType:TYPE> note tag to set TYPE for items
    Multiple types separated by | (no spaces)

VisualChestStored NAME TYPE ICON - With custom icon

VisualChestIcon ICON - Set custom icon for next chest

SetStoredChestLimit LIMIT - Set cells limit for next visual chest
    Call this before VisualChestStored command

InventoryButton Move X Y - Move button to position
InventoryButton Reset - Reset settings and position
InventoryButton Show - Show button
InventoryButton Hide - Hide button
InventoryButton Disable - Disable button
InventoryButton Enable - Enable button

RPG Maker MZ

For RPG Maker MZ, use the script calls described in the next section instead of plugin commands.

---

Script Calls

Basic Inventory Control

// Open/Close Inventory
OpenMapInventory();
CloseMapInventory();
OpenOrCloseMapInventory();

// Enable/Disable Inventory
DisableMapInventory();
EnableMapInventory();
IsInventoryAllowed();  // Returns true or false

// UI Visibility
HideMapInventoryUI();
ShowMapInventoryUI();

Player Storage (PRO only)

// Open/Close User Chest
OpenMapUserChest();
CloseMapUserChest();

// Add Items to Storage
AddWeaponInPlayerStorage(ID, COUNT);
AddArmorInPlayerStorage(ID, COUNT);
AddItemInPlayerStorage(ID, COUNT);

// Transfer Items
MoveAllItemsToStorage();          // Move all items except key items
MoveEquipedItemsToStorage();      // Move equipped items (party leader only)
TakeAllFromContainer();           // Take all from opened chest

// Clear Storage
ClearPlayerStorage();             // WARNING: Cannot be undone!

Visual Chests (PRO only)

// Open Visual Chest
MIOpenVisualChest("NAME");

// Open Stored Visual Chest
MIOpenVisualChestStored("NAME", "TYPE");
// Example: MIOpenVisualChestStored("Ammunition", "Ammo|Grenade");

// Open Stored Visual Chest for Trading
MIOpenVisualChestStoredForTrade("NAME", "TYPE");
// Example: MIOpenVisualChestStoredForTrade("For Sell", "Misc");

// Set Custom Icon
MISetIconForChest("ICON_PIC_NAME");
// Call before opening visual chest

// Set Cell Limit
MISetStoredChestLimit(limit);

// Clear Chests
ClearAllStoredChests();              // Clear all chests from all maps
ClearStoredChestsOnMap();            // Clear chests on current map
ClearStoredChestsOnMap(ID);          // Clear chests from specific map

Weight System (PRO only)

// Get Weight Information
GetMaxWeight();          // Returns max carrying weight
GetCurrentWeight();      // Returns current weight
IsOverWeight();          // Returns true if overloaded

// Manage Weight
RefreshWeightSystem();                    // Refresh party weight
ModifyInventoryMaxWeight(value);          // Add value to max weight (value > 0)

Limited Cells System (PRO only)

// Check Available Slots
IsHaveFreeSlotsForItems();     // Returns true if free slots for items
IsHaveFreeSlotsForWeapons();   // Returns true if free slots for weapons
IsHaveFreeSlotsForArmors();    // Returns true if free slots for armors

Trade System (PRO only)

// Trade Operations
MIPriceForItemsInTradeChest("NAME", VAR_ID);
// Returns total price and sets to variable (doesn't delete items)

MIClearTradeChest("NAME");
// Deletes all items (doesn't gain gold)

MITradeItemsFromChest("NAME");
// Returns total price, gains gold, and deletes all items

Hot Cells Groups (PRO only)

// Switch Hot Cell Groups
MI_SwitchHotCellsGroup(index);
// Where 0 = default, 1+ = Extra Groups

Item Selection to Variable

// Select Item to Variable
MISelectItemToVariable(type, variableId, commonEventId);
// type: "item", "keyItem", "weapon", "armor"
// variableId: Variable ID to store selected item ID
// commonEventId: Common event to start after selection (0 = none)
// Example: MISelectItemToVariable("item", 100, 24);

// Force Close Selection
MICloseSelectWindow(isCallCommonEvent);
// isCallCommonEvent: true/false

External Item Description Window

// Show Description Window
PKD_MI.showExternalItemDescriptionWindowFor(ITEM, X, Y, APPEAR_SPEED);
// ITEM: item object ($dataItems[11])
// X, Y: screen coordinates
// APPEAR_SPEED: null/0 = instant, number = fade speed
// Example: PKD_MI.showExternalItemDescriptionWindowFor($dataItems[11], 100, 200, 25);

// Close Description Window
PKD_MI.closeExternalDescriptionWindow();

Party Selector Control

// Manage Forbidden Actors
PKD_MI.addForbiddenActorForPartySelector(ACTOR_ID);
PKD_MI.removeForbiddenActorForPartySelector(ACTOR_ID);

---

Database Note Tags

Use these note tags in the Notes section of Items, Weapons, and Armor in your database:

Basic Note Tags

<aItemType:CUSTOM_TYPE>
Define custom item type
Example: <aItemType:Ammunition>

<aItemType:TYPE1|TYPE2>
Multiple types for one item
Example: <aItemType:Weapon|Tool>

<aItemTypeColor:#HEXCOLOR>
Custom color for item type
Example: <aItemTypeColor:#ba9059>

<itemRare:QUALITY_LEVEL>
Set item quality/rarity level (0, 1, 2, 3, etc.)
Example: <itemRare:2>

<notForHotCell>
Prevents item from being dragged to Hot Cell

<iImg:NAME>
Use image as item icon (from img\pMapInventory\Icons\)
Example: <iImg:potion>

<invDescBackImg:NAME>
Custom background for item description
Example: <invDescBackImg:customBackground>

Weight System Note Tags (PRO only)

<weight:VALUE>
Set item weight
Example: <weight:6>

<weightStore:VALUE>
Add to max weight when equipped
Example: <weightStore:20>

Equipment Note Tags

<lvReq:X>
Equipment level requirement
Example: <lvReq:10>

<invDescH:X>
Change description window height (in pixels)
Example: <invDescH:200>

<invDescW:X>
Change description window width (in pixels)
Example: <invDescW:300>

<iOnlyForActor:X>
Restrict item to specific actor (X = Actor ID)
Example: <iOnlyForActor:1>

Complete Example

<aItemType:Ammunition>
<aItemTypeColor:#ba9059>
<itemRare:2>
<weight:6>
<iImg:potion>
<invDescBackImg:customBackground>
<notForHotCell>

---

Advanced Features

Visual Chests

⚠️ PRO version only

Visual Chests allow players to choose which items to take from a chest, rather than automatically receiving all items. There are two types:

Regular Visual Chest

A chest where players choose which items to take. Can only be opened once.

Setup:

1. Create an event
2. Add plugin command: VisualChest (or script call: MIOpenVisualChest("NAME"))
3. Add event commands: Change Gold, Change Items, Change Weapon, Change Armor
4. Important: Add a Self Switch to prevent infinite items

With Custom Name:

VisualChest Treasure

Visual Chest Stored

A chest that:

• Remembers its contents between openings
• Allows players to store items
• Can be opened multiple times
• Persists across game sessions

Setup:

1. Create an event
2. Add plugin command: VisualChestStored NAME (or script call)
3. Add item commands
4. No Self Switch needed

Example with name:

VisualChestStored StoredOne

Type-Specific Stored Chests

Create chests that only accept certain item types:

VisualChestStored Ammunition Ammo|Grenade

Performance Tips:

• Stored chests increase save file size
• Use these script calls to clear chests:

  ClearAllStoredChests();              // Clear all chests
  ClearStoredChestsOnMap();            // Clear current map
  ClearStoredChestsOnMap(MAP_ID);      // Clear specific map

Settings File: data/PKD_MapChestSettings.json

---

Player Storage

⚠️ PRO version only

Player Storage is a special persistent chest for storing items.

Features:

• Only one User Chest (all instances share items)
• Cannot store Key Items
• Cannot store equipped items
• Persists between game sessions

Setup:

Add plugin command:

MapUserChest

Or use script call:

OpenMapUserChest();

Managing Storage:

// Add items programmatically
AddItemInPlayerStorage(ID, COUNT);
AddWeaponInPlayerStorage(ID, COUNT);
AddArmorInPlayerStorage(ID, COUNT);

// Transfer items
MoveAllItemsToStorage();          // Move all (except key items)
MoveEquipedItemsToStorage();      // Move equipped items
TakeAllFromContainer();           // Take all from chest

// Clear storage
ClearPlayerStorage();             // WARNING: Cannot be undone

Settings File: data/PKD_UserChestSettings.json

---

Hot Bar (Hot Cells)

⚠️ PRO version only
⚠️ Available since build 1.6

The Hot Bar provides quick access shortcuts for important items.

Features:

• Drag items to hot bar slots
• Press assigned keys to use items
• Click on slots to use items
• Multiple hot bar groups
• Customizable position and appearance
• Hotbar items are for party leader only

Setup

1. Enable Hot Bar in plugin parameters (4 slots by default)

2. Configure Text Settings for slot labels

3. Set Hotkeys for each slot

4. Add Extra Hot Bars and position them (optional)

Script Calls

// Switch between hot cell groups
MI_SwitchHotCellsGroup(index);
// 0 = default group
// 1+ = extra groups from plugin parameters

---

Items Weight System

⚠️ PRO version only
⚠️ Available since build 1.3

The Weight System adds realistic inventory management with carrying capacity limits.


Setup

1. Enable Weight System in plugin parameters

2. Set Max Weight Variable - This variable stores the maximum carrying weight

3. Configure Default Weight (default is 1 per item)

Note Tags

<weight:X>
Set item weight
Example: <weight:6>

<weightStore:X>
Equipment increases max weight when equipped
Example: <weightStore:20>

Overweight Effects

Configure effects when player exceeds max weight:

• Movement speed reduction
• Custom events triggered
• Visual indicators

Script Calls

// Get weight information
GetMaxWeight();               // Return max weight
GetCurrentWeight();           // Return current weight
IsOverWeight();              // Return true if overloaded

// Manage weight
RefreshWeightSystem();                    // Refresh calculations
ModifyInventoryMaxWeight(value);          // Add to max weight (permanent)

---

Item Quality System

The Item Quality System adds rarity levels to items with visual borders and color coding.

Setup

1. Enable Item Quality in plugin parameters

2. Define Quality Levels in data/PKD_MapInventorySettings.json

Each quality level has:

• Index (0, 1, 2, 3, etc.)
• Name (Basic, Good, Rare, Epic)
• Text Color (hex color code)

Example:

{
  "qualityLevels": [
    { "name": "Basic", "color": "#FFFFFF" },
    { "name": "Good", "color": "#00FF00" },
    { "name": "Rare", "color": "#0080FF" },
    { "name": "Epic", "color": "#A335EE" }
  ]
}

3. Create Quality Border Images

Place images in img/pMapInventory/ with naming format:

• QualityLevel_0.png (Basic)
• QualityLevel_1.png (Good)
• QualityLevel_2.png (Rare)
• QualityLevel_3.png (Epic)

4. Add Note Tags to items

<itemRare:0>  // Basic
<itemRare:1>  // Good
<itemRare:2>  // Rare
<itemRare:3>  // Epic

---

Custom Item Types

By default, Map Inventory uses RPG Maker's standard item categories. You can create custom types for better organization.

Default Types:

Creating Custom Types

Use note tags to define custom item types:

<aItemType:TYPE>
Define single type
Example: <aItemType:Ammunition>

<aItemType:TYPE1|TYPE2>
Define multiple types
Example: <aItemType:Weapon|Tool>

<aItemTypeColor:#HEXCOLOR>
Custom color for type display
Example: <aItemTypeColor:#ba9059>

Example:

Result:

Using with Stored Chests

Create type-specific chests:

VisualChestStored Ammunition Ammo|Grenade

Only items with matching <aItemType> tags can be stored.

---

Images as Item Icons

⚠️ PRO version only
⚠️ Available since build 1.7

Use custom images instead of icon sheet icons for a more detailed visual presentation.

Setup

1. Place Images in img/pMapInventory/Icons/

   • Use any size (recommended: square/rectangular)
   • Same x and y dimensions work best
   • Supports common formats (PNG recommended)

2. Add Note Tag to items

<iImg:NAME>
Where NAME is the image filename without extension
Example: <iImg:potion>

3. Enable in Default Windows (optional)

Show custom image icons in standard RPG Maker windows by enabling in plugin parameters.

Icon Drawing Modes

Choose how icons are displayed:

• Fit Grid - Stretch to fill cell (default)
• Centered - Keep original size, center in cell

Large Inventory Mode

You can increase inventory and icon size:

1. Edit positions in PKD_MapInventorySettings.json
2. Modify cell size parameter
3. Template files included in update

---

Random Loot System

⚠️ PRO version only
⚠️ Available since update 2.1

Create dynamic chests with randomized contents and drop chances.

Basic Chance System

Add comment chance:X before Change Items event command, where X is the drop chance percentage (0-100).

Example:

chance:50  // 50% chance to drop next item

Extended Chance Options

Variable-Based Chance:

chance:X|V

Chance value comes from Variable X

Switch-Based Chance:

chance:X|S

If Switch X is ON = 100%, OFF = 0%

Conditional Item Placement

Use put:TYPE:ID:COUNT comment after chest script call and before gain item commands.

Syntax:

put:TYPE:ID:COUNT

TYPE: item, weapon, or armor
ID: Direct ID (7) or Variable (18|V)
COUNT: Direct count (1) or Variable (100|V)

Example:

chance:50
put:item:7:1           // Item ID 7, count 1

chance:10
put:weapon:10|V:1      // Weapon ID from Variable 10

put:item:8:4|V         // Item ID 8, count from Variable 4

⚠️ Important: At least one gain item command is required after put: comments.

---

Customization

Settings Files

The plugin uses JSON files for visual customization:

Main Inventory Settings:

data/PKD_MapInventorySettings.json

• UI positions and sizes
• Category visibility
• Colors and fonts
• Cell dimensions
• Quality level definitions

Visual Chest Settings:

data/PKD_MapChestSettings.json

• Chest appearance
• Button positions
• Window layouts

User Chest Settings:

data/PKD_UserChestSettings.json

• Storage chest UI
• Capacity limits

Image Assets

Custom images are stored in:

img/pMapInventory/

Image Types:

• UI elements (backgrounds, buttons, frames)
• Quality level borders (QualityLevel_X.png)
• Chest icons
• Custom item icons (in Icons/ subfolder)

Tips for Customization

1. Back up files before editing JSON settings
2. Use JSON validators to check syntax
3. Test changes incrementally
4. Keep original images as templates
5. Document custom changes for future reference

---

Support

Resources

• Official Website: https://kdworkshop.net/map-inventory
• YouTube Channel: KageDesu YouTube

Support Development

If you enjoy this plugin and want more frequent updates:

• Patreon: https://www.patreon.com/KageDesu
• Boosty: https://boosty.to/kagedesu

Special Thanks

SMO_Valadorn, Zee, Fiquei, Carlos Ferreira, Raffle, Zekkent