Merge branch 'develop' into rebased-quats

.github/ISSUE_TEMPLATE/1-bug_report.yml

@@ -12,7 +12,7 @@ body:
         - This repository is maintained by volunteers, it may take a while for them to come back to you.
         - Remember to include sufficient details and context.
         - If you have multiple questions, suggestions, or bugs, please submit them in separate issues.
-        - We accept pull request. If you know how to fix it - go ahead!
+        - We accept pull requests. If you know how to fix it - go ahead!
 
         Please provide the following details about the issue you encountered. *Issues that do not provide the information requested in this form will be flagged as **incomplete** & automatically closed.*
   - type: markdown

.github/ISSUE_TEMPLATE/2-balance_idea.yml

@@ -12,7 +12,7 @@ body:
         - This repository is maintained by volunteers, it may take a while for them to come back to you.
         - Remember to include sufficient details and context.
         - If you have multiple Idea's or suggestions, please submit them in separate issues.
-        - We accept pull request. If you know how to fix it - go ahead!
+        - We accept pull requests. If you know how to fix it - go ahead!
 
         Please bare in mind that any Balance Idea's are subject to balance team approval.
   - type: markdown

.github/ISSUE_TEMPLATE/4-feature_request.yml → .github/ISSUE_TEMPLATE/3-feature_request.yml

@@ -11,8 +11,8 @@ body:
 
         - This repository is maintained by volunteers, it may take a while for them to come back to you.
         - Remember to include sufficient details and context.
-        - If you have multiple Idea's or suggestions, please submit them in separate issues.
-        - We accept pull request. If you know how to fix it - go ahead!
+        - If you have multiple ideas or suggestions, please submit them in separate issues.
+        - We accept pull requests. If you know how to fix it - go ahead!
   - type: textarea
     id: describe
     attributes:

.github/ISSUE_TEMPLATE/4-general-issue.yml

@@ -0,0 +1,39 @@
+name: General issue
+description: Create an issue for purposes not covered by the other templates
+labels: ["status: novel issue"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time in submitting an issue.
+
+        - This repository is maintained by volunteers, it may take a while for them to come back to you.
+        - Remember to include sufficient details and context.
+        - If you have multiple problems or suggestions, please submit them in separate issues.
+        - We accept pull requests. If you know how to fix it - go ahead!
+  - type: textarea
+    id: describe
+    attributes:
+      label: Describe the issue
+      description: A clear and concise description of what the issue is.
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Expected Behavior
+      description: If applicable, a clear and concise description of what you expect to happen in various scenarios.
+    validations:
+      required: false
+  - type: textarea
+    id: images
+    attributes:
+      label: Screenshots
+      description: If applicable, add screenshots to help explain the issue.
+    validations:
+      required: false
+  - type: markdown
+    attributes:
+      value: |
+        _This issue will be read by people that are unable to look into your thoughts - this request is all they have to understand the situation. The more precise your request, the easier it becomes for us to help you._

.github/ISSUE_TEMPLATE/3-contributors_template.yml → .github/ISSUE_TEMPLATE/5-contributors_template.yml

@@ -1,5 +1,5 @@
 name: Contributors template
-description: Template for an extensive description of the issue to solve.
+description: Template for an extensive description, to enable other contributors to work on a feature.
 labels: ["status: novel issue"]
 
 body:

.github/ISSUE_TEMPLATE/6-nav_mesh_feature.yml

@@ -13,7 +13,7 @@ body:
         - This repository is maintained by volunteers, it may take a while for them to come back to you.
         - Remember to include sufficient details and context.
         - If you have multiple Idea's or suggestions, please submit them in separate issues.
-        - We accept pull request. If you know how to fix it - go ahead!
+        - We accept pull requests. If you know how to fix it - go ahead!
   # Describe
   - type: textarea
     id: describe

.github/ISSUE_TEMPLATE/5-improvements.yml → .github/ISSUE_TEMPLATE/7-unit-improvements.yml

@@ -13,7 +13,7 @@ body:
         - This repository is maintained by volunteers, it may take a while for them to come back to you.
         - Remember to include sufficient details and context.
         - If you have multiple Idea's or suggestions, please submit them in separate issues.
-        - We accept pull request. If you know how to fix it - go ahead!
+        - We accept pull requests. If you know how to fix it - go ahead!
 
   # Faction Selection
   - type: dropdown

.github/workflows/auto-draft-pr.yaml

@@ -0,0 +1,34 @@
+# Copyright (c) 2024 FAForever
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+name: Convert PRs to Draft on Opening
+
+on:
+  pull_request:
+    types: [opened]
+
+jobs:
+  convert_to_draft:
+    runs-on: ubuntu-latest
+    steps:
+      - run: gh pr ready --undo ${{ github.event.pull_request.number }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}

CONTRIBUTING.md

@@ -1,23 +1,102 @@
-Contributing
-------------
 
-To contribute, please fork this repository and make pull requests to the
-`deploy/fafdevelop` branch.
+## When making a PR:
 
-Use the normal git conventions for commit messages, with the following rules:
- - Subject line shorter than 80 characters
- - No trailing period
- - For non-trivial commits, always include a commit message body, describing the change in detail
- - If there are related issues, reference them in the commit message footer
+If you plan a bigger change, make an issue first to discuss the feature. This way you can avoid spending time on something that would ultimately be denied integration.
 
-We use [git flow](http://nvie.com/posts/a-successful-git-branching-model/) for our branch conventions.
+- Target the `develop` branch.
+- Start your PR as draft.
+- Don't forget to add appropriate tags.
 
-When making _backwards incompatible API changes_, do so with a stub function and put in a logging statement including traceback. This gives time for mod authors to change their code, as well as for us to catch any incompatibilities introduced by the change.
+Each PR needs a [snippet](https://faforever.github.io/fa/development/changelog) for the changelog file of the release.
+When you have made all the changes you intended to do and have added the snippet, you can mark the PR as ready for review by removing the draft status from the PR.
+Now the PR should be milestoned to the next release.
+You can request reviews from people that a knowledgable in the domains of the code you changed (See below).
 
-Code convention
----------------
 
-Please follow the [Lua Style Guide](http://lua-users.org/wiki/LuaStyleGuide) as
-much as possible.
+## How to do a review:
 
-For file encoding, use UTF-8 and unix-style file endings (Set core.autocrlf).
+1. Do we want this feature?  
+   If it's just a bugfix this can generally be answered as yes.  
+   If it's a new feature or changes gameplay in a more meaningful way there is ideally a linked issue where the discussion already happened and it was concluded that we want this feature.  
+   Sanity check: Should this rather be a sim/ui mod?
+
+2. Functionality  
+   Start the game with these changes and see if the described changes work as intended.  
+   Test if related functionality still works and didn't inadvertantly break.
+   There is no hard rule how much testing is needed, especially as we can't automate this. You don't have to go overboard with testing as we still have the duration between the merge and the next release to notice bugs during actual gameplay.
+
+3. Technical code review  
+   Is the code style correct? Please follow the [Lua Style Guide](http://lua-users.org/wiki/LuaStyleGuide).  
+   Is the code readable and doing things the way things should be done?  
+   This step should be done by people that have knowledge of the affected domains of the code base (See below).
+
+4. Balance implications (only for PRs labeled as balance)  
+   Changes touching balance need a green light from the balance team.
+
+It's totally possible to review not all steps if you don't have the knowledge or motivation to do them all. Someone else can pick up the other steps.  
+If you don't review all steps, don't formally approve the PR, but state your approval of the steps you did in a review comment. Only PRs that passed all review steps should be formally approved.
+
+
+## When to merge:
+
+After all the necessary reviews have passed and the PR has been approved it can be merged. We suggest to wait 24 hours after approval, so the owner of the PR can interject if there was some sort of miscommunication and the owner still intends to do some changes. The PR owner can also merge the PR if they want.
+
+Merge by using the squash option.  
+Use the normal git conventions for the commit message, with the following rules:
+
+- Subject line shorter than 80 characters
+- Pull request number at the end
+- No trailing period
+- For non-trivial commits, always include a commit message body, describing the change in detail
+
+If the branch was in the FAForever repository, delete it after the merge, so it doesn't clutter the repo.
+
+## Reviewers
+
+These are people knowledgeable of the indicated areas, that are good candidates to request a review from.
+
+**lua (ui)**  
+@4z0t  
+@Basilisk3  
+@lL1l1  
+@Garanas  
+@Hdt80bro  
+@clyfordv  
+@speed2CZ  
+
+**lua (sim)**  
+@lL1l1  
+@4z0t  
+@Basilisk3  
+@Garanas  
+@Hdt80bro  
+@clyfordv  
+@speed2CZ  
+@The-Balthazar  
+
+**AI**  
+@relent0r  
+@Garanas  
+
+**blueprints**  
+@Basilisk3  
+@Garanas  
+@Hdt80bro  
+@lL1l1  
+@The-Balthazar  
+
+**mapping**  
+@speed2CZ  
+
+**modeling**  
+@MadMaxFAF  
+@The-Balthazar  
+@lL1l1  
+
+**graphics**  
+@BlackYps  
+@Garanas  
+
+**binary patches**  
+@4z0t  
+@Hdt80bro  

changelog/snippets/balance.6423.md

@@ -0,0 +1,11 @@
+- (#6423) The Pulsar receives various tweaks in anticipation of its future introduction into the game. Additionally, the Pulsar's files have been updated to remove the last remnants of its former name. Initially, the unit was called Othismash.
+
+  - Pulsar: T3 Mobile EMP Missile Launcher (SRL0310):
+    - Categories added:
+      - `PRODUCTDL`
+      - `SNIPEMODE`
+    - Pulsar EMP Missile Barrage:
+      - DamageRadius: 0 --> 1 (same as its EMP weapon)
+      - TurretPitchRange: 15 --> 40 (required against nearby units and units on top of mountains)
+      - TurretPitchSpeed: 20 --> 50 (improves the responsiveness of the turret)
+      - Introduce a taller firing arc to allow the Pulsar to shoot over obstacles more easily

changelog/snippets/balance.6440.md

@@ -0,0 +1,7 @@
+- (#6440) The Infinity Class Cruiser is equipped with two copies of Zealot AA Missile launchers. These two weapons function identically except for the `MuzzleVelocity` stat, where one weapon has a higher value than the other. This is misleading because the models look the same, and the unit databases imply that both AA batteries have a `MuzzleVelocity` of `40`. This PR equalizes the stats of both launchers to resolve this issue. In terms of gameplay, there is virtually no difference.
+
+    - Infinity Class: T2 Cruiser (UAS0202):
+        - Zealot AA Missile (right battery):
+            - MuzzleVelocity: 40 --> 35
+        - Zealot AA Missile (left battery):
+            - MuzzleVelocity: 30 --> 35

changelog/snippets/fix.6416.md

@@ -0,0 +1 @@
+- (#6416) Fix Salvation's reload time not increasing from 2.5 to 2.6 when missing T1 power generator adjacency and only having T3 power generators.

changelog/snippets/fix.6418.md

@@ -0,0 +1 @@
+- (#6418) Fix ACU explosions being able to kill TMD structures.

changelog/snippets/fix.6419.md

@@ -0,0 +1 @@
+- (#6419) Fix engineer stations without a `GuardScanRadius` defaulting to 300 radius for their build range overlay. They now display their full build range in the radius for better compatibility with the reclaim tower mods, even though `GuardScanRadius` defaults to 25.

changelog/snippets/fix.6429.md

@@ -0,0 +1 @@
+- (#6429) Fix the aim of the GC's claws being disrupted by the walking animation.

changelog/snippets/fix.6430.md

@@ -0,0 +1 @@
+- (#6430) Fix an `OnImpact` error caused by CZAR's depth charges.

changelog/snippets/fix.6432.md

@@ -0,0 +1 @@
+- (#6432) Fix units failing to transfer after defeat if the player that is being transferred to is defeated during the transfer process.

changelog/snippets/fix.6433.md

@@ -0,0 +1 @@
+- (#6433) Fix Aeon destroyer's depth charge's indirect fire range ring not appearing.

changelog/snippets/fix.6436.md

@@ -0,0 +1 @@
+- (#6436) Prevent the logging of an unecessary warning when certain units make landfall.

changelog/snippets/fix.6439.md

@@ -0,0 +1 @@
+- (#6439) Fix `table.empty` and `table.getsize` not using their asm implementation due to reimports.

changelog/snippets/fix.6446.md

@@ -0,0 +1 @@
+- (#6446) Fix the "assist to upgrade" and "assist to unpause" game options conflicting and causing upgrading units to unpause during lag spikes.

changelog/snippets/fix.6447.md

@@ -0,0 +1 @@
+- (#6447) Fix `repr` causing an "attempt to call upval 'match' (a nil value)" error when used in the blueprint loading scripts.

changelog/snippets/other.6431.md

@@ -0,0 +1 @@
+- (#6431) Make CZAR depth charges give underwater vision on impact alongside the normal vision they give.

changelog/snippets/other.6450.md

@@ -0,0 +1 @@
+- (#6450) Improve beam blueprint annotations with thorough descriptions of beam parameters.

changelog/snippets/other.6451.md

@@ -0,0 +1 @@
+- (#6451) Annotate emitter blueprint parameters with extensive descriptions.

docs/Gemfile.lock

@@ -3,6 +3,7 @@ GEM
   specs:
     addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
+    bigdecimal (3.1.8)
     colorator (1.1.0)
     concurrent-ruby (1.2.3)
     em-websocket (0.5.3)
@@ -11,11 +12,14 @@ GEM
     eventmachine (1.2.7)
     ffi (1.16.3)
     forwardable-extended (2.6.0)
-    google-protobuf (4.26.1-arm64-darwin)
+    google-protobuf (4.27.5-arm64-darwin)
+      bigdecimal
       rake (>= 13)
-    google-protobuf (4.26.1-x64-mingw-ucrt)
+    google-protobuf (4.27.5-x64-mingw-ucrt)
+      bigdecimal
       rake (>= 13)
-    google-protobuf (4.26.1-x86_64-linux)
+    google-protobuf (4.27.5-x86_64-linux)
+      bigdecimal
       rake (>= 13)
     http_parser.rb (0.8.0)
     i18n (1.14.4)
@@ -65,7 +69,7 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.3.3)
+    rexml (3.3.6)
       strscan
     rouge (4.2.1)
     safe_yaml (1.0.5)

engine/Core/Blueprints/BeamBlueprint.lua

@@ -1,12 +1,20 @@
 ---@meta
 
+---@alias BeamBlendmode
+---| 0 # Alpha blend
+---| 1 # Modulate Inverse
+---| 2 # Modulate2X Inverse
+---| 3 # Add
+---| 4 # Premodulated Alpha
+
 ---@class BeamBlueprint : EmitterBlueprint
----@field Length number                Total length of beam
----@field Lifetime number              Lifetime of the emitter
----@field Thickness number             Thickness of the beam
----@field TextureName FileName         Filename of texture
----@field StartColor NamedQuaternion   RGBA start color of beam
----@field EndColor NamedQuaternion     RGBA end color of beam
----@field UShift number                U Texture shift of beam texture
----@field VShift number                V Texture shift of beam texture
----@field RepeatRate number            How often the texture repeats per ogrid blendmode of this beam
+---@field Length number                # Total length of beam
+---@field Lifetime number              # Lifetime of the emitter
+---@field Thickness number             # Thickness of the beam in both directions from the center
+---@field TextureName FileName         # Filename of texture
+---@field StartColor NamedQuaternion   # Color multiplier from 0 to 1 of beam texture at start point. `w, x, y, z = ARGB`
+---@field EndColor NamedQuaternion     # Color multiplier from 0 to 1 of beam texture at end point. `w, x, y, z = ARGB`
+---@field UShift number                # Proportional shift of beam texture per tick in the U direction (across width of beam, X direction of texture)
+---@field VShift number                # Proportional shift of beam texture per tick in the V direction (across the length of the beam, Y direction of texture)
+---@field RepeatRate number            # How often the texture repeats per ogrid. `0` stretches the texture over the length of the beam.
+---@field Blendmode BeamBlendmode      # Blend mode of the beam.

engine/Core/Blueprints/EffectBlueprint.lua

@@ -5,17 +5,20 @@
 ---@field MedFidelity  boolean Allowed in medium fidelity
 ---@field LowFidelity  boolean Allowed in low fidelity
 
+--- A curve made of linear segments defined by a set of points.
+--- It defines the values for an effect at a specific time in an emitter's cycle.
 ---@class EffectCurve
----@field XRange number
+---@field XRange number Defines what value of `x` corresponds to the end of the emitter's cycle. The emitter editor will default this to the cycle's tick count.
 ---@field Keys NamedPosition[]
 
 ---@class NamedPosition
----@field x number
----@field y number
----@field z number
+---@field x number Time at the point on the curve, relative to `XRange`. Represents ticks in the emitter editor.
+---@field y number Value at the point.
+---@field z number Range within which the value is randomized.
 
+--- Used by beam blueprints to interpolate the color/alpha of the beam between the start point and end point
 ---@class NamedQuaternion
----@field x number
----@field y number
----@field z number
----@field w number
+---@field x number # Red
+---@field y number # Green
+---@field z number # Blue
+---@field w number # Alpha