Add scripted lightning weapon mods with interpolated anchored effects

docs/mod-authoring-checklist.md

@@ -0,0 +1,114 @@
+# 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
+  original game pixels, the extracted catalog or local reference captures.
+
+## 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.