Skip to content

Getting Started

The GameServer includes a Lua 5.4 scripting engine. Scripts register event handlers through BridgeFunctionAttach() and are loaded automatically on startup via ScriptCore.lua.

First Script

Create a file called Welcome.lua in your scripts directory:

-- Welcome.lua - Send a welcome message when players log in

local function OnPlayerLogin(aIndex)
    local player = GetUser(aIndex)
    if player == nil then return end

    GCNoticeSend(aIndex, 1, "Welcome to the server, " .. player.Name .. "!")
    LogAdd(LOG_GREEN, "[Welcome] " .. player.Name .. " has logged in.")
end

-- Register the handler
BridgeFunctionAttach("OnCharacterEntry", OnPlayerLogin)

Key Concepts

Event-Driven Architecture

Handlers are attached to events via BridgeFunctionAttach():

BridgeFunctionAttach("OnMonsterDie", function(aIndex, bIndex)
    -- This runs every time a monster dies
    -- aIndex = monster, bIndex = killer
end)

The GetUser() Function

Handlers receive an aIndex (object index). GetUser() returns the full object:

local player = GetUser(aIndex)
if player then
    -- Access properties
    print(player.Name)      -- Character name
    print(player.Level)     -- Current level
    print(player.Map)       -- Current map
    print(player.Class)     -- Character class
end

Return Values in Hooks

Some hooks use return values to control game behavior:

Return Meaning
0 Block the default action
1 Allow the default action 
BridgeFunctionAttach("OnItemDrop", function(aIndex, slot, item)
    if item:IsSetItem() then
        GCNoticeSend(aIndex, 1, "You cannot drop Ancient items!")
        return 0  -- Block the drop
    end
    return 1  -- Allow normally
end)

Next Steps