Various annotations

[lL1l1]

Description of the proposed changes

Some engine stuff and other lua stuff I found while looking around recently.

Testing done on the proposed changes

I tested OnExtraDamageDealt by setting "Normal" armor type to take 2.0x from "Normal" damage type.

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
  • Clarified damage-reduction behavior and patrol-related capabilities in engine documentation.
  • Improved documentation for Lua UI groups, unit damage callbacks, and sorted iteration utilities.
  • Added clearer type information for engine callbacks and public Lua APIs.
  • Updated changelog notes with recent engine annotation and function documentation changes.

[coderabbitai]

Warning

Review limit reached

@lL1l1, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 1 minute

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 065a7836-d9fd-4d3b-bbcc-d5aaf44f94d3

📥 Commits

Reviewing files that changed from the base of the PR and between 8146338 and 26552bf.

📒 Files selected for processing (2)

• .vscode/settings.json
• lua/system/utils.lua

📝 Walkthrough

Walkthrough

The changes add engine callback and behavior annotations, refine LuaDoc type signatures for several APIs, and add a changelog entry describing the annotation updates.

Changes

Annotation updates

Layer / File(s)	Summary
Engine callback and behavior annotations engine/Core/Categories.lua, engine/Sim.lua, engine/Sim/Unit.lua	Documents patrol helper behavior and handicap-based damage reduction, and adds the typed Unit.OnExtraDamageDealt callback hook.
Lua API type annotations lua/maui/group.lua, lua/sim/Unit.lua, lua/system/utils.lua, changelog/snippets/other.7179.md	Adds a Group constructor overload, changes OnDamageBy’s army parameter type, expands sortedpairs generics and iterator typing, and records the annotation updates in the changelog.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: type: intellisense

Suggested reviewers: speed2cz, 4z0t, vjt4

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is very generic and does not clearly describe the specific annotations and documentation updates in the PR.	Use a concise, specific title such as “Add Lua and engine annotations for damage callbacks and utilities.”

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description covers the main change, testing, and checklist, but omits the optional Additional context section and leaves the changelog item unchecked.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch annotations/engine-unit-funcs

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lua/system/utils.lua`:
- Around line 356-360: Update the comparator annotation for sortedpairs so its
parameters use the table key type k instead of the unrelated generic T; remove
the unused T generic if it is no longer referenced, while preserving the
existing table and return annotations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b9ba66b9-c443-47fd-b385-48d8d1d8bdd7

📥 Commits

Reviewing files that changed from the base of the PR and between e4130a1 and 8146338.

📒 Files selected for processing (8)

• changelog/snippets/category.7158.md
• changelog/snippets/other.7179.md
• engine/Core/Categories.lua
• engine/Sim.lua
• engine/Sim/Unit.lua
• lua/maui/group.lua
• lua/sim/Unit.lua
• lua/system/utils.lua

💤 Files with no reviewable changes (1)

• changelog/snippets/category.7158.md

[4z0t]

The fact that sort functions are in global space is very bad, these must be put into separate module.