Understanding Instance Items
Some scripters have expressed confusion about how I have implemented Instance Items, so I have decided to explain how it is designed and how it works. I will discuss how add-ons can be written for it in order for you to write your own item/equip related scripts to take advantage of instance items.
Problem
To understand why the script created, we begin by understanding what problem I have tried to address.
Imagine you have several blunt swords in your inventory.
Assuming you’ve set up your project so that instead of stacking items together, there is still an issue with this setup: all items reference the same database object.
This means that no matter which sword you pick, they all point to the same sword. They will have the same name, same parameters, same features, same animation, and so on. If you change one blunt sword, that change applies to every blunt sword. So, while it looks like you have different swords, they are in fact one in the same.
Solution?
I introduce the idea of having “instance items”. What are they “instances” of? If you think about the way your database is constructed, you have your weapons that you put a lot of time into carefully crafting
In my model, I consider all of these to be “templates” of your weapons. They describe the properties that they have by default. A blunt sword would start off with 3 Atk and cost 180 to purchase. When you actually receive a blunt sword during the game, you will receive an instance of the blunt sword, which will have all of the default properties that the template describes, along with anything extra that is unique to the particular instance.
So when I say “instance item” I simply mean they are instances of the items that you have defined in the database.
How instance items are managed
There are a few challenges presented when it comes to actually managing instance items. Several scripts have been written in the past by various scripters, all trying to address the problem. In fact, Instance Items succeeds an older script that I had written (called “FP Inventory System“), and far surpasses it in terms of compatibility and flexibility.
Instance Items uses three general concepts to implement item management:
- All instances are stored in the database as their own separate objects with their own ID’s. This ensures that every instance can be uniquely identified. This decision was made based on the fact that all database access in the default scripts use object ID’s, so all I have to do is give each object a different ID and everything comes together.
- Only instances can exist in the game. Every blunt sword that you see in the first screenshot is an instance, and you can assume any object that you work with will be an instance. When you access the database with that object’s ID, you will always get the correct object. This means you don’t need to worry about whether something is a template or not.
- All instances are RPG objects. You don’t have to worry about any custom classes that are created to handle instance items. If your item script originally worked with RPG objects, then it will work with instance items (with a few minor modifications)
If you assume these three assumptions are always true, then every object that you will ever work with in your own scripts are instances, and you can simply use the RPG classes as you always have.
Instance Items and Save Games
What happens when the player chooses to save their game? After all, the items you have in one save file may not be the same as the ones in another save file, even if they are part of the same run. One blunt sword in one game might be upgraded to level 5, but the same blunt sword later on might be level 8. And have extra gems. And a new look.
Fortunately, this is something scripters don’t need to worry about. The instance items are stored with the appropriate game, and will be loaded into the database when the player resumes a save file. Any properties that are defined with instance items are automatically saved.
Instance Items and Custom Properties
Instance Items comes with a number of add-ons written by both myself and other scripters. You can give your equips levels, add affixes, define rarity levels, set durabilities, and so on.
One of the advantages of using this script to manage your items is that add-ons do not need to know about any of the other add-ons. Instance Items provides a set of make methods that allow you to define how some common properties such as name, parameter, or feature changes should be applied, and then the script will perform all of the operations and calculations for you using a set of refresh methods. You can define how the make and refresh methods are applied.
This design allows the game to accurately performs updates to your items. For example, suppose your blunt sword currently has a base atk of 3, along with a gem that doubles its atk for a total of 6. You then upgrade your blunt sword so that its base atk increases to 5. Rather than having to worry about how to re-calculate the sword’s final atk, the script will notice that your base atk has changed (because you would explicitly call refresh), and it will re-apply the gem’s effect so that your sword has a total atk of 10 using the make rules that are defined for the gem add-on.
Conclusion
Hopefully, this article clarifies why the instance items script is written the way it is, and also encourages you to try and write your own equip or item add-ons for it.
Credits
The equip menu was taken from the “Etrian” sample project that comes with Luna Engine.
Spread the word
If you liked the post and feel that others could benefit from it, consider tweeting it or sharing it on whichever social media channels that you use. You can also follow@HimeWorks to get the latest updates or suggest topics that you would like to read about.
![[Tutorial Series] Hime ATB #4: State Turns and Effect Timings](https://himeworks.com/blog/wp-content/themes/hueman/assets/front/img/thumb-medium-empty.png)
At first I was thinking gasp, is this our first look at Tsukihime's personal project?
But alas.
Heheh.