Custom items are a common goal for new mod authors, but they're one of the hardest things to do because the game uses the item spritesheet index as the ID. That means IDs need to fit within the spritesheet's max size, and mods can't avoid conflicts with other mods without complex workarounds like Json Assets and Dynamic Game Assets (which add their own problems and limitations).
This proposal solves that by giving each item a string
UniqueKey, and allowing custom
spritesheets per item. That also avoids needing to check item types in most code, since there's no
longer any possible ID overlap.
This proposal aims to...
- minimize changes needed in the game code where possible;
- maximize compatibility with existing content packs where possible;
- allow item keys anywhere that currently uses the parent sheet index;
- let mods add items without Harmony or complex frameworks;
- let mods add any number of custom items without key or sprite index conflicts.
Changes to C# code
Item class has two new fields:
||The spritesheet texture to draw (e.g.
||A globally unique string key for the item, like
ParentSheetIndex field is unchanged, except that it targets
ParentSheet instead of a global texture (which would be the same for vanilla items).
Creating an item would be the same as before, except that it'd take the key instead of the spritesheet index. For example:
new Object("634", 1); // 634 = unique key for apricot (see changes to data assets below) new Object("Pathoschild.ExampleMod_watermelon", 1); new Furniture("groovy_chair", Vector2.Zero);
The game would ideally provide a method to get any item by its key too (which would enable things like sending non-object items through the mail):
Item item = Game1.getItemByKey("groovy_chair");
Most item references would use the key instead. For example:
|old code||new code|
Changes to data assets
Assets which define an item
This section applies to:
These all have two new fields:
||(optional for objects) The item's index in the spritesheet. (For
||(optional) The item spritesheet's asset name under
Data/ObjectInformation is identical for vanilla items, while custom items can use the new fields:
"634": "Apricot/50/15/Basic -79/Apricot/A tender little fruit with a rock-hard pit.", "Pathoschild.ExampleMod_watermelon": "Watermelon/300/10/Basic -79/Watermelon/Takes 28 days to grow. Plant in summer./3/Pathoschild.ExampleMod_objectSprites"
Unfortunately non-objects can't use the same trick, since their unique keys would overlap with
object keys. These have a unique key based on the name instead. For example, in
"groovy_chair": "Groovy Chair/chair/-1/-1/4/750/82"
Assets which reference an item
These now reference the unique key instead of the parent sheet index. Since those are the same for objects, many assets are unchanged.
For example, here's from
Data/NPCDispositions with one custom item:
Universal_Like: "-2 -7 -26 -75 -80 72 395 613 634 635 636 637 638 724 459 Pathoschild.ExampleMod_watermelon"