Object lists: add datum struct and mention garbage collection

README.md

@@ -10,9 +10,9 @@ This repo contains the source content and build scripts for the Reclaimers Libra
 The library is not directly editable by its readers. This allows the editing team to verify information before it's added. However, we want and need the community's help filling in gaps. If you want to submit information or join the editing team, see the [Contributing page](https://c20.reclaimers.net/contributing).
 
 ## Development
-The codebase is essentially a [static site](https://en.wikipedia.org/wiki/Static_web_page) generator. We use [Gulp](https://gulpjs.com/) as the build task runner, with various tasks to process stylesheets, render pages, bundle JS ([esbuild](https://esbuild.github.io/)), and copy assets. All build results go into a `dist` folder that is ready to serve.
+The codebase is essentially a [static site](https://en.wikipedia.org/wiki/Static_web_page) generator. We use [Gulp](https://gulpjs.com/) as the build task runner, with various tasks to process stylesheets ([Sass](https://sass-lang.com/)), render pages, bundle JS ([esbuild](https://esbuild.github.io/)), and copy assets. All build results go into a `dist` folder that is ready to serve.
 
-Content is written in a combination of [Markdoc-flavoured markdown](https://markdoc.dev) and YAML files for structured data, which are rendered to HTML using [Preact](https://preactjs.com/) in TypeScript. Pages are also rendered in plaintext form and bundled into a client-side search index using [Minisearch](https://lucaong.github.io/minisearch/). We use [Sass](https://sass-lang.com/) as a CSS preprocessor.
+Content is written in a combination of [Markdoc-flavoured markdown](https://markdoc.dev) and YAML files for structured data, which are rendered to HTML using [Preact](https://preactjs.com/) in TypeScript. Pages are also rendered in plaintext form and bundled into a client-side search index using [Minisearch](https://lucaong.github.io/minisearch/).
 
 ### Building and testing
 In order to see content as it will appear online, you can run c20 in development mode. As a pre-requisite this project requires installing at least [Node.js v14+](https://nodejs.org/en/) and [Git LFS](https://git-lfs.github.com/).

src/content/h1/engine/game-state/readme.md

@@ -2,6 +2,7 @@
 title: Game state
 thanks:
   gbMichelle: Reversing stock table limits
+  Conscars: Reversing object list header datum
 ---
 **Game state** is the in-memory data which describes the state of the game world as it is simulated over time. It differs from [tags](~) which, although they are also [loaded into memory](~maps#map-loading), describe static or initial properties of classes of game objects rather than the current properties of individual ones.
 
@@ -25,7 +26,7 @@ Since the game world is dynamic, the datum count can rise up to a limit. The fol
 |[widget](~object#tag-field-widgets)|12|-|
 |[flag](~)|2|-|
 |[antenna](~)|12|24|
-|glow|8|-|Stores the state of [glow](~glow#glow-path) systems/paths. For example, the energy sword has 2 glow paths so up to 4 energy swords can be glowing.|
+|[glow](#glow-datum)|8|-|Stores the state of [glow](~glow#glow-path) systems/paths. For example, the energy sword has 2 glow paths so up to 4 energy swords can be glowing.|
 |glow particles|512|-|Stores the state of individual [glow particles](~glow#particle-types), like colour and position.|
 |[light volumes](~light_volume)|256|-|
 |[lightnings](~lightning)|256|-|
@@ -50,8 +51,8 @@ Since the game world is dynamic, the datum count can rise up to a limit. The fol
 |prop|768|-|Part of the [AI knowledge model](~ai#props) and stores a web of relationships between units like allies and enemies. Likely used when determining if actors have more enemies than allies nearby, if enemies are reachable, occluded, etc. Props can be visualized with `ai_render_props`.|
 |[encounter](~scenario#tag-field-encounters)|128|-|
 |ai pursuit|256|-|
-|object list header|48|-|
-|list object reference|128|-|
+|[object list header](#object-list-header-datum)|48|-|Stores object lists returned by scripting functions like `ai_actors`. These are reference-counted and periodically garbage collected.
+|list object reference|128|-|Stores object references belonging to object lists (above). These datums reference each other by ID to form linked lists.
 |[hs thread](~scripting#script-threads)|256|-|
 |hs globals|1024|-|Stores the state of HS globals, including [external globals](~scripting#external-globals), not just those in the level script.|
 |recorded animations|64|-|
@@ -68,5 +69,15 @@ Glow datums hold the state of [glows](~glow). For example, the gold Elite's ener
   id="glow-datum"
 /%}
 
+## Object list header datum
+
+{% structTable
+  entryModule="h1/gamestate/object_list_header_datum"
+  entryType="ObjectListHeaderDatum"
+  showOffsets=true
+  id="object-list-header-datum"
+/%}
+
+
 # Related HaloScript
 {% relatedHsc game="h1" tagFilter="game-state" /%}

src/content/h1/scripting/limits/readme.md

@@ -87,6 +87,9 @@ Strings used in scripts are also stored [in the scenario](~scenario#tag-field-sc
 
 The total amount of string data from all the scenario's scripts must remain below the limit.
 
+## Object lists
+When you generate object lists by calling functions like `ai_actors`, the list and its referenced objects are stored in the [game state](~game-state). The number of lists is limited to 48 while references total 128. If you request too many object lists per tick you may see the warning `no more script object lists; something bad will probably happen` in the console. To force unused lists to be garbage collected before the tick ends, you can call `garbage_collect_now`.
+
 ## Threads
 Although you can declare [512 or 1024 scripts](#script-declarations), the [game state](~game-state#datum-arrays) supports at most **256** running threads, which static scripts wouldn't contribute to.
 
@@ -126,4 +129,5 @@ There is not currently a reliable way to exactly tell when stack memory has been
 Things manually entered into the console ingame also share script space with the scenario's baked-in scripts. In rare circumstances (e.g. you're just on the cusp of using too much memory), a console script's memory can overflow into a scenario script's memory, causing the above mentioned issues.
 
 [rng]: https://en.wikipedia.org/wiki/Pseudorandom_number_generator
-[rng-seed]: https://en.wikipedia.org/wiki/Random_seed
+[rng-seed]: https://en.wikipedia.org/wiki/Random_seed
+[stack]: http://en.wikipedia.org/wiki/Call_stack

src/content/h1/scripting/readme.md

@@ -18,6 +18,7 @@ thanks:
   Ifafudafi: Script limits information
   InfernoPlus: Flipped vehicle test
   Krevil: Modulus operator
+  MattDratt: AI following the player tutorial
 redirects:
   - /h1/engine/scripting
 childOrder:
@@ -137,6 +138,5 @@ Some defunct parts of HaloScript were removed in H1A MCC. This is not a complete
 
 [Lisp]: https://en.wikipedia.org/wiki/Lisp_(programming_language)
 [c-format]: http://www.cplusplus.com/reference/cstdio/printf/
-[stack]: http://en.wikipedia.org/wiki/Call_stack
 [bitfield]: https://en.wikipedia.org/wiki/Bit_field
 [cast]: https://en.wikipedia.org/wiki/Type_conversion

src/data/hsc/h1/functions.yml

@@ -774,7 +774,8 @@ functions:
         ```
         Sets the follow target for an encounter to be the closest player. AI
         follow their target by [moving to firing positions](~ai#firing-positions)
-        near their target with the same letter label.
+        near their target with the same letter label. Note that the AI may need
+        to be migrated to follow the player through multiple sets of firing positions.
   - slug: ai_follow_target_unit
     info:
       en: |-
@@ -2436,15 +2437,12 @@ functions:
         the next
   - slug: garbage_collect_now
     info:
-      en: >-
+      en: |-
         ```hsc
-
         (<void> garbage_collect_now)
-
         ```
-
-        Causes all garbage objects except those visible to a player to be collected
-        immediately
+        Causes all dead [bipeds](~biped) and [garbage](~) objects except those
+        visible to a player to be collected (removed) immediately.
   - slug: get_digital_forward_throttle
     info:
       en: |-
@@ -3222,30 +3220,24 @@ functions:
         Attaches the second object to the first; both strings can be empty
   - slug: objects_can_see_flag
     info:
-      en: >-
+      en: |-
         ```hsc
-
         (<boolean> objects_can_see_flag <object_list> <cutscene_flag> <real>)
-
-        (objects_can_see_flag the_warthogs tunnel_flag 45)
-
+        (objects_can_see_flag (players) tunnel_flag 45)
         ```
-
         Returns `true` if any of the specified units are looking within the specified
-        number of degrees of the flag
+        number of degrees of the flag. This is a simple direction test; obstructions
+        like scenery or the BSP are not considered blockers.
   - slug: objects_can_see_object
     info:
-      en: >-
+      en: |-
         ```hsc
-
         (<boolean> objects_can_see_object <object_list> <object> <real>)
-
-        (objects_can_see_object the_warthogs (player0) 90)
-
+        (objects_can_see_object (player0) the_warthog 90)
         ```
-
         Returns `true` if any of the specified units are looking within the specified
-        number of degrees of the object
+        number of degrees of the object. This is a simple direction test; obstructions
+        like scenery or the BSP are not considered blockers.
   - slug: objects_delete_by_definition
     info:
       en: |-

src/data/hsc/h1/globals.yml

@@ -3681,7 +3681,7 @@ external_globals:
         (screenshot_size [short])
         ```
         Appears to set some kind of crop or scaling factor for generated screenshots,
-        but is probably not working as intended. Ssetting this to a value other than `1`
+        but is probably not working as intended. Setting this to a value other than `1`
         can crash when using `screenshot_size`.
   - slug: slow_server_startup_safety_zone_in_seconds
     info:

src/data/structs/h1/gamestate/glow_datum.yml

@@ -5,6 +5,7 @@ imports:
 type_defs:
   GlowDatum:
     class: struct
+    assert_size: 0x258
     endianness: little
     fields:
       - name: id

src/data/structs/h1/gamestate/object_list_header_datum.yml

@@ -0,0 +1,24 @@
+entry_type: ObjectListHeaderDatum
+imports:
+  h1/gamestate/common:
+    - DatumHeader
+type_defs:
+  ObjectListHeaderDatum:
+    class: struct
+    assert_size: 0xC
+    endianness: little
+    fields:
+      - name: id
+        type: DatumHeader
+      - type: pad
+        size: 2
+      - name: reference_count
+        type: uint16
+      - name: count
+        type: uint16
+      - name: list_object_reference_id
+        type: uint16
+        comments:
+          en: ID of the first (or last?) element of this list, from the list object reference datum array.
+      - type: pad
+        size: 2