# aholo

**Repository Path**: wangqiyuejava63/aholo

## Basic Information

- **Project Name**: aholo
- **Description**: 基于Aholo平台的3D版本的装修小游戏
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Aholo 家装关卡游戏 V2

本项目是在 `v1.0.0-day1` 基线上实现的第一关卧室布置游戏。房间与家具全部由本地 TypeScript 程序化生成，不加载外部模型、纹理、图片、字体、CDN 或物理引擎。

## 环境与固定依赖

- Node.js 20.18.0
- npm 与 `package-lock.json`
- `@manycore/aholo-viewer` 1.8.1
- Vite 6.4.3
- TypeScript 6.0.3
- Vitest 3.2.4

## 本地运行

在本目录执行：

```powershell
npm ci
npm run dev
```

按终端显示的本地地址打开浏览器。生产构建与本地预览：

```powershell
npm run build
npm run preview
```

一次执行类型检查、单测和生产构建：

```powershell
npm run check
```

## 游戏规则

第一关房间为 8×6×3 米、+Z 向上、无天花板，网格为 0.25 米。将双人床、衣柜和床头柜全部放到房间内，且家具之间不能重叠，即可通关。评分固定为 `null`。

- 布置模式：鼠标或单指拖动家具；拖动时仅更新预览，松手合法后才提交一个命令。
- 视角模式：鼠标或单指拖动环视，滚轮或双指缩放；相机操作不进入命令历史。
- 旋转：选择家具后点击“旋转 90°”，角度按 0/90/180/270° 循环。
- 撤销/重做：覆盖移动和旋转；执行新命令会清空 redo。
- 重新开始：恢复关卡初始状态并清空历史。

无效放置不会修改 `World`，视图会回到已提交状态并显示短提示。

## 配置

- `public/levels/index.json`：关卡索引。
- `public/levels/level-01.json`：第一关语义配置。

配置包含 `version`、`id`、`title`、`room`、`camera`、`gridSize`、`inventory`、`task` 和 `score`。加载时手写校验版本、必填字段、有限数字、正尺寸、唯一家具 ID、任务引用及已注册家具类型。配置只保存家具语义和尺寸，不保存 Mesh 顶点。

## 架构

输入只通过 `PlacementController` 和 Command 修改 `World`：

```text
UI / GameInput → PlacementController → CommandHistory / Command → World
                                      ↓ 已发生事实
                                   EventBus

World → ScenePresenter → FurnitureFactoryRegistry → FurnitureView → AholoRenderer
```

- `World`、关卡校验、碰撞、命令、任务和评分不依赖 Aholo。
- Aholo 引用仅位于 `src/renderer` 层。
- `FurnitureFactoryRegistry` 隔离家具语义与视图工厂，未来可注册本地模型工厂而无需修改 World、关卡或任务代码。
- `ResourceManager` 对共享 Geometry/Material 做引用计数；位置、旋转、选择态和预览态保留在各家具视图实例中。
- `EventBus` 只发布已经发生的冻结事实；TaskSystem 与 UI 订阅者只读 World。

## 渲染与生命周期

使用 Basic Background，关闭 Splatting、TAA 和 Aholo 内置 ground。渲染为按需 `requestAnimationFrame`，没有持续游戏循环。窗口变化通过 `ResizeObserver` 更新 Viewer 和相机；默认 WebGL 初始化失败时尝试 `preferWebGL1`。

关卡卸载和 Vite HMR 会移除 Pointer/Wheel 监听、断开 ResizeObserver、销毁家具视图、释放引用计数资源、销毁房间资源和 Viewer，避免重复 canvas 与 GPU 资源泄漏。

## 测试

Vitest 覆盖：

- 配置校验
- 0.25 米吸附与旋转 footprint
- 房间边界与家具重叠
- TaskSystem 与 `score: null`
- Command undo/redo 与新命令清 redo
- EventBus
- ResourceManager 引用计数
- 关卡卸载
- 双指距离计算

Aholo Picker、WebGL、resize 和手机尺寸 Pointer Event 需要在真实浏览器中验收，不能由 Node 单测替代。