One of the most expansive features of TR Tools is the ability to add fully custom items to the game. This page describes in detail exactly how to accomplish this, what is fully supported, and what is explicity not supported at the moment.
Some items, such as clothing, can be created much more quickly and without any coding required. To read more about that, check out the Quick Item Creation page.
All custom items must be created as an AssetBundle and use many of the scripts/components that are used on vanilla items. This process looks very different depending on the item you're creating, but these are the general steps.
For instructions on how to do this, read the Loading Into Unity page.
Choose a vanilla item to use as a base. For instance, if you're adding a new vehicle, you might use the motorbike as a base. Typically these can be found in the “Assets/PrefabInstance” folder but may be found elsewhere and the correct objects may not always have the names you'd expect them to.
Most items will require multiple relevant objects to be duplicated.
- All items need an object with the InventoryItem component on it. Usually these start with "Inv_" for vanilla items.
- If your item is a tile object, it will need two additional objects. One has at least the TileObject component on it, and the other object has a TileObjectSettings component on it.
- Paths require an object with the TileTypes component.
- Vehicles require an object with the Vehicle component.
- Carryable items (such as Thunder Eggs) require an object with the PickUpAndCarry component.
Example: For a vanilla wooden crate there are four objects - Crate (the tile object), Inv_Crate (the inventory item), 23 Crate (the tile object settings), and Cratehand (the object held by the player).
Once you've found all the relevant objects to the vanilla item, duplicate them, rename the duplicates, and place them in a separate folder so they are easy to keep track of.
Each of the objects you've duplicated will have important components on them with a large number of settings. I highly recommend looking carefully through each component's settings and adjusting them as desired. Some objects will also have child objects with important settings.
In general, the most important settings are:
- On InventoryItem you'll want to change ItemSprite (the icon used in inventory), ItemPrefab (the object shown in the player's hand), and Placeable (the tile object if needed) to reference your objects instead.
- If it's a tile object, on TileObjectSettings you'll want to change the DropsItemOnDeath to reference your inventory item.
- If it's any kind of object that requires a world model (tile objects, vehicles, etc) you'll change the models, textures, animations, etc as desired.
There is no need to change any item ID settings on any components, because that is all handled by the framework automatically.
Once your objects are fully set up, you need to add all of them to an asset bundle that is used only for this one item.
To create an assetbundle:
- In the unity project, create a new folder anywhere named “Editor”.
- Download this CreateAssetBundles.cs script and place it in your new Editor folder.
- Select the first object for your item, then look to the very bottom of the inspector where it says “AssetBundle” with a dropdown next to it.
- Click on the dropdown menu and select “New” to create an assetbundle specifically for this item.
- For each of the other objects involved, repeat the process, but select the created assetbundle from the dropdown.
- Once all objects have been added to the assetbundle, go to the top left menu of Unity and choose Assets → Build AssetBundles.
- Your new build will be created in the "Assets/Custom Item Bundles" directory. Open this directory in Windows.
- You only need the file with no extension. The manifest and meta files can be ignored. The bundle file is what you need to load in your code, so copy it and place it in a folder for your mod in the Dinkum/BepInEx/plugins folder.
For more information on how to use and create assetbundles, read the Unity documentation.
This section explains how to take a completed custom item assetbundle and load it into Dinkum, but we will assume that you already know how to create a BepInEx plugin and that you have followed the Basic Setup of TR Tools.
Adding a custom item is fairly simple. An example of adding two separate items is below.
private void Awake() {
plugin = TRTools.Initialize(this, yourNexusID, yourChatTrigger);
myFirstItem = plugin.AddCustomItem("TR Tools/MyCustomItem", 1);
mySecondItem = plugin.AddCustomItem("TR Tools/MySecondItem", 2);
}
The important aspects of this are:
- You MUST specify a nexus ID when initializing. (See the Nexus ID page for more information)
- Adding custom items is done through your initialization reference.
- The first parameter of AddCustomItem() is the path to your assetbundle. This path is relative to the plugins folder. So in our case, we have the “TR Tools” folder inside the plugins folder, and inside that is our asset bundles.
- The second parameter is a unique ID for this item in particular. This should never be changed at any point after releasing the mod. Otherwise, users will lose or mix up data. I recommend just starting with 1 and counting up with each new item added. The full unique ID for a particular item is a combination of your nexus ID and the unique item ID you specified. This will be used for save data and by players when using chat commands.
- It's not absolutely necessary but is recommended to store the return of AddCustomItem() to a variable. This allows you to easily access components of your custom item if desired.
If, when adding your custom item, you've saved the returned value to a variable, then you can access its various components more easily. The references that can be accessed are: inventoryItem, tileObject, tileObjectSettings, tileTypes, vehicle, and pickUpAndCarry. Each is a reference to the component of the same name. If your item doesn't use one of these components, then it will, of course, return null. Note that these references are not to any one specific instance of your item. They are references to components on the prefabs for your item.
You can also call yourItem.GetUniqueID() (where yourItem is the reference you've saved) and it will return the full ID for your custom item. This is NOT the itemID that is typically used in vanilla Dinkum. Instead, this is the ID that is used in your item's save data and for chat commands. It is a combination of your mod's nexus ID and the unique ID you specific when adding the item. For instance, if your mod's nexus ID is 83 and you gave your item the ID of 1. Then 83.1 would be the full ID.
There are a couple ways for a player to receive your custom item.
- When creating your asset bundle for the item, if you put a Recipe component on the same object as the InventoryItem component, you can specify a recipe for the item and requirements to unlock the recipe. If all requirements are met, the player will automatically receive the recipe. This method, however, does not allow for specifying custom items as ingredients in the recipe.
- They can use item related chat commands. See the Chat Commands (Users) page for more info.
- You can send them the item by mail using
TRMail.SendItemInMail().
While the framework makes this process far easier and safer than it would otherwise be, it is still a little complicated and there is no guarantee that it will work for every possible item in every possible situation.
If your item is fairly simple or similar to a vanilla item it should work well. Some items, however, may have issues or caveats:
- Tools: Most tools should be fine, but shovels have multiple models depending on what kind of dirt they're holding. We plan to eventually add support for this.
- Storage: If you're adding a new kind of box/chest to the game, it will work fine as long as you're only changing the design of the model/texture. If you change or add any functionality or you change the number of slots it can use, then you may experience issues. We plan to better support custom storage in the future.
- Plants: Not specifically implemented or tested. Trees are tested and seem to work fine.
- Bugs & Fish: Added a custom inventory item and world object for these should work fine, but there's no way to add custom bugs or fish to the world with TR Tools yet, so this isn't specifically supported.
- Consumables: These are not tested yet, but they should work. Let us know if you experience issues.
- Items with Special Functionality: If your item has some new functionality, there's a good chance it will work great, but there's always the chance of issues. We want to include support for anything we can, so feel free to tell us about your issues and we'll try to figure something out.