EdwardAThomson/xaya-roguelike

# Xaya Roguelike 一个基于 [Xaya](https://xaya.io) 游戏框架构建的区块链 roguelike 游戏，通过 Xaya X 桥接针对 EVM 链。玩家将探索一个持久的地下城世界，其中角色、物品栏和进度都存储在链上，而实时的地下城游戏过程则发生在带有加密验证的链下游戏通道中。 ## 运行原理 - **链上大世界**：玩家注册、发现地下城区块、在区块间移动、管理物品栏以及装备物品。世界地图是一个由玩家发现的相互连接的地下城区块组成的永久图谱。 - **链下地下城通道**：当玩家进入一个地下城区块时，会开启一个单人游戏通道。地下城会话（移动、战斗、物品、怪物）在本地实时运行。退出时，玩家会提交一个动作回放证明，GSP 会对其进行确定性验证。 - **确定性生成**：地下城布局、怪物位置和物品生成完全由种子确定性生成。相同的种子在 C++ 后端和 TypeScript 前端中会产生完全相同的地下城。 ## 架构 ``` Polygon / Anvil (EVM) | Xaya X (bridge) | rogueliked (GSP) -- on-chain game state processor | JSON-RPC API / \ Browser AI Player -- clients Frontend (ai_player.py) ``` **GSP**（Game State Processor）是权威的游戏逻辑。它从区块链读取动作，进行处理，并维护 SQLite 游戏数据库。客户端通过 JSON-RPC 连接以读取状态并提交动作。 ## 项目结构 ``` CMakeLists.txt Build system (FetchContent for deps) main.cpp GSP daemon entry point logic.cpp/hpp RoguelikeLogic (extends ChannelGame) moveprocessor.cpp/hpp Processes all 16 on-chain move types moveparser.cpp/hpp JSON move validation and parsing statejson.cpp/hpp State JSON extraction for RPC rpcserver.cpp/hpp Custom JSON-RPC methods dungeon.cpp/hpp Deterministic dungeon generation (80x40 grid) dungeongame.cpp/hpp Dungeon gameplay engine (combat, AI, items) combat.cpp/hpp Attack/defense/crit/dodge math monsters.cpp/hpp 12 monster types scaled by depth items.cpp/hpp 30 item definitions with real stats pending.cpp/hpp Pending move tracking schema.sql SQLite schema (players, segments, visits, etc.) play.cpp Standalone dungeon play binary (JSON stdin/stdout) channelboard.cpp/hpp Channel framework integration (BoardRules) proto/ Protobuf definitions for channel state rpc-stubs/ JSON-RPC stub definitions tests/ Unit tests (132 tests) devnet/ Local development scripts docs/ Setup guide, security docs, segment lifecycle ``` ## 构建 ### 前置条件 有关完整的系统包列表，请参阅 [docs/SETUP.md](docs/SETUP.md)。主要依赖项： - CMake 3.14+ - C++17 编译器 - libxayagame（通过 CMake FetchContent 自动获取） - SQLite3、protobuf、glog、jsoncpp、ZeroMQ、libmicrohttpd ### 编译 ``` cmake -B build cmake --build build -j$(nproc) ``` 这将生成： - `build/rogueliked` -- GSP daemon - `build/roguelike-play` -- 独立的地下城游戏可执行文件 - `build/roguelike-tests` -- 单元测试运行器 ### 运行测试 ``` cd build && ctest --output-on-failure ``` ## 运行 ### 本地 devnet（用于开发） devnet 脚本会启动一个完整的本地技术栈：Anvil（EVM 节点）+ Xaya X（桥接）+ rogueliked（GSP）。 ``` # 前置条件：Foundry (anvil), Xaya X (xayax-eth), Python xayax package source ~/Explore/xayax/.venv/bin/activate # 运行 smoke tests（启动 stack，运行 7 个测试，然后销毁） python3 devnet/smoke_test.py # 运行带有 move proxy 的 persistent devnet 以进行 frontend 开发 python3 devnet/frontend_devnet.py ``` 前端 devnet 会打印连接信息： ``` GSP RPC: http://localhost: Move Proxy: http://localhost:18380 ``` ### 生产环境 ``` ./build/rogueliked \ --xaya_rpc_url= \ --xaya_rpc_protocol=2 \ --game_rpc_port=18332 \ --datadir=/path/to/data \ --genesis_height= \ --genesis_hash= \ --pending_moves ``` ## 游戏动作 所有动作都是以游戏 ID `"rog"` 提交的 Xaya name 更新的 JSON 对象： | 动作 | 格式 | 描述 | |------|--------|-------------| | 注册 | `{"r": {}}` | 创建一个新玩家 | | 发现 | `{"d": {"depth": N, "dir": "east"}}` | 发现一个新区块 | | 移动 | `{"t": {"dir": "east"}}` | 移动到相邻区块 | | 进入通道 | `{"ec": {"id": N}}` | 开始一次地下城会话 | | 退出通道 | `{"xc": {"id": N, "results": {...}, "actions": [...]}}` | 提交带有回放证明的地下城结果 | | 使用物品 | `{"ui": {"item": "health_potion"}}` | 使用一个消耗品 | | 装备 | `{"eq": {"rowid": N, "slot": "weapon"}}` | 装备一件物品 | | 卸下 | `{"uq": {"rowid": N}}` | 卸下物品至背包 | | 分配属性 | `{"as": {"stat": "strength"}}` | 消耗一个属性点 | ## 前端 浏览器前端位于单独的代码库中：`~/Projects/xaya-roguelike-frontend/` 它通过 JSON-RPC 连接到 GSP，显示大世界区块地图，并在本地运行带有链上结算的地下城会话。 ## 安全性 - **动作回放验证**：地下城结果通过在链上重新播放完整的动作序列来进行验证 - **临时区块**：新区块要求发现者在成为永久区块之前完成一次通道运行 - **发现冷却时间**：两次发现之间有 50 个区块的冷却时间，以防止世界地图垃圾信息 - **确定性 RNG**：由 SHA-256 播种的 MT19937，在 C++ 和 TypeScript 中完全一致 有关详细的攻击向量分析，请参阅 [docs/SECURITY_Attack_and_Mitigations.md](docs/SECURITY_Attack_and_Mitigations.md)。 ## 文档 - [PLAN.md](PLAN.md) -- 完整的开发计划和阶段状态 - [docs/SETUP.md](docs/SETUP.md) -- 开发环境设置 - [docs/SECURITY_Attack_and_Mitigations.md](docs/SECURITY_Attack_and_Mitigations.md) -- 攻击向量与缓解措施 - [docs/segment-lifecycle.md](docs/segment-lifecycle.md) -- 区块的发现与生命周期

标签：Bash脚本, C++, EVM, Roguelike, 区块链游戏, 数据擦除, 游戏开发, 状态通道, 逆向工具