feat(metal-farp): DCS injection recipe (#20)

[FullGas1]

Summary

• inject_scene.lua: reads uh1-1 position + heading, spawns Metal FARP 100 m ahead via playSceneAtPos
• cleanup.lua: destroys all objects in all coalitions/categories except the "uh1" group; generic for any plugin
• RECIPE.md: full dev/test loop documented (setup, play, cleanup, fix, replay) with visual timing checkpoints and three injection method options (MCP, TUI, REST API)

Closes #20

Test plan

• CI passes (lua-lint, luacheck on inject_scene.lua and cleanup.lua)
• inject_scene.lua runs in DCS without error when uh1-1 slot is taken
• cleanup.lua destroys all spawned objects and leaves uh1-1 intact
• Full dev loop can be repeated without mission reload

Generated with Claude Code

Summary by Sourcery

Add DCS injection utilities and a documented visual test workflow for the Metal FARP construction scene.

New Features:

• Introduce an inject_scene script to play the Metal FARP construction scene relative to the UH-1 reference unit.
• Add a generic cleanup script that clears all spawned scene objects while preserving the reference helicopter group.
• Provide a detailed Metal FARP visual test recipe documenting the dev/test loop and injection options for dcs-bridge.

Documentation:

• Document the Metal FARP DCS visual test recipe, including prerequisites, injection methods, dev/test loop, and visual checkpoints.

[sourcery-ai]

Reviewer's Guide

Adds a DCS injection test harness for the Metal FARP scene: a scripted scene injector that spawns the construction sequence relative to a reference helicopter, a generic cleanup script that wipes all spawned objects except the reference group, and a documented dev/test loop explaining how to inject and iterate via dcs-bridge.

File-Level Changes

Change	Details	Files
Introduce a documented visual test recipe for iterating on the Metal FARP construction scene without mission reloads.	Create RECIPE.md describing prerequisites, repo layout, and mission setup for testing the Metal FARP plugin. Document three dcs-bridge injection methods (MCP via Claude, TUI client, direct REST API). Define a repeatable dev/test loop: initial CTLD + scene registration, scene play, cleanup/fix/replay cycle. Add timing-based visual checkpoints and notes for tuning scene positions and understanding warehouse behavior.	plugins/metal-farp/tests/RECIPE.md
Add a generic cleanup script that destroys all spawned scene objects while preserving the reference helicopter group.	Define a KEEP_GROUP constant for the reference group name and track a destroyed counter. Implement destroyGroups helper to iterate coalition groups by category and destroy all except the KEEP_GROUP. Sweep all coalitions and major group categories (ground, helicopter, airplane, ship) plus static objects, destroying each and incrementing the counter. Log a summary via env.info and display an on-screen message with the total destroyed count and confirmation that cleanup is complete.	plugins/metal-farp/tests/cleanup.lua
Add an injection script that plays the Metal FARP scene at a position computed 100 meters ahead of a specific helicopter unit in the mission.	Lookup the reference unit by name and bail out with env.error if it is not found, hinting at mission/slot prerequisites. Read the unit world position and heading and compute a spawn position 100 meters directly ahead using trigonometric projection. Derive coalition and country from the reference unit for the scene spawn context. Log an informational message including heading in degrees and invoke CTLDSceneManager.playSceneAtPos to play the Metal FARP scene at the computed position.	plugins/metal-farp/tests/inject_scene.lua

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#20	Implement inject_scene.lua that reads the position and heading of unit 'uh1-1' from the running mission and plays the 'Metal FARP' scene 100 m ahead via CTLDSceneManager.getInstance():playSceneAtPos, using CTLD loaded from the ../CTLD neighbour repo.	✅
#20	Implement cleanup.lua that destroys all objects currently present in the mission except the 'uh1' group / 'uh1-1' unit, sweeping all coalitions and all object categories via the DCS scripting API, so the dev/test loop can be repeated without reloading the mission.	✅
#20	Create RECIPE.md documenting the full dev/test iteration loop (inject, observe, cleanup, fix, replay) including visual timing checkpoints, usage of dcs-bridge, and the ../CTLD neighbour-repo convention with guidance or error handling when the CTLD path does not resolve.	❌	RECIPE.md clearly documents the dev/test loop, visual checkpoints, dcs-bridge usage, and the ../CTLD neighbour-repo convention (repos side-by-side, paths relative to CTLD_plugins). However, neither RECIPE.md nor the Lua scripts implement or describe a specific error message shown when the ../CTLD path fails to resolve; the only explicit error handling present is for a missing 'uh1-1' unit.

Possibly linked issues

• feat(metal-farp): DCS injection recipe (inject + cleanup + RECIPE.md) #20: PR implements the Metal FARP inject/cleanup Lua scripts and RECIPE.md documentation matching the issue’s requested recipe.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The cleanup script blindly destroys all groups and statics except the uh1 group, which could inadvertently remove non-scene entities; consider scoping cleanup to scene-tagged objects or a dedicated coalition/category to avoid collateral deletion.
• There is a mismatch between the reference helicopter names (uh1-1 in inject_scene.lua and uh1 in cleanup.lua); aligning these or clearly separating slot vs. group naming in code would reduce confusion and prevent accidental destruction of the reference unit.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The cleanup script blindly destroys all groups and statics except the `uh1` group, which could inadvertently remove non-scene entities; consider scoping cleanup to scene-tagged objects or a dedicated coalition/category to avoid collateral deletion.
- There is a mismatch between the reference helicopter names (`uh1-1` in inject_scene.lua and `uh1` in cleanup.lua); aligning these or clearly separating slot vs. group naming in code would reduce confusion and prevent accidental destruction of the reference unit.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}