KATA 5 OF 8 · ASSET LAYER

Custom Assets: Icons, Models & Bundles

Everything so far reused vanilla art and worked server-side. This kata crosses a line: you bring your own art. The reward is a mod that looks like yours; the cost is that every player now has to install it - assets do not push from a server to clients. Knowing exactly where that line is matters more than the art itself.

What you'll build

A real custom icon for the resourceReinforcedPlank item from Kata 3 (fully doable today), plus an honest map of the AssetBundle workflow for custom models and sounds, which needs Unity.

The Resources folder

Custom art lives in a Resources/ folder at the root of your mod (a sibling of Config/ and ModInfo.xml). Two things go here: loose icon PNGs in an atlas folder, and Unity AssetBundles for everything heavier.

Step 1 - A custom item icon (the doable part)

Item icons must be exact, or the game rejects them:

• Format: PNG, ARGB32 (8 bits each for alpha, red, green, blue).
• Size: 116 x 80 pixels.
• Location (A18 and later): Resources/UIAtlases/ItemIconAtlas/<iconName>.png. (The old A17 /ItemIcons/ path is wrong on modern builds - use the atlas path.)

Name the file after the icon you want, then point your item at it. Revisit Kata 3's item and change the icon line from the reused vanilla icon to your own:

<!-- in Config/items.xml -->
<property name="CustomIcon" value="reinforcedPlank" />   <!-- matches reinforcedPlank.png, no extension -->
<!-- and drop CustomIconTint, since your PNG already has the colours you want -->

So your mod folder becomes:

ReinforcedPlank/
  ModInfo.xml
  Config/
    items.xml  recipes.xml  Localization.txt
  Resources/
    UIAtlases/
      ItemIconAtlas/
        reinforcedPlank.png   (116x80, ARGB32)

On load, the game folds your PNG into the in-memory item-icon atlas, and CustomIcon="reinforcedPlank" resolves to it.

Step 2 - Models & sounds via AssetBundles (the Unity part)

Anything beyond a 2D icon - a custom block mesh, a weapon model, a sound - ships as a Unity AssetBundle (a .unity3d file) placed in Resources/. The honest summary of the workflow, because this is a genuinely bigger task than XML:

• You need the Unity editor at the version that matches the game's build, plus the community asset-build setup (the SDX/DMT toolchain and the game's Unity asset references).
• You import your model/texture/sound into Unity, mark the assets, and build an AssetBundle.
• You place the resulting .unity3d in your mod's Resources/, then reference a prefab inside it from a block or item's mesh property, using the modfolder syntax (roughly #@modfolder(YourModName):Resources/yourBundle.unity3d?YourPrefab).

This is a real specialty - do not expect to learn Unity in one kata. The takeaway here is where bundles live and how the XML points at them; building the bundle itself is a Unity skill you layer on top.

The line you just crossed

This is the single most important thing in this kata: icons and AssetBundles do not get pushed from a server to clients. A server-side XML mod (Kata 4) just works for anyone who joins. An asset mod requires every player to install the same files locally, or they see missing icons and pink ("missing texture") models. So:

• EAC: pure assets do not require EAC off (only code does, Kata 7) - but they do require client installs.
• Distribution: the moment your mod has a Resources/ folder with content, it is a "client mod." Share the exact same ZIP with every player, and they install it in their own Mods/ folder.

Test it

1. Drop a correctly-sized PNG in the atlas folder, set CustomIcon to its name, restart.
2. In-game crafting/inventory, the item should now show your icon. If it is blank or wrong, it is almost always the size/format or a name mismatch.

Common pitfalls

• Wrong icon size/format. Not 116x80 ARGB32 PNG and the icon will not appear. This is the number-one icon bug.
• Wrong folder. It is Resources/UIAtlases/ItemIconAtlas/ on A18+; the older /ItemIcons/ path silently does nothing.
• Bundle built against the wrong Unity/game version. AssetBundles are version-sensitive; one built for an older build often fails to load after a game update - a big reason asset mods lag a version jump.
• Players see pink models / blank icons. They did not install the mod (or installed a different version). Asset mods are all-or-nothing across the group.