feat(examples): add an authoritative guest room server

.github/workflows/ci.yml

@@ -223,7 +223,7 @@ jobs:
         id: vcpkg-cache
         env:
           VCPKG_CACHE_REVISION: 0699a19d0c6386247ce50d4dedbb8217d484d536
-          VCPKG_CACHE_FEATURES: 'application;boost;compression-tests;etcd-client'
+          VCPKG_CACHE_FEATURES: 'application;boost;compression-tests;etcd-client;guest-room'
           VCPKG_CACHE_DEFAULT_FEATURES: 'true'
           VCPKG_CACHE_PROFILE: applications
         run: node .github/scripts/vcpkg-cache.mjs
@@ -277,7 +277,7 @@ jobs:
         run: >-
           cmake -S . -B ci-build -G Ninja
           "-DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
-          "-DVCPKG_MANIFEST_FEATURES=application;boost;compression-tests;etcd-client"
+          "-DVCPKG_MANIFEST_FEATURES=application;boost;compression-tests;etcd-client;guest-room"
           -DCMAKE_BUILD_TYPE=Debug
           "-DCMAKE_C_COMPILER_LAUNCHER=$env:ARK_COMPILER_LAUNCHER"
           "-DCMAKE_CXX_COMPILER_LAUNCHER=$env:ARK_COMPILER_LAUNCHER"
@@ -292,6 +292,7 @@ jobs:
           -DARK_BUILD_CORE_TESTS=ON
           -DARK_BUILD_COMPRESSION_TESTS=ON
           -DARK_BUILD_EXAMPLES=ON
+          -DARK_BUILD_GUEST_ROOM_EXAMPLE=ON
           -DASIO_STANDALONE=OFF
       - name: Save vcpkg package archives
         if: ${{ success() && steps.vcpkg-cache.outputs.enabled == 'true' && steps.vcpkg-restore.outputs.cache-hit != 'true' }}

config/guest_room.app.toml

@@ -0,0 +1,23 @@
+[application]
+plugin_library_dir = "bin/"
+plugin_config_dir = "conf/"
+
+[[plugins]]
+name = "ark_utility_plugin"
+config = ""
+
+[[plugins]]
+name = "ark_kernel_plugin"
+config = "kernel.plugin.conf"
+
+[[plugins]]
+name = "ark_bus_plugin"
+config = "guest_room.bus.toml"
+
+[[plugins]]
+name = "ark_net_plugin"
+config = ""
+
+[[plugins]]
+name = "guest_room_plugin"
+config = ""

config/guest_room.bus.toml

@@ -0,0 +1,21 @@
+[bus]
+relations = []
+
+[[bus.applications]]
+name = "game"
+type = 31
+
+[[bus.processes]]
+bus_id = "1.1.31.1"
+server_endpoint = "tcp://127.0.0.1:19100"
+intranet_endpoint = ""
+max_connections = 32
+threads = 1
+
+# Required by the current Bus schema; no registration or external service is used.
+[bus.registry]
+host = "127.0.0.1"
+port = 0
+service_name = "unused"
+check_interval = "10s"
+check_timeout = "3s"

docs/guides/examples.md

@@ -7,6 +7,7 @@ The bundled examples use capability names. Configure with applications and examp
 | `examples/timers` / `timers` | `timers_plugin` | Utility timers and module lifecycle; enabled, participates in updates |
 | `examples/module_lifecycle` / `module_lifecycle` | `module_lifecycle_plugin` | Lifecycle and a small data-list demonstration; enabled, no update override. The callback demonstration remains commented out |
 | `examples/entity_operations` / `entity_operations` | `entity_operations_plugin` | Kernel entity/data/table operations; enabled, no update override. Startup performs a bounded functional demonstration; the [old timed workload](../../benchmarks/ENTITY_OPERATIONS.md) runs only through an explicit benchmark command |
+| `examples/guest_room` / `guest_room` | `guest_room_plugin` | Optional 2D guest lobby with Kernel entities and the real Net transport; enable `ARK_BUILD_GUEST_ROOM_EXAMPLE`. [Build, protocol and native verification](../../examples/guest_room/README.md); official [C# Godot client](https://github.com/OpenArkStudio/ark-client-godot) |
 | `examples/mysql_sample` / `mysql_sample` | `mysql_sample_plugin` | Native MySQL coroutine example; disabled in the application example list, assembly checked by database tests with SSL enabled |
 | `examples/redis_sample` / `redis_sample` | `redis_sample_plugin` | Native Redis coroutine example; disabled in the application example list, assembly checked by database tests |
 | `examples/physics_scene` / `physics_scene` | `physics_scene_plugin` | Disabled; requires unsupported legacy PhysX 3. The checked-in sources and manifest do not establish a runnable integration |

docs/guides/examples_CN.md

@@ -7,6 +7,7 @@
 | `examples/timers`／`timers` | `timers_plugin` | Utility 定时器与模块生命周期；启用，参与 update |
 | `examples/module_lifecycle`／`module_lifecycle` | `module_lifecycle_plugin` | 生命周期与少量 data-list 演示；启用，无 update 覆写。回调演示代码仍被注释 |
 | `examples/entity_operations`／`entity_operations` | `entity_operations_plugin` | Kernel 实体、数据和表操作；启用，无 update 覆写。启动仅做有界功能演示；[旧计时负载](../../benchmarks/ENTITY_OPERATIONS_CN.md)只能通过显式基准命令运行 |
+| `examples/guest_room`／`guest_room` | `guest_room_plugin` | 可选二维访客大厅，使用 Kernel 实体与真实 Net 传输；通过 `ARK_BUILD_GUEST_ROOM_EXAMPLE` 启用。[构建、协议与原生验证](../../examples/guest_room/README_CN.md)；官方 [C# Godot 客户端](https://github.com/OpenArkStudio/ark-client-godot) |
 | `examples/mysql_sample`／`mysql_sample` | `mysql_sample_plugin` | 原生 MySQL 协程示例；应用示例列表中仍关闭，开启 SSL 的数据库测试检查其装配 |
 | `examples/redis_sample`／`redis_sample` | `redis_sample_plugin` | 原生 Redis 协程示例；应用示例列表中仍关闭，数据库测试检查其装配 |
 | `examples/physics_scene`／`physics_scene` | `physics_scene_plugin` | 关闭，依赖不支持的旧 PhysX 3；保留源码与清单不代表集成可运行 |

examples/CMakeLists.txt

@@ -52,3 +52,8 @@ add_subdirectory(entity_operations)
 
 #add_subdirectory(http_client)
 #add_subdirectory(mysql_sample)
+
+option(ARK_BUILD_GUEST_ROOM_EXAMPLE "Build the optional JSON guest-room client/server example" OFF)
+if(ARK_BUILD_GUEST_ROOM_EXAMPLE)
+    add_subdirectory(guest_room)
+endif()

examples/guest_room/CMakeLists.txt

@@ -0,0 +1,28 @@
+find_package(nlohmann_json CONFIG REQUIRED)
+BUILD_PLUGIN_MACRO("guest_room_plugin")
+set_property(TARGET guest_room_plugin APPEND PROPERTY LINK_LIBRARIES nlohmann_json::nlohmann_json ark::kernel ark::net)
+
+add_executable(ark_guest_room_codec_tests ../../tests/core/main.cpp ../../tests/guest_room/codec.cpp)
+set_property(TARGET ark_guest_room_codec_tests PROPERTY LINK_LIBRARIES ark::net nlohmann_json::nlohmann_json)
+add_custom_target(check-guest-room-codec
+    COMMAND $<TARGET_FILE:ark_guest_room_codec_tests> "--test-case=*"
+    DEPENDS ark_guest_room_codec_tests USES_TERMINAL VERBATIM)
+target_compile_definitions(ark_guest_room_codec_tests PRIVATE
+    ARK_GUEST_ROOM_VECTORS="${CMAKE_CURRENT_SOURCE_DIR}/wire-vectors.json")
+
+if(UNIX)
+    add_executable(ark_guest_room_server_tests ../../tests/guest_room/server.cpp)
+    set_property(TARGET ark_guest_room_server_tests PROPERTY LINK_LIBRARIES ark::net nlohmann_json::nlohmann_json)
+    add_custom_target(check-guest-room-server
+        COMMAND ${CMAKE_COMMAND} "-DBIN_DIR=$<TARGET_FILE_DIR:guest_room_plugin>"
+            "-DRUNTIME_DIR=${CMAKE_CURRENT_BINARY_DIR}/native-runtime" -DHOST=127.0.0.1 -DPORT=19191
+            -P "${CMAKE_CURRENT_SOURCE_DIR}/stage.cmake"
+        COMMAND $<TARGET_FILE:ark_guest_room_server_tests> "$<TARGET_FILE:app>"
+            "${CMAKE_CURRENT_BINARY_DIR}/native-runtime" 19191
+        DEPENDS app guest_room_plugin ark_kernel_plugin ark_utility_plugin ark_bus_plugin ark_net_plugin
+            ark_guest_room_server_tests
+        USES_TERMINAL VERBATIM)
+    add_custom_target(check-guest-room DEPENDS check-guest-room-codec check-guest-room-server)
+else()
+    add_custom_target(check-guest-room DEPENDS check-guest-room-codec)
+endif()

examples/guest_room/README.md

@@ -0,0 +1,39 @@
+# Guest room example
+
+[中文](README_CN.md)
+
+`guest_room_plugin` runs a small 2D guest lobby through the real ARK launcher, Utility, Kernel, Bus and Net plugins. A joined session owns a `GuestPlayer` Kernel entity. Movement updates the server entity; snapshots read its custom name, position and sequence fields. The sequence uses the supported Kernel custom int64 setter while preserving the protocol's unsigned 32-bit bounds. Net callbacks and all business mutations execute on the launcher owner thread. Login and the default CS/SS framing are unchanged. No Registry, Consul, database, account or persistence service is required.
+
+## Build and run
+
+Use the repository's normal native dependencies, including the existing optional `nlohmann_json` CMake package. Enable applications, examples and this optional example in the same build:
+
+```sh
+cmake -S . -B app-build -DARK_BUILD_APPLICATIONS=ON -DARK_BUILD_EXAMPLES=ON -DARK_BUILD_GUEST_ROOM_EXAMPLE=ON
+cmake --build app-build --target app guest_room_plugin ark_kernel_plugin ark_utility_plugin ark_bus_plugin ark_net_plugin --parallel 1
+./examples/guest_room/run.sh --bin-dir "$PWD/app-build/bin" --runtime-dir "$PWD/run/guest_room" --host 127.0.0.1 --port 19100
+```
+
+Supply the normal dependency toolchain/prefix arguments when configuring; select the `guest-room` vcpkg manifest feature when using vcpkg. Add `--debug` to the run command for a Debug build (`app_d` and `_d` plugins). The script stages a complete matching binary directory, the TOML manifests and the example's metadata. `--host` is a local bind address/hostname; `--port` must be 1..65535. Use a fresh runtime directory. Stop with Ctrl+C. The launcher retains resources and reports a failure if its five-second shutdown deadline is exceeded.
+
+The equivalent platform-neutral staging command is:
+
+```sh
+cmake -DBIN_DIR=/absolute/app-build/bin -DRUNTIME_DIR=/absolute/run/guest_room -DHOST=127.0.0.1 -DPORT=19100 -P examples/guest_room/stage.cmake
+cd /absolute/run/guest_room
+./bin/app --busid=1.1.31.1 --name=guest_room --app_conf=conf/guest_room.app.toml --log_conf=conf/log.conf --shutdown_timeout_ms=5000
+```
+
+Use `app.exe` / `app_d.exe` on Windows. Connect the official [C# Godot client](https://github.com/OpenArkStudio/ark-client-godot) to the same host/port; send movement at about 10 Hz. The client must join again after reconnecting, clear old frame/state buffers and accept a new player ID. Detailed wire fields and errors are in the [protocol](protocol.md); [wire-vectors.json](wire-vectors.json) mirrors the C# test fixture.
+
+## Native verification
+
+```sh
+cmake --build app-build --target check-guest-room --parallel 1
+```
+
+`check-guest-room-codec` checks the shared golden frames, every single split point, coalesced frames, the 4096/4097-byte boundary, invalid magic/flags, fresh parser state and numeric/name bounds using the real Net session parser. On POSIX systems, `check-guest-room-server` launches the real `app`, loads the actual plugin DSOs and exercises two native TCP peers: join, both directions of authoritative movement, stale and malformed requests, bounded errors, disconnect, reduced roster, fresh rejoin, invalid-frame close and normal process shutdown. It stages an isolated runtime and uses local port 19191; run one instance at a time. The process test uses POSIX child-process control and is not a Windows runtime acceptance check.
+
+The Applications workflow enables this optional example on its existing platform matrix. Its default build includes the plugin on Linux, macOS and Windows; `check-core` includes the codec checks everywhere and the real launcher/two-peer process checks on POSIX systems. Workflow configuration is separate from the result of an individual hosted run.
+
+The application bounds frames to 4096 bytes, connections to 32, joined players to 16, business callbacks to 64 per tick, per-peer messages to 32 per second and its own pending output to eight frames per peer. Exceeding work/output limits closes the affected peer. JSON nesting is limited to eight levels. The sample retains the underlying transport's send-queue limit and closes peers whose sends are rejected. These are demonstration limits; no comprehensive hostile-client hardening, production-capacity, public deployment or Godot visual acceptance is implied by native tests.

examples/guest_room/README_CN.md

@@ -0,0 +1,39 @@
+# 访客房间示例
+
+[English](README.md)
+
+`guest_room_plugin` 通过真实 ARK 启动器及 Utility、Kernel、Bus、Net 插件运行一个二维访客大厅。每个已加入的会话拥有一个 `GuestPlayer` Kernel 实体；移动更新服务端实体，快照读取实体的名称、位置和序列号自定义字段。序列号使用 Kernel 已支持的自定义 int64 setter，协议仍限制为无符号 32 位范围。Net 回调及业务状态修改均在启动器所属线程执行。现有 Login 和默认 CS／SS 帧格式不变，无需 Registry、Consul、数据库、账号或持久化服务。
+
+## 构建与运行
+
+准备仓库的常规原生依赖，以及现有可选依赖 `nlohmann_json` 的 CMake 包。在同一次构建中启用 applications、examples 和本示例：
+
+```sh
+cmake -S . -B app-build -DARK_BUILD_APPLICATIONS=ON -DARK_BUILD_EXAMPLES=ON -DARK_BUILD_GUEST_ROOM_EXAMPLE=ON
+cmake --build app-build --target app guest_room_plugin ark_kernel_plugin ark_utility_plugin ark_bus_plugin ark_net_plugin --parallel 1
+./examples/guest_room/run.sh --bin-dir "$PWD/app-build/bin" --runtime-dir "$PWD/run/guest_room" --host 127.0.0.1 --port 19100
+```
+
+配置时仍需传入正常的依赖工具链或前缀参数；使用 vcpkg 时选择 `guest-room` 清单特性。Debug 构建的运行命令增加 `--debug`，使用 `app_d` 和 `_d` 插件。脚本复制同次构建的完整产物目录、TOML 清单和示例元数据。`--host` 指定本机绑定地址或主机名，`--port` 范围为 `1..65535`。使用新的运行目录，以 Ctrl+C 停服。停服超过五秒时，启动器保留资源并报告失败。
+
+跨平台配置步骤如下：
+
+```sh
+cmake -DBIN_DIR=/absolute/app-build/bin -DRUNTIME_DIR=/absolute/run/guest_room -DHOST=127.0.0.1 -DPORT=19100 -P examples/guest_room/stage.cmake
+cd /absolute/run/guest_room
+./bin/app --busid=1.1.31.1 --name=guest_room --app_conf=conf/guest_room.app.toml --log_conf=conf/log.conf --shutdown_timeout_ms=5000
+```
+
+Windows 使用 `app.exe`／`app_d.exe`。官方 [C# Godot 客户端](https://github.com/OpenArkStudio/ark-client-godot)连接相同主机和端口，移动发送频率约为 10 Hz。断线重连后，客户端须清空旧帧和房间状态，重新加入并接收新的玩家 ID。字段和错误约定见[协议](protocol_CN.md)；[wire-vectors.json](wire-vectors.json) 与 C# 测试使用相同的线格式向量。
+
+## 原生验证
+
+```sh
+cmake --build app-build --target check-guest-room --parallel 1
+```
+
+`check-guest-room-codec` 使用真实 Net 会话解析器，检查共享线格式向量、每个单一拆分位置、粘包、4096／4097 字节边界、错误标记和 flags、全新解析状态，以及数字和名称边界。POSIX 系统上的 `check-guest-room-server` 启动真实 `app` 并加载插件动态库，通过两个原生 TCP 客户端检查加入、双向权威移动、过期与非法请求、有界错误、断线后的名单缩减、重新加入、非法帧断开及正常停服。测试使用独立运行目录和本机端口 19191；同一时间仅运行一份。进程测试采用 POSIX 子进程控制，不构成 Windows 运行验收。
+
+Applications 工作流在现有平台矩阵中启用本可选示例。默认构建在 Linux、macOS 和 Windows 编译插件；`check-core` 在各平台运行 codec 检查，并在 POSIX 系统运行真实启动器与双客户端进程检查。工作流配置与某次托管运行的结果分别验收。
+
+示例将帧正文限制为 4096 字节，连接数限制为 32，房间人数限制为 16；每轮最多处理 64 次业务回调，每个连接每秒最多 32 条消息，每个连接的业务待发送队列最多保留八帧。超过工作量或输出队列限制时关闭对应连接。JSON 嵌套最多八层。示例沿用底层传输的发送队列限制，发送被拒绝时关闭对应连接。这些是演示限制，原生测试不代表完整的恶意客户端加固、生产容量、公网部署或 Godot 视觉验收。