---

name: skynet description: Create and manage Skynet game server projects. Use this skill when working with the Skynet framework, including creating new game projects, generating services, managing protocols, database integration with MySQL/Redis/MongoDB, and service debugging.

Skynet Game Server Development

Overview

Skynet is a multi-threaded actor model framework for building scalable game servers in Lua. This skill automates common development tasks including project scaffolding, service creation, protocol definition, and database integration.

Key Concepts:

• Each service is an isolated actor with its own Lua state and message queue
• Services communicate via message passing: skynet.call() for RPC, skynet.send() for one-way messages
• No shared global state between services
• Worker threads process messages concurrently

Quick Start

Create a New Game Project

Generate a complete Skynet game project structure:

cd /root/skynet
./skynet examples/config  # Start example server

Use this skill to create a new game project with standard structure, configuration, and core services.

Project Structure

A typical Skynet game project:

mygame/
├── config                 # Skynet configuration (Lua-based)
├── config.path            # Path configuration for modules and services
├── main.lua              # Entry point service
├── service/              # Game-specific services
│   ├── watchdog.lua     # Connection manager
│   ├── agent.lua        # Player agent (one per client)
│   └── game.lua         # Game logic service
├── proto/               # Protocol definitions (sproto)
├── lualib/              # Game-specific libraries
└── scripts/             # Utility scripts

Service Development Patterns

Basic Service Pattern

All Skynet services follow this structure:

local skynet = require "skynet"

local CMD = {}

function CMD.command_name(args)
    -- Handle command
    return result
end

skynet.start(function()
    skynet.dispatch("lua", function(session, source, cmd, ...)
        local f = assert(CMD[cmd], "Unknown command")
        skynet.ret(skynet.pack(f(...)))
    end)
    skynet.error("Service started")
end)

Key Components:

• CMD table: Command handlers
• skynet.dispatch(): Register message handler
• skynet.ret(): Send response back
• skynet.error(): Logging

Watchdog-Agent-Gate Pattern

Standard pattern for handling client connections:

Watchdog (examples/watchdog.lua):

• Manages client connections
• Spawns one agent service per client
• Handles socket events (open, close, error)

Agent (examples/agent.lua):

• Represents a single client session
• Handles protocol messages (sproto)
• Processes client requests
• Maintains player state

Gate (service/gate.lua):

• TCP connection management
• Message forwarding between watchdog and agents

Service Communication

-- Request/Response (blocks coroutine until response)
local result = skynet.call(service_addr, "lua", "command", args)

-- One-way message (fire and forget)
skynet.send(service_addr, "lua", "event", data)

-- Named service (singleton - only one instance)
local db = skynet.uniqueservice("database")
skynet.call("database", "lua", "query", sql)

-- Create new service
local agent = skynet.newservice("agent")

Configuration

Config File Structure

-- config
include "config.path"

thread = 8              -- Worker threads (match CPU cores)
logger = nil            -- Logger service
logpath = "."           -- Log directory
harbor = 0              -- 0 = single node, >0 = cluster mode
start = "main"          -- Entry point service
bootstrap = "snlua bootstrap"

-- Path configuration
luaservice = root.."service/?.lua;"..root.."mygame/service/?.lua"
lua_path = root.."lualib/?.lua;"..root.."mygame/lualib/?.lua"
lua_cpath = root.."luaclib/?.so"

Path Configuration

-- config.path
root = "./"
luaservice = root.."service/?.lua;"..root.."mygame/service/?.lua"
lualoader = root.."lualib/loader.lua"
lua_path = root.."lualib/?.lua;"..root.."lualib/?/init.lua"
lua_cpath = root.."luaclib/?.so"

Protocol Management

Skynet uses sproto for client-server protocol definition:

-- proto/login.lua
local sprotoparser = require "sprotoparser"

return {
    c2s = sprotoparser.parse [[
        .package {
            type 0 : integer
            session 1 : integer
        }
        login 1 {
            request {
                username 0 : string
                password 1 : string
            }
            response {
                ok 0 : boolean
                token 1 : string
            }
        }
    ]],

    s2c = sprotoparser.parse [[
        .package {
            type 0 : integer
            session 1 : integer
        }
        heartbeat 1 {}
        kick 2 {
            reason 0 : string
        }
    ]]
}

Protocol Types:

• C2S (Client to Server): Request messages from client
• S2C (Server to Client): Response and push messages

Database Integration

MySQL

local skynet = require "skynet"
local mysql = require "skynet.db.mysql"

local db
local CMD = {}

function CMD.connect(conf)
    db = mysql.connect({
        host = conf.host or "127.0.0.1",
        port = conf.port or 3306,
        database = conf.database,
        user = conf.user,
        password = conf.password,
        charset = "utf8mb4",
        max_packet_size = 1024 * 1024
    })
    return true
end

function CMD.query(sql)
    return db:query(sql)
end

function CMD.execute(stmt, ...)
    return db:execute(stmt, ...)
end

skynet.start(function()
    skynet.dispatch("lua", function(_, _, cmd, ...)
        local f = CMD[cmd]
        skynet.ret(skynet.pack(f(...)))
    end)
end)

Redis

local redis = require "skynet.db.redis"

local db
local CMD = {}

function CMD.connect(conf)
    db = redis.connect({
        host = conf.host or "127.0.0.1",
        port = conf.port or 6379,
        db = conf.db or 0,
        auth = conf.auth
    })
    return true
end

function CMD.get(key)
    return db:get(key)
end

function CMD.set(key, value)
    return db:set(key, value)
end

Debugging

Debug Console

Skynet provides a built-in debug console:

-- In main.lua
skynet.newservice("debug_console", 8000)

Connect via telnet:

telnet localhost 8000

Console Commands:

• list - List all services
• call <addr> <cmd> [...] - Call service command
• kill <addr> - Kill service
• stat - Show statistics
• mem <addr> - Show memory usage
• gc - Force garbage collection
• info <addr> - Service information

Logging

-- Log to console
skynet.error("Error message")

-- Log with context
skynet.error(string.format("User %d logged in", uid))

Common Workflows

Starting a New Game Project

1. Create project directory structure
2. Set up config files (examples/config)
3. Create main.lua entry point (examples/main.lua)
4. Implement watchdog for connections (examples/watchdog.lua)
5. Implement agent for player logic (examples/agent.lua)
6. Define protocols (sproto)
7. Add database services if needed
8. Test with debug console

Adding a New Service

1. Create service file in service/
2. Define CMD table with command handlers
3. Register dispatch handler
4. Launch from other services using skynet.newservice()

Testing Services

-- test/testservice.lua
local skynet = require "skynet"

skynet.start(function()
    local service = skynet.newservice("myservice")

    -- Test commands
    local result = skynet.call(service, "lua", "command", args)
    assert(result == expected, "Test failed")

    skynet.error("Test passed!")
    skynet.exit()
end)

Run test:

./skynet test/testservice

Best Practices

1. Use CMD table pattern for command handlers
2. Implement proper error handling with pcall()
3. Register unique services with skynet.uniqueservice() for singletons
4. Use skynet.call() for responses, skynet.send() for notifications
5. Avoid circular dependencies between services
6. Test services individually before integration
7. Use meaningful service names for debugging
8. Log important events with skynet.error()
9. Profile performance with skynet.stat()
10. Use skynet.timeout() instead of busy loops

Core APIs Reference

Service APIs

• skynet.start(func) - Service entry point
• skynet.newservice(name, ...) - Launch new service
• skynet.call(addr, typename, ...) - Synchronous RPC
• skynet.send(addr, typename, ...) - Asynchronous message
• skynet.ret(msg, sz) - Send response
• skynet.response() - Create response object
• skynet.self() - Get current service handle
• skynet.name(name, handle) - Register service name

Dispatch APIs

• skynet.dispatch(typename, func) - Register message handler
• skynet.register_protocol(class) - Register custom protocol

Timing APIs

• skynet.sleep(time) - Sleep (1 = 1/100 second)
• skynet.timeout(time, func) - Schedule callback
• skynet.fork(func, ...) - Create new coroutine

Utility APIs

• skynet.error(...) - Log error message
• skynet.getenv(key) - Get environment variable
• skynet.setenv(key, value) - Set environment variable
• skynet.now() - Get current time (centiseconds)

Examples

See examples/ directory for complete working examples:

• basic-service/ - Minimal service template
• watchdog-agent-gate/ - Client connection pattern
• database-integration/ - MySQL/Redis/MongoDB examples
• protocol-handling/ - Sproto protocol examples
• complete-game/ - Full mini game server

References

For detailed documentation on specific topics:

• references/service-patterns.md - Common service patterns
• references/database-integration.md - Database usage patterns
• references/protocol-guide.md - Sproto protocol guide
• references/configuration.md - Config file reference
• references/debugging-guide.md - Debug console and debugging
• references/deployment.md - Build and deployment

External Resources

• Skynet Wiki - Official documentation
• Skynet Examples - Working code examples
• Skynet Source - Framework source code