关于 Shield

Shield 是一个受 Skynet 启发的游戏服务器运行时，采用 Actor 模型和 Lua 优先的设计理念。本项目目前处于重构设计阶段，文档描述的是目标架构和 API 方向，而非稳定发布的实现。

设计目标

• C++ 运行时基础设施：Actor 调度、网络通信、Lua 绑定、定时器、配置管理和日志记录
• Lua 游戏逻辑：每个服务都是一个使用 shield.* API 的 Lua 脚本
• CAF 作为内部 Actor 传输：CAF 仅作为实现细节，对 Lua 业务代码和用户 C++ 扩展隐藏
• 单节点最小部署：核心部署路径专注于单进程/单节点游戏服务器
• 集群能力可选：集群支持是 shield_core 之外的官方可选扩展

设计理念

Shield 遵循以下核心设计原则：

1. 清晰的边界：shield_core 刻意设计得很窄，只包装围绕 CAF 的 actor/service 语义
2. Lua 优先：游戏逻辑通过 Lua 服务编写，C++ 不承载业务代码
3. 模块化：核心功能与可选能力明确分离，用户可以按需组合
4. 简单性优先：避免过度设计，不提供分布式编排、DI/IoC 容器、ORM 等企业级框架特性

适用场景

Shield 适合以下类型的游戏服务器项目：

• MMOARPG：大型多人在线角色扮演游戏，需要服务端逻辑和状态管理
• 即时战斗游戏：MOBA、FPS 等需要低延迟和高并发的游戏
• 社交游戏：卡牌、棋牌等需要房间管理和实时通信的游戏
• 休闲游戏：中小型休闲游戏，需要简单易用的服务器框架

核心能力

Shield core 仅提供以下核心能力：

能力	职责
服务生命周期	创建、命名、停止和检查服务
消息语义	send / call 路由和超时行为
协程调度	无阻塞地挂起和恢复 Lua 面向的调用
定时器语义	附加到服务执行的超时原语
CAF 适配器	将 CAF 隐藏在 Shield 服务句柄之后

快速开始

local M = {}

function M.on_init()
    shield.log.info("echo service started")
end

function M.ping()
    local src = shield.sender()
    shield.send(src, "pong", { time = shield.now() })
end

return M

非目标

Shield core 不提供以下功能（这些可由用户构建或作为可选扩展评估）：

• 分布式编排或集群管理作为核心路径的一部分
• DI/IoC 容器或基于注解的组装
• ORM 或企业级数据框架
• 与 actor 消息分离的事件总线抽象
• 作为框架策略层的中间件链
• Prometheus、health-check 注册表或插件系统作为核心运行时特性

模块结构

官方运行时模块围绕 core 构建，但不属于核心语义的一部分：

模块	职责
shield_base	Result、Error、ByteBuffer、时间、ID 等共享值类型
shield_lua	Lua VM 管理和 shield.* 绑定
shield_net	客户端连接（TCP/UDP/KCP/WebSocket）、会话管理
shield_transport	可选的字节流适配，如帧或加密
shield_data	原始 DB/Redis 访问，无 ORM 策略
shield_config	YAML 配置加载
shield_log	运行时日志记录
shield_bootstrap	将选定模块组合为可运行服务器

状态与路线图

当前项目处于重构设计阶段。现有的源代码树仍包含先前较广泛架构的模块。在重构期间：

• 文档应首先描述目标边界
• 实现工作应随后移除、合并或降级不再属于 shield_core 或一级运行时模块的模块

查看路线图了解分阶段重构计划和当前范围。

参与贡献

我们欢迎贡献！请查看贡献指南了解如何参与项目开发。

许可证

Apache License 2.0