快速开始
本教程引导你用 Apollo 的实 API(与 HEAD 仓库一致,2026-10-07 按实对账)搭一个最小游戏服务器:宿主帧驱动 + 结构化日志 + AOI 场景兴趣管理。
对账口径(2026-10-07,P4-1 批):本页全部代码引自仓库实接头文件——
apollo::runtime::ServiceHost/IHostedService(modules/runtime)、APOLLO_LOG()(modules/core/log)、SceneAoi(modules/game/world)。 早期版本引用的find_package(apollo-*)安装导出与net/tcp/server.hpp均不存在,已按现状重写;网络面现状见文末注记。
创建项目
1. 获取仓库
bash
git clone https://github.com/cuihairu/apollo.git
mkdir my-game-server && cd my-game-server
mkdir src2. 创建 CMakeLists.txt
Apollo 当前不提供 find_package 安装导出;消费方式是把仓库作为子目录加进来,直接链接模块 ALIAS target:
cmake
cmake_minimum_required(VERSION 3.20)
project(MyGameServer CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# 上一级目录克隆的 apollo 仓库作为子项目
add_subdirectory(../apollo apollo-build)
add_executable(game-server src/main.cpp)
target_link_libraries(game-server PRIVATE
apollo::runtime # 宿主/生命周期(modules/runtime)
apollo::core # 日志/配置/指标(modules/core)
apollo::game_world # 场景/AOI/副本(modules/game/world)
)三个 ALIAS target 均为 PUBLIC include 传导:game_world 自带 game_core(EntityId),runtime 自带 core(日志)。
3. 创建主程序
cpp
// src/main.cpp
#include <apollo/runtime/application_host.hpp>
#include <apollo/core/log/log_manager.hpp>
#include <apollo/game/world/scene_aoi.hpp>
#include <csignal>
#include <cstdint>
#include <memory>
#include <string_view>
using apollo::game::core::EntityId;
using apollo::game::world::SceneAoi;
using apollo::runtime::IHostedService;
using apollo::runtime::ServiceHost;
using apollo::runtime::StopReason;
namespace {
volatile std::sig_atomic_t g_interrupted = 0;
}
// 业务服务:实现 IHostedService(start/stop/tick 由宿主帧驱动)
class GameServer : public IHostedService {
public:
std::string_view service_name() const override { return "game-server"; }
bool start() override {
APOLLO_LOG()->info("[GameServer] 游戏服务器启动中...");
// 1000x1000 世界、格子 100、视野半径 30(Scene 独享一个 SceneAoi)
aoi_ = std::make_unique<SceneAoi>(1000.0f, 1000.0f, 100.0f, 30.0f);
// 事件面:Enter / Sync / Leave(sink 缺省静默,由宿主注入)
aoi_->set_event_sink([](const SceneAoi::Event&) { /* 下发面见 P3-2 */ });
// 实体进入(只认 EntityId + 位置值,与实体类型解耦)
for (int i = 1; i <= 100; ++i) {
aoi_->enter(EntityId{static_cast<std::uint64_t>(i)},
{static_cast<float>(i), 0.0f, 0.0f});
}
APOLLO_LOG()->info("[GameServer] 游戏服务器已启动(AOI 100 实体)");
running_ = true;
return true;
}
void stop() override {
APOLLO_LOG()->info("[GameServer] 游戏服务器关闭中...");
running_ = false;
}
bool is_running() const override { return running_; }
void tick() override { /* 定帧业务 */ }
private:
std::unique_ptr<SceneAoi> aoi_;
bool running_ = false;
};
int main() {
// Ctrl+C:信号处理里只置 sig_atomic_t 标志(async-signal-safe),
// 收口走宿主 request_stop。ISignalSource 注入面保留给更复杂的信号源。
std::signal(SIGINT, [](int) { g_interrupted = 1; });
ServiceHost host;
host.add_service(std::make_shared<GameServer>());
if (!host.start()) {
return 1;
}
while (host.is_running() && !g_interrupted) {
host.run_once();
}
if (g_interrupted) {
host.request_stop(StopReason::SignalRequested);
}
host.stop();
return 0;
}要点:
APOLLO_LOG()返回默认 logger(shared_ptr<Logger>),未显式初始化时自动以缺省配置初始化,零配置即用;便捷方法debug/info/warning/error/critical,std::source_location自动溯源。IHostedService的五个纯虚点:service_name/start/stop/is_running+tick(缺省空实现)。- 退出原因经
StopReason(Completed / ConsoleRequested / SignalRequested / StartupFailed)回流,可用host.stop_reason()观察。
4. 构建运行
bash
cmake -B build \
-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
-DAPOLLO_BUILD_GAME_MODULE=ON
cmake --build build
./build/game-server两个必带参数(缺一则构建失败):
CMAKE_TOOLCHAIN_FILE指向 vcpkg——依赖由仓库vcpkg.jsonmanifest 自动安装; 复用已有构建树的依赖可加-DVCPKG_INSTALLED_DIR=<仓库>/build/vcpkg_installed跳过重装。APOLLO_BUILD_GAME_MODULE=ON——apollo::game_world系模块缺省关闭,不带则 target 不存在。
运行后可见宿主与服务日志(ApplicationHost starting → [GameServer] 游戏服务器已启动(AOI 100 实体) → ApplicationHost ready),Ctrl+C 经 request_stop(SignalRequested) 收口。
添加网络通信
现状注记(2026-10-07 复核):
net/tcp/server.hpp(net::tcp::Server) 在仓库中不存在,本节暂无教学示例。现状真实网络面:
modules/net/protocol(apollo::net/protocol::endpoint——服务发现元数据,nng Channel 已退役);modules/protocol(apollo/protocol/messages.hpp+codec.hpp——契约消息与编解码);- legacy
include/apollo/net/(connection/listener/session/websocket/rpc 等头,随迁移批次逐步收敛);- 跨进程最小链路归 net M1(P3-1 G-1 收尾批之后)。
