Item Instances Base
Version: 1.0
Author: modern algebra
Date: August 7, 2011
Version History
- <Version 1.0> 2011.08.07 - Original Release
Description
This is a scripting tool that changes the way items are handled in the game to allow for item instances. This means that items specially marked will be uniquely saved every time you collect them.
This script was designed since scripts which require items to be saved as instances, even if they were conceptually simple (like durability), were impractical to make since they required a heavy overhaul of the entire item system. The only other scripts I know about that have tried tend to be very bulky and usually incompatible with every other item-based script out there. This script was therefore designed to (a) change the way marked items were saved so as to be more dynamic and saved as instances; (b) be compatible or easily made compatible with most other scripts that deal with items; and (c) be easy to create addons which make use of the framework to create functional changes to items, weapons, and armors.
This script makes little functional difference aside from changing how marked items are stacked in the menu and allows you to change the specific stats of items if you add them through the Change Item/Weapon/Armor event commands by using a comment. However, it provides a necessary structure for other scripts, such as a weapon durability or charges script, where the stats necessarily must vary between items of the same type.
While I made this script to provide a base for a series of scripts I will make, any scripter is welcome to use this as a base for their own scripts.
Features
- Allows you to mark some items to be saved individually, thus allowing you to modify their stats without changing the stats of every other instance of the item
- Highly compatible by retaining much of the same basic structure as default. Where there will still be some incompatibilities, it is designed to be easy to make a compatibility patch for
- Unlike other similar scripts, separating the base from the scripts that utilize it allows users to only grab the scripts they want to use and not have it come in a huge bundle
Screenshots
(https://rmrk.net/proxy.php?request=http%3A%2F%2Fimg204.imageshack.us%2Fimg204%2F1797%2Finstanceitems.png&hash=6c2b5051c113db2441752c149b4d40fff8fd1e56)
Though the same item, they are saved individually. The stats are different in this
case because I am using the Random Stat Variance for Items (http://rmrk.net/index.php/topic,43442.0.html) script.
Instructions
This script must be placed above Main and BELOW every regular custom script that might deal with items, even if they do so only incidentally.
However, it must be ABOVE any scripts that directly utilize this framework (see the "Derivative Scripts" list).
See the Header for more detailed instructions on utilization.
Guidelines
If you are a scripter and want to use this as a base for a script, you should familiarize yourself with it fully. However, here are a few little (non-exhaustive) guidelines/tips:
- To check if a particular item creates instances, you can use the code: item.instance_based?
- If you are adding a notebox code, you can add the RegExp to the RPG::BaseItem::MA_INSTANCE_CHECKS constant and it will interpret any item with that code as instance based and treat it accordingly. Otherwise, you would need to manually alias the instance_based? method or else require the use of the generic \Instance code.
- You can get the ID of the base item from an instance item by asking for the item_id attribute, while the id attribute will return the unique index of the instance item. If you ever need the id method to return the base's item ID instead of its unique ID, then you turn the get_item_id attribute to true and it will. This is useful especially for aliasing.
- If you want instance items to be destroyed when they are lost (which you should do if the player will never have a chance to recover them), you can set $game_party.ii_destroy_lost_instances to true.
- To create a new instance without going through the gain_item method, you use the code data.create_instance (base_item), where data is either $data_items, $data_weapons, or $data_armors and base_item is an RPG::Item/Weapon/Armor object. To destroy an instance, you use data.destroy_instance (index) where data is the same and index is the item's unique ID.
- You can retrieve all the existing instance items with a base ID by the code: data.items_with_id (x) where x is the ID in question. For instance, if you want to get all instances of the long sword (ID 2), you'd ask for $data_weapons.items_with_id (2). Note that it will return ALL instance items with that ID and not only those held by the party. For instance, it will also give you them even if they are currently equipped.
- $data_items, $data_weapons, & $data_armors are all still the arrays they used to be, only with the [] and []= methods altered for instance item support. As such, any array methods will work exactly as they used to - So, for instance, if you do $data_items.each {} then you will cycle through only the base items and not the instance items.
- The code $game_party.newest_instance_items will return an array of all the latest items the party has received through the gain_item command.
Script
The script is too long. Get it at Pastebin (http://pastebin.com/w8mdkSZW)
Derivative Scripts
The following is a list of scripts (existing and planned) that use this script as a base:
- Random Stat Variance for Items (http://rmrk.net/index.php/topic,43442.0.html)
- Perishable Items (http://rmrk.net/index.php/topic,43476.0.html)
- Weapon/Armor Durability
- Unidentified Artifacts
- Achievement Upgrades (like in Fable 3)
- Poisoned Weapons
- Weapon/Armor Socketing and Enchantments
- Weapon Levelling
Credit
Support
Please post in this topic if you encounter any compatibility issues at all - I would love to know about them and fix them for you.
Known Compatibility Issues
This script must be placed above Main and below EVERY custom script that deals with items, weapons, or armors, even if they do so in a merely incidental way.
Though I tried to make this script highly compatible, I am extremely fallible and it will still be incompatible with some scripts. If you find such an incompatibility, alert me to it and I will quickly correct it.
Demo
I will eventually make a demo and will update it every time I make a new script that uses it. For now, since it makes no significant functional difference, there is no demo.
Author's Notes
This is a scripting utility I designed mostly for myself as I plan to make a series of scripts that require items to be saved as instances, such as item durability, poisoning and socketing weapons, unidentified artifacts, etc...
I experimented a little with this script, and I invite comments from other scripters on how I could improve it, particularly with an eye to anticipated incompatibilities.
You can create it with the code:
$data_items.create_instance (item)
where item is an RPG::Item.
From a Game_Item instance, you can retrieve the RPG::Item it was derived from with the code:
item.base_item
where item is a Game_Item. Alternatively, you could retrieve it with:
$data_items[item.item_id]
where item is either a Game_Item or an RPG::Item (though if it were an RPG::Item, it would be pointless since you already have it).