• Studio

  • Studio API

  • Bots

  • Web API

  • Designer Resources

  • Host Resources

  • Globals

    GameServer

    Inherits from:

    The global server object provides access to server-side game context and is available in Server and ClientAndServer scripts. Inherits from Game, so all Game properties (Players, Info, PlayerCount, etc.) are also available.

    Use cases:

    • Managing player connections and disconnections (authoritative source)
    • Scene management (loading, unloading, moving players between scenes)
    • Matchmaking priority configuration
    • Cross-world event communication (SendWorldEvent, OnWorldEvent)
    • Server-side game logic and state management

    Availability:

    • Server scripts: server is always available
    • ClientAndServer scripts: Check if server ~= nil or client == nil to determine if running on server

    Available on: Server and ClientAndServer scripts

    Properties

    PlayerConnected

    ServerOnly
    ReadOnly

    Event triggered when a player connects to the server. This is the authoritative server-side event for player connections. Fires before the client-side PlayerConnected event.

    NOTE: This fires when a player connects, NOT when their avatar spawns. For avatar spawn events, use player.CharacterChanged event or PlayerCharacterSpawner.OnCharacterSpawned.

    Event Parameters: Player: The player who connected

    --!Type(Server)
    
    function self:ServerStart()
        server.PlayerConnected:Connect(function(player)
            print("[SERVER] " .. player.name .. " connected!")
            print("User ID: " .. player.user.id)
            
            -- Use scene.playerCount for players in current scene (recommended)
            print("Players in scene: " .. scene.playerCount)
            -- Use server.playerCount for total across all scenes
            print("Total players: " .. server.playerCount)
            
            -- Initialize player data on server
            Storage.SetPlayerValue(player, "JoinTime", os.time())
            
            -- Grant starting items
            local transaction = InventoryTransaction.new()
            transaction:GivePlayer(player, "welcome_coins", 100)
            Inventory.CommitTransaction(transaction)
        end)
    end
    

    PlayerDisconnected

    ServerOnly
    ReadOnly

    Event triggered when a player disconnects from the server. This is the authoritative server-side event for player disconnections. Use this to save player data, clean up resources, or notify other players.

    Event Parameters: Player: The player who disconnected

    --!Type(Server)
    
    function self:ServerStart()
        server.PlayerDisconnected:Connect(function(player)
            print("[SERVER] " .. player.name .. " disconnected!")
            
            -- Save player session data
            Storage.SetPlayerValue(player, "LastSeen", os.time())
            
            -- Notify remaining players
            print("Players in scene: " .. scene.playerCount)
            print("Total players in world: " .. server.playerCount)
        end)
    end
    

    isLoading

    boolean
    ServerOnly
    ReadOnly

    Indicates whether the server is currently in a loading state. Returns true while the server is initializing scenes and resources.

    --!Type(Server)
    
    function self:ServerUpdate()
        if server.isLoading then
            -- Server is still loading, don't start game logic yet
            return
        end
        
        -- Normal game logic here
    end
    

    sceneCount

    number
    ServerOnly
    ReadOnly

    The total number of loaded scenes in the world. Equivalent to #server.Scenes

    --!Type(Server)
    
    function self:ServerStart()
        print("Active scenes: " .. server.sceneCount)
    end
    

    scenes

    ServerOnly
    ReadOnly

    Array of all loaded scenes in the world. Use this to iterate through scenes or find a specific scene.

    --!Type(Server)
    
    function self:ServerStart()
        print("Total scenes: " .. server.sceneCount)
        
        for i, scene in ipairs(server.scenes) do
            print("Scene " .. i .. " player count: " .. #scene.players)
        end
    end
    

    spectatorCount

    number
    ServerOnly
    ReadOnly

    The number of spectators currently in the spectator scene. Spectators are observers who don't count towards the MaxPlayers limit.

    --!Type(Server)
    
    function self:ServerUpdate()
        if server.spectatorCount > 0 then
            print("Spectators watching: " .. server.spectatorCount)
        end
    end
    

    spectatorScene

    ServerOnly
    WriteOnly

    Gets or sets the spectator scene where players can observe without actively participating. Spectators don't count towards the MaxPlayers limit.

    Methods

    Gets the current matchmaking priority for this world instance. Returns the priority value set by SetMatchMakingPriority (default is 0).

    --!Type(Server)
    
    function self:ServerStart()
        local currentPriority = server.GetMatchMakingPriority()
        print("Current matchmaking priority: " .. currentPriority)
    end
    

    Returns

    number

    LoadScene

    ServerOnly

    Loads a scene into the game environment. Can load scenes by name (string) or scene ID (int).

    Parameters:

    • sceneName/sceneId: The scene to load
    • additive: If true, adds the scene without unloading others. If false, replaces the current scene.

    Returns the loaded WorldScene object.

    --!Type(Server)
    
    function self:ServerStart()
        -- Load a scene by name (replacing current scene)
        local mainScene = server.LoadScene("MainArena", false)
        print("Loaded scene: " .. mainScene.name)
        
        -- Load additional scene additively
        local bonusScene = server.LoadScene("BonusArea", true)
        print("Added bonus scene")
    end
    

    Parameters

    sceneId
    number
    additive
    boolean

    Returns

    LoadScene

    ServerOnly

    Loads a scene into the game environment. Can load scenes by name (string) or scene ID (int).

    Parameters:

    • sceneName/sceneId: The scene to load
    • additive: If true, adds the scene without unloading others. If false, replaces the current scene.

    Returns the loaded WorldScene object.

    --!Type(Server)
    
    function self:ServerStart()
        -- Load a scene by name (replacing current scene)
        local mainScene = server.LoadScene("MainArena", false)
        print("Loaded scene: " .. mainScene.name)
        
        -- Load additional scene additively
        local bonusScene = server.LoadScene("BonusArea", true)
        print("Added bonus scene")
    end
    

    Parameters

    sceneName
    string
    additive
    boolean

    Returns

    Loads a scene additively into the game environment. Convenience method equivalent to LoadScene(sceneName, true) or LoadScene(sceneId, true). Can load scenes by name (string) or scene ID (int).

    Returns the loaded WorldScene object.

    --!Type(Server)
    
    function self:ServerStart()
        -- Load base scene
        local mainScene = server.LoadScene("MainWorld", false)
        
        -- Add additional scenes
        local shopScene = server.LoadSceneAdditive("Shop")
        local pvpScene = server.LoadSceneAdditive("PvPArena")
        
        print("Total scenes loaded: " .. server.sceneCount)
    end
    

    Parameters

    sceneId
    number

    Returns

    Loads a scene additively into the game environment. Convenience method equivalent to LoadScene(sceneName, true) or LoadScene(sceneId, true). Can load scenes by name (string) or scene ID (int).

    Returns the loaded WorldScene object.

    --!Type(Server)
    
    function self:ServerStart()
        -- Load base scene
        local mainScene = server.LoadScene("MainWorld", false)
        
        -- Add additional scenes
        local shopScene = server.LoadSceneAdditive("Shop")
        local pvpScene = server.LoadSceneAdditive("PvPArena")
        
        print("Total scenes loaded: " .. server.sceneCount)
    end
    

    Parameters

    sceneName
    string

    Returns

    Moves a player to a specified scene within the game environment. Useful for multi-scene worlds where players can be in different areas.

    Returns true if the move was successful, false otherwise.

    --!Type(Server)
    
    function self:ServerStart()
        -- Load multiple scenes
        local lobbyScene = server.LoadScene("Lobby", false)
        local gameScene = server.LoadScene("GameArena", true)
        
        -- Move player to game scene when they're ready
        server.PlayerConnected:Connect(function(player)
            -- Start in lobby
            print(player.name .. " spawned in lobby")
            
            -- Move to game scene after 5 seconds
            Timer.After(5, function()
                local success = server.MovePlayerToScene(player, gameScene)
                if success then
                    print(player.name .. " moved to game arena")
                end
            end)
        end)
    end
    

    Parameters

    player
    scene

    Returns

    boolean

    OnWorldEvent

    ServerOnly

    Registers a callback to receive world events from other instances or the current instance. Use this to listen for events sent via SendWorldEvent from other world instances.

    Callback Parameters:

    • eventName (string): The name of the event
    • isLocal (bool): True if event was sent from this instance, false if from another instance
    • payload (table): The event data sent by SendWorldEvent
    --!Type(Server)
    
    function self:ServerStart()
        -- Listen for world events
        server.OnWorldEvent(function(eventName, isLocal, payload)
            print("Received world event: " .. eventName)
            print("Is from this instance: " .. tostring(isLocal))
            
            if eventName == "GlobalAnnouncement" then
                print("Announcement: " .. payload.message)
                -- Notify all players in the current scene (recommended)
                for i, player in ipairs(scene.players) do
                    -- Send UI notification to players in this scene
                end
            elseif eventName == "PlayerAchievement" then
                print(payload.playerName .. " earned: " .. payload.achievement)
            end
        end)
    end
    

    Parameters

    callback
    (eventName: string, isLocal: boolean, payload: any) -> ()

    Returns

    void

    SendWorldEvent

    ServerOnly

    Sends a custom event to other world instances, enabling cross-instance communication. Useful for global notifications, leaderboard updates, or coordinating multiple world instances.

    Event name must be 1-128 characters. Payload is a Lua table/value that will be serialized and sent to other instances.

    Overloads:

    • SendWorldEvent(eventName, payload): Fire and forget
    • SendWorldEvent(eventName, payload, callback): Get error feedback
    • SendWorldEvent(eventName, payload, callback, instanceIds): Target specific instances

    IMPORTANT: Rate limited. Avoid sending events too frequently.

    --!Type(Server)
    
    function self:ServerStart()
        -- Send a global event to all instances
        server.SendWorldEvent("GlobalAnnouncement", {
            message = "Special event starting!",
            timestamp = os.time()
        })
        
        -- Send with error handling
        server.SendWorldEvent("PlayerAchievement", {
            playerName = "John",
            achievement = "First Victory"
        }, function(error)
            if error == EmitWorldEventError.None then
                print("Event sent successfully!")
            elseif error == EmitWorldEventError.RequestThrottled then
                print("Too many events sent, throttled")
            else
                print("Error sending event: " .. tostring(error))
            end
        end)
    end
    

    Parameters

    eventName
    string
    eventPayload
    any

    Returns

    void

    SendWorldEvent

    ServerOnly

    Sends a custom event to other world instances, enabling cross-instance communication. Useful for global notifications, leaderboard updates, or coordinating multiple world instances.

    Event name must be 1-128 characters. Payload is a Lua table/value that will be serialized and sent to other instances.

    Overloads:

    • SendWorldEvent(eventName, payload): Fire and forget
    • SendWorldEvent(eventName, payload, callback): Get error feedback
    • SendWorldEvent(eventName, payload, callback, instanceIds): Target specific instances

    IMPORTANT: Rate limited. Avoid sending events too frequently.

    --!Type(Server)
    
    function self:ServerStart()
        -- Send a global event to all instances
        server.SendWorldEvent("GlobalAnnouncement", {
            message = "Special event starting!",
            timestamp = os.time()
        })
        
        -- Send with error handling
        server.SendWorldEvent("PlayerAchievement", {
            playerName = "John",
            achievement = "First Victory"
        }, function(error)
            if error == EmitWorldEventError.None then
                print("Event sent successfully!")
            elseif error == EmitWorldEventError.RequestThrottled then
                print("Too many events sent, throttled")
            else
                print("Error sending event: " .. tostring(error))
            end
        end)
    end
    

    Parameters

    eventName
    string
    eventPayload
    any
    callback
    (error: EmitWorldEventError) -> ()

    Returns

    void

    SendWorldEvent

    ServerOnly

    Sends a custom event to other world instances, enabling cross-instance communication. Useful for global notifications, leaderboard updates, or coordinating multiple world instances.

    Event name must be 1-128 characters. Payload is a Lua table/value that will be serialized and sent to other instances.

    Overloads:

    • SendWorldEvent(eventName, payload): Fire and forget
    • SendWorldEvent(eventName, payload, callback): Get error feedback
    • SendWorldEvent(eventName, payload, callback, instanceIds): Target specific instances

    IMPORTANT: Rate limited. Avoid sending events too frequently.

    --!Type(Server)
    
    function self:ServerStart()
        -- Send a global event to all instances
        server.SendWorldEvent("GlobalAnnouncement", {
            message = "Special event starting!",
            timestamp = os.time()
        })
        
        -- Send with error handling
        server.SendWorldEvent("PlayerAchievement", {
            playerName = "John",
            achievement = "First Victory"
        }, function(error)
            if error == EmitWorldEventError.None then
                print("Event sent successfully!")
            elseif error == EmitWorldEventError.RequestThrottled then
                print("Too many events sent, throttled")
            else
                print("Error sending event: " .. tostring(error))
            end
        end)
    end
    

    Parameters

    eventName
    string
    eventPayload
    any
    callback
    (error: EmitWorldEventError) -> ()
    instanceIds
    string[]

    Returns

    void

    Sets the matchmaking priority for this world instance. Higher priority instances are more likely to receive new players. Use this to balance player distribution or prioritize certain instances.

    Default priority is 0. Higher values = higher priority.

    --!Type(Server)
    
    function self:ServerStart()
        -- Set lower priority if almost full
        if server.playerCount >= server.info.maxPlayers - 2 then
            server.SetMatchMakingPriority(-100)
            print("Instance almost full, lowered priority")
        end
    end
    
    function self:ServerUpdate()
        -- Dynamically adjust based on player count
        if server.playerCount < 3 then
            server.SetMatchMakingPriority(100) -- High priority when empty
        elseif server.playerCount > 10 then
            server.SetMatchMakingPriority(-50) -- Lower priority when busy
        else
            server.SetMatchMakingPriority(0) -- Normal priority
        end
    end
    

    Parameters

    priority
    number

    Returns

    void

    Updated 19 days ago

    PocketWorlds Icon

    © 2025 Pocket Worlds. All rights reserved.