Tyrian modding: mod.json and items

mod.json is JSON with comments (// and /* */) and trailing commas allowed. Every unknown key is an error, at every level, so a typo is always reported.

Top level

{
  "$schema": "https://raw.githubusercontent.com/Patm4nzzz/opentyrian-enhanced/rewrite/godot-rust/rewrite/mods/mod.schema.json",
  "format_version": 1,        // required: the only version that exists
  "name": "My Mod",           // required
  "author": "Me", "version": "1.0", "description": "…",
  "enabled": false,           // initial state; Setup → Mods overrides it
  "tint": "green",            // hue applied to every PNG of the mod
  "weapons": [ … ], "ships": [ … ], "sidekicks": [ … ],
  "shields": [ … ], "specials": [ … ],
  "enemy_weapons": [ … ], "enemies": [ … ],
  "starter": { … }
}

Key	Type	Meaning
`$schema`	string	Optional path or URL of the schema, for editors. Ignored by the game.
`format_version`	`1`	Required. Any other value, or none, is an error.
`name`	string	Required. Display name.
`author`, `version`, `description`	string	Shown in Setup → Mods.
`enabled`	bool	Initial state (default `true`).
`tint`	string or number	Recolors the mod's PNG files (Tint).
`weapons`, `ships`, `sidekicks`, `shields`, `specials`	arrays	Player items, below.
`enemy_weapons`, `enemies`	arrays	Enemies and behaviors.
`starter`	object	Starting loadout.

Fields shared by every item

Field	Meaning
`name`	Required and unique in the mod. It is the item's identity in saves and in `starter`.
`base`	Name of an original item to copy. Case, spaces, dashes and underscores are ignored. Every field you set overrides the copy.
`cost`	Shop price.
`icon_sprite`	Name of the shop icon: a PNG of the mod or an original sprite.
`always_available`	Sold in every shop.

All mods together can add at most 20 weapons, 14 ships, 13 sidekicks, 9 shields and 16 specials. The names of the original items are the ones in the shop, listed on the equipment pages.

Weapons

Field	Default without `base`	Meaning
`power_use`	20	Energy used per volley.
`cost`	1000	Price at power 1.
`tint`	—	Hue of this weapon's sprites only.
`front[]`, `rear[]`	—	Power levels, 11 at most each.

A weapon with only front[] or only rear[] has one firing mode; with both, the player switches with the change-fire key. With always_available, a weapon with front[] is sold as a front gun, one with rear[] as a rear gun, and one with both (or neither) in both shops.

Power levels

Each entry of front[] or rear[] is one power level. Enemy weapons use the same fields plus a name.

Field	Meaning
`fire_delay`	Frames between two volleys.
`projectile_count`	Projectiles per volley.
`max_on_screen`	Length of the cycle through `projectiles[]`.
`animation`	Animation speed; 0 means no frame cycling.
`offset_x`, `offset_y`	Spawn offset.
`homing`	`true` or a number; above 5 the shot is guided towards the nearest enemy.
`accel_x`, `accel_y`	Acceleration per frame.
`circle_radius`	Orbit radius.
`sound`	Sound effect index.
`trail`	Trail effect; 255 means none (the default).
`ship_blast_filter`	Damage type mask.
`projectiles[]`	Up to 8 projectiles, below.

Projectiles and damage

Field	Default	Meaning
`damage`	0	Damage code, below.
`sub_delay`	255	Lifetime in frames; 255 means until it leaves the screen. Never 0 (the shot would never be drawn).
`speed_x`, `speed_y`	0	Velocity. For a player weapon a positive `speed_y` goes up; for an enemy weapon it goes down.
`spawn_x`, `spawn_y`	0	Spawn position offset.
`sprite`	—	Name of the projectile sprite.

`damage`	Effect
`0` to `98`	Damage per hit.
`"freeze"`	No damage; freezes the enemy.
`{ "pierce": n }` (n = 0 to 5)	Goes through enemies, `n` damage to each.
`{ "chain": "<original weapon>" }`	Chain reaction: 1 damage, and the hit fires that original enemy weapon.

Any other number (99 and above) is an error: the engine's internal codes are never written by hand.

Ships

Field	Default without `base`	Meaning
`damage_resistance`	20	Armor.
`cost`	5000	Price.
`ship_sprite`	—	Name of a 24×28 ship image; the engine uses it for all banking poses.
`ship_poses`	—	`{ "neutral", "left_full", "left", "right", "right_full" }`, one name each, to draw the poses yourself.

Sidekicks

Field	Default without `base`	Meaning
`trail`	0	Movement: 0 fires with the player, 1 follows, 2 orbits, 3 independent, 4 stationary orbit.
`ammo`	0	Shots before recharge; 0 means unlimited.
`cost`	5000	Price.

Shields

Field	Default without `base`	Meaning
`shield_power`	9	Recharge rate, 0 to 28 (clamped with a warning).
`max_power`	14	Maximum, 0 to 18 (clamped with a warning). The strongest original shield has 14.
`cost`	10000	Price.

Specials

Field	Default without `base`	Meaning
`power`	100	Effect strength.
`subtype`	1	Effect kind.

A special fires the weapon of its base. Shops never sell specials: give one through starter.

Shop slots

always_available items are added to every shop, 16 per category at most. A shop shows at most 10 items per category including the level's own items, so items past the free places are not shown. Keep about eight flagged items per category.

Starting loadout

"starter": { "ship": "Xeno Vanguard", "front_weapon": "Alien Vulcan Cannon",
             "rear_weapon": "…", "shield": "…", "generator": "…",
             "sidekick_left": "…", "sidekick_right": "…" }

Each value is the exact name of an item, original or from any loaded mod. Names are resolved after every mod has loaded; an unknown name is an error.