feat(metal-farp): animated construction scene + dev/test recipe

[FullGas1]

Summary

• Progressive animated construction sequence for Metal FARP (Tower Crane + UC helipad, ~40s total)
• DCS injection recipe for visual testing (inject_scene.lua, cleanup.lua, RECIPE.md)
• Plugin dev/test process guide (docs/plugin-dev-guide.md)
• Download buttons (same-origin), mod links, versioned mike docs
• Closes feat(metal-farp): progressive animated construction scene #18, Fix download buttons: same-origin .lua serving and external link tab behaviour #11, feat: catalogue download buttons, mod links, generated docs, versioned site #4

Test plan

• CI green on all jobs (busted, luacheck, validate-docs, build)
• Visual scene validated in DCS: crane t+0.5s, UC t+5.5s, helipad t+25.5s, crane gone t+30.5s
• Download buttons tested in browser
• Versioned docs accessible on GitHub Pages

Generated with Claude Code

Summary by Sourcery

Add an animated, timed construction sequence to the Metal FARP scene and document a full plugin development and DCS visual test workflow.

New Features:

• Introduce a progressive Metal FARP construction animation using tower crane and under-construction helipad variants with timed deployment steps.
• Provide DCS injection scripts (inject_scene.lua and cleanup.lua) and a visual test recipe for iterating on scenes without mission reloads.
• Add an English and French plugin development and test guide, including unit testing, DCS visual testing, and CI expectations.

Enhancements:

• Extend Metal FARP scene metadata to include the under-construction helipad mod type while keeping tower crane as a stock asset.
• Update template plugin tests to reference the new plugin development guide in the docs navigation.

Documentation:

• Add bilingual plugin development and test guides and link them into the MkDocs navigation, documenting repo layout, test loop, and CI gates.
• Document the Metal FARP visual test procedure and timing checkpoints for validating the construction animation in DCS.

Tests:

• Add smoke tests for the Metal FARP scene model covering registration, crate declaration, modTypes contents, step count, and critical flags.
• Introduce a generic cleanup script for destroying scene-spawned objects while preserving the reference helicopter group for repeated visual testing.

[sourcery-ai]

Reviewer's Guide

Implements a timed, animated Metal FARP construction sequence, adds DCS visual test scripts and recipe, introduces unit tests for the scene model, and documents the plugin development/testing process in both English and French with MkDocs navigation updates.

Sequence diagram for the animated Metal FARP construction scene

sequenceDiagram
    actor Pilot
    participant CTLDSceneManager
    participant metalFarpScene
    participant TowerCrane
    participant UnderConstructionPad as FG_small_Helipad_Under_Construction
    participant FinalPad as FG_small_Helipad

    Pilot->>CTLDSceneManager: playSceneAtPos(metalFarpScene)
    CTLDSceneManager->>metalFarpScene: steps[1..3] spawn support equipment

    CTLDSceneManager->>metalFarpScene: step 4 (Tower Crane)
    metalFarpScene->>CTLDSceneManager: func(ctx) saves _craneObj
    CTLDSceneManager->>TowerCrane: spawn static object

    CTLDSceneManager->>metalFarpScene: step 5 (FG_small_Helipad_Under_Construction)
    metalFarpScene->>CTLDSceneManager: func(ctx) saves _underConstObj
    CTLDSceneManager->>UnderConstructionPad: spawn fortification

    CTLDSceneManager->>metalFarpScene: step 6 destroy UC pad
    metalFarpScene->>UnderConstructionPad: Object.isExist(obj)
    metalFarpScene->>UnderConstructionPad: destroy()

    CTLDSceneManager->>metalFarpScene: step 7 (final FG_small_Helipad)
    CTLDSceneManager->>FinalPad: spawn heliport (critical=true)
    metalFarpScene->>metalFarpScene: func(ctx) sets farpName

    CTLDSceneManager->>metalFarpScene: step 8 destroy Tower Crane
    metalFarpScene->>TowerCrane: Object.isExist(obj)
    metalFarpScene->>TowerCrane: destroy()

    CTLDSceneManager->>metalFarpScene: steps[9..13] spawn remaining objects

Loading

File-Level Changes

Change	Details	Files
Add a progressive, timed construction animation for the Metal FARP scene including under-construction helipad and tower crane lifecycle.	Extend scene object registry with visual-only under-construction helipad and Tower Crane entries, including proper categories and probeSkip handling. Update metalFarpScene.modTypes to include the under-construction helipad variant while keeping Tower Crane as a stock type. Restructure metalFarpScene.steps into a 13-step sequence that spawns trucks, tent, construction props, transitions from under-construction pad to final helipad, and destroys temporary objects at specific timings. Ensure critical=true on the finished helipad step and persist references to spawned objects in scene._params for later destruction.	plugins/metal-farp/src/CTLD_metalFarpScene.lua
Introduce automated tests and DCS injection/cleanup scripts for the Metal FARP scene, plus a visual test recipe.	Add a Busted spec that loads the Metal FARP scene, verifies registration, crate declaration, requiresCtld version, modTypes contents, step count, and critical flag semantics. Provide inject_scene.lua that spawns the Metal FARP scene 100m ahead of reference unit uh1-1 using a mock unit aligned to the helicopter’s heading. Provide cleanup.lua that generically destroys all groups, static objects, and non-airdrome airbases while preserving the uh1 group, with logging and on-screen feedback. Document the Metal FARP DCS visual test loop, prerequisites, injection order, and expected animation timing checkpoints in RECIPE.md.	plugins/metal-farp/tests/metal_farp_spec.lua plugins/metal-farp/tests/inject_scene.lua plugins/metal-farp/tests/cleanup.lua plugins/metal-farp/tests/RECIPE.md
Document the plugin development and test workflow and expose it in MkDocs navigation.	Add English and French plugin development guides describing directory layout, template usage, modUrls front-matter, scene authoring rules, unit test expectations, DCS visual testing flow, injection methods, cleanup contract, and CI gates. Reference the plugin dev guide from the template plugin’s test spec header comments to direct authors to the full documentation. Update MkDocs navigation to include the new plugin dev guide under the authors section.	docs/plugin-dev-guide.md docs/plugin-dev-guide.fr.md plugins/_template/tests/template_spec.lua mkdocs.yml

Possibly linked issues

• feat(metal-farp): progressive animated construction scene #18: PR delivers the requested progressive Metal FARP build sequence, registry changes, modTypes update, and unit tests for behavior.
• feat(metal-farp): progressive animated construction scene #18: PR adds crane/under-construction helipad animation, CTLD-based inject_scene.lua, cleanup, and RECIPE.md matching the issue’s request.
• feat(metal-farp): DCS injection recipe (inject + cleanup + RECIPE.md) #20: The PR delivers the Metal FARP DCS injection recipe (inject_scene.lua, cleanup.lua, RECIPE.md) matching the issue requirements.

---

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 found 1 issue, and left some high level feedback:

• The documented timing in CTLD_metalFarpScene.lua and plugins/metal-farp/tests/RECIPE.md (e.g., UC pad at 10.5s, crane/ ammo at 35.5s, lights at 40s) does not match the actual delayAfterPreviousStep values in the scene steps; please reconcile the comments and recipe table with the cumulative timings from the code.
• plugins/metal-farp/tests/cleanup.lua currently destroys all static objects and non-airdrome airbases across all coalitions, which could wipe unrelated mission content; consider narrowing the cleanup to objects spawned by this scene (e.g., by namePrefix or a scene-specific tag) to make it safer to reuse.
• The "has exactly 13 steps" assertion in plugins/metal-farp/tests/metal_farp_spec.lua is quite brittle and will fail on any future step adjustment; you might prefer asserting the presence and properties of key steps (e.g., helipad spawn, UC variant, crane destroy) rather than the total count.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The documented timing in CTLD_metalFarpScene.lua and plugins/metal-farp/tests/RECIPE.md (e.g., UC pad at 10.5s, crane/ ammo at 35.5s, lights at 40s) does not match the actual delayAfterPreviousStep values in the scene steps; please reconcile the comments and recipe table with the cumulative timings from the code.
- plugins/metal-farp/tests/cleanup.lua currently destroys all static objects and non-airdrome airbases across all coalitions, which could wipe unrelated mission content; consider narrowing the cleanup to objects spawned by this scene (e.g., by namePrefix or a scene-specific tag) to make it safer to reuse.
- The "has exactly 13 steps" assertion in plugins/metal-farp/tests/metal_farp_spec.lua is quite brittle and will fail on any future step adjustment; you might prefer asserting the presence and properties of key steps (e.g., helipad spawn, UC variant, crane destroy) rather than the total count.

## Individual Comments

### Comment 1
<location path="docs/plugin-dev-guide.md" line_range="136" />
<code_context>
+**On a problem (Step 3):**
+
+1. Inject `plugins/{name}/tests/cleanup.lua`.
+2. Fix the plugin lua.
+3. Repeat from Step 1.
+
</code_context>
<issue_to_address>
**nitpick (typo):** Use "Lua" (capital L) for consistency with the rest of the document.

This instance should be capitalized to "Lua" to match usage elsewhere in the guide.

Suggested implementation:

```
2. Fix the plugin Lua.

```

If "Lua" appears elsewhere in lowercase (e.g. "lua script", "lua file") in this guide, those should be updated to "Lua" as well for consistency, following the same SEARCH/REPLACE pattern.
</issue_to_address>

---

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.}

[sourcery-ai]

nitpick (typo): Use "Lua" (capital L) for consistency with the rest of the document.

This instance should be capitalized to "Lua" to match usage elsewhere in the guide.

Suggested implementation:

2. Fix the plugin Lua.

If "Lua" appears elsewhere in lowercase (e.g. "lua script", "lua file") in this guide, those should be updated to "Lua" as well for consistency, following the same SEARCH/REPLACE pattern.