This script introduces the concept of “instance items”. In order to understand what an instance item is, you need to first understand what a “template item” is.
All of your database items, weapons, and armors are called “template items”.
That is, they serve as templates for in-game items.
An instance item is simply an instance of a template. For example, you design weapon ID 1 in your database and call it a “Short Sword”. This is a template of a Short Sword; everytime you receive a Short Sword in-game, you receive a unique “instance” of this template. Two Short Swords in your inventory are treated as two individual entities that have nothing to do with each other besides both being based on the Short Sword template.
It is important to note that this script simply provides instance item functionality. Additional add-ons are required to provide various features such as equip levels, equip affixes, and so on.
There are several known issues with the script. I have discussed them at the bottom of this post. Read through them to see if they affect you, and some ways they can be resolved.
Script: download here
A list of add-ons that add more functionality to your games. It will be updated continuously. You can have your script added to this list by leaving a comment.
- Item Affixes – add prefixes and suffixes to your equips
- Item Rarity – add colours to your equips based on rarity
- Selchar’s Equipment Level Base + Leveling by Exp
- Selchar’s Weapon Durability
- Selchar’s Equip Evolve By Exp
- Feldherren’s SnapDragon – turn actors into new equips!
- Patch for Yanfly’s Ace Equip Engine
- Patch for Falcao’s Mana Stones Enchantment
- Patch for Emerald’s Equipment Sets
In the script editor, place this script below Materials and above Main
You should place this below any equip-related scripts, such as my Core Equip Slots or Yanfly’s Ace Equip Engine.
This script is plug and play for the most part as I’ve set up some default values.
You can determine what type of objects allow instances or not in the configuration by changing its “instance mode”. For example, you can disable instances for items so that they stack as normal.
These are the default values I have picked:
Items - false Weapons - true Armors - true
Currently, if instance mode is ON for that category of items, all items will be treated as instances.
The following event commands behave differently if instance mode is on.
When I say “item” I refer to weapons, armors, and items.
- When you gain an item using events, new instances will be added to the inventory.
- When you lose an item using events, it follows “template discard” rules. For example, if your event says to “lose 1 short sword”, then the engine will simply look for ANY instance item that is based on the short sword. The same applies to equips if you include equips.
- When you use the “change equipment” event command, the engine looks for the first instance of the specified equip.
This script serves as a framework for all instance items. Currently, it only supports item, weapon, and armor instances.
The goal is to allow developers to write their own scripts that require “unique” items very easily without having to worry about how to actually implement it.
This script is designed so that you only need to focus on two things
- The RPG module, which contains the template weapons, armors, and items.
- the InstanceManager module, which handles everything related to instances.
A simple script would first load note-tags from the RPG objects and store them with the templates. For example, suppose we want to give all instance weapons a random attack bonus. We start by defining the max possible bonus a weapon could receive.
class RPG::Weapon < RPG::EquipItem def attack_bonus 50 end end
Now, we make it so that whenever an instance weapon is created, a random bonus will be applied to its attack. The InstanceManager provides several “setup” methods available for you, depending on what kind of object you’re working with:
setup_equip_instance(obj) - use this for any equips (weapons or armors) setup_weapon_instance(obj) - use this only for weapons setup_armor_instance(obj) - use this only for armors setup_item_instance(obj) - use this only for items
Since our example is applying a random flat bonus to an instance weapon, we would alias the weapon setup method.
module InstanceManager class << self alias :th_random_weapon_bonus_setup_weapon_instance :setup_weapon_instance end def self.setup_weapon_instance(obj) template_obj = get_template(obj) th_random_weapon_bonus_setup_weapon_instance(obj) obj.params += rand(template_obj.attack_bonus) end end end
Note the use of the
get_template method in the setup.
obj is an instance weapon that we are creating.Our data is stored with the template weapon, so we need to get it first before we can use it. After you have your template, you can easily get the data you need to apply to your instance object.
And that’s it! Your instance weapon now has a random attack bonus. You can verify this by adding the same weapon to your inventory multiple times and checking their parameters in the equip menu.
This is a very simple example, but its goal is to demonstrate how to modify your instance objects. The rest of the game will just see it as another item or equip.
There may be a few issues that will occur due to the way the items are stored. If you find more issues, you can report them on my issue tracker.