API Reference

Event Handlers

Your WebSocket function must define these event handlers:

on_connect()

Called when a player connects to the WebSocket.

async def on_connect():
    # Access connection data
    player_name = request.get('player_name', 'Guest')
    room_id = request.get('room_id', 'default')

    # Join a room
    room.join(room_id, max_players=10)

    # Initialize state
    if not room.state:
        room.state = {'players': {}}

    # Add player
    room.state['players'][session.player_id] = {
        'name': player_name
    }

    # Broadcast to others
    await room.broadcast({
        'type': 'player_joined',
        'player_id': session.player_id
    })

    # Return welcome message (sent only to this player)
    return {
        'type': 'welcome',
        'your_id': session.player_id,
        'players': room.state['players']
    }

Returns: Dictionary that will be sent to the connecting player

on_message()

Called when a player sends a message to the server.

async def on_message():
    # Get message data
    action = request.get('action')
    data = request.get('data')

    # Process based on action
    if action == 'move':
        x = request.get('x')
        y = request.get('y')

        # Update state
        room.state['players'][session.player_id]['x'] = x
        room.state['players'][session.player_id]['y'] = y

        # Broadcast to all except sender
        await room.broadcast({
            'type': 'player_moved',
            'player_id': session.player_id,
            'x': x,
            'y': y
        }, exclude=[session.player_id])

    # Return response (sent only to sender)
    return {'status': 'ok'}

Returns: Dictionary that will be sent back to the message sender

on_disconnect()

Called when a player disconnects (closes WebSocket or loses connection).

async def on_disconnect():
    # Clean up player data
    if session.player_id in room.state['players']:
        player_name = room.state['players'][session.player_id]['name']
        del room.state['players'][session.player_id]

        # Notify others
        await room.broadcast({
            'type': 'player_left',
            'player_id': session.player_id,
            'player_name': player_name
        })

    # Destroy room if empty
    if room.get_player_count() == 0:
        room.destroy()

on_tick()

Called repeatedly at a fixed rate (default 20 times per second) for continuous game updates.

async def on_tick():
    # Update game state
    current_time = time.time()
    delta_time = current_time - room.state.get('last_update', current_time)
    room.state['last_update'] = current_time

    # Example: Move objects
    for obj in room.state.get('objects', []):
        obj['x'] += obj['vx'] * delta_time
        obj['y'] += obj['vy'] * delta_time

    # Broadcast updates
    await room.broadcast({
        'type': 'state_update',
        'objects': room.state['objects']
    })

To use on_tick, you must start the game loop by calling room.start_game_loop() in your on_connect handler.

Available Objects

session

Access player session data and information.

Properties

string

Unique identifier for this player

object | null

Authenticated user object (if JWT token provided)

string

Current room ID the player is in

datetime

Timestamp when player connected

dict

Custom session metadata dictionary

Methods

function

Store custom session data

session.set('score', 100)
session.set('inventory', ['sword', 'shield'])

function

Retrieve custom session data

score = session.get('score', 0)
inventory = session.get('inventory', [])

room

Manage rooms and broadcast messages to players.

Properties

string

Current room ID

dict

Shared room state accessible to all players. Initialize this in on_connect.

# Initialize
if not room.state:
    room.state = {'players': {}, 'game_phase': 'waiting'}

# Access/modify
room.state['game_phase'] = 'playing'
room.state['players'][session.player_id] = {'score': 0}

dict

Room configuration (tick_rate, custom flags, etc.)

room.config['tick_rate'] = 30  # 30 updates per second
room.config['game_started'] = True

dict

Custom room metadata for room listing

room.metadata['game_mode'] = 'battle_royale'
room.metadata['map'] = 'desert'
room.metadata['public'] = True

Methods

function

Join a room (auto-created if doesn’t exist)

room.join('lobby', max_players=10)
room.join('private-room-123', max_players=2)

async function

Send message to all players in room

# Broadcast to everyone
await room.broadcast({'type': 'game_started'})

# Exclude specific players
await room.broadcast(
    {'type': 'player_moved', 'x': 100, 'y': 200},
    exclude=[session.player_id]
)

# Send only to specific players
await room.broadcast(
    {'type': 'secret_message'},
    include=['player-id-1', 'player-id-2']
)

async function

Send message to a specific player

await room.send_to('player-id-123', {
    'type': 'private_message',
    'text': 'Hello!'
})

function

Get list of connected player IDs

player_ids = room.get_players()
# ['player-1', 'player-2', 'player-3']

function

Get number of connected players

count = room.get_player_count()  # 3

function

Start the game loop (enables on_tick calls)

# In on_connect
if not room.config.get('game_loop_started'):
    room.config['game_loop_started'] = True
    room.config['tick_rate'] = 20  # 20 ticks/second
    room.start_game_loop()

function

Stop the game loop

room.stop_game_loop()

function

Destroy the room and disconnect all players

if room.get_player_count() == 0:
    room.destroy()

request

Access incoming message data from the client.

Methods

function

Get value from incoming message

action = request.get('action')
x = request.get('x', 0)
player_name = request.get('player_name', 'Guest')

function

Get entire message as dictionary

full_message = request.json()
# {'action': 'move', 'x': 100, 'y': 200}

db

Access your project’s database (same as HTTP functions).

# Create document
user = await db.collection('users').insert({
    'name': 'Alice',
    'score': 100
})

# Query documents
high_scores = await db.collection('users').where('score', '>', 50).get()

# Update document
await db.collection('users').update(user_id, {'score': 150})

# Delete document
await db.collection('users').delete(user_id)

See the Database Documentation for full database API reference.

Built-in Modules

The following Python modules are available in your functions:

module

Time-related functions

current_time = time.time()
time.sleep(1)

module

Random number generation

rand_num = random.random()
rand_int = random.randint(1, 10)
choice = random.choice(['a', 'b', 'c'])

module

JSON encoding/decoding

data = json.loads('{"key": "value"}')
string = json.dumps({'key': 'value'})

module

UUID generation

unique_id = str(uuid.uuid4())

module

Date and time handling

now = datetime.now()
timestamp = datetime.fromtimestamp(1234567890)

Rate Limiting

Each player is limited to 60 messages per second to prevent abuse. Messages exceeding this limit will receive an error response:

{
  "error": "Rate limit exceeded",
  "message": "Maximum 60 messages per second"
}

Room Listing

List all active rooms for your project:

curl http://localhost:8000/ws/rooms/YOUR_PROJECT_ID

const rooms = await coco.multiplayer.listRooms({
  publicOnly: true  // Optional: only show public rooms
});

console.log(rooms);
// [
//   {
//     room_id: 'lobby',
//     player_count: 5,
//     max_players: 10,
//     status: 'waiting',
//     game_mode: 'battle_royale'
//   }
// ]

Response:

{
  "rooms": [
    {
      "room_id": "lobby",
      "player_count": 5,
      "max_players": 10,
      "created_at": "2024-01-15T10:30:00Z",
      "game_mode": "battle_royale",
      "map": "desert",
      "status": "waiting",
      "custom_data": {}
    }
  ],
  "total": 1
}

Getting Started

Core Concepts

Data & Querying

Cloud Functions

Hooks

Realtime & Multiplayer

Storage

Auth & Security

Guides

SDK Reference

API Reference

Event Handlers

on_connect()

on_message()

on_disconnect()

on_tick()

Available Objects

session

Properties

Methods

room

Properties

Methods

request

Methods

db

Built-in Modules

Rate Limiting

Room Listing

​Event Handlers

​on_connect()

​on_message()

​on_disconnect()

​on_tick()

​Available Objects

​session

​Properties

​Methods

​room

​Properties

​Methods

​request

​Methods

​db

​Built-in Modules

​Rate Limiting

​Room Listing

Event Handlers

on_connect()

on_message()

on_disconnect()

on_tick()

Available Objects

session

Properties

Methods

room

Properties

Methods

request

Methods

db

Built-in Modules

Rate Limiting

Room Listing