前端概览

ai-world-sim-web 仓库是 AI 世界模拟器项目的前端应用，负责提供用户界面、实时渲染世界状态以及处理用户交互。它基于现代前端技术栈构建，旨在提供流畅、响应式的用户体验。

1. 技术栈

• 框架：Vue 3 (Composition API)
• 语言：TypeScript
• 构建工具：Vite
• UI 库：TailwindCSS (用于快速构建样式)
• 图形渲染：PixiJS 8 (用于高性能 2D 像素艺术渲染)
• 路由：Vue Router
• 状态管理：Vue ref/reactive (配合 composables)

2. 核心功能

• 实时世界地图：使用 PixiJS 渲染动态的像素艺术世界地图，包括地形、建筑、角色、装饰物等。
• 角色管理：显示所有 NPC 和玩家角色的状态、位置和详细信息。
• 事件日志：实时显示世界中发生的各种游戏事件。
• 用户认证：登录、注册功能，通过 API 与后端交互。
• 响应式布局：适应不同屏幕尺寸的设备，提供良好的移动端体验。

3. 架构设计

前端应用采用组件化和模块化的设计思想，主要分为以下几个部分：

• 页面 (Views)：顶层组件，定义了应用的整体布局和路由。
  • MapPage.vue：主地图页面，包含世界地图、侧边栏、角色列表和事件日志。
  • LoginPage.vue：登录/注册页面。
  • CharactersPage.vue：角色列表页面。
  • EventsPage.vue：事件日志页面。
• 组件 (Components)：可复用的 UI 元素，如 GameHeader.vue, CharCard.vue, EventList.vue 等。
• 组合式函数 (Composables)：封装可复用的逻辑，如 useWorld.ts (处理世界状态和 SSE 事件)，useAuth.ts (处理认证逻辑)。
• 工具函数 (Utils)：提供通用的辅助函数，如 textureAtlas.ts (PixiJS 纹理加载)，spriteConfig.ts (精灵配置)。
• 类型定义 (Types)：types.ts 定义了前端和后端之间共享的数据结构。
• API 客户端 (API Client)：api.ts 封装了与后端 API 的交互逻辑。

4. 渲染流程

前端的核心是 PixiJS 渲染引擎，它负责将后端传来的世界状态数据转换为可视化的像素艺术地图。详细的渲染器设计请参考 docs/zh/frontend/RendererDesign.md。

1. 数据获取：通过 useWorld composable 从后端 API 获取世界状态、角色、地点和事件数据，并通过 SSE 接收实时更新。
2. 素材加载：textureAtlas.ts 负责从 R2 CDN 加载精灵图集 (PNG + JSON)，并提供 getAtlasFrame 方法获取单个精灵纹理。
3. 场景构建：WorldMapStardew.vue (或重构后的独立渲染器) 使用 PixiJS 构建场景图，包括多个图层 (地形、建筑、角色、装饰物)。
4. 渲染循环：PixiJS 在渲染循环中根据最新的数据和纹理绘制场景，并处理用户交互 (拖拽、缩放)。
5. 深度排序 (Y-Sort)：通过对渲染对象进行 Y 轴坐标排序，实现 2.5D 视角下的正确层叠关系。

5. 开发规范

• TypeScript：强制使用 TypeScript，确保代码类型安全和可维护性。
• Vue 3 Composition API：推荐使用 Composition API 组织组件逻辑。
• 代码风格：遵循 ESLint 和 Prettier 规范。
• 性能优化：关注 PixiJS 渲染性能，避免不必要的重绘和对象创建。

---

作者：Manus AI 日期：2026年7月10日