Merge branch 'develop' into dd-6237-convert-md-to-lua

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

.github/workflows/docs-url-check.yaml

@@ -50,4 +50,4 @@ jobs:
 
           # URLs are excluded because not all type of URLs are supported, see also:
           # - https://github.com/urlstechie/urlchecker-action/issues/105
-          exclude_urls: https://code.visualstudio.com/shortcuts/keyboard-shortcuts-windows.pdf,https://github.com/FAForever/fa/deployments
+          exclude_urls: https://code.visualstudio.com/shortcuts/keyboard-shortcuts-windows.pdf,https://github.com/FAForever/fa/deployments,https://github.com/FAForever/fa/deployments/production

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.6469.md

@@ -0,0 +1,4 @@
+- (#6469) Unlike other Tech 2 units, the Fire Beetle only takes up one clamp on transports. This makes it possible to load the same quantities of Fire Beetles and Tech 1 units into transports. To ensure that the Fire Beetle does not slow transports down excessively, its `TransportSpeedReduction` stat is reduced to match that of Tech 1 units.
+
+  - Fire Beetle: T2 Mobile Bomb (XRL0302):
+    - TransportSpeedReduction: 0.3 --> 0.15

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.6436.md

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

changelog/snippets/fix.6471.md

@@ -0,0 +1 @@
+- (#6471) Fix Seraphim walls not orientating towards the terrain

changelog/snippets/other.6451.md

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

docs/Gemfile.lock

@@ -83,7 +83,7 @@ GEM
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
     unicode-display_width (2.5.0)
-    webrick (1.8.1)
+    webrick (1.8.2)
 
 PLATFORMS
   arm64-darwin

docs/deployment.md

@@ -21,19 +21,22 @@ The deployment procedure can be a lengthy process because it involves various st
 
 ### Deployment of engine patches
 
-The deployment of engine patches to the release branch is a manual process. This is intentional as users will automatically download the executable upon launching the game. 
+The deployment of engine patches to the release branch is a manual process. This is intentional from a security perspective - it provides a second pair of eyes from a server administrator who is usually not directly related to the game team. 
 
 - (1) Make sure that any open changes that you want to include are merged to the `master` branch of the [Binary patches](https://github.com/FAForever/FA-Binary-Patches) repository.
 - (2) Update the executable of the `FAF Develop` and `FAF Beta Balance` game types using the [Upload workflow](https://github.com/FAForever/FA-Binary-Patches/actions).
-- (3) Ask a server administrator to prepare the executable to be updated upon the next game release.
-- (4) ???
 
-You can continue the deployment steps but you can not finalize it until the server administrator got back to you that it is set. This may take an arbitrary amount of time so make sure this is done well in advance. 
+The workflow requires an approval of another maintainer. Once approved, wait for the workflow to finish.
 
-### Changelog for a deployment
+- (3) Verify the executable on the `FAF Develop` game type.
+- (4) Ask a server administrator to prepare the executable to be updated upon the next game release. This practically involves a copy operation where the server administrator verifies the executable of FAF Develop and copies it to a different location.
 
-- (0) Checkout on the `develop` branch and pull in the latest version. Make sure that there are no other open changes.
-- (1) Create a new branch that originates from `develop`. We'll refer to this branch as the `changelog branch`.
+You can continue the deployment steps, but you can not finalize it until the server administrator got back to you that it is set. This may take an arbitrary amount of time so make sure this is done well in advance.
+
+### Deployment of Lua
+
+- (0) Checkout on the [develop](https://github.com/FAForever/fa/tree/develop) branch and pull in the latest version. Make sure that there are no other open changes.
+- (1) Create a new branch that originates from [develop](https://github.com/FAForever/fa/tree/develop). We'll refer to this branch as the `changelog branch`.
 - (2) Generate the changelog using the [Changelog generation workflow](https://github.com/FAForever/fa/actions/workflows/docs-changelog.yaml).
 - (3) Once the workflow is completed, navigate to the summary section and download the artifact that is created by the workflow.
 - (4) Save the generated changelog to a new file in the format `yyyy-mm-dd-game-version.md` in `docs/_posts`. As an example for a file name: `2024-08-03-3811.md`.
@@ -48,31 +51,32 @@ permalink: changelog/3811
 ---
 ```
 
-- - (5.1) Add an introduction at the top of the changelog.
-- - (5.2) Add the contributors at the bottom.
+- - (5.2) Add an introduction at the top of the changelog.
+- - (5.3) Add the contributors at the bottom.
 
-- (6) Stage, commit and push the changes to GitHub. Create a pull request on GitHub to allow other maintainers to review the changelog. Make sure the pull requests points to `develop`. 
+- (6) Stage, commit and push the changes to GitHub. Create a pull request on GitHub to allow other maintainers to review the changelog. Make sure the pull request points to [develop](https://github.com/FAForever/fa/tree/develop).
 - (7) Delete the current snippets and stage, commit and push the changes to GitHub.
+- (8) Update the game version in [mod_info.lua](https://github.com/FAForever/fa/blob/develop/mod_info.lua) and [version.lua](https://github.com/FAForever/fa/blob/develop/lua/version.lua) and stage, commit and push the changes to GitHub.
 
-You can re-use the same branch and pull request in the next phase of the deployment.
-
-### Deployment of Lua
-
-The following (manual) steps are relevant to create a valid deployment to the FAF game type.
+At this point you need to wait until the `changelog branch` is merged.
 
-- (0) Checkout on the `changelog branch` branch created in the previous step and pull in the latest version.
-- (1) Update the game version in [mod_info.lua](https://github.com/FAForever/fa/blob/develop/mod_info.lua) and [version.lua](https://github.com/FAForever/fa/blob/develop/lua/version.lua).
-- (3) Push everything that you want to release to the [master](https://github.com/FAForever/fa/tree/master) branch.
-- (4) Use the [Deploy to FAF Workflow](https://github.com/FAForever/fa/actions/workflows/deploy-faf.yaml) to perform the deployment.
-- (5) Create a [release on GitHub](https://github.com/FAForever/fa/releases) that targets the [master](https://github.com/FAForever/fa/tree/master) branch.
+- (9) Push everything that you want to release from [develop](https://github.com/FAForever/fa/tree/develop) to the [master](https://github.com/FAForever/fa/tree/master) branch.
 
-### Release on GitHub
+### Deployment - final steps
 
-Once `deploy/faf` is updated it is important to create a [release](https://github.com/FAForever/fa/releases/new) on GitHub
+- (1) Create a [release on GitHub](https://github.com/FAForever/fa/releases) that targets the [master](https://github.com/FAForever/fa/tree/master) branch.
+- - (1.1) Set the tag with the game version. 
+- - (1.2) Match the format of the title with that of previous releases.
+- - (1.3) Copy and paste the changelog into the description. Make sure to remove the title as a release has its own title.
+- - (1.4) Create the release.
+- (2) Use the [Deploy to FAF Workflow](https://github.com/FAForever/fa/actions/workflows/deploy-faf.yaml) to perform the deployment.
 
+The workflow requires an approval of another maintainer. Once approved, wait for the workflow to finish.
 
+- (3) Use the [Update SpookyDB](https://github.com/FAForever/fa/actions/workflows/spookydb-update.yaml) workflow to update [SpookyDB](https://github.com/FAForever/spooky-db)
+- (4) Use the [Update UnitDB](https://github.com/FAForever/fa/actions/workflows/unitdb-update.yaml) workflow to update [UnitDB](https://github.com/FAForever/UnitDB)
 
-The last step allows us to systematically post process what we deploy. You can learn more about this by inspecting the workflow file.
+Once all this is run you can review the status of the deployment by the server in the [production environment](https://github.com/FAForever/fa/deployments/production). Once that returns green the deployment succeeded and you can inform the community of the deployment. Congratulations!
 
 ## Automated deployments
 

engine/Core/Blueprints/EffectBlueprint.lua

@@ -5,15 +5,18 @@
 ---@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 # Red
 ---@field y number # Green