skynet.start(start_func)#

注册 service 的启动入口。 一般在这里完成：

• dispatch 注册
• 初始化状态
• 对外注册名字
• 打开监听或定时器

skynet.init(init_func)#

初始化阶段回调。 发生在 start 之前。 适合做不依赖消息循环的预初始化。

skynet.exit()#

让当前 service 退出。 如果当前消息还没返回，Skynet 会在该消息处理完成后再真正结束。

skynet.abort()#

立即终止当前进程。 这是进程级别的硬退出。 只适合致命错误。

skynet.self()#

返回当前 service 地址。

skynet.address(addr)#

把地址转成人类可读字符串。

skynet.register(name)#

把当前 service 注册为一个名字。 通常配合 skynet.name / queryservice 使用。

skynet.name(name, handle)#

给指定 handle 绑定名字。

skynet.localname(name)#

查询本地名字。

skynet.getenv(key) / skynet.setenv(key, value)#

读写环境变量。 这些值来自配置文件或运行时设置。

常见用途：

• 读数据库地址
• 读集群名
• 读业务开关

skynet.newservice(name, ...)#

创建一个 Lua service。 返回新 service 的 handle。

skynet.uniqueservice(name, ...)#

获取一个唯一 service。 如果还没创建，会自动创建。 常用在：

• 全局配置服务
• 玩家管理中心
• 排行榜中心

skynet.queryservice(name)#

查询一个已经存在的唯一 service。 如果没有，会等待服务出现。

注意：

• uniqueservice 适合“没有就创建”。
• queryservice 适合“必须等已有服务上线”。

skynet.dispatch(proto_name, dispatch_func)#

注册某种协议的消息处理函数。 最常见的是：

• lua
• client
• socket
• 自定义协议

dispatch_func 的典型参数是：

• session
• source
• 命令或消息体

skynet.register_protocol { ... }#

注册新协议。 通常要给出：

• name
• id
• pack
• unpack
• dispatch

如果项目里需要客户端私有协议，通常就在这里做协议接线。

skynet.call(addr, proto, ...)#

同步 RPC。 当前 coroutine 会挂起，直到对方返回。

特点：

• 写法最直观
• 链路长时容易堆积等待
• 不适合高频大广播

skynet.send(addr, proto, ...)#

异步发送。 不等返回。

适合：

• 通知
• 事件投递
• 日志
• 非关键链路的状态刷新

skynet.redirect(addr, source, proto, session, msg, sz)#

把收到的消息原样转发。 适合做网关、代理或桥接层。

skynet.response(pack_func)#

生成一个延迟响应器。 适合需要异步算完再回包的场景。

配套 API：

• skynet.ret(...)
• skynet.retpack(...)
• skynet.pack(...)
• skynet.packstring(str)
• skynet.unpack(...)
• skynet.tostring(msg, sz)

常见分工：

• ret / retpack：给当前请求回包
• pack / packstring：手动打包消息
• unpack：解包参数
• tostring：把底层消息缓冲转 Lua 字符串

skynet.now()#

返回当前 tick。 单位是 1/100 秒。

skynet.time()#

返回秒级时间，精度更适合统计和超时计算。

skynet.starttime()#

返回 Skynet 启动时的时间基准。

skynet.sleep(ti)#

挂起当前 coroutine 指定 tick。

skynet.timeout(ti, func)#

在未来某个 tick 执行函数。

skynet.fork(func, ...)#

启动新的 coroutine 执行任务。

skynet.yield()#

主动让出当前 coroutine。

skynet.wait(token) / skynet.wakeup(token)#

按 token 阻塞和唤醒 coroutine。 适合 service 内部小范围同步。

面向业务的建议：

• timeout 适合定时任务。
• fork 适合把当前消息拆成并行 coroutine。
• wait/wakeup 适合 service 内部条件等待。
• 但不要把复杂状态机全写成互相 wakeup 的风格，后期会很难追。

skynet.error(...)#

输出日志。

skynet.traceback()#

输出当前 coroutine 栈。

skynet.stat(what)#

从 APIList 看，stat 可用于取 service 统计信息。 wiki 本页没有展开细节，适合去源码确认具体字段。

skynet.info_func(func)#

注册调试信息输出函数。 常和 debug console 配合。

socket.listen(host, port, backlog)#

监听一个 TCP 地址。 返回监听 fd。

socket.start(id, accept_cb)#

让当前 service 成为 socket owner，并开始接收该 socket 事件。

如果是监听 fd，accept_cb 会在新连接到来时拿到：

• newid
• addr

socket.open(addr, port)#

主动建立 TCP 连接。 成功返回连接 id。

socket.read(id, sz)#

读固定长度。

socket.readline(id, sep)#

按分隔符读一行。

socket.readall(id)#

一直读到对端关闭。

socket.block(id)#

把 socket 切成阻塞模式读。 适合简单协议或工具脚本。

socket.write(id, data)#

写数据。

socket.lwrite(id, data)#

低优先级写。 官方说明是：适合不会立刻被读取的数据。

socket.close(id)#

关闭连接。

socket.shutdown(id)#

关闭写方向。

socket.abandon(id)#

放弃 socket 所有权。 常见于：

• watchdog 接入后把 fd 交给 agent
• 网关把已认证连接转交业务 service

socket.close_fd(id)#

直接关底层 fd。

socket.limit(id, limit)#

设置写缓冲限制。

socket.warning(id, callback)#

注册写缓冲告警回调。

MMORPG 里这两个很有用。 因为广播、场景同步、聊天风暴都可能把某个连接拖成慢连接。

socket.udp(handler, host, port)#

创建 UDP socket。

socket.sendto(id, addr, port, data)#

发送 UDP 包。

socket.udp_connect(id, addr, port, callback)#

给 UDP socket 绑定默认远端。

socket.udp_address(msg, from)#

从回调参数里取 UDP 来源地址。

channel:request(request, response, padding)#

发送请求，并用给定 response 函数读取回包。

channel:response(dispatch)#

切换成推送模式。 适合远端会主动推消息的连接。

channel:close()#

关闭连接。

cluster.open(node_name)#

开启当前节点的集群监听。 node_name 来自 cluster 配置表里的节点名。 官方示例是 cluster.open "db"。

cluster.reload(config)#

重载节点配置。

cluster.call(node, addr, ...)#

跨节点同步调用。

cluster.send(node, addr, ...)#

跨节点异步发送。

官方特别提醒：

• 它不保证一定送达
• 远端节点重启时，投递中的消息可能丢失

这对游戏服很重要。 关键资产链路不要只靠 cluster.send。

cluster.proxy(node, addr)#

构造一个远端代理对象。 后续能像本地对象那样做 call/send 风格访问。

cluster.register(name, addr)#

把本地服务注册成远端可访问的名字。

cluster.query(node, name)#

按名字查远端服务地址。

sharedata.new(name, value)#

创建一个共享对象。

sharedata.update(name, value)#

更新对象。

sharedata.delete(name)#

删除对象。

sharedata.query(name, ...)#

读取对象或其深层子节点。

wiki 明确说明：

• 取到的对象和 table 类似
• 读起来比普通 table 稍慢
• 不能直接改
• 自动跟踪更新

sharedata.deepcopy(obj)#

深拷贝成普通 Lua table。

官方说明的取舍是：

• 直接读共享对象较慢，但能自动看到更新
• 深拷贝后读取更快，但不会自动更新

sharedata.flush()#

把旧版本对象在所有 service 都不再使用后再回收。

datacenter.set(key1, key2, ..., value)#

写一个全局共享变量。

datacenter.get(key1, key2, ...)#

读变量。

datacenter.wait(key1, key2, ...)#

如果键还没值，就阻塞等待。

官方还明确提醒：

• datacenterd 是单点
• 不适合大量访问
• 在 cluster 模式下不可直接工作
• 跨节点需求应改用 sharedata 或 cluster.call

结论：

• datacenter 适合少量全局开关和启动时同步
• 不适合高频在线业务数据

gateserver.openclient(fd)#

允许该连接开始接收客户端数据。

官方特别说明：

• 新连接建立后，默认不会立刻把客户端包送到 message
• 只有调用 openclient 后才开始收包

这很适合认证前拦截。

gateserver.closeclient(fd)#

关闭客户端连接。