Echo March（残响远征）

链上领土策略游戏，部署于 Monad Testnet。玩家派遣军队穿越网格地形、夺取城池，与 AI 控制的「旧日之主」及其他玩家展开长期对抗。区块归属、驻军、行军、积分流转与战斗结算均在链上记录与执行。

功能状态

✅ 已完成（Week 2 MVP）：

• 链上核心合约 EchoMarch.sol：10×10 地图、5 种地形、44 格危险区（28 格可驻防平原）、注册/日补给、行军（5 min/格、途经遭遇）、驻防/邻格协防/紧急增援、惰性战斗结算、旧日之主约束、Keeper 查询接口
• Hardhat 工程：编译、23 项单元测试（覆盖地图、注册、行军、战斗、增援、旧日约束、Keeper）、部署脚本（Monad Testnet / 本地）
• Web 前端：营销落地页 + RTS 游戏 UI（六边形地图、寻路、行军/战斗面板、事件日志、小地图）；钱包连接（MetaMask）、链上读写、自动推进自己的行军与战斗；未配置合约时以 Demo 数据运行
• 旧日之主 Bot + Keeper：bot/ 工程（viem），K0~K2 推进行军/战斗，P0 回防 / P1 拦截 / P2 反击 / P3 扩张 / P4 压边决策
• 文档：设计文档 Phase 清单已更新，README 即本文件

⏳ 尚未完成 / 规划中：

• 演示截图与录屏
• 事件索引器（可选）、PointsLedger 桥接、防多账号（Sybil）、联盟系统（设计文档明确为非 MVP 范围）

目录结构

Echo-March/
├── contracts/            # 链上合约（唯一源）与部署产物 deployed.json
├── chain/                # Hardhat 工程：编译 / 测试 / 部署 / ABI 同步
├── bot/                  # 旧日之主 AI + Keeper（Node.js + viem）
├── web/                  # React + TypeScript + Vite 前端（营销页 + 游戏）
├── docs/                 # 设计文档与素材提示词
├── image/                # 原始 AI 素材
└── scripts/              # 辅助脚本

快速开始

1. Web 前端（Demo 模式）

cd web
npm install
npm run dev

打开 http://localhost:5173 → 点击「开始游戏」。未配置合约地址时以本地 Demo 数据运行。

启用链上模式（Monad Testnet）：

cd web
cp .env.example .env
# 编辑 .env：填入 VITE_ECHO_MARCH_ADDRESS=<部署后的合约地址>
npm run dev

连接 MetaMask（自动请求切换到 Monad Testnet）后：注册玩家 → 领取日补给 → 规划路径发兵 / 驻防 / 增援。链上事件会实时出现在事件日志。

2. 合约：编译 / 测试 / 部署

cd chain
npm install
cp .env.example .env        # 填入测试网私钥与旧日地址
npm run compile             # 编译合约（contracts/EchoMarch.sol）
npm test                    # 运行 23 项单元测试
npm run sync-abi            # 同步 ABI 到 web/src/chain 与 bot/src

# 部署到 Monad Testnet（结果写入 contracts/deployed.json）
npm run deploy:testnet

# 本地 Hardhat 网络部署（验证流程）
npm run deploy:local

部署后将 contracts/deployed.json 中的地址填入 web/.env 与 bot/.env。

3. 旧日之主 Bot + Keeper

cd bot
npm install
cp .env.example .env        # 填入合约地址与旧日私钥（测试网专用）
npm run smoke               # 决策逻辑冒烟测试（无需真实链）
npm start                   # Keeper + AI 主循环（默认 30s 一轮）

仅运行 Keeper（推进行军与战斗，不决策）：

npm run keeper

环境变量

文件	变量	说明
web/.env	VITE_ECHO_MARCH_ADDRESS	合约地址；留空则前端运行 Demo
web/.env	VITE_MONAD_RPC_URL	默认 https://testnet-rpc.monad.xyz
chain/.env	MONAD_RPC_URL / DEPLOYER_PRIVATE_KEY / OLD_LORD_ADDRESS	部署配置
bot/.env	ECHO_MARCH_ADDRESS / OLD_LORD_PRIVATE_KEY / TICK_INTERVAL_MS / MAX_ACTIONS_PER_TICK	Bot 配置

链上网络

• 网络：Monad Testnet
• Chain ID：10143
• RPC：https://testnet-rpc.monad.xyz
• 浏览器：https://testnet.monadscan.xyz

测试

chain/test/EchoMarch.test.ts 覆盖：

• 地图初始化（100 格、5 地形数量、危险区与旧日初始驻军）
• 注册 / 重复注册 / 每日补给计时
• 行军路径校验（长度、通行、连续、终点可驻防）、发兵扣款、惰性推进
• 途经旧日之城触发战斗、战斗损耗、结算占领
• 驻防上限、邻格协防冷却与门槛、紧急增援到账
• 旧日单格 500 上限与危险区总驻军上限
• Keeper 查询接口（getActiveMarchIds / getMarchProgress 等）

安全说明

• 所有私钥仅用于测试网；生产环境请使用 KMS / 环境变量注入
• Bot 私钥切勿提交到 Git（.gitignore 已忽略 .env）
• 战斗与行军推进对所有人开放调用，Bot 只是例行 Keeper，无法篡改规则

文档

• 设计文档（v0.8） — 完整游戏设计、链上架构与 MVP 范围
• UI 图像提示词
• 营销页提示词