sm64coopdx/docs/lua/hooks.md

⏪ Lua Reference

Hooks

Hooks are a way for SM64 to trigger Lua code, whereas the functions listed in functions allow Lua to trigger SM64 code.

hook_chat_command

hook_chat_command() allows Lua mods to react and respond to chat commands. Chat commands start with the / character. The function the mod passes to the hook should return true when the command was valid and false otherwise.

Parameters

Field	Type
command	string
description	string
func	Lua Function

Lua Example

function on_test_command(msg)
    if msg == 'on' then
        djui_chat_message_create('Test: enabled')
        return true
    elseif msg == 'off' then
        djui_chat_message_create('Test: disabled')
        return true
    end
    return false
end

hook_chat_command('test', "[on|off] turn test on or off", on_hide_and_seek_command)

🔼

hook_event

The lua functions sent to hook_event() will be automatically called by SM64 when certain events occur.

Hook Event Types

Type	Description	Parameters
HOOK_UPDATE	Called once per frame	None
HOOK_MARIO_UPDATE	Called once per player per frame at the end of a mario update	MarioState mario
HOOK_BEFORE_MARIO_UPDATE	Called once per player per frame at the beginning of a mario update	MarioState mario
HOOK_ON_SET_MARIO_ACTION	Called every time a player's current action is changed	MarioState mario
HOOK_BEFORE_PHYS_STEP	Called once per player per frame before physics code is run	MarioState mario
HOOK_ON_PVP_ATTACK	Called when one player attacks another	MarioState attacker, MarioState victim
HOOK_ON_PLAYER_CONNECTED	Called when a player connects	MarioState connector
HOOK_ON_PLAYER_DISCONNECTED	Called when a player disconnects	MarioState disconnector

Parameters

Field	Type
hook_event_type	HookEventType
func	Lua Function

Lua Example

The following example will print out a message 16 times per frame (once for every possible player).

function mario_update(m)
    print('Mario update was called for player index ', m.playerIndex)
end

hook_event(HOOK_MARIO_UPDATE, mario_update)

🔼

hook_mario_action

hook_mario_action() allows Lua mods to create new actions or override existing ones.

Parameters

Field	Type
action_id	integer
func	Lua Function
interaction_type	enum InteractionFlag

Lua Example

ACT_WALL_SLIDE = (0x0BF | ACT_FLAG_AIR | ACT_FLAG_MOVING | ACT_FLAG_ALLOW_VERTICAL_WIND_ACTION)

function act_wall_slide(m)
    if (m.input & INPUT_A_PRESSED) ~= 0 then
        local rc = set_mario_action(m, ACT_TRIPLE_JUMP, 0)
        m.vel.y = 72.0

        if m.forwardVel < 20.0 then
            m.forwardVel = 20.0
        end
        m.wallKickTimer = 0
        return rc
    end

    -- attempt to stick to the wall a bit. if it's 0, sometimes you'll get kicked off of slightly sloped walls
    mario_set_forward_vel(m, -1.0)

    m.particleFlags = m.particleFlags | PARTICLE_DUST

    play_sound(SOUND_MOVING_TERRAIN_SLIDE + m.terrainSoundAddend, m.marioObj.header.gfx.cameraToObject)
    set_mario_animation(m, MARIO_ANIM_START_WALLKICK)

    if perform_air_step(m, 0) == AIR_STEP_LANDED then
        mario_set_forward_vel(m, 0.0)
        if check_fall_damage_or_get_stuck(m, ACT_HARD_BACKWARD_GROUND_KB) == 0 then
            return set_mario_action(m, ACT_FREEFALL_LAND, 0)
        end
    end

    m.actionTimer = m.actionTimer + 1
    if m.wall == nil and m.actionTimer > 2 then
        mario_set_forward_vel(m, 0.0)
        return set_mario_action(m, ACT_FREEFALL, 0)
    end

    -- gravity
    m.vel.y = m.vel.y + 2

    return 0
end

function mario_on_set_action(m)
    -- wall slide
    if m.action == ACT_SOFT_BONK then
        m.faceAngle.y = m.faceAngle.y + 0x8000
        set_mario_action(m, ACT_WALL_SLIDE, 0)
    end
end

hook_event(HOOK_ON_SET_MARIO_ACTION, mario_on_set_action)
hook_mario_action(ACT_WALL_SLIDE, act_wall_slide)

🔼

hook_on_sync_table_change

hook_on_sync_table_change() allows Lua mods to react to sync table changes.

• syncTable parameter must be a sync table, e.g. gGlobalSyncTable, gPlayerSyncTable[], or one of their child tables.
• field parameter must be one of the fields in the SyncTable.
• tag parameter can be any type, and is automatically passed to the callback.
• func parameter must be a function with three parameters: tag, oldVal, and newVal.
  • tag will be the same tag passed into hook_on_sync_table_change().
  • oldVal will be the value before it was set.
  • newVal will be the value that it was set to.

Parameters

Field	Type
syncTable	SyncTable
field	value
tag	value
func	Lua Function

Lua Example

function on_testing_field_changed(tag, oldVal, newVal)
    print('testingField changed:', tag, ',', oldVal, '->', newVal)
end

hook_on_sync_table_change(gGlobalSyncTable, 'testingField', 'tag', on_testing_field_changed)

-- now when testingField is set, either locally or over the network, on_testing_field_changed() will be called
gGlobalSyncTable.testingField = 'hello'

🔼