From 8ab2519da084e85c1df0db67f0f3913328542947 Mon Sep 17 00:00:00 2001 From: csauve Date: Wed, 17 Apr 2024 00:40:30 -0700 Subject: [PATCH] Object lists: add datum struct and mention garbage collection --- README.md | 4 +-- src/content/h1/engine/game-state/readme.md | 17 ++++++++-- src/content/h1/scripting/limits/readme.md | 6 +++- src/content/h1/scripting/readme.md | 2 +- src/data/hsc/h1/functions.yml | 34 +++++++------------ src/data/hsc/h1/globals.yml | 2 +- src/data/structs/h1/gamestate/glow_datum.yml | 1 + .../h1/gamestate/object_list_header_datum.yml | 24 +++++++++++++ 8 files changed, 61 insertions(+), 29 deletions(-) create mode 100644 src/data/structs/h1/gamestate/object_list_header_datum.yml diff --git a/README.md b/README.md index c6eb6add..2c1e5b1e 100644 --- a/README.md +++ b/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/). diff --git a/src/content/h1/engine/game-state/readme.md b/src/content/h1/engine/game-state/readme.md index afe8c1b4..1e827f2d 100644 --- a/src/content/h1/engine/game-state/readme.md +++ b/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" /%} \ No newline at end of file diff --git a/src/content/h1/scripting/limits/readme.md b/src/content/h1/scripting/limits/readme.md index c64fb110..45f3292c 100644 --- a/src/content/h1/scripting/limits/readme.md +++ b/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 \ No newline at end of file +[rng-seed]: https://en.wikipedia.org/wiki/Random_seed +[stack]: http://en.wikipedia.org/wiki/Call_stack \ No newline at end of file diff --git a/src/content/h1/scripting/readme.md b/src/content/h1/scripting/readme.md index b9db1e66..81bc338c 100644 --- a/src/content/h1/scripting/readme.md +++ b/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 diff --git a/src/data/hsc/h1/functions.yml b/src/data/hsc/h1/functions.yml index 7e13da8c..79b81cd7 100644 --- a/src/data/hsc/h1/functions.yml +++ b/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 - ( 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 - ( objects_can_see_flag ) - - (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 - ( objects_can_see_object ) - - (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: |- diff --git a/src/data/hsc/h1/globals.yml b/src/data/hsc/h1/globals.yml index 2919b373..0d76ee8c 100644 --- a/src/data/hsc/h1/globals.yml +++ b/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: diff --git a/src/data/structs/h1/gamestate/glow_datum.yml b/src/data/structs/h1/gamestate/glow_datum.yml index 6e3280eb..6f4ee602 100644 --- a/src/data/structs/h1/gamestate/glow_datum.yml +++ b/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 diff --git a/src/data/structs/h1/gamestate/object_list_header_datum.yml b/src/data/structs/h1/gamestate/object_list_header_datum.yml new file mode 100644 index 00000000..22bfcebf --- /dev/null +++ b/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 \ No newline at end of file