Annotations related to script tasks #6596

lL1l1 · 2024-12-21T02:19:21Z

Description of the proposed changes

Annotates ScriptTasks and related code.
- All task scripts
- Scry ability (Eye of Rhianne's ability)
  - orders.lua's interaction with scripted abilities like Scry
  - The remote viewing unit class for Scry
Whitespace formatting

Testing done on the proposed changes

Used cc440f3 to play around with the tasks using the test task while figuring out the behavior.
Logging commandmode.lua and UserScriptCommand
Looked for and cleared out annotation warnings in the task scripts, RemoteViewing.lua, and XAB3301_script.lua

Clipboard command to view all UnitCommands from RULEUCC command caps

LOG('RULEUCC_Move = ', GetUnitCommandFromCommandCap('RULEUCC_Move'))
LOG('RULEUCC_Stop = ', GetUnitCommandFromCommandCap('RULEUCC_Stop'))
LOG('RULEUCC_Attack = ', GetUnitCommandFromCommandCap('RULEUCC_Attack'))
LOG('RULEUCC_Guard = ', GetUnitCommandFromCommandCap('RULEUCC_Guard'))
LOG('RULEUCC_Patrol = ', GetUnitCommandFromCommandCap('RULEUCC_Patrol'))
LOG('RULEUCC_RetaliateToggle = ', GetUnitCommandFromCommandCap('RULEUCC_RetaliateToggle'))
LOG('RULEUCC_Repair = ', GetUnitCommandFromCommandCap('RULEUCC_Repair'))
LOG('RULEUCC_Capture = ', GetUnitCommandFromCommandCap('RULEUCC_Capture'))
LOG('RULEUCC_Transport = ', GetUnitCommandFromCommandCap('RULEUCC_Transport'))
LOG('RULEUCC_CallTransport = ', GetUnitCommandFromCommandCap('RULEUCC_CallTransport'))
LOG('RULEUCC_Nuke = ', GetUnitCommandFromCommandCap('RULEUCC_Nuke'))
LOG('RULEUCC_Tactical = ', GetUnitCommandFromCommandCap('RULEUCC_Tactical'))
LOG('RULEUCC_Teleport = ', GetUnitCommandFromCommandCap('RULEUCC_Teleport'))
LOG('RULEUCC_Ferry = ', GetUnitCommandFromCommandCap('RULEUCC_Ferry'))
LOG('RULEUCC_SiloBuildTactical = ', GetUnitCommandFromCommandCap('RULEUCC_SiloBuildTactical'))
LOG('RULEUCC_SiloBuildNuke = ', GetUnitCommandFromCommandCap('RULEUCC_SiloBuildNuke'))
LOG('RULEUCC_Sacrifice = ', GetUnitCommandFromCommandCap('RULEUCC_Sacrifice'))
LOG('RULEUCC_Pause = ', GetUnitCommandFromCommandCap('RULEUCC_Pause'))
LOG('RULEUCC_Overcharge = ', GetUnitCommandFromCommandCap('RULEUCC_Overcharge'))
LOG('RULEUCC_Dive = ', GetUnitCommandFromCommandCap('RULEUCC_Dive'))
LOG('RULEUCC_Reclaim = ', GetUnitCommandFromCommandCap('RULEUCC_Reclaim'))
LOG('RULEUCC_SpecialAction = ', GetUnitCommandFromCommandCap('RULEUCC_SpecialAction'))
LOG('RULEUCC_Dock = ', GetUnitCommandFromCommandCap('RULEUCC_Dock'))
LOG('RULEUCC_Script = ', GetUnitCommandFromCommandCap('RULEUCC_Script'))
LOG('RULEUCC_Invalid = ', GetUnitCommandFromCommandCap('RULEUCC_Invalid'))
LOG('RULEUTC_ShieldToggle = ', GetUnitCommandFromCommandCap('RULEUTC_ShieldToggle'))
LOG('RULEUTC_WeaponToggle = ', GetUnitCommandFromCommandCap('RULEUTC_WeaponToggle'))
LOG('RULEUTC_JammingToggle = ', GetUnitCommandFromCommandCap('RULEUTC_JammingToggle'))
LOG('RULEUTC_IntelToggle = ', GetUnitCommandFromCommandCap('RULEUTC_IntelToggle'))
LOG('RULEUTC_ProductionToggle = ', GetUnitCommandFromCommandCap('RULEUTC_ProductionToggle'))
LOG('RULEUTC_StealthToggle = ', GetUnitCommandFromCommandCap('RULEUTC_StealthToggle'))
LOG('RULEUTC_GenericToggle = ', GetUnitCommandFromCommandCap('RULEUTC_GenericToggle'))
LOG('RULEUTC_SpecialToggle = ', GetUnitCommandFromCommandCap('RULEUTC_SpecialToggle'))
LOG('RULEUTC_CloakToggle = ', GetUnitCommandFromCommandCap('RULEUTC_CloakToggle'))

Checklist

Changes are annotated, including comments where useful
Changes are documented in the changelog for the next game version

seems to not be referenced in any files?

---| and " instead of --- | and '

This is what you get from `GetUnitCommandFromCommandCap`

Specify every RULEUCC conversion Add the default "None" value Fix spelling

the comment was being set as the comment for the import on the line after it

Basically mprovements upon annotations in FAForever#5822 Co-Authored-By: (Jip) Willem Wijnia <[email protected]>

This reverts commit cc440f3.

Garanas · 2024-12-25T07:44:06Z

engine/Library.lua

@@ -73,6 +73,7 @@ end
 function debug.allocatedsize(obj)
 end

+--- Returns a cached table of all table allocations tracked between calls of `debug.trackallocations(true)` and `debug.trackallocations(false)`.


Oh, this is super interesting!

Garanas · 2024-12-25T07:45:01Z

engine/User.lua

+          RULEUCC_Invalid = None
+```]]
+---@param rule EngineCommandCap
+---@return string | "None"


You could turn this into a list of options instead of just a string.

Garanas

Looks like some much-needed documentation on the available tasks. I strongly believe there's still a world to discover here for the FAForever project 😄 !

4z0t · 2024-12-26T16:14:55Z

lua/sim/ScriptTask.lua

+---| -3 # Abort: "kill all tasks on this thread". Not implemented, usage will cause the unit to be stuck on the command.
+---| -4 # Delay: move task to end of this tick's task queue. There is no way to have multiple tasks per tick?
+---| 0 # Repeat execution immediately.
+---| 1+ # 1+: The task waits the given number of ticks. For example, the value `3` means the task waits for three ticks.


1+? Maybe +1?

"1+" means "1 or more". Also are you referring to the 1+ in the type or in the comment? The + symbol in the type doesn't actually do anything with intellisense, it doesn't even show up in the tooltip, so that's why I repeated "1+" in the comment.

4z0t · 2024-12-26T16:18:44Z

lua/sim/tasks/GiveTask.lua

@@ -3,12 +3,17 @@ local TASKSTATUS = import("/lua/sim/scripttask.lua").TASKSTATUS
 local GiveUnitsToPlayer = import("/lua/simutils.lua").GiveUnitsToPlayer
 local SpawnPing = import("/lua/simping.lua").SpawnPing

-local transferList =  {}
+local transferList = {}


There mustn't be global values like this in sim.

Can you elaborate?

Such tables tend to prevent from garbage collection entities that were already destroyed. Something like this really has to be weak or be defined within some other object like ai brain.

lua/system/utils.lua

4z0t · 2024-12-26T16:26:49Z

lua/sim/ScriptTask.lua

        self.CommandData = commandData
    end,

-    -- Called by the engine every tick. Function must return a value in TaskStatus
+    --- Called by the engine in an interval. Function must return a value in TaskStatus


Whether Function must return a value defined in TaskStatus or Function must return a value from TaskStatus.

Or simply Function must return TaskStatus

How about "Called by the engine at an interval determined by the returned TaskStatus value"?
The required return value is obvious from the @return and every script task using it, so I omitted it and added info about how the interval is determined.

its always nil anyway

lL1l1 and others added 15 commits December 20, 2024 18:17

Add all script task annotations

0309b05

Annotations related to the scry ability

58c71c5

Annotate table.merged

c040c18

Fix altCursor annotation

cc20071

seems to not be referenced in any files?

Change UserUnitCommand annotation formatting

b7145da

---| and " instead of --- | and '

Add the short versions of the UNITCOMMANDs

9f4d285

This is what you get from `GetUnitCommandFromCommandCap`

Improve annotation for GetUnitCommandFromCommandCap

2a1abca

Specify every RULEUCC conversion Add the default "None" value Fix spelling

Annotate IssueCommand, IssueUnitCommand

9150dee

Apply formatter

8dccdad

Apply formatter to the scry-related files

acedfe1

Add newline after copyright block

a61a303

the comment was being set as the comment for the import on the line after it

Add comment for debug.allocinfo

6629d31

Further documentation ScriptTask class behavior

26f48f1

Basically mprovements upon annotations in FAForever#5822 Co-Authored-By: (Jip) Willem Wijnia <[email protected]>

Add a test task with some other debug stuff

b5509fa

Revert "Add a test task with some other debug stuff"

8fb4df9

This reverts commit cc440f3.

lL1l1 added area: sim Area that is affected by the Simulation of the Game area: ui Anything to do with the User Interface of the Game type: intellisense labels Dec 21, 2024

lL1l1 added this to the Development I of 2025 milestone Dec 21, 2024

lL1l1 requested review from clyfordv, Garanas and Hdt80bro December 21, 2024 02:19

Create other.6596.md

c6b29fb

lL1l1 marked this pull request as ready for review December 21, 2024 02:24

Garanas reviewed Dec 25, 2024

View reviewed changes

Garanas approved these changes Dec 25, 2024

View reviewed changes

4z0t reviewed Dec 26, 2024

View reviewed changes

lua/system/utils.lua Outdated Show resolved Hide resolved

4z0t reviewed Dec 26, 2024

View reviewed changes

lL1l1 added 3 commits December 27, 2024 04:20

Improve TaskTick comment

b3449f7

Remove unused local in TargetLocation

63b9d68

its always nil anyway

Correct table.merged comment

4f7bcef

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Annotations related to script tasks #6596

Annotations related to script tasks #6596

lL1l1 commented Dec 21, 2024 •

edited

Loading

Garanas Dec 25, 2024

Garanas Dec 25, 2024

Garanas left a comment

4z0t Dec 26, 2024

lL1l1 Dec 27, 2024

4z0t Dec 26, 2024

lL1l1 Dec 27, 2024

4z0t Dec 27, 2024

4z0t Dec 26, 2024

4z0t Dec 26, 2024

lL1l1 Dec 27, 2024

Annotations related to script tasks #6596

Are you sure you want to change the base?

Annotations related to script tasks #6596

Conversation

lL1l1 commented Dec 21, 2024 • edited Loading

Description of the proposed changes

Testing done on the proposed changes

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Garanas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lL1l1 commented Dec 21, 2024 •

edited

Loading