129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# AI Native Visual RPG
|
||
|
||
一个以“AI 叙事 + 本地规则 + 像素演出”为核心的视觉 RPG 原型。
|
||
|
||
当前已经具备这些主要能力：
|
||
|
||
- 世界与角色选择
|
||
- AI 剧情推进与流式对话
|
||
- 战斗演出、NPC 战斗、切磋
|
||
- NPC 交易、送礼、求助、招募
|
||
- 宝藏交互
|
||
- 同伴跟随与战斗
|
||
- 游戏主流程内嵌的角色资产工坊、自定义世界实体编辑与角色形象编辑
|
||
- 自动存档与继续游戏
|
||
|
||
## 运行
|
||
|
||
前置条件：
|
||
|
||
- Node.js
|
||
- Rust / Cargo
|
||
- SpacetimeDB CLI
|
||
|
||
安装依赖：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
准备环境变量：
|
||
|
||
- 复制 `.env.example` 为 `.env.local`
|
||
- 填入 `LLM_API_KEY` / `ARK_API_KEY`
|
||
- 按需设置 `VITE_LLM_MODEL`
|
||
- 如需启用阿里云短信验证码登录，填写 `ALIYUN_SMS_ACCESS_KEY_ID`、`ALIYUN_SMS_ACCESS_KEY_SECRET`，并确认 `SMS_AUTH_PROVIDER="aliyun"`
|
||
- 本地联调短信登录时，建议将 `VITE_AUTH_ALLOW_DEV_GUEST` 设为 `false`，避免开发模式自动进入游客账号而跳过登录页
|
||
- 如需打印完整 prompt/output，可把 `VITE_LLM_DEBUG_LOG` 设为 `true`
|
||
|
||
启动开发环境：
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
补充说明：
|
||
|
||
- `npm run dev` 会启动 SpacetimeDB standalone、Rust `api-server`、主站 Vite 与后台 Vite，适合完整联调。
|
||
- 主站默认地址是 `http://127.0.0.1:3000`，后台可从 `http://127.0.0.1:3000/admin/` 进入，也可直连 `http://127.0.0.1:3102`。
|
||
- 四个模块可独立启动：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run dev:web`、`npm run dev:admin-web`。
|
||
- 如需自动刷新后端模块，使用 `npm run dev -- --watch`；其中 `spacetime-module` 改动后只会重新发布模块，不会重启 standalone，`api-server` 改动后会重启 Rust 进程。主站和后台前端源码变化交给 Vite 自身 HMR，不由外层 watcher 重启。非 watch 模式下可在 `npm run dev` 终端输入 `rs api-server`、`rs web`、`rs admin-web`、`rs spacetime` 或 `rs all`，其中 `rs spacetime` 也是只重新发布模块。
|
||
|
||
构建生产包：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
## 常用检查
|
||
|
||
类型检查：
|
||
|
||
```bash
|
||
npm run lint
|
||
```
|
||
|
||
编码检查：
|
||
|
||
```bash
|
||
npm run check:encoding
|
||
```
|
||
|
||
内容引用校验：
|
||
|
||
```bash
|
||
npm run check:data
|
||
```
|
||
|
||
编辑器 override 校验：
|
||
|
||
```bash
|
||
npm run check:overrides
|
||
```
|
||
|
||
关键内容 smoke 检查：
|
||
|
||
```bash
|
||
npm run check:smoke
|
||
```
|
||
|
||
一键内容检查：
|
||
|
||
```bash
|
||
npm run check:content
|
||
```
|
||
|
||
## 主要结构
|
||
|
||
主运行时：
|
||
|
||
- [src/App.tsx](./src/App.tsx)
|
||
- [src/components/GameShell.tsx](./src/components/GameShell.tsx)
|
||
- [src/hooks/useCombatFlow.ts](./src/hooks/useCombatFlow.ts)
|
||
- [src/hooks/useStoryGeneration.ts](./src/hooks/useStoryGeneration.ts)
|
||
|
||
主流程内嵌编辑能力：
|
||
|
||
- [src/components/CustomWorldEntityEditorModal.tsx](./src/components/CustomWorldEntityEditorModal.tsx)
|
||
- [src/components/CustomWorldNpcVisualEditor.tsx](./src/components/CustomWorldNpcVisualEditor.tsx)
|
||
- [src/components/CustomWorldRoleAssetStudioModal.tsx](./src/components/CustomWorldRoleAssetStudioModal.tsx)
|
||
|
||
核心数据：
|
||
|
||
- [src/data/scenePresets.ts](./src/data/scenePresets.ts)
|
||
- [src/data/characterPresets.ts](./src/data/characterPresets.ts)
|
||
- [src/data/monsterPresets.ts](./src/data/monsterPresets.ts)
|
||
- [src/data/npcInteractions.ts](./src/data/npcInteractions.ts)
|
||
- [src/data/treasureInteractions.ts](./src/data/treasureInteractions.ts)
|
||
|
||
## 文档入口
|
||
|
||
`docs/` 已在 `2026-05-15` 完成压缩整理，旧 PRD、设计、审计、阶段计划和技术流水账不再作为实现依据。当前只读取：
|
||
|
||
- [docs/README.md](./docs/README.md)：当前文档总入口。
|
||
- [docs/【项目基线】当前产品与工程约束-2026-05-15.md](./docs/【项目基线】当前产品与工程约束-2026-05-15.md)：产品、命名、UI、协作和废弃路线。
|
||
- [docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md](./docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)：DDD 边界、API 分组、SpacetimeDB schema 规则和表目录。
|
||
- [docs/【玩法创作】平台入口与玩法链路-2026-05-15.md](./docs/【玩法创作】平台入口与玩法链路-2026-05-15.md)：创作入口、草稿架和各玩法当前口径。
|
||
- [docs/【开发运维】本地开发验证与生产运维-2026-05-15.md](./docs/【开发运维】本地开发验证与生产运维-2026-05-15.md)：本地启动、检查、部署、埋点和运营查询。
|
||
- [UI_CODING_STANDARD.md](./UI_CODING_STANDARD.md)：像素 UI 资产与编码规范。
|