116 lines
6.6 KiB
Markdown
116 lines
6.6 KiB
Markdown
# 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](modding-api.md), 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](weapon-balance.md).
|
||
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:
|
||
|
||
```sh
|
||
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.
|