Add hook to docs, fix some crashes semi-related

autogen/lua_definitions/constants.lua

@@ -8213,8 +8213,8 @@ HOOK_ON_FIND_FLOOR                          = 62 --- @type LuaHookedEventType
 HOOK_ON_FIND_WATER_LEVEL                    = 63 --- @type LuaHookedEventType
 HOOK_ON_FIND_POISON_GAS_LEVEL               = 64 --- @type LuaHookedEventType
 HOOK_ON_FIND_SURFACE_ON_RAY                 = 65 --- @type LuaHookedEventType
-HOOK_BEFORE_PLAY_MODE_RUN                   = 66 --- @type LuaHookedEventType
-HOOK_ON_PLAY_MODE_RUN                       = 67 --- @type LuaHookedEventType
+HOOK_BEFORE_PLAY_MODE_UPDATE                = 66 --- @type LuaHookedEventType
+HOOK_ON_PLAY_MODE_UPDATE                    = 67 --- @type LuaHookedEventType
 HOOK_MAX                                    = 68 --- @type LuaHookedEventType
 
 --- @alias LuaHookedEventType
@@ -8284,8 +8284,8 @@ HOOK_MAX                                    = 68 --- @type LuaHookedEventType
 --- | `HOOK_ON_FIND_WATER_LEVEL`
 --- | `HOOK_ON_FIND_POISON_GAS_LEVEL`
 --- | `HOOK_ON_FIND_SURFACE_ON_RAY`
---- | `HOOK_BEFORE_PLAY_MODE_RUN`
---- | `HOOK_ON_PLAY_MODE_RUN`
+--- | `HOOK_BEFORE_PLAY_MODE_UPDATE`
+--- | `HOOK_ON_PLAY_MODE_UPDATE`
 --- | `HOOK_MAX`
 
 --- @type integer

docs/lua/constants.md

@@ -3543,8 +3543,8 @@
 | HOOK_ON_FIND_WATER_LEVEL | 63 |
 | HOOK_ON_FIND_POISON_GAS_LEVEL | 64 |
 | HOOK_ON_FIND_SURFACE_ON_RAY | 65 |
-| HOOK_BEFORE_PLAY_MODE_RUN | 66 |
-| HOOK_ON_PLAY_MODE_RUN | 67 |
+| HOOK_BEFORE_PLAY_MODE_UPDATE | 66 |
+| HOOK_ON_PLAY_MODE_UPDATE | 67 |
 | HOOK_MAX | 68 |
 - MAX_HOOKED_BEHAVIORS
 

docs/lua/guides/hooks.md

@@ -143,7 +143,7 @@ The lua functions sent to `hook_event()` will be automatically called by SM64 wh
 | HOOK_ON_GEO_PROCESS | Called when a GeoLayout is processed **Note:** You must set the `hookProcess` field of the graph node to a non-zero value | [GraphNode](../structs.md#GraphNode) graphNode, `integer` matStackIndex |
 | HOOK_BEFORE_GEO_PROCESS | Called before a GeoLayout is processed **Note:** You must set the `hookProcess` field of the graph node to a non-zero value | [GraphNode](../structs.md#GraphNode) graphNode, `integer` matStackIndex |
 | HOOK_ON_GEO_PROCESS_CHILDREN | Called when the children of a GeoLayout node is processed **Note:** You must set the `hookProcess` field of the parent graph node to a non-zero value | [GraphNode](../structs.md#GraphNode) graphNode, `integer` matStackIndex |
-| HOOK_MARIO_OVERRIDE_GEOMETRY_INPUTS | Called before running Mario's geometry input logic, return `false` to not run it. | [MarioState](../structs.md) m | 
+| HOOK_MARIO_OVERRIDE_GEOMETRY_INPUTS | Called before running Mario's geometry input logic, return `false` to not run it. | [MarioState](../structs.md) m |
 | HOOK_ON_INTERACTIONS | Called when the Mario interactions are processed | [MarioState](../structs.md#MarioState) mario |
 | HOOK_ALLOW_FORCE_WATER_ACTION | Called when executing a non-water action while under the water's surface, or vice versa. Return `false` to prevent the player from being forced out of the action at the water's surface | [MarioState](../structs.md#MarioState) mario, `boolean` isInWaterAction |
 | HOOK_BEFORE_WARP | Called before the local player warps. Return a table with `destLevel`, `destArea`, `destWarpNode`, to override the warp | `integer` destLevel, `integer` destArea, `integer` destWarpNode, `integer` arg |
@@ -157,6 +157,8 @@ The lua functions sent to `hook_event()` will be automatically called by SM64 wh
 | HOOK_ON_FIND_WATER_LEVEL | Called after water level detection completes. Return a number to override the water level | `number` x, `number` z, `number` waterLevel |
 | HOOK_ON_FIND_POISON_GAS_LEVEL | Called after poison gas level detection completes. Return a number to override the gas level | `number` x, `number` z, `number` gasLevel |
 | HOOK_ON_FIND_SURFACE_ON_RAY | Called after ray-surface intersection completes. Return `surface` to override the hit surface, or `surface, hitPos` to override both | `Vec3f` orig, `Vec3f` dir, [Surface](../structs.md#Surface) hitSurface, `Vec3f` hitPos |
+| HOOK_BEFORE_PLAY_MODE_UPDATE | Called before the play mode is ran. Return a number to override the play mode to be ran. | `number` playMode |
+| HOOK_ON_PLAY_MODE_UPDATE | Called after the play mode is ran. Return a number to override the change level. | `number` playMode |
 
 ### Parameters
 

src/game/behaviors/bbh_tilting_trap.inc.c

@@ -22,6 +22,7 @@ void bhv_bbh_tilting_trap_platform_loop(void) {
     u8 playersTouched = 0;
     for (s32 i = 0; i < MAX_PLAYERS; i++) {
         if (!is_player_active(&gMarioStates[i])) { continue; }
+        if (gMarioStates[i].marioObj == NULL) { continue; }
         if (gMarioStates[i].marioObj->platform == o) {
             x += gMarioStates[i].marioObj->oPosX;
             y += gMarioStates[i].marioObj->oPosY;

src/game/behaviors/controllable_platform.inc.c

@@ -183,6 +183,7 @@ void controllable_platform_tilt_from_mario(void) {
     f32 z = 0;
 
     for (s32 i = 0; i < MAX_PLAYERS; i++) {
+        if (gMarioStates[i].marioObj == NULL) { continue; }
         if (gMarioStates[i].marioObj->platform == o || gMarioStates[i].marioObj->platform == cur_obj_nearest_object_with_behavior(bhvControllablePlatformSub)) {
             x += gMarioStates[i].pos[0];
             z += gMarioStates[i].pos[2];

src/game/behaviors/dorrie.inc.c

@@ -136,6 +136,7 @@ void dorrie_act_raise_head(void) {
 
         for (s32 i = 0; i < MAX_PLAYERS; i++) {
             if (!is_player_active(&gMarioStates[i])) { continue; }
+            if (gMarioStates[i].marioObj == NULL) { continue; }
             if (gMarioStates[i].marioObj->platform != o) { continue; }
             s32 dist = dist_between_objects(o, gMarioStates[0].marioObj);
             if (dist <= 780.0f) { continue; }

src/game/behaviors/floating_platform.inc.c

@@ -23,6 +23,7 @@ void floating_platform_act_0(void) {
     u8 playersTouched = 0;
     for (s32 i = 0; i < MAX_PLAYERS; i++) {
         if (!is_player_active(&gMarioStates[i])) { continue; }
+        if (gMarioStates[i].marioObj == NULL) { continue; }
         if (gMarioStates[i].marioObj->platform == o) {
             x += gMarioStates[i].marioObj->oPosX;
             z += gMarioStates[i].marioObj->oPosZ;

src/game/behaviors/platform_on_track.inc.c

@@ -291,6 +291,7 @@ static void platform_on_track_rock_ski_lift(void) {
     struct Object* player = NULL;
     for (s32 i = 0; i < MAX_PLAYERS; i++) {
         if (!is_player_active(&gMarioStates[i])) { continue; }
+        if (gMarioStates[i].marioObj == NULL) { continue; }
         if (gMarioStates[i].marioObj->platform != o) { continue; }
         player = gMarioStates[i].marioObj;
         break;

src/game/behaviors/seesaw_platform.inc.c

@@ -51,6 +51,7 @@ void bhv_seesaw_platform_update(void) {
     u8 playersTouched = 0;
     for (s32 i = 0; i < MAX_PLAYERS; i++) {
         if (!is_player_active(&gMarioStates[i])) { continue; }
+        if (gMarioStates[i].marioObj == NULL) { continue; }
         if (gMarioStates[i].marioObj->platform == o) {
             x += gMarioStates[i].marioObj->oPosX;
             y += gMarioStates[i].marioObj->oPosY;

src/game/behaviors/tilting_inverted_pyramid.inc.c

@@ -87,6 +87,7 @@ void bhv_tilting_inverted_pyramid_loop(void) {
     u8 playersTouched = 0;
     for (s32 i = 0; i < MAX_PLAYERS; i++) {
         if (!is_player_active(&gMarioStates[i])) { continue; }
+        if (gMarioStates[i].marioObj == NULL) { continue; }
         if (gMarioStates[i].marioObj->platform != o) { continue; }
         x += gMarioStates[i].marioObj->oPosX;
         y += gMarioStates[i].marioObj->oPosY;
@@ -135,7 +136,7 @@ void bhv_tilting_inverted_pyramid_loop(void) {
         o->oTiltingPyramidMarioOnPlatform = FALSE;
     }
 
-    // Approach the normals by 0.01f towards the new goal, then create a transform matrix and orient the object. 
+    // Approach the normals by 0.01f towards the new goal, then create a transform matrix and orient the object.
     // Outside of the other conditionals since it needs to tilt regardless of whether Mario is on.
     o->oTiltingPyramidNormalX = approach_by_increment(dx, o->oTiltingPyramidNormalX, 0.01f);
     o->oTiltingPyramidNormalY = approach_by_increment(dy, o->oTiltingPyramidNormalY, 0.01f);

src/game/level_update.c

@@ -1508,7 +1508,7 @@ s32 run_current_play_mode() {
     s32 changeLevel = 0;
 
     s16 hookPlaymode = sCurrPlayMode;
-    if (smlua_call_event_hooks(HOOK_BEFORE_PLAY_MODE_RUN, sCurrPlayMode, &hookPlaymode)) {
+    if (smlua_call_event_hooks(HOOK_BEFORE_PLAY_MODE_UPDATE, sCurrPlayMode, &hookPlaymode)) {
         sCurrPlayMode = hookPlaymode;
     }
 
@@ -1535,7 +1535,10 @@ s32 run_current_play_mode() {
             changeLevel = play_mode_frame_advance();
             break;
     }
-    smlua_call_event_hooks(HOOK_ON_PLAY_MODE_RUN, sCurrPlayMode);
+    s32 hookChangeLevel = changeLevel;
+    if (smlua_call_event_hooks(HOOK_ON_PLAY_MODE_UPDATE, sCurrPlayMode, &hookChangeLevel)) {
+        changeLevel = hookChangeLevel;
+    }
     return changeLevel;
 }
 

src/pc/lua/smlua_constants_autogen.c

@@ -3553,8 +3553,8 @@ char gSmluaConstants[] = ""
 "HOOK_ON_FIND_WATER_LEVEL=63\n"
 "HOOK_ON_FIND_POISON_GAS_LEVEL=64\n"
 "HOOK_ON_FIND_SURFACE_ON_RAY=65\n"
-"HOOK_BEFORE_PLAY_MODE_RUN=66\n"
-"HOOK_ON_PLAY_MODE_RUN=67\n"
+"HOOK_BEFORE_PLAY_MODE_UPDATE=66\n"
+"HOOK_ON_PLAY_MODE_UPDATE=67\n"
 "HOOK_MAX=68\n"
 "MAX_HOOKED_BEHAVIORS=1024\n"
 "HUD_DISPLAY_LIVES=0\n"

src/pc/lua/smlua_hook_events.inl

@@ -64,5 +64,5 @@ SMLUA_EVENT_HOOK(HOOK_ON_FIND_FLOOR, _, f32 posX, f32 posY, f32 posZ, struct Sur
 SMLUA_EVENT_HOOK(HOOK_ON_FIND_WATER_LEVEL, _, f32 x, f32 z, f32 *waterLevel) // Manually defined hook
 SMLUA_EVENT_HOOK(HOOK_ON_FIND_POISON_GAS_LEVEL, _, f32 x, f32 z, f32 *gasLevel) // Manually defined hook
 SMLUA_EVENT_HOOK(HOOK_ON_FIND_SURFACE_ON_RAY, _, Vec3f orig, Vec3f dir, struct Surface **hit_surface, Vec3f hit_pos) // Manually defined hook
-SMLUA_EVENT_HOOK(HOOK_BEFORE_PLAY_MODE_RUN, HOOK_RETURN_NEVER, s16 playmode, OUTPUT s16 *overridePlaymode)
-SMLUA_EVENT_HOOK(HOOK_ON_PLAY_MODE_RUN, HOOK_RETURN_NEVER, s16 playmode)
+SMLUA_EVENT_HOOK(HOOK_BEFORE_PLAY_MODE_UPDATE, HOOK_RETURN_NEVER, s16 playmode, OUTPUT s16 *overridePlaymode)
+SMLUA_EVENT_HOOK(HOOK_ON_PLAY_MODE_UPDATE, HOOK_RETURN_NEVER, s16 playmode, OUTPUT s32 *changeLevel)

src/pc/lua/smlua_hook_events_autogen.inl

@@ -1864,12 +1864,12 @@ bool smlua_call_event_hooks_HOOK_ON_PACKET_BYTESTRING_RECEIVE(s32 modIndex, s32
     return hookResult;
 }
 
-bool smlua_call_event_hooks_HOOK_BEFORE_PLAY_MODE_RUN(s16 playmode, s16 *overridePlaymode) {
+bool smlua_call_event_hooks_HOOK_BEFORE_PLAY_MODE_UPDATE(s16 playmode, s16 *overridePlaymode) {
     lua_State *L = gLuaState;
     if (L == NULL) { return false; }
     bool hookResult = false;
 
-    struct LuaHookedEvent *hook = &sHookedEvents[HOOK_BEFORE_PLAY_MODE_RUN];
+    struct LuaHookedEvent *hook = &sHookedEvents[HOOK_BEFORE_PLAY_MODE_UPDATE];
     for (int i = 0; i < hook->count; i++) {
         s32 prevTop = lua_gettop(L);
 
@@ -1881,7 +1881,7 @@ bool smlua_call_event_hooks_HOOK_BEFORE_PLAY_MODE_RUN(s16 playmode, s16 *overrid
 
         // call the callback
         if (0 != smlua_call_hook(L, 1, 1, 0, hook->mod[i], hook->modFile[i])) {
-            LOG_LUA("Failed to call the callback for hook %s - '%s/%s'", sLuaHookedEventTypeName[HOOK_BEFORE_PLAY_MODE_RUN], hook->mod[i]->relativePath, hook->modFile[i]->relativePath);
+            LOG_LUA("Failed to call the callback for hook %s - '%s/%s'", sLuaHookedEventTypeName[HOOK_BEFORE_PLAY_MODE_UPDATE], hook->mod[i]->relativePath, hook->modFile[i]->relativePath);
             continue;
         }
         hookResult = true;
@@ -1896,12 +1896,12 @@ bool smlua_call_event_hooks_HOOK_BEFORE_PLAY_MODE_RUN(s16 playmode, s16 *overrid
     return hookResult;
 }
 
-bool smlua_call_event_hooks_HOOK_ON_PLAY_MODE_RUN(s16 playmode) {
+bool smlua_call_event_hooks_HOOK_ON_PLAY_MODE_UPDATE(s16 playmode, s32 *changeLevel) {
     lua_State *L = gLuaState;
     if (L == NULL) { return false; }
     bool hookResult = false;
 
-    struct LuaHookedEvent *hook = &sHookedEvents[HOOK_ON_PLAY_MODE_RUN];
+    struct LuaHookedEvent *hook = &sHookedEvents[HOOK_ON_PLAY_MODE_UPDATE];
     for (int i = 0; i < hook->count; i++) {
         s32 prevTop = lua_gettop(L);
 
@@ -1912,12 +1912,17 @@ bool smlua_call_event_hooks_HOOK_ON_PLAY_MODE_RUN(s16 playmode) {
         lua_pushinteger(L, playmode);
 
         // call the callback
-        if (0 != smlua_call_hook(L, 1, 0, 0, hook->mod[i], hook->modFile[i])) {
-            LOG_LUA("Failed to call the callback for hook %s - '%s/%s'", sLuaHookedEventTypeName[HOOK_ON_PLAY_MODE_RUN], hook->mod[i]->relativePath, hook->modFile[i]->relativePath);
+        if (0 != smlua_call_hook(L, 1, 1, 0, hook->mod[i], hook->modFile[i])) {
+            LOG_LUA("Failed to call the callback for hook %s - '%s/%s'", sLuaHookedEventTypeName[HOOK_ON_PLAY_MODE_UPDATE], hook->mod[i]->relativePath, hook->modFile[i]->relativePath);
             continue;
         }
         hookResult = true;
 
+        // return changeLevel
+        if (lua_type(L, -1) == LUA_TNUMBER) {
+            *changeLevel = smlua_to_integer(L, -1);
+        }
+
         lua_settop(L, prevTop);
     }
     return hookResult;

src/pc/lua/smlua_hooks.h

@@ -82,8 +82,8 @@ enum LuaHookedEventType {
     HOOK_ON_FIND_WATER_LEVEL,
     HOOK_ON_FIND_POISON_GAS_LEVEL,
     HOOK_ON_FIND_SURFACE_ON_RAY,
-    HOOK_BEFORE_PLAY_MODE_RUN,
-    HOOK_ON_PLAY_MODE_RUN,
+    HOOK_BEFORE_PLAY_MODE_UPDATE,
+    HOOK_ON_PLAY_MODE_UPDATE,
     HOOK_MAX,
 };