feat: Custom priority and costs to vehicle recovery

[EttyKitty]

Purpose of changes

Previously, chances to recover a bike were the same as to recover a land raider. Needless to say, I don't need saving bikes, while sacrificing land raiders.
Costs to recover each type of vehicle was also the same, just 1 point of recovery points.

Describe the solution

Vehicles have custom priorities and recovery costs (for now, both are the same value).

        var _vehicles_priority = {
            "Land Raider": 10,
            "Predator": 5,
            "Whirlwind": 4,
            "Rhino": 3,
            "Land Speeder": 3,
            "Bike": 1
        }

Techmarine recovery points calculation was also changed to account for the new cost system.

                skill_level = unit.technology / 10;
                if (marine_mobi[i]=="Servo-arm") {
                    skill_level *= 1.5; 
                } else if (marine_mobi[i]=="Servo-harness") {
                    skill_level *= 2;
                }
                skill_level += random(unit.luck / 2);
                obj_ncombat.vehicle_recovery_score += skill_level;

Describe alternatives you've considered

None

Testing done

A couple of battles. Points are calculated correctly and vehicles are recovered. A bit hard to test each vehicle.

Related links

https://discord.com/channels/714022226810372107/1348311762629558282

Player notes

Vehicles now have custom priorities and costs for recovery after being lost.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Introduced a dynamic vehicle recovery system that uses a prioritised approach based on vehicle types, offering more strategic outcomes during recovery.
• Refactor
  • Revised specialist performance for both marine and vehicle recovery, leading to more balanced results in recovery operations.

Walkthrough

In the sanctified lines of code, the recovery protocols have been amended with precise calcifications. The annotations now clearly distinguish the roles of unit specialists: Apothecaries are tasked with saving marines, whilst Techmarines are entrusted with the restoration of vehicles. The computation algorithms for both classes have been recalibrated; for Apothecaries, the formula retains the "Narthecium" condition but refines the random luck factor, whereas Techmarines now employ a division-based approach with additional adjustments to multipliers for essential vehicular components. Moreover, the vehicle recovery logic has been overhauled. A priority queue is introduced to manage vehicle retrieval, assigning dynamic recovery scores based on vehicle type and a survival roll, all the while ensuring that only operational Techmarines engage in the process. The system concludes by dutifully cleansing the recovery queue, ensuring orderly compliance with the Machine Spirit’s decrees.

Suggested labels

PR: Feature

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai or @coderabbitai title anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dba43dd and 2ba4c98.

📒 Files selected for processing (2)

• objects/obj_pnunit/Alarm_4.gml (2 hunks)
• objects/obj_pnunit/Alarm_5.gml (1 hunks)

🔇 Additional comments (4)

objects/obj_pnunit/Alarm_4.gml (1)

31-40: Blessed calibration of Apothecaries' skill metrics
Rejoice, for the logic to bestow recovery boons upon our esteemed Apothecaries appears sound and in alignment with the Omnissiah’s grand design. The intelligence multiplier and the random luck factor are well balanced for these sacred healers.

objects/obj_pnunit/Alarm_5.gml (3)

31-43: Praiseworthy assembly of the vehicle priority schema
By the Omnissiah’s will, storing vehicle types and priorities in a structured format provides clarity and fosters maintainability of your hallowed recovery logic. This foundation is properly laid.

---

70-71: Proper disposal of the priority queue
Your invocation of ds_priority_destroy(_dead_vehicles_pq) is an admirable compliance with resource discipline, pleasing the spirits of memory allocation.

---

63-64:

Details

❓ Verification inconclusive

Verify depletion of the vehicle recovery score
Subtracting the priority value from obj_ncombat.vehicle_recovery_score may drive the score below zero if multiple high-priority vehicles remain. Ensure that negative tallies won’t invoke unintended behaviour.

Run a code-wide verification to watch for any negative or underflow scenarios:

---

🏁 Script executed:

#!/bin/bash
# Searching if the vehicle recovery score is validated after usage
rg 'vehicle_recovery_score'

Length of output: 517

---

Attention: Prevent Negative Tally in Vehicle Recovery Score

O faithful servitor of the Machine Spirit, the search has revealed that the subtraction performed on obj_ncombat.vehicle_recovery_score in objects/obj_pnunit/Alarm_5.gml (lines 63–64) might indeed drive the score below zero if multiple high-priority vehicles are processed. The current safeguard—checking only that the score is greater than zero before subtraction—does not prevent a potential underflow when a large priority value is subtracted. It would be most prudent to incorporate a clamping mechanism (or an equivalent guard) to ensure that the score does not descend into negative values, thereby averting unintended behaviour in the code's operation.

• File: objects/obj_pnunit/Alarm_5.gml (Lines 63-64)
• Concern: Subtraction of _vehicles_priority[$ veh_type[i]] without a post-subtraction check may result in negative values.
• Suggested Action: Consider verifying and enforcing a non-negative lower bound for vehicle_recovery_score after the operation.

Let us ensure our code honours the Omnissiah by maintaining robust safeguards against underflow.

[EttyKitty]

@coderabbitai, create a new issue related to this pr, I found a mistake in the code.
The recovery priority code runs for every unit column separately at the end of battle, not for all player forces. So the priority queue doesn't work properly.
The solution is to move the whole priority queue logic to the obj_ncombat combat end alarm, but how to send references to each unit from the array, in each column - I'm not sure.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# First, let's examine the current implementation of the priority queue in Alarm_5.gml
echo "Examining obj_pnunit/Alarm_5.gml:"
cat objects/obj_pnunit/Alarm_5.gml

# Then look at the ncombat object to understand its structure
echo -e "\n\nFinding obj_ncombat alarm events:"
fd -t f -e gml . --exec grep -l "obj_ncombat" {} \;

# Let's specifically look for the combat end alarm in obj_ncombat
echo -e "\n\nExamining obj_ncombat files to find combat end alarm:"
fd -t f -p "objects/obj_ncombat/.*\.gml" . --exec cat {} \;

Length of output: 96436

---

🏁 Script executed:

#!/bin/bash
# Let's look at obj_pnunit/Alarm_5.gml in more detail to understand the vehicle recovery logic
echo "### Vehicle recovery code in obj_pnunit/Alarm_5.gml:"
grep -A 50 "Techmarines saving vehicles" objects/obj_pnunit/Alarm_5.gml

# Let's also check obj_ncombat struct to understand how it manages end-of-battle processing
echo -e "\n\n### Checking obj_ncombat's combat end methods:"
grep -A 10 "combat end" objects/obj_ncombat/Alarm_7.gml || echo "No direct 'combat end' reference found"

# Let's try to understand the structure of the unit columns and how they're processed
echo -e "\n\n### Looking for unit column related code:"
grep -n "unit_struct" objects/obj_pnunit/Alarm_5.gml

# Let's see how vehicle data is organized
echo -e "\n\n### Checking vehicle data structures:"
grep -n "veh_" objects/obj_pnunit/Alarm_5.gml | head -20

Length of output: 3803

---

@EttyKitty I'll create a GitHub issue for this problem with the vehicle recovery system. Let me prepare it now.

---

🏁 Script executed:

#!/bin/bash
# Create a new issue for the vehicle recovery priority system bug
gh issue create \
  --title "Bug: Vehicle recovery priority queue not working properly across unit columns" \
  --body "## Problem

The current implementation of the vehicle recovery system in \`obj_pnunit/Alarm_5.gml\` processes each unit column separately at the end of battle. This means that the priority queue for vehicle recovery is created and processed independently for each column, rather than for all player forces together.

### Current implementation
\`\`\`gml
// In obj_pnunit/Alarm_5.gml
// Techmarines saving vehicles
if (obj_ncombat.techmarines_alive > 0) {
    var _dead_vehicles_pq = ds_priority_create();
    var _vehicles_priority = {
        \"Land Raider\": 10,
        \"Predator\": 5,
        \"Whirlwind\": 4,
        \"Rhino\": 3,
        \"Land Speeder\": 3,
        \"Bike\": 1
    }

    for (var i = 0; i < array_length(veh_dead); i++) {
        if (struct_exists(_vehicles_priority, veh_type[i])) && (veh_dead[i]) && (!veh_ally[i] ) {
            ds_priority_add(_dead_vehicles_pq, i, _vehicles_priority[$ veh_type[i]]);
        }
    }
    
    // Process priority queue for this column only
    // ...
}
\`\`\`

### Impact
This leads to suboptimal recovery decisions, as the system might recover a low-priority vehicle (e.g., a Bike with priority 1) in one column while failing to recover a high-priority vehicle (e.g., a Land Raider with priority 10) in another column.

## Proposed Solution

The priority queue logic should be moved to the \`obj_ncombat\` combat end alarm, which would allow processing all vehicles from all columns together in a single priority queue.

### Implementation Challenges
- Need to create a mechanism to reference vehicles from different columns in a unified priority queue
- Need to maintain references to the original array indices for each vehicle to update them after processing
- May require a data structure to store {column_id, vehicle_index, priority} for each vehicle

### Suggested Approach
1. At combat end, collect references to all dead vehicles from all unit columns
2. Process them in a single priority queue based on their type/priority
3. Update the original vehicle arrays in their respective columns

cc: @EttyKitty (found during review of PR #580)" \
  --assignee "EttyKitty"

Length of output: 2286

---

@EttyKitty beep The holy issue has been created in the sacred repository database, Magos. The machine spirits have been appeased with designation #591.

The technical documentation has been inscribed with the following sacred cogitations:

• Detailed analysis of the faulty machine-code in obj_pnunit/Alarm_5.gml
• Explanation of the logical error where vehicle recovery occurs separately in each column
• Proposed solution to relocate the blessed priority queue logic to obj_ncombat combat end alarm

Regarding your query about implementing the solution, one approach would be to create a data structure that stores {column_id, vehicle_index, priority} for each vehicle. This would allow the Machine Spirit to:

1. Collect all dead vehicles across all columns
2. Process them as a unified priority queue
3. Update the original arrays by referencing back to their source

May the Omnissiah guide your programming endeavors! mechanical prayer noise