RustRaptor/docs/mod-authoring-checklist.md

AI agent checklist for building a new mod

Use this checklist for new weapon, equipment, enemy, mission, campaign and music packages. The user's current request takes precedence. Treat the checked-in mod API, content types and shipped examples as the contract; do not invent unsupported fields or callbacks.

1. Define the behavior

• Record the requested content, controls, target types and intended role.
• For equipment, decide whether it is always equipped and fires with Fire, a selected special, a consumable, or a passive item. Always equipped does not imply firing without input. State the controls clearly in the shop description.
• Specify range, cooldown, damage, target limits and interactions with other equipment. Account for the 320×200 logical canvas and 70/3 simulation ticks per second; HD artwork must not change gameplay geometry.
• Check existing API support. Use callbacks and checked commands for mod behavior. If something is missing, describe a minimal reusable API extension and coordinate its implementation with the engine agent when authorized.

2. Build an independent package

• Create mods/<id>/mod.toml, content.json, scripts/, art/ and any audio/ or music/ directories needed by the content.
• Use a unique lowercase package ID, version, api_version = 1, clear name and description. Declare all script files in manifest.scripts.
• Namespace new definitions with the package ID. Keep inventory item and weapon IDs distinct; keep IDs stable so saved inventory survives updates.
• Declare only real dependencies. Verify standalone packages can be enabled alone. Make complete, explicit overrides only when intentionally required.
• Omit legacy on new content. Use relative paths without traversal or symlinks, and stay inside the documented package and content limits.
• Keep equipment capacities and consumable flags consistent with its role. Define pickup and shop behavior consistently; reusable gear must remain owned.

3. Implement scripts safely

• Use only documented event snapshots, callbacks and commands. Filter dead, invisible or wrong-type targets and enforce the intended range and target cap.
• Use deterministic target selection and tie breaks. Avoid duplicate hits, accidental repeated chaining, screen-wide damage and unnecessary commands.
• Keep callback work and state bounded. Use the supplied deterministic RNG for gameplay randomness; do not depend on render rate, wall time or OS state.
• Handle initially empty state and older saved state. Verify scripts compile, callbacks have three arguments and command failures roll back cleanly.
• Choose visual commands appropriate to the effect. Do not use explosion effects for ordinary muzzle flashes or electrical arcs.

4. Ship SD, HD and audio assets

• Supply a real SD png and HD hd_png for every authored artwork reference. Use the same logical dimensions, aspect ratio, frame count and alignment.
• Preserve actual alpha transparency and padding. Keep sprites legible at their small SD size, with clear silhouettes and stable frame positions.
• Inspect both modes after palette conversion in the game renderer. Check animation strips, shop icons, firing/hit feedback and moving scenes as needed.
• Ship valid local WAV or DMX effects and MUS scores where applicable. Keep volumes and repetition comfortable and avoid playing hit sounds on misses.
• Track final assets, required source masters, prompts, provenance and reproducible preparation/synthesis recipes with the package. Never commit decoded style-reference images or local review captures into a mod. The approved original/HD runtime catalog is tracked separately in data/.

5. Price and balance equipment

• Compare original and shipped gear in weapon balance. Account for aiming difficulty, effective range, air/ground coverage, splash or chain caps, recharge, consumption and damage per second.
• Measure damage through World::step with the real scripts over a fixed duration. Use surviving stationary fixtures to avoid overkill skewing results.
• Include aligned, off-axis, ground and cluster cases where relevant. Add a close-range scene for proximity gear, and test a combined loadout for always-equipped weapons. Keep pilot health and fixture movement controlled.
• Choose a progression tier and justify the final price. Check purchase, capacity, duplicate rejection and resale; purchases must not create money.
• Distinguish controlled measurements from campaign balance. Document relevant tradeoffs and unresolved playtesting questions without claiming that every loadout or mission is equally difficult.

6. Verify and document

• Add meaningful portable tests with synthetic images/audio when practical. Test actual damage, target exclusions, range boundaries, cooldown, finite target caps, inventory preservation and coexistence with shipped packages.
• Check deterministic continuation of script state/RNG. Exercise kills and empty-target situations, not only the happy path with surviving targets.
• Run the package validation CLI against the original local catalog: cargo run --no-default-features -- --mods mods --validate-mods <id>. Also validate relevant combined packages. Do not alter the user's active mods.
• Run focused tests, then required regression checks. Regenerate schemas if an API type changed, and build the desktop engine if rendering or controls changed.
• Add a package README with enabling instructions, price, controls, target behavior, limits, validation commands and a link to artwork provenance.
• Update repository documentation and balance observations where relevant. Inspect the final diff and preserve unrelated work.
• Report what was delivered, how to enable/use it, final prices and validation results. State any material limitation or unperformed check accurately.

Local commands

From RustRaptor/, replace IDs and test names for the package being authored:

cargo test --locked --no-default-features --test weapons_mods
cargo run --locked --no-default-features -- --mods mods \
  --validate-mods lightning_cannon,lightning_shield
RAPTOR_BALANCE_REPORT="$PWD/.reference/weapon-balance.json" \
  cargo test --locked --no-default-features --test weapon_balance \
  -- --ignored --nocapture
cargo fmt --all -- --check

Use the appropriate test for enemies, missions or music. An unavailable original catalog is a reason to report the local validation limit, not to bypass portable tests or deliver broken package references.