Item Mod Tutorial

Creating your own item mod with ModComponent involves 4 steps:

1. Having 3D models, sounds and icons for the items you want to make
2. Building an asset bundle with the Unity Editor
3. Installing your mod
4. Testing and fine-tuning

Assets (3D Models, Sounds, Textures and Icons)

3D Models

Sounds

Textures

Textures are regular images that are used in the UI (e.g. representing items in the player's inventory, a backdrop in the skills list), applied to 3D objects to make them look more realistic or basically anywhere else in the game.

The difference between a texture and an icon in this tutorial is in the technical way they are provided.
Some things in TLD are called "icons" because that's they represent (Wikipedia: "a pictogram or ideogram displayed on a computer screen"), but technically they are still provided as a texture.
So while an item needs an "inventory icon", you still need to provide a "texture" for this.

Unity can handle textures in many different image formats (PNG, JPEG, BMP, etc.) and they can be edited with any regular image manipulation software.
Unity will automatically export textures that are used by exported prefabs. Textures that are only referenced by scripts (either your own, plugins or TLD directly) need to be assigned to an Asset Bundle or in a folder that's assigned to an Asset Bundle.

When you have a suitable image, import it as a new asset and configure its settings in the Inspector.
For "inventory icons" the settings can usually be left at their defaults.

Alpha Is Transparency

Use the "alpha" channel of the texture and interpret is as transparency. That means the texture might have areas that are completely invisible (it will have "holes"). If the image does not have an alpha channel (e.g. JPEG, BMP), there will be no invisible areas.

This setting should be enabled when using textures for "icons" and basically everywhere, where a texture is displayed over some background.

Generate Mip Maps

Mipmaps are pre-calculated smaller versions of the original texture. At runtime the most suitable size of the texture is used, which improves rendering speed and quality, since the mipmaps can be produced using are "more expensive" algorithms.

The only downside of this is increased size (the total size of the mipmaps will be 1/3 of the original texture).

Usually there's no reason to disable mipmaps.

Icons

TBD

Building an Asset Bundle

For this step you need the correct version of Unity installed. (listed on For-Developers).

The easiest way to start your Unity project is to use the template project: https://github.com/WulfMarius/ModComponent/tree/master/Template (Download the whole repository as zip and then copy the "Template" folder)

Ignore the contents of the folders "Editor" and "Plugins" for now, but do not delete them - They are required!

Remember that you need to save your scene and project to prevent loss of work and data.
Save when you feel like you completed a step and are confident that the current state of the project is good.
Consider using a versioning system like Git, even if you don't intend to share your mod (which you should really do!)

You can take a look at the example project to see how the finished result might look.

• Decide which name you want to use for your asset bundle and assign the folders "InventoryGridIcons" and "Prefabs" and the file "Localization.csv" to the asset bundle with that name. Variants are not required.
  See section "Working with AssetBundles" in https://unity3d.com/learn/tutorials/topics/scripting/assetbundles-and-assetbundle-manager for how to do this.
  (If your mod requires additional assets, you will need to assign them to the asset bundle as well.)

• For each item you want to make, repeat the following steps:

  • Import your 3D model into the "Models" folder.
  • Create a new GameObject in the scene using the imported model
  • Add a collider.
    This collider is used for detecting items under the reticle. A BoxCollider is usually good enough.
  • Add the components from ModComponent that you need/want and configure them accordingly.
  • Create a prefab from your finished GameObject and name it "GEAR_...", e.g. "GEAR_CarKey".
    This is very important, because a lot of the functions in TLD expect items to have a name like that.
  • Move your new prefab into the "Prefabs" folder.
  • Add a suitable texture as inventory icon in the folder "InventoryGridIcons". (For details see Basic Item Configuration)
  • Add the required texts to "Localization.csv". (For details see Basic Item Configuration)

• Export the asset bundle with the menu item "Assets > Build AssetBundles"
  The asset bundle will be created as new file in the folder "AssetBundles" in your Unity project. The file will automatically receive the extension ".unity3d". Do not remove this extension - it is required by the Auto-Mapper.
  (The folder "AssetBundles" will be next to the "Assets" folder, so you won't see it in the Unity Editor. Use a file explorer instead.)

Installing your Mod

Make sure you have the latest version of ModComponent and AssetLoader installed.

• Create the folder "TheLongDark/mods/auto-mapped"
• Copy your asset bundle into this folder.
  You can create additional subfolders inside "auto-mapped", this will keep it nice and tidy.

Optional:

• Create a gear spawn configuration for your item(s).
  If you do not provide a spawn configuration, the only way to obtain your item(s) will be console commands and crafting.
• Create a blueprint configuration for your item(s).
  If you do not provide a blueprint configuration, the only way to obtain your item(s) will be console commands and finding it somewhere in the game.
• Copy additional resources into the "auto-mapped" folder, e.g. sound banks, DLLs.
  This is only required if your mod needs those additional resources.

Testing and Fine-Tuning

If you completed all of the steps above, you are ready to test your mod.
Start The Long Dark and either resume a saved game or start a new one.

Using the console, you can add a new item to your inventory with
add [gearname]

The "gearname" for your item(s) is either the "Console Name" you configured in the Unity Editor, or the name of the prefab without the leading "GEAR_".
So add carkey (the gearname is case-insensitive) would add a new car key to your inventory (assuming such an item exists).
(The console provides auto-complete for all known gearnames.)

Look into your inventory and you should see the item.
It should have an icon, a name, description and properties (weight, etc.) according to your configuration.
This tests your basic configuration, icons and localization

Drop the item and see if the reticle will react to it and show its name.
This tests your collider

Move the item around and compare it with other existing items. See if its size, color and texture is good and matches what you wanted to have. Pick it up and rotate it in the inspect view.
This tests the size and look of your model

The item should be back in your inventory now. See if it still has the correct icon and properties.
This tests if the item works properly when being found and picked up

If you created an item with a primary function, e.g. food, test if you can use the item and see if it behaves correctly. Depending on what type of item you created, this can be more complex and require multiple steps. E.g. for clothing you might want to try and combine it with different other items to see how they overlap on the paper doll.

If you find anything that you want to change:

• quit The Long Dark
• go back to the Unity Editor and adjust the prefab (only the prefab is exported, not the GameObject in the scene)
  or the inventory icon in "InventoryGridIcons"
  or the texts in "Localization.csv"
• export the asset bundle
• copy the new asset bundle to "TheLongDark/mods/auto-mapped"
• start testing again
• repeat until you're satisfied with the result.