Skip to content

Game Hooks (Callbacks)

These are Lua functions called by the GameServer at specific events. Register them using BridgeFunctionAttach() from ScriptCore.lua.

OnReadScript()

Called when scripts are loaded/reloaded. Use for initialization.

function BridgeFunction_OnReadScript()
    LogAdd(LOG_BLUE, "Scripts loaded!")
end

OnShutScript()

Called when the server shuts down. Use for cleanup.

function BridgeFunction_OnShutScript()
    LogAdd(LOG_RED, "Server shutting down...")
end

OnTimerThread()

Called on each timer tick (approximately once per second). Use for periodic tasks.

function BridgeFunction_OnTimerThread()
    -- Periodic logic here
end

OnConnectDataBase()

Called when the database connection is established.

OnCommandManager(aIndex, code, arg) -> number

Called when a player uses a custom command. Return 1 to block default handling, 0 to pass through.

function BridgeFunction_OnCommandManager(aIndex, code, arg)
    if code == 100 then
        GCNoticeSend(aIndex, 1, "Custom command executed!")
        return 1 -- Handled
    end
    return 0 -- Not handled
end

OnCharacterEntry(aIndex)

Called when a character enters the game world.

function BridgeFunction_OnCharacterEntry(aIndex)
    local player = GetUser(aIndex)
    if player then
        GCNoticeSend(aIndex, 1, "Welcome, " .. player.Name .. "!")
    end
end

OnCharacterClose(aIndex)

Called when a character disconnects.

function BridgeFunction_OnCharacterClose(aIndex)
    LogAdd(LOG_BLUE, "Player disconnected: index " .. aIndex)
end

OnGremoryCaseReady(aIndex)

Called when the Gremory Case data is loaded for a player. Use this instead of OnCharacterEntry for Gremory operations.

function BridgeFunction_OnGremoryCaseReady(aIndex)
    GremoryGive(aIndex, GET_ITEM(14, 13), 0, 0, 0, 0, 0, 0,
        GREMORY_CASE_CHARACTER, GREMORY_REWARD_EVENT, GREMORY_EXPIRE_7_DAYS)
end

OnNpcTalk(aIndex, bIndex) -> number

Called when a player talks to an NPC. Return 1 to block default dialog, 0 to allow.

function BridgeFunction_OnNpcTalk(aIndex, bIndex)
    local npc = GetUser(bIndex)
    if npc and npc.Class == 257 then -- Custom NPC class
        GCNoticeSend(aIndex, 1, "Hello from custom NPC!")
        return 1
    end
    return 0
end

OnMonsterDie(aIndex, bIndex) -> number

Called when a monster dies. aIndex = monster, bIndex = killer. Return 1 to block default loot, 0 to allow.

function BridgeFunction_OnMonsterDie(aIndex, bIndex)
    local monster = GetUser(aIndex)
    if monster and monster.Class == 275 then
        GCNoticeSendToAll(0, "The boss has been defeated!")
    end
    return 0
end

OnUserDie(aIndex, bIndex)

Called when a player dies. aIndex = victim, bIndex = killer.

function BridgeFunction_OnUserDie(aIndex, bIndex)
    LogAdd(LOG_RED, "Player " .. aIndex .. " killed by " .. bIndex)
end

OnUserRespawn(aIndex, killerType)

Called when a player respawns after death.

function BridgeFunction_OnUserRespawn(aIndex, killerType)
    local player = GetUser(aIndex)
    if player then
        player.Life = player.MaxLife
    end
end

OnCheckUserTarget(aIndex, bIndex) -> number

Called to validate if a player can attack another player. Return 0 to block, 1 to allow.

function BridgeFunction_OnCheckUserTarget(aIndex, bIndex)
    local attacker = GetUser(aIndex)
    local target = GetUser(bIndex)
    if attacker and target and attacker.Map == 0 then
        return 0 -- No PvP in Lorencia
    end
    return 1
end

OnCheckUserKiller(aIndex, bIndex) -> number

Called to validate PK penalties. Return 0 to skip PK processing, 1 to apply.

OnItemGet(aIndex, itemObjIndex, pItem) -> number

Called when a player picks up an item. Return 0 to block, 1 to allow.

function BridgeFunction_OnItemGet(aIndex, itemObjIndex, pItem)
    if pItem and pItem:IsExcItem() then
        LogAdd(LOG_GREEN, "Player picked up an Excellent item!")
    end
    return 1
end

OnItemDrop(aIndex, slot, x, y, pItem) -> number

Called when a player drops an item. Return 0 to block, 1 to allow.

function BridgeFunction_OnItemDrop(aIndex, slot, x, y, pItem)
    if pItem and pItem:IsSetItem() then
        GCNoticeSend(aIndex, 1, "You cannot drop Ancient items!")
        return 0
    end
    return 1
end

OnPacketRecv(aIndex, lpMsg, size) -> number

Called when a custom packet (headcode 0xFE) is received. Return 1 if handled.

function BridgeFunction_OnPacketRecv(aIndex, lpMsg, size)
    -- Parse custom packets here
    return 0
end

OnMapChange(aIndex, oldMap, newMap)

Called when a player changes maps.

function BridgeFunction_OnMapChange(aIndex, oldMap, newMap)
    LogAdd(LOG_BLUE, "Player " .. aIndex .. " moved from map " .. oldMap .. " to " .. newMap)
end

OnValidateSkillUse(aIndex, skillIndex, [targetIndex]) -> boolean

Called to validate if a skill can be used. Return true to allow, false to block. Has two overloads (with and without target).

function BridgeFunction_OnValidateSkillUse(aIndex, skillIndex, targetIndex)
    if skillIndex == 41 and GetUser(aIndex).Map == 6 then
        GCNoticeSend(aIndex, 1, "This skill is disabled in the Arena!")
        return false
    end
    return true
end

OnTradeStart(aIndex, bIndex)

Called when a trade begins between two players.

function BridgeFunction_OnTradeStart(aIndex, bIndex)
    LogAdd(LOG_BLUE, "Trade started: " .. aIndex .. " <-> " .. bIndex)
end

OnTradeConfirm(aIndex, bIndex)

Called when both players confirm a trade.

function BridgeFunction_OnTradeConfirm(aIndex, bIndex)
    LogAdd(LOG_GREEN, "Trade confirmed: " .. aIndex .. " <-> " .. bIndex)
end