io_bugsnax

A Blender addon for importing and exporting the cache formats used by Bugsnax and the Horsepower Engine — the static mesh caches (.objcache / .daecache) that ship alongside the engine's skinned characters, and the skinned-character cache (.xcache) itself.

All three share the SEMS binary magic. The static caches hold a single static mesh with up to three texture references (diffuse, normal, specular); the .xcache format additionally carries a skeleton, skin weights, and animation.

Installation

1. Go to Edit → Preferences → Add-ons → Install…
2. Select the io_bugsnax folder (zip it first if Blender asks for a zip).
3. Tick "Bugsnax Cache (.objcache, .daecache, .xcache)" in the add-on list.

You'll get six new menu entries:

• File → Import → Bugsnax Cache (.objcache)
• File → Import → Bugsnax Cache (.daecache)
• File → Import → Bugsnax Cache (.xcache)
• File → Export → Bugsnax Cache (.objcache)
• File → Export → Bugsnax Cache (.daecache)
• File → Export → Bugsnax Cache (.xcache)

Static caches (.objcache / .daecache)

Importing

The importer creates one mesh object with a Principled-BSDF material. Texture slots are wired up automatically: diffuse to Base Color, normal to Normal (via a Normal Map node), specular to Specular IOR Level. Cache files are Y-up; the importer rotates them to Blender's Z-up convention so they sit upright in the viewport.

When Use Diffuse Alpha is on, a diffuse texture that actually carries sub-1.0 alpha (leaf/foliage cutouts, fences, etc.) is wired through to the material's Alpha and the material is set to Alpha Clip with a 0.5 threshold — so only the genuinely transparent pixels are discarded and the rest of the surface stays solid. Fully opaque textures are detected and left untouched, so ordinary props don't go see-through.

Where the importer looks for textures

Cache files store asset-relative paths like Content/Models/Environment/Forest/Plants/PalmTree_D.dds. The importer searches:

• The cache file's directory
• Common subfolders: Textures/, tex/, textures/, Content/
• Up to three parent directories
• These extensions: .png .jpg .jpeg .tga .dds .bmp .tif .tiff .webp

Exporting

Texture paths are read from the active material's Principled-BSDF inputs (the inverse of what the importer does). Asset-relative Content/... paths are preserved verbatim; anything else falls back to the file's basename.

Static-mesh conformity

Both static cache formats are single static mesh binaries. The exporter silently strips anything else, sampled at the current frame:

• Armature modifiers are baked into the vertex positions via the depsgraph (current pose is what gets written)
• Vertex groups / skin weights are dropped (no skin slot in the format)
• Shape keys are evaluated at their current values before write
• Animation actions are ignored (single-frame format)

When any of these is present, the export report (Blender's status bar) notes what was stripped. .objcache mirrors the OBJ format's limitations; .daecache is the DAE binary cache — DAE the source format supports skeletons, but the compiled cache does not.

If you need to keep the skeleton, animation, and skin weights, use .xcache instead.

Skinned cache (.xcache)

The .xcache importer builds a full rig: a mesh (optionally split into its internal sub-meshes), an armature, vertex-group skin weights, and an animation action. You can select and import several .xcache files at once.

Importing

Rest Pose Source — Bind Pose (the default) reads the SkinWeights matrixOffset inverse-bind matrices, which is the correct interpretation for Bugsnax .xcache files. Frame Hierarchy instead walks the FrameTransformMatrix chain; use it only if a file imports with a broken rest pose under the default.

Texture search — the xcache importer extends the static-cache search with a cross-Content/ lookup: it walks up to find a Content ancestor directory and does a shallow scan of the subtrees beneath it, so a character in Content/Characters/Banana/ can still resolve a texture that actually lives under Content/Models/Bugs/Banana/.

Exporting

Round-trip behaviour

For the static caches, import → export produces a structurally identical file. Vertex counts, face counts, texture references, AABB, and the daecache extent all round-trip exactly. Byte-level equality isn't guaranteed (small metadata bytes are regenerated rather than carried verbatim) but the engine reads the result identically.

The daecache extras (UV2, UV3) are exposed in Blender as additional UV layers — keep those layer names intact if you want them preserved on export.

For .xcache, the importer/exporter were validated against a large dev corpus of Bugsnax character files; the mesh, skeleton, skin weights, and animation round-trip through Blender's armature/pose system.

File layout

io_bugsnax/
├── __init__.py           Blender operators and menu registration (all 3 formats)
├── parser.py             binary read/write — CacheMesh (.objcache / .daecache) + XNode (.xcache)
├── importer.py           .objcache / .daecache / .xcache → Blender object
└── exporter.py           Blender object → .objcache / .daecache / .xcache → file