Added Lua definitions for autocomplete in visual studio code

autogen/common.py

@@ -124,6 +124,8 @@ def translate_type_to_lua(ptype):
     if ptype == 'char*' or ('char' in ptype and '[' in ptype):
         return '`string`', None
 
+    ptype = ptype.replace('const ', '')
+
     if 'Vec3' in ptype:
         return ptype, 'structs.md#%s' % ptype
 
@@ -136,6 +138,18 @@ def translate_type_to_lua(ptype):
         else:
             return '`integer`', None
 
+    if ptype == 'char':
+        return '`integer`', None
+
+    if ptype == 'int':
+        return '`integer`', None
+
+    if ptype == 'float':
+        return '`number`', None
+
+    if ptype == 'bool':
+        return '`boolean`', None
+
     if 'void' == ptype:
         return None, None
 
@@ -161,3 +175,10 @@ def gen_comment_header(f):
     s += ""   + comment_l + "\n"
     s += "\n"
     return s
+
+def translate_to_def(ptype):
+    if ptype == None:
+        return 'nil'
+    if 'Lua Function' in ptype:
+        return 'function'
+    return ptype.replace('enum ', '').replace('const ', '').replace(' ', '').replace('`', '').replace('<', '_').replace('>', '')

autogen/convert_constants.py

@@ -6,6 +6,7 @@ from extract_constants import *
 in_filename = 'autogen/lua_constants/built-in.lua'
 out_filename = 'src/pc/lua/smlua_constants_autogen.c'
 out_filename_docs = 'docs/lua/constants.md'
+out_filename_defs = 'autogen/lua_definitions/constants.lua'
 
 in_files = [
     "include/types.h",
@@ -292,6 +293,42 @@ def doc_files(processed_files):
 
 ############################################################################
 
+def def_constant(processed_constant):
+    constants = processed_constant
+    s = ''
+
+    is_enum = 'identifier' in processed_constant
+    if is_enum:
+        s += '\n--- @class %s\n' % translate_to_def(processed_constant['identifier'])
+        constants = processed_constant['constants']
+        if len(constants) == 0:
+            return ''
+        for c in constants:
+            s += '\n--- @type %s\n' % translate_to_def(processed_constant['identifier'])
+            s += '%s = %s\n' % (c[0], c[1])
+        return s
+
+    for c in [processed_constant]:
+        s += '\n--- @type integer\n'
+        s += '%s = %s\n' % (c[0], c[1])
+
+    return s
+
+def build_to_def(processed_files):
+    s = '-- AUTOGENERATED FOR CODE EDITORS --\n\n'
+    with open(get_path(in_filename), 'r') as f:
+        s += f.read()
+        s += '\n'
+
+    for file in processed_files:
+        constants = sorted(file['constants'], key=lambda d: 'zzz' + d['identifier'] if 'identifier' in d else d[0])
+        for c in constants:
+            s += def_constant(c)
+
+    return s
+
+############################################################################
+
 def main():
     processed_files = process_files()
     built_files = build_files(processed_files)
@@ -306,6 +343,10 @@ def main():
     with open(get_path(out_filename_docs), 'w') as out:
         out.write(doc)
 
+    defs = build_to_def(processed_files)
+    with open(get_path(out_filename_defs), 'w') as out:
+        out.write(defs)
+
     global totalConstants
     print("Total constants: " + str(totalConstants))
 

autogen/convert_functions.py

@@ -8,7 +8,8 @@ integer_types = ["u8", "u16", "u32", "u64", "s8", "s16", "s32", "s64", "int"]
 number_types = ["f32", "float"]
 param_override_build = {}
 out_filename = 'src/pc/lua/smlua_functions_autogen.c'
-docs_lua_functions = 'docs/lua/functions.md'
+out_filename_docs = 'docs/lua/functions.md'
+out_filename_defs = 'autogen/lua_definitions/functions.lua'
 
 in_files = [
     "src/audio/external.h",
@@ -599,7 +600,56 @@ def doc_files(processed_files):
         s += '\n# functions from %s\n\n<br />\n\n' % processed_file['filename']
         s += doc_functions(processed_file['functions'])
 
-    with open(get_path(docs_lua_functions), 'w') as out:
+    with open(get_path(out_filename_docs), 'w') as out:
+        out.write(s)
+
+############################################################################
+
+def_pointers = []
+
+def def_function(function):
+    s = ''
+    if not function['implemented']:
+        return ''
+
+    fid = function['identifier']
+    rtype, rlink = translate_type_to_lua(function['type'])
+    param_str = ', '.join([x['identifier'] for x in function['params']])
+
+    if rtype == None:
+        rtype = 'nil'
+
+    for param in function['params']:
+        pid = param['identifier']
+        ptype = param['type']
+        ptype, plink = translate_type_to_lua(ptype)
+
+        ptype = translate_to_def(ptype)
+        if ptype.startswith('Pointer_') and ptype not in def_pointers:
+            def_pointers.append(ptype)
+
+        s += '--- @param %s %s\n' % (pid, ptype)
+
+    rtype = translate_to_def(rtype)
+    if rtype.startswith('Pointer_') and rtype not in def_pointers:
+        def_pointers.append(rtype)
+
+    s += '--- @return %s\n' % rtype
+    s += "function %s(%s)\n    -- ...\nend\n\n" % (fid, param_str)
+
+    return s
+
+
+def def_files(processed_files):
+    s = '-- AUTOGENERATED FOR CODE EDITORS --\n\n'
+    for processed_file in processed_files:
+        for function in processed_file['functions']:
+            s += def_function(function)
+
+    for def_pointer in def_pointers:
+        s += '--- @class %s\n' % def_pointer
+
+    with open(get_path(out_filename_defs), 'w') as out:
         out.write(s)
 
 ############################################################################
@@ -624,6 +674,7 @@ def main():
     print('REJECTS:\n%s' % rejects)
 
     doc_files(processed_files)
+    def_files(processed_files)
 
     global total_functions
     print('Total functions: ' + str(total_functions))

autogen/convert_structs.py

@@ -21,8 +21,10 @@ in_files = [
     'src/game/spawn_sound.h',
 ]
 
-smlua_cobject_autogen = 'src/pc/lua/smlua_cobject_autogen'
-docs_lua_structs = 'docs/lua/structs.md'
+out_filename_c = 'src/pc/lua/smlua_cobject_autogen.c'
+out_filename_h = 'src/pc/lua/smlua_cobject_autogen.h'
+out_filename_docs = 'docs/lua/structs.md'
+out_filename_defs = 'autogen/lua_definitions/structs.lua'
 
 c_template = """/* THIS FILE IS AUTOGENERATED */
 /* SHOULD NOT BE MANUALLY CHANGED */
@@ -388,7 +390,51 @@ def doc_structs(structs):
             continue
         s += doc_struct(struct) + '\n'
 
-    with open(get_path(docs_lua_structs), 'w') as out:
+    with open(get_path(out_filename_docs), 'w') as out:
+        out.write(s)
+
+############################################################################
+
+def_pointers = []
+
+def def_struct(struct):
+    sid = struct['identifier']
+
+    stype = translate_to_def(sid)
+    if stype.startswith('Pointer_') and stype not in def_pointers:
+        def_pointers.append(stype)
+
+    s = '\n--- @class %s\n' % stype
+
+    for field in struct['fields']:
+        fid, ftype, fimmutable, lvt, lot = get_struct_field_info(struct, field)
+
+        if '???' in lvt or '???' in lot:
+            continue
+
+        ftype, flink = translate_type_to_lua(ftype)
+
+        ftype = translate_to_def(ftype)
+        if ftype.startswith('Pointer_') and ftype not in def_pointers:
+            def_pointers.append(ftype)
+
+        s += '--- @field public %s %s\n' % (fid, ftype)
+
+    return s
+
+def def_structs(structs):
+    s = '-- AUTOGENERATED FOR CODE EDITORS --\n'
+
+    for struct in structs:
+        if struct['identifier'] in exclude_structs:
+            continue
+        s += def_struct(struct)
+
+    s += '\n'
+    for def_pointer in def_pointers:
+        s += '--- @class %s\n' % def_pointer
+
+    with open(get_path(out_filename_defs), 'w') as out:
         out.write(s)
 
 ############################################################################
@@ -406,15 +452,16 @@ def build_files():
     built_enum = build_lot_enum()
     built_include = build_includes()
 
-    out_c_filename = get_path(smlua_cobject_autogen + '.c')
+    out_c_filename = get_path(out_filename_c)
     with open(out_c_filename, 'w') as out:
         out.write(c_template.replace("$[BODY]", built_body).replace('$[INCLUDES]', built_include))
 
-    out_h_filename = get_path(smlua_cobject_autogen + '.h')
+    out_h_filename = get_path(out_filename_h)
     with open(out_h_filename, 'w') as out:
         out.write(h_template.replace("$[BODY]", built_enum))
 
     doc_structs(parsed)
+    def_structs(parsed)
 
     global total_structs
     global total_fields

autogen/lua_constants/built-in.lua

@@ -45,6 +45,9 @@ _ReadOnlyTable = {
     end
 }
 
+--- @param dest Vec3f
+--- @param src Vec3f
+--- @return Vec3f
 function vec3f_copy(dest, src)
     dest.x = src.x
     dest.y = src.y
@@ -52,6 +55,11 @@ function vec3f_copy(dest, src)
     return dest
 end
 
+--- @param dest Vec3f
+--- @param x number
+--- @param y number
+--- @param z number
+--- @return Vec3f
 function vec3f_set(dest, x, y, z)
     dest.x = x
     dest.y = y
@@ -59,6 +67,9 @@ function vec3f_set(dest, x, y, z)
     return dest
 end
 
+--- @param dest Vec3f
+--- @param a Vec3f
+--- @return Vec3f
 function vec3f_add(dest, a)
     dest.x = dest.x + a.x
     dest.y = dest.y + a.y
@@ -66,6 +77,10 @@ function vec3f_add(dest, a)
     return dest
 end
 
+--- @param dest Vec3f
+--- @param a Vec3f
+--- @param b Vec3f
+--- @return Vec3f
 function vec3f_sum(dest, a, b)
     dest.x = a.x + b.x
     dest.y = a.y + b.y
@@ -73,6 +88,9 @@ function vec3f_sum(dest, a, b)
     return dest
 end
 
+--- @param dest Vec3f
+--- @param a number
+--- @return Vec3f
 function vec3f_mul(dest, a)
     dest.x = dest.x * a
     dest.y = dest.y * a
@@ -80,6 +98,8 @@ function vec3f_mul(dest, a)
     return dest
 end
 
+--- @param dest Vec3f
+--- @return Vec3f
 function vec3f_normalize(dest)
     local divisor = math.sqrt(dest.x * dest.x + dest.y * dest.y + dest.z * dest.z)
     if divisor == 0 then
@@ -94,14 +114,22 @@ function vec3f_normalize(dest)
     return dest
 end
 
+--- @param a Vec3f
+--- @return number
 function vec3f_length(a)
     return math.sqrt(a.x * a.x + a.y * a.y + a.z * a.z)
 end
 
+--- @param a Vec3f
+--- @param b Vec3f
+--- @return number
 function vec3f_dot(a, b)
     return a.x * b.x + a.y * b.y + a.z * b.z
 end
 
+--- @param vec Vec3f
+--- @param onto Vec3f
+--- @return Vec3f
 function vec3f_project(vec, onto)
   local numerator = vec3f_dot(vec, onto)
   local denominator = vec3f_dot(onto, onto)
@@ -111,6 +139,9 @@ function vec3f_project(vec, onto)
   return out
 end
 
+--- @param v1 Vec3f
+--- @param v2 Vec3f
+--- @return number
 function vec3f_dist(v1, v2)
     dx = v1.x - v2.x
     dy = v1.y - v2.y
@@ -118,6 +149,9 @@ function vec3f_dist(v1, v2)
     return math.sqrt(dx * dx + dy * dy + dz * dz)
 end
 
+--- @param dest Vec3s
+--- @param src Vec3s
+--- @return Vec3s
 function vec3s_copy(dest, src)
     dest.x = src.x
     dest.y = src.y
@@ -125,6 +159,11 @@ function vec3s_copy(dest, src)
     return dest
 end
 
+--- @param dest Vec3s
+--- @param x number
+--- @param y number
+--- @param z number
+--- @return Vec3s
 function vec3s_set(dest, x, y, z)
     dest.x = x
     dest.y = y
@@ -132,6 +171,9 @@ function vec3s_set(dest, x, y, z)
     return dest
 end
 
+--- @param dest Vec3s
+--- @param a Vec3s
+--- @return Vec3s
 function vec3s_add(dest, a)
     dest.x = dest.x + a.x
     dest.y = dest.y + a.y
@@ -139,6 +181,10 @@ function vec3s_add(dest, a)
     return dest
 end
 
+--- @param dest Vec3s
+--- @param a Vec3s
+--- @param b Vec3s
+--- @return Vec3s
 function vec3s_sum(dest, a, b)
     dest.x = a.x + b.x
     dest.y = a.y + b.y
@@ -146,6 +192,9 @@ function vec3s_sum(dest, a, b)
     return dest
 end
 
+--- @param dest Vec3s
+--- @param a number
+--- @return Vec3s
 function vec3s_mul(dest, a)
     dest.x = dest.x * a
     dest.y = dest.y * a
@@ -153,6 +202,9 @@ function vec3s_mul(dest, a)
     return dest
 end
 
+--- @param v1 Vec3s
+--- @param v2 Vec3s
+--- @return number
 function vec3s_dist(v1, v2)
     dx = v1.x - v2.x
     dy = v1.y - v2.y
@@ -160,6 +212,11 @@ function vec3s_dist(v1, v2)
     return math.sqrt(dx * dx + dy * dy + dz * dz)
 end
 
+--- @param current number
+--- @param target number
+--- @param inc number
+--- @param dec number
+--- @return number
 function approach_f32(current, target, inc, dec)
     if current < target then
         current = current + inc
@@ -175,6 +232,11 @@ function approach_f32(current, target, inc, dec)
     return current;
 end
 
+--- @param current number
+--- @param target number
+--- @param inc number
+--- @param dec number
+--- @return number
 function approach_s32(current, target, inc, dec)
     if current < target then
         current = current + inc
@@ -190,6 +252,12 @@ function approach_s32(current, target, inc, dec)
     return current;
 end
 
+--- @param bank number
+--- @param playFlags number
+--- @param soundID number
+--- @param priority number
+--- @param flags2 number
+--- @return number
 function SOUND_ARG_LOAD(bank, playFlags, soundID, priority, flags2)
     return ((bank << 28) | (playFlags << 24) | (soundID << 16) | (priority << 8) | (flags2 << 4) | 1)
 end

autogen/lua_definitions/manual.lua

@@ -0,0 +1,116 @@
+-------------
+-- globals --
+-------------
+
+--- @type MarioState[]
+gMarioStates = {}
+
+--- @type NetworkPlayer[]
+gNetworkPlayers = {}
+
+--- @type Character[]
+gCharacter = {}
+
+--- @type GlobalTextures
+gTextures = {}
+
+--- @type GlobalObjectAnimations
+gObjectAnimations = {}
+
+--- @type GlobalObjectCollisionData
+gGlobalObjectCollisionData = {}
+
+--- @alias SyncTable table
+
+--- @type SyncTable
+gGlobalSyncTable = {}
+
+--- @type SyncTable[]
+gPlayerSyncTable = {}
+
+-----------
+-- hooks --
+-----------
+
+--- @param behaviorId BehaviorId
+--- @param objectList ObjectList
+--- @param replaceBehavior boolean
+--- @param initFunction fun(obj:Object)
+--- @param loopFunction fun(obj:Object)
+--- @return BehaviorId
+function hook_behavior(behaviorId, objectList, replaceBehavior, initFunction, loopFunction)
+    -- ...
+end
+
+--- @param command string
+--- @param description string
+--- @param func fun(msg:string)
+function hook_chat_command(command, description, func)
+    -- ...
+end
+
+--- @param hookEventType LuaHookedEventType
+--- @param func function
+function hook_event(hookEventType, func)
+    -- ...
+end
+
+--- @param actionId integer
+--- @param func fun(m:MarioState):integer
+--- @param interactionType InteractionFlag
+function hook_mario_action(actionId, func, interactionType)
+    -- ...
+end
+
+--- @param syncTable SyncTable
+--- @param field any
+--- @param tag any
+--- @param func fun(tag:any, oldVal:any, newVal:any)
+function hook_on_sync_table_change(syncTable, field, tag, func)
+    -- ...
+end
+
+---------------
+-- functions --
+---------------
+
+--- @param t number
+--- @return number
+function sins(t)
+    -- ...
+end
+
+--- @param t number
+--- @return number
+function coss(t)
+    -- ...
+end
+
+--- @param y number
+--- @param x number
+--- @return integer
+function atan2s(y, x)
+    -- ...
+end
+
+--- @param objFieldTable table
+--- @return nil
+function define_custom_obj_fields(objFieldTable)
+    -- ...
+end
+
+--- @param object Object
+--- @param standardSync boolean
+--- @param fieldTable table
+--- @return nil
+function network_init_object(object, standardSync, fieldTable)
+    -- ...
+end
+
+--- @param object Object
+--- @param reliable boolean
+--- @return nil
+function network_send_object(object, reliable)
+    -- ...
+end
+

docs/lua/functions.md

@@ -1236,9 +1236,9 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 | Field | Type |
 | ----- | ---- |
 | message | `string` |
-| x | `float` |
-| y | `float` |
-| scale | `float` |
+| x | `number` |
+| y | `number` |
+| scale | `number` |
 
 ### Returns
 - None
@@ -1375,7 +1375,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 | Field | Type |
 | ----- | ---- |
 | message | `string` |
-| lines | `int` |
+| lines | `integer` |
 
 ### Returns
 - None
@@ -2292,7 +2292,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 ## [mario_can_bubble](#mario_can_bubble)
 
 ### Lua Example
-`local boolValue = mario_can_bubble(m)`
+`local booleanValue = mario_can_bubble(m)`
 
 ### Parameters
 | Field | Type |
@@ -2300,7 +2300,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 | m | [MarioState](structs.md#MarioState) |
 
 ### Returns
-- `bool`
+- `boolean`
 
 ### C Prototype
 `bool mario_can_bubble(struct MarioState* m);`
@@ -5467,13 +5467,13 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 ## [network_is_server](#network_is_server)
 
 ### Lua Example
-`local boolValue = network_is_server()`
+`local booleanValue = network_is_server()`
 
 ### Parameters
 - None
 
 ### Returns
-- `bool`
+- `boolean`
 
 ### C Prototype
 `bool network_is_server(void);`
@@ -11528,7 +11528,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 ## [warp_exit_level](#warp_exit_level)
 
 ### Lua Example
-`local boolValue = warp_exit_level(aDelay)`
+`local booleanValue = warp_exit_level(aDelay)`
 
 ### Parameters
 | Field | Type |
@@ -11536,7 +11536,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 | aDelay | `integer` |
 
 ### Returns
-- `bool`
+- `boolean`
 
 ### C Prototype
 `bool warp_exit_level(s32 aDelay);`
@@ -11548,13 +11548,13 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 ## [warp_restart_level](#warp_restart_level)
 
 ### Lua Example
-`local boolValue = warp_restart_level()`
+`local booleanValue = warp_restart_level()`
 
 ### Parameters
 - None
 
 ### Returns
-- `bool`
+- `boolean`
 
 ### C Prototype
 `bool warp_restart_level(void);`
@@ -11566,7 +11566,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 ## [warp_to_castle](#warp_to_castle)
 
 ### Lua Example
-`local boolValue = warp_to_castle(aLevel)`
+`local booleanValue = warp_to_castle(aLevel)`
 
 ### Parameters
 | Field | Type |
@@ -11574,7 +11574,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 | aLevel | `integer` |
 
 ### Returns
-- `bool`
+- `boolean`
 
 ### C Prototype
 `bool warp_to_castle(s32 aLevel);`
@@ -11586,7 +11586,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 ## [warp_to_level](#warp_to_level)
 
 ### Lua Example
-`local boolValue = warp_to_level(aLevel, aArea, aAct)`
+`local booleanValue = warp_to_level(aLevel, aArea, aAct)`
 
 ### Parameters
 | Field | Type |
@@ -11596,7 +11596,7 @@ The `reliable` field will ensure that the packet arrives, but should be used spa
 | aAct | `integer` |
 
 ### Returns
-- `bool`
+- `boolean`
 
 ### C Prototype
 `bool warp_to_level(s32 aLevel, s32 aArea, s32 aAct);`

docs/lua/structs.md

@@ -236,7 +236,7 @@
 | capMetalWingModelId | `integer` | read-only |
 | capModelId | `integer` | read-only |
 | capWingModelId | `integer` | read-only |
-| hudHead | `char` | read-only |
+| hudHead | `integer` | read-only |
 | hudHeadTexture | [TextureInfo](structs.md#TextureInfo) | read-only |
 | modelId | `integer` | read-only |
 | name | `string` | read-only |
@@ -816,14 +816,14 @@
 
 | Field | Type | Access |
 | ----- | ---- | ------ |
-| connected | `bool` | read-only |
+| connected | `boolean` | read-only |
 | currActNum | `integer` | read-only |
 | currAreaIndex | `integer` | read-only |
-| currAreaSyncValid | `bool` | read-only |
+| currAreaSyncValid | `boolean` | read-only |
 | currCourseNum | `integer` | read-only |
 | currLevelAreaSeqId | `integer` | read-only |
 | currLevelNum | `integer` | read-only |
-| currLevelSyncValid | `bool` | read-only |
+| currLevelSyncValid | `boolean` | read-only |
 | description | `string` | read-only |
 | descriptionA | `integer` | read-only |
 | descriptionB | `integer` | read-only |
@@ -1818,10 +1818,10 @@
 
 | Field | Type | Access |
 | ----- | ---- | ------ |
-| bitSize | `const u8` | read-only |
-| height | `const u32` | read-only |
+| bitSize | `integer` | read-only |
+| height | `integer` | read-only |
 | texture | `Pointer` <`integer`> | read-only |
-| width | `const u32` | read-only |
+| width | `integer` | read-only |
 
 [:arrow_up_small:](#)
 
@@ -1849,9 +1849,9 @@
 
 | Field | Type | Access |
 | ----- | ---- | ------ |
-| x | `float` |  |
-| y | `float` |  |
-| z | `float` |  |
+| x | `number` |  |
+| y | `number` |  |
+| z | `number` |  |
 
 [:arrow_up_small:](#)
 

mods/football.lua

@@ -163,6 +163,7 @@ define_custom_obj_fields({
     oFrozen = 'u32',
 })
 
+--- @param obj Object
 function bhv_ball_particle_trail(obj)
     local spi = obj_get_temp_spawn_particles_info(E_MODEL_SPARKLES)
     if spi == nil then
@@ -184,6 +185,7 @@ function bhv_ball_particle_trail(obj)
     cur_obj_spawn_particles(spi)
 end
 
+--- @param obj Object
 function bhv_ball_particle_bounce(obj)
     local spi = obj_get_temp_spawn_particles_info(E_MODEL_MIST)
     if spi == nil then
@@ -205,6 +207,7 @@ function bhv_ball_particle_bounce(obj)
     cur_obj_spawn_particles(spi)
 end
 
+--- @param obj Object
 function bhv_ball_init(obj)
     -- flags and such
     obj.oFlags = OBJ_FLAG_UPDATE_GFX_POS_AND_ANGLE
@@ -244,6 +247,7 @@ function bhv_ball_init(obj)
     })
 end
 
+--- @param obj Object
 function bhv_ball_player_collision(obj)
     local alterPos = { x = 0, y = 0, z = 0}
 
@@ -434,6 +438,8 @@ function bhv_ball_player_collision(obj)
     return alterPos
 end
 
+--- @param obj Object
+--- @param offset Vec3f
 function bhv_ball_resolve(obj, offset)
     local a   = { x = obj.oPosX + 0, y = obj.oPosY + 0, z = obj.oPosZ + 0 }
     local dir = { x = offset.x * -1.0, y = offset.y * -1.0, z = offset.z * -1.0}
@@ -450,6 +456,7 @@ function bhv_ball_resolve(obj, offset)
     return { x = info.surface.normal.x, y = info.surface.normal.y, z = info.surface.normal.z }
 end
 
+--- @param obj Object
 function bhv_ball_loop(obj)
     if obj.oFrozen ~= 0 then
         return
@@ -1026,6 +1033,7 @@ function gamemode_update()
     end
 end
 
+--- @param m MarioState
 function on_player_connected(m)
     -- only run on server
     if not network_is_server() then
@@ -1160,6 +1168,7 @@ end
 -- update stuff --
 ------------------
 
+--- @param m MarioState
 function mario_update_local(m)
     local np = gNetworkPlayers[m.playerIndex]
     local s = gPlayerSyncTable[m.playerIndex]
@@ -1231,6 +1240,7 @@ function mario_update_local(m)
     end
 end
 
+--- @param m MarioState
 function mario_update(m)
     if m.playerIndex == 0 then
         mario_update_local(m)

src/pc/lua/smlua_constants_autogen.c

@@ -42,36 +42,56 @@ char gSmluaConstants[] = ""
 "    __newindex = function (t,k,v)\n"
 "    end\n"
 "}\n"
+"--- @param dest Vec3f\n"
+"--- @param src Vec3f\n"
+"--- @return Vec3f\n"
 "function vec3f_copy(dest, src)\n"
 "    dest.x = src.x\n"
 "    dest.y = src.y\n"
 "    dest.z = src.z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3f\n"
+"--- @param x number\n"
+"--- @param y number\n"
+"--- @param z number\n"
+"--- @return Vec3f\n"
 "function vec3f_set(dest, x, y, z)\n"
 "    dest.x = x\n"
 "    dest.y = y\n"
 "    dest.z = z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3f\n"
+"--- @param a Vec3f\n"
+"--- @return Vec3f\n"
 "function vec3f_add(dest, a)\n"
 "    dest.x = dest.x + a.x\n"
 "    dest.y = dest.y + a.y\n"
 "    dest.z = dest.z + a.z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3f\n"
+"--- @param a Vec3f\n"
+"--- @param b Vec3f\n"
+"--- @return Vec3f\n"
 "function vec3f_sum(dest, a, b)\n"
 "    dest.x = a.x + b.x\n"
 "    dest.y = a.y + b.y\n"
 "    dest.z = a.z + b.z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3f\n"
+"--- @param a number\n"
+"--- @return Vec3f\n"
 "function vec3f_mul(dest, a)\n"
 "    dest.x = dest.x * a\n"
 "    dest.y = dest.y * a\n"
 "    dest.z = dest.z * a\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3f\n"
+"--- @return Vec3f\n"
 "function vec3f_normalize(dest)\n"
 "    local divisor = math.sqrt(dest.x * dest.x + dest.y * dest.y + dest.z * dest.z)\n"
 "    if divisor == 0 then\n"
@@ -83,12 +103,20 @@ char gSmluaConstants[] = ""
 "    dest.z = dest.z * invsqrt\n"
 "    return dest\n"
 "end\n"
+"--- @param a Vec3f\n"
+"--- @return number\n"
 "function vec3f_length(a)\n"
 "    return math.sqrt(a.x * a.x + a.y * a.y + a.z * a.z)\n"
 "end\n"
+"--- @param a Vec3f\n"
+"--- @param b Vec3f\n"
+"--- @return number\n"
 "function vec3f_dot(a, b)\n"
 "    return a.x * b.x + a.y * b.y + a.z * b.z\n"
 "end\n"
+"--- @param vec Vec3f\n"
+"--- @param onto Vec3f\n"
+"--- @return Vec3f\n"
 "function vec3f_project(vec, onto)\n"
 "  local numerator = vec3f_dot(vec, onto)\n"
 "  local denominator = vec3f_dot(onto, onto)\n"
@@ -97,48 +125,77 @@ char gSmluaConstants[] = ""
 "  vec3f_mul(out, numerator / denominator)\n"
 "  return out\n"
 "end\n"
+"--- @param v1 Vec3f\n"
+"--- @param v2 Vec3f\n"
+"--- @return number\n"
 "function vec3f_dist(v1, v2)\n"
 "    dx = v1.x - v2.x\n"
 "    dy = v1.y - v2.y\n"
 "    dz = v1.z - v2.z\n"
 "    return math.sqrt(dx * dx + dy * dy + dz * dz)\n"
 "end\n"
+"--- @param dest Vec3s\n"
+"--- @param src Vec3s\n"
+"--- @return Vec3s\n"
 "function vec3s_copy(dest, src)\n"
 "    dest.x = src.x\n"
 "    dest.y = src.y\n"
 "    dest.z = src.z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3s\n"
+"--- @param x number\n"
+"--- @param y number\n"
+"--- @param z number\n"
+"--- @return Vec3s\n"
 "function vec3s_set(dest, x, y, z)\n"
 "    dest.x = x\n"
 "    dest.y = y\n"
 "    dest.z = z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3s\n"
+"--- @param a Vec3s\n"
+"--- @return Vec3s\n"
 "function vec3s_add(dest, a)\n"
 "    dest.x = dest.x + a.x\n"
 "    dest.y = dest.y + a.y\n"
 "    dest.z = dest.z + a.z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3s\n"
+"--- @param a Vec3s\n"
+"--- @param b Vec3s\n"
+"--- @return Vec3s\n"
 "function vec3s_sum(dest, a, b)\n"
 "    dest.x = a.x + b.x\n"
 "    dest.y = a.y + b.y\n"
 "    dest.z = a.z + b.z\n"
 "    return dest\n"
 "end\n"
+"--- @param dest Vec3s\n"
+"--- @param a number\n"
+"--- @return Vec3s\n"
 "function vec3s_mul(dest, a)\n"
 "    dest.x = dest.x * a\n"
 "    dest.y = dest.y * a\n"
 "    dest.z = dest.z * a\n"
 "    return dest\n"
 "end\n"
+"--- @param v1 Vec3s\n"
+"--- @param v2 Vec3s\n"
+"--- @return number\n"
 "function vec3s_dist(v1, v2)\n"
 "    dx = v1.x - v2.x\n"
 "    dy = v1.y - v2.y\n"
 "    dz = v1.z - v2.z\n"
 "    return math.sqrt(dx * dx + dy * dy + dz * dz)\n"
 "end\n"
+"--- @param current number\n"
+"--- @param target number\n"
+"--- @param inc number\n"
+"--- @param dec number\n"
+"--- @return number\n"
 "function approach_f32(current, target, inc, dec)\n"
 "    if current < target then\n"
 "        current = current + inc\n"
@@ -153,6 +210,11 @@ char gSmluaConstants[] = ""
 "    end\n"
 "    return current;\n"
 "end\n"
+"--- @param current number\n"
+"--- @param target number\n"
+"--- @param inc number\n"
+"--- @param dec number\n"
+"--- @return number\n"
 "function approach_s32(current, target, inc, dec)\n"
 "    if current < target then\n"
 "        current = current + inc\n"
@@ -167,6 +229,12 @@ char gSmluaConstants[] = ""
 "    end\n"
 "    return current;\n"
 "end\n"
+"--- @param bank number\n"
+"--- @param playFlags number\n"
+"--- @param soundID number\n"
+"--- @param priority number\n"
+"--- @param flags2 number\n"
+"--- @return number\n"
 "function SOUND_ARG_LOAD(bank, playFlags, soundID, priority, flags2)\n"
 "    return ((bank << 28) | (playFlags << 24) | (soundID << 16) | (priority << 8) | (flags2 << 4) | 1)\n"
 "end\n"