Document engine-side of Weapon:CanFire

[lL1l1]

Description of the proposed changes

Documents the engine-side details of Weapon:CanFire. This is relevant when working with air units and understanding how the busy state interacts with weapons.

Testing done on the proposed changes

• Reading the decompilation of UnitWeapon::CanFire at .text:006D4C80.
• Testing+logging with a strat bomber, a t1 bomber, and an ASF to understand the minimum air speed rule. Discovered that strat bombers no longer obey the rule because after Strat agility buff #6535 their bomb weapon does not auto initiate attack commands anymore.

Additional Context

This stems from testing with restorer and looking in the default projectile weapon script to see why its AA missiles can't fire, and then seeing that NotExclusive was poorly documented.

Checklist

• Changes are annotated, including comments where useful
• Changes are documented in a changelog snippet according to the guidelines.
• Request 2-3 reviewers from the list of reviewers and their areas of knowledge.

Summary by CodeRabbit

• Documentation
  • Improved inline documentation for weapon systems, including enhanced details on bomb drop computation behavior and weapon firing logic.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds documentation for weapon firing logic across three files. A changelog entry documents engine-side behavior of UnitWeapon:CanFire(), inline documentation for the NeedToComputeBombDrop field is clarified, and an extended comment block detailing CanFire() logic and conditions is added to the implementation.

Changes

Cohort / File(s)	Summary
Weapon Documentation changelog/snippets/other.7045.md, engine/Core/Blueprints/WeaponBlueprint.lua, engine/Sim/UnitWeapon.lua	Added changelog entry and extended documentation for weapon firing logic, including clarification of NeedToComputeBombDrop field behavior and CanFire() method details.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• Fix silos with delay before firing being able to fire twice #7010 — Both PRs document weapon firing logic in UnitWeapon.lua and WeaponBlueprint.lua, covering related CanFire behavior and firing-state details.

Suggested reviewers

• BlackYps
• 4z0t

Poem

🐰 A rabbit's ode to clarity:

When weapons fire, confusion clouds the way,
But docs shine bright to save the review day!
CanFire() dance is now for all to see,
No secrets hiding—just pure clarity! 🎯✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and specifically describes the main change: documenting engine-side behavior of Weapon:CanFire, which is the primary purpose of this PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The pull request description includes all required sections: a clear description of proposed changes, detailed testing methodology, additional context, and a completed checklist with annotations and changelog snippet.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@engine/Core/Blueprints/WeaponBlueprint.lua`:
- Around line 215-217: The comment for the optional field NeedToComputeBombDrop?
is ambiguous and reads like a fragment; update its docstring to explicitly state
that this boolean controls whether the unit is marked as "busy" during the
weapon's charge/reload/fire cycle (true = unit is set busy and cannot perform
other actions; false = weapon activity does not mark the unit busy). Locate the
doc comment above the NeedToComputeBombDrop? field in WeaponBlueprint.lua and
replace the current wording with this clear, self-contained explanation
referencing the charge/reload/fire phases.

In `@engine/Sim/UnitWeapon.lua`:
- Around line 26-40: The pseudo-code in the UnitWeapon:CanFire comment has a
typo and an inconsistent call style; fix "reutrn" to "return" and make method
calls consistent (use colon form for instance methods like unit:IsStunned(),
unit:IsUnitState("Busy"), unit:IsUnitState("Immobile"),
unit:IsUnitState("MakingAttackRun") and keep unit:_GetSpeed() if it’s private;
ensure weapon calls use consistent naming like weapon:_HasTarget() and
weapon:_UnitIsInBombDropZone() and return weapon._AimOnTarget where indicated;
also clarify the Winged check to read "if not unit.Blueprint.Air.Winged then
return weapon._AimOnTarget end" and keep comments about BombDropThreshold and
PredictAheadForBombDrop unchanged.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Clarify the “busy” wording to avoid ambiguity.

The current phrasing reads like a sentence fragment and can be interpreted as contradictory. Consider making it explicit that this field controls whether the unit is set as “busy” during charge/reload/fire.

✏️ Suggested wording tweak

---- If the unit is set as "busy" while the weapon charges/reloads/fires. Set to `true` to allow
---- other weapons to fire/unit actions to occur while this weapon is working.
+--- Controls whether the unit is set as "busy" while the weapon charges/reloads/fires. Set to `true` to allow
+--- other weapons to fire/unit actions to occur while this weapon is working.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	---@field NeedToComputeBombDrop? boolean
	--- if the unit is set as "busy" while the weapon charges
	--- If the unit is set as "busy" while the weapon charges/reloads/fires. Set to `true` to allow
	--- other weapons to fire/unit actions to occur while this weapon is working.
	---@field NeedToComputeBombDrop? boolean
	--- Controls whether the unit is set as "busy" while the weapon charges/reloads/fires. Set to `true` to allow
	--- other weapons to fire/unit actions to occur while this weapon is working.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@engine/Core/Blueprints/WeaponBlueprint.lua` around lines 215 - 217, The
comment for the optional field NeedToComputeBombDrop? is ambiguous and reads
like a fragment; update its docstring to explicitly state that this boolean
controls whether the unit is marked as "busy" during the weapon's
charge/reload/fire cycle (true = unit is set busy and cannot perform other
actions; false = weapon activity does not mark the unit busy). Locate the doc
comment above the NeedToComputeBombDrop? field in WeaponBlueprint.lua and
replace the current wording with this clear, self-contained explanation
referencing the charge/reload/fire phases.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix typos/inconsistent call style in pseudo-code.

There’s a misspelling and one method call that deviates from the rest of the block, which can confuse readers or lead to copy/paste errors.

✏️ Suggested doc fixes

---- Check if the weapon's below/above water firing restrictions.
+--- Check if the weapon meets below/above water firing restrictions.
---- unit.IsUnitState("MakingAttackRun")
+--- unit:IsUnitState("MakingAttackRun")
---- if weapon:_UnitIsInBombDropZone() then reutrn weapon._AimOnTarget end --Involves weapon BombDropThreshold and unit PredictAheadForBombDrop
+--- if weapon:_UnitIsInBombDropZone() then return weapon._AimOnTarget end -- Involves weapon BombDropThreshold and unit PredictAheadForBombDrop

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@engine/Sim/UnitWeapon.lua` around lines 26 - 40, The pseudo-code in the
UnitWeapon:CanFire comment has a typo and an inconsistent call style; fix
"reutrn" to "return" and make method calls consistent (use colon form for
instance methods like unit:IsStunned(), unit:IsUnitState("Busy"),
unit:IsUnitState("Immobile"), unit:IsUnitState("MakingAttackRun") and keep
unit:_GetSpeed() if it’s private; ensure weapon calls use consistent naming like
weapon:_HasTarget() and weapon:_UnitIsInBombDropZone() and return
weapon._AimOnTarget where indicated; also clarify the Winged check to read "if
not unit.Blueprint.Air.Winged then return weapon._AimOnTarget end" and keep
comments about BombDropThreshold and PredictAheadForBombDrop unchanged.