From 3242c4e7c8a73c44723b44414194ec83de175ed3 Mon Sep 17 00:00:00 2001
From: Sunk <69110309+Sunketchupm@users.noreply.github.com>
Date: Tue, 18 Jul 2023 18:00:35 -0400
Subject: [PATCH] Document manual.lua (#443)

* Properly set Mario's y vel to 0 on popping

* Change 0 to 0.0f, just in case

* Massively increase surface pool size

Also exposed the surface pool counts by creating a few functions to get them. They only existed for debugging but may as well keep them.

* Allow extended moveset to be toggled from a chat command

I got permission to edit extended moveset. Eventually I'll try to see if I can improve upon this moveset.

* Remove old surface code

Part 1

* Heavily document manual.lua

Hopefully nothing I added is wrong

* Small change in descriptions
---
 autogen/lua_definitions/manual.lua | 99 +++++++++++++++++++-----------
 1 file changed, 63 insertions(+), 36 deletions(-)

diff --git a/autogen/lua_definitions/manual.lua b/autogen/lua_definitions/manual.lua
index e7de31dd..c24e8c4d 100644
--- a/autogen/lua_definitions/manual.lua
+++ b/autogen/lua_definitions/manual.lua
@@ -3,12 +3,21 @@
 -------------
 
 --- @type MarioState[]
+--- Array of MarioStates, from 0 to MAX_PLAYERS - 1
+--- - Uses the local index, which is different between every player
+--- - Index 0 always refers to the local player
 gMarioStates = {}
 
 --- @type NetworkPlayer[]
+--- Array of NetworkPlayers, from 0 to MAX_PLAYERS - 1
+--- - Uses the local index, which is different between every player
+--- - Index 0 always refers to the local player
 gNetworkPlayers = {}
 
 --- @type Mod[]
+--- Array of all mods loaded, starting from 0
+--- - All mods are loaded in the same order for every player
+--- - Index 0 is the first mod in the list (The top of the mod list)
 gActiveMods = {}
 
 --- @type Character[]
@@ -26,9 +35,15 @@ gGlobalObjectCollisionData = {}
 --- @alias SyncTable table
 
 --- @type SyncTable
+--- Any keys added and modified to this table will be synced among everyone.
+--- - This shouldn't be used to sync player-specific values; Use gPlayerSyncTable for that
+--- - Note: Does not support tables as keys
 gGlobalSyncTable = {}
 
 --- @type SyncTable[]
+--- An array of sync tables. Any change to any sync tables will be synced to everyone else.
+--- - This array takes in a local index, however it automatically translates to the global index
+--- - Note: Does not support tables as keys
 gPlayerSyncTable = {}
 
 --- @type LevelValues
@@ -37,13 +52,12 @@ gLevelValues = {}
 --- @type BehaviorValues
 gBehaviorValues = {}
 
---- @type BehaviorValues
-gBehaviorValues = {}
-
 --- @type PlayerPalette[]
 gPalettePresets = {}
 
 --- @type LakituState
+--- The primary struct that controls the camera
+--- - Local player only
 gLakituState = {}
 
 --- @type PaintingValues
@@ -56,47 +70,57 @@ gServerSettings = {}
 -- hooks --
 -----------
 
---- @param behaviorId BehaviorId
---- @param objectList ObjectList
---- @param replaceBehavior boolean
---- @param initFunction fun(obj:Object)
---- @param loopFunction fun(obj:Object)
---- @param behaviorName string
---- @return BehaviorId
+--- @param behaviorId BehaviorId | integer?  The behavior id of the object to modify. Pass in as `nil` to create a custom object
+--- @param objectList ObjectList | integer Object list
+--- @param replaceBehavior boolean Whether or not to completely replace the behavior
+--- @param initFunction? fun(obj:Object) Run on object creation
+--- @param loopFunction? fun(obj:Object) Run every frame
+--- @param behaviorName? string Optional
+--- @return BehaviorId BehaviorId Use if creating a custom object, otherwise can be ignored
+--- Modify an object's behavior or create a new custom object
 function hook_behavior(behaviorId, objectList, replaceBehavior, initFunction, loopFunction, behaviorName)
     -- ...
 end
 
---- @param command string
---- @param description string
---- @param func fun(msg:string)
+--- @param command string The command to run. Should be easy to type
+--- @param description string Should describe what the command does and how to use it
+--- @param func fun(msg:string): boolean Run upon activating the command. Return `true` to confirm the command has succeeded
+--- @return nil
 function hook_chat_command(command, description, func)
     -- ...
 end
 
---- @param command string
---- @param description string
+--- @param command string The command to change the description of
+--- @param description string The description to change to
 function update_chat_command_description(command, description)
     -- ...
 end
 
---- @param hookEventType LuaHookedEventType
---- @param func function
+--- @param hookEventType LuaHookedEventType When a function should run
+--- @param func fun(...: any): any The function to run
+--- Different hooks can pass in different parameters and have different return values. Be sure to read the hooks guide for more information.
 function hook_event(hookEventType, func)
     -- ...
 end
 
---- @param actionId integer
---- @param funcOrFuncTable fun(m:MarioState):integer | table(fun(m:MarioState):integer)
---- @param interactionType InteractionFlag
+--- @class ActionTable
+    --- @field every_frame fun(m:MarioState):integer?
+    --- @field gravity fun(m:MarioState):integer?
+
+--- @param actionId integer The action to replace
+--- @param funcOrFuncTable fun(m:MarioState):integer? | ActionTable The new behavior of the action
+--- @param interactionType? InteractionFlag Optional; The flag that determines how the action interacts with other objects
+--- If a function table is used, it must be in the form of `{ act_hook = [func], ... }`. Current action hooks include:
+--- - every_frame
+--- - gravity
 function hook_mario_action(actionId, funcOrFuncTable, interactionType)
     -- ...
 end
 
---- @param syncTable SyncTable
---- @param field any
---- @param tag any
---- @param func fun(tag:any, oldVal:any, newVal:any)
+--- @param syncTable SyncTable Must be the gGlobalSyncTable or gPlayerSyncTable[] or one of their child tables
+--- @param field string Field name
+--- @param tag any An additional parameter
+--- @param func fun(tag:any, oldVal:any, newVal:any) Run when the specified field has been changed
 function hook_on_sync_table_change(syncTable, field, tag, func)
     -- ...
 end
@@ -124,16 +148,18 @@ function atan2s(y, x)
     -- ...
 end
 
---- @param objFieldTable table
+--- @param objFieldTable table<any, "u32"|"s32"|"f32">
 --- @return nil
+--- Keys must start with `o` and values must be `"u32"`, `"s32"`, or `"f32"`
 function define_custom_obj_fields(objFieldTable)
     -- ...
 end
 
---- @param object Object
---- @param standardSync boolean
---- @param fieldTable table
+--- @param object Object Object to sync
+--- @param standardSync boolean Automatically syncs common fields and syncs with distance. If `false`, all syncing must be done with `network_send_object`.
+--- @param fieldTable table<string> The fields to sync
 --- @return nil
+--- All synced fields must start with `o` and there should not be any keys, just values
 function network_init_object(object, standardSync, fieldTable)
     -- ...
 end
@@ -141,6 +167,7 @@ end
 --- @param object Object
 --- @param reliable boolean
 --- @return nil
+--- Sends a sync packet to sync up the object with everyone else
 function network_send_object(object, reliable)
     -- ...
 end
@@ -148,6 +175,7 @@ end
 --- @param reliable boolean
 --- @param dataTable table
 --- @return nil
+--- Note: `dataTable` can only contain strings, integers, numbers, booleans, and nil
 function network_send(reliable, dataTable)
     -- ...
 end
@@ -156,6 +184,7 @@ end
 --- @param reliable boolean
 --- @param dataTable table
 --- @return nil
+--- Note: `dataTable` can only contain strings, integers, numbers, booleans, and nil
 function network_send_to(toLocalIndex, reliable, dataTable)
     -- ...
 end
@@ -166,12 +195,6 @@ function get_texture_info(textureName)
     -- ...
 end
 
---- @param textureName string
---- @return TextureInfo
-function get_texture_info(textureName)
-    -- ...
-end
-
 --- @param texInfo TextureInfo
 --- @param x number
 --- @param y number
@@ -241,8 +264,12 @@ function smlua_anim_util_register_animation(name, flags, animYTransDivisor, star
     -- ...
 end
 
---- @param levelNum number
---- @param func fun(areaIndex:number, bhvData:table, macroBhvIds:table, macroBhvArgs:table)
+--- @class bhvData
+    --- @field behavior BehaviorId
+    --- @field behaviorArg integer
+
+--- @param levelNum LevelNum | integer
+--- @param func fun(areaIndex:number, bhvData:bhvData, macroBhvIds:BehaviorId[], macroBhvArgs:integer[])
 --- @return nil
 --- When `func` is called, arguments are filled depending on the level command:
 --- - `AREA` command: only `areaIndex` is filled. It's a number.