洪荒大陆 · 游戏设计项目

当前阶段：游戏设计阶段 — 暂停技术实现

在宣布进入开发阶段前不做技术实现。代码骨架保留项目结构，不继续开发。 设计文档位于 docs/，按策划职能分层组织。

设计文档总览

文档按 世界观 → 系统 → 数值 → 产品 → 技术选型 → 美术 → 测试 → 运营 的依赖链分层：

目录	内容	文档数
docs/00_项目概述/	决策总索引、开发规范、里程碑	10+
docs/01_世界观与剧情/	世界观设定、神话体系	4
docs/02_种族与角色/	19 种族设计、境界体系、转生转化	12
docs/03_核心机制/	底层机制、能量体系、渡劫、数值平衡	5
docs/04_战斗系统/	ATB 战斗、技能总库、PVP	6
docs/05_功法与职业/	功法、职业、生活技能、丹药	5
docs/06_经济系统/	经济循环、拍卖、玩家驱动经济	3
docs/07_地图与世界/	五层世界、副本遗迹、随机事件	7
docs/08_装备系统/	装备打造、强化、本命法宝	2
docs/09_社交系统/	帮派、好友、洞府、新手引导	12
docs/10_产品需求/	PRD 需求文档（核心玩法/战斗/经济/社交/职业/装备/新手引导）	10
docs/11_技术选型/	技术栈选型总览（详细 TDD 待开发阶段补充）	1
docs/12_美术需求/	UI 规范	1

快速链接

• 决策总索引 - 所有核心决策的单一事实源
• 开发规范 - 项目约束与编码标准
• 技术选型总览 - 技术栈选型与架构概览

1. 准备环境变量

cp .env.example .env

.env 中已包含本地开发默认值，通常无需修改。

2. 一键启动全部服务

docker compose up -d

首次启动会自动完成：

• 拉取/构建 PostgreSQL 16、Nakama 3.24.2、Valkey 8、Nacos 2.x 镜像
• 自动创建 nakama（Nakama 元数据）和 honghuang（游戏业务）两个数据库
• 在 honghuang 库执行 database/migrations/001_init_schema.up.sql（含种族、境界、世界层、货币等 seed 数据）
• 自动创建 Nacos namespace honghuang 并导入 configs/nacos/*.yaml
• 编译并加载 server/honghuang-server.so 插件

3. 查看服务状态

docker compose ps
docker compose logs -f nakama

4. 常用端口

服务	端口	说明
Nakama	7349	gRPC API
Nakama	7350	Realtime / HTTP API
Nakama	7351	Console（admin / password）
PostgreSQL	5432	业务库 honghuang + Nakama 库
Valkey	6379	Redis 兼容缓存
Nacos	8848	配置中心 http://localhost:8848/nacos

5. 停止/重置

# 停止服务
docker compose down

# 停止并清空所有本地数据卷（彻底重置）
docker compose down -v

# 只重启 Nakama
docker compose restart nakama

目录说明

• docs/ — 游戏设计文档（GDD/PRD/技术选型/开发规范），按策划职能分层
  • 00_项目概述/ — 决策总索引、开发规范、里程碑
  • 01~09/ — 按系统分层的设计文档（世界观→种族→机制→战斗→职业→经济→地图→装备→社交）
  • 10_产品需求/ — PRD 需求文档
  • 11_技术选型/ — 技术栈选型总览（详细 TDD 待开发阶段补充）
  • 12_美术需求/ — UI 规范
  • 15_归档/ — 过程稿、审阅记录、废弃文档
• AGENTS.md — 项目强约束（人机协作/文档体系/技术合规等）
• client/ — Cocos Creator 项目骨架（设计阶段保留结构，不开发）
• server/ — 服务端骨架（设计阶段保留结构，不开发）
• docker-compose.yml — 本地开发环境配置（设计阶段保留）
• database/migrations/ — 数据库迁移脚本
• configs/nacos/ — Nacos 动态配置（GDD-21 数值参数）
• docker/ — 各服务 Dockerfile 与初始化脚本
• api/ — Protobuf / OpenAPI 定义
• client/ — Cocos Creator 3.x 客户端资源（骨架阶段）
• docs/ — GDD / TDD / PRD 等设计文档（核心产出）
  • docs/设计文档/ — GDD-00~33 游戏设计文档
  • docs/技术文档/ — TDD-01~10 技术设计文档
  • docs/需求文档/ — PRD-01~03 需求文档
  • docs/ai-collab/ — AI协作记录

本地开发 tip

• 修改 server/ 源码后，重新构建 Nakama 镜像：

  docker compose up -d --build nakama
  

• 修改 configs/nacos/*.yaml 后，重新执行配置导入：

  docker compose run --rm nacos-init
  

• 数据库迁移脚本可通过 scripts/migrate.sh、scripts/seed.sh、scripts/reset.sh 在本地 psql 环境执行（需安装 PostgreSQL 客户端）。