Modding
Tyrian modding: limits and troubleshooting
The game treats a mod as untrusted data. A file over a limit produces an error or a warning, never a crash.
Limits
| What | Limit |
|---|---|
| Mods loaded | 32 |
mod.json | 1 MiB, nesting depth 48, strings of 16 KiB, 200,000 values |
| PNG files | 4 MiB, 2048 px per side, 1024 per folder |
| Level files | 64 per mod, 2500 events and 40 random enemies each |
| README.md | 1 KiB |
| Items added by all mods together | 20 weapons, 14 ships, 13 sidekicks, 9 shields, 16 specials, 100 new enemies, 1200 projectile slots |
| Items per shop category | 10 shown, level items included |
Common problems
| Symptom | Check |
|---|---|
| The mod is ERR in Setup → Mods | Read the reason on its line, then run tyrian-mods check for every message. |
| Error about the format version | mod.json needs "format_version": 1; the game reads only this format. |
| “unknown key” | A typo, or a field that is not part of the format: check it against mod.json and items. |
| A weapon makes a sound but nothing is drawn | The first projectile's sprite is missing or unknown. |
| An item is not in the shop | Add "always_available": true; remember the 10 items per category. |
| A new enemy never appears | Cite it by its name in levels/*.json; tyrian-mods run --level epN_NN counts its appearances. |
| A ship is invisible | ship_sprite must name a 24×28 PNG of sprites/ships/ or an original ship sprite. |