Conventions & best practices

Follow these and rsmm lint stays green and your mod survives game updates. They mirror the “best practices” pages every mature Minecraft loader ships.

Mod structure

mods/<id>/
  manifest.toml        # the only required file
  assets/
    <decoded path>/...  # overrides, e.g. Ui/.../Portrait.png.Texture.dxt
  lang/<locale>.toml    # optional i18n
  tags.json             # generated by Mod.tag(...)

• One id, one directory. id in manifest.toml must match the folder name and be unique across the user’s mods.
• Forward slashes in decoded paths. Always, regardless of OS.
• No stray .py. The deliverable is data. See Mods ship data, not code.

Naming

• Mod id — stable, namespaced-feeling, no spaces (RubyBlades, not Ruby Blades). Renaming it orphans a user’s applied state.
• Content ids — unique within the mod per kind. Prefer descriptive names over vanilla collisions (RubyDagger, not Knife).
• Tags — lower-kebab, topic-first (daggers, fire-immune).

The confidence gate

Every content kind is confirmed, experimental, or guess (details).

Caution

Non-confirmed kinds require sdk.Mod(..., experimental=True). Don’t ship an experimental/guess mod to other users without testing it in-game — the emitted bytes are not verified and may not appear or may crash.

Surviving game updates

• Address engine functions by name (R.call("Name")), never by raw address — the symbol map re-resolves by byte pattern.
• Declare target_game_build in your manifest so RSMM can warn on drift.
• Prefer [[patch]] over whole-file overrides where possible: patches merge and are far more update-resilient than replacing a whole cooked file.

Distribution

• Ship a repo.json with SHA256 (and optional Ed25519 signature) so users can verify downloads — see the repo SDK reference.
• No central host is required; the spec is open.

Pre-flight checklist

• rsmm lint passes (no stray scripts, confidence gate satisfied).
• rsmm apply then launch the game — content actually appears.
• rsmm restore --all returns to vanilla cleanly.
• manifest.toml has id, name, version, author, description.