家居生成器 Cartoon 开源项目 3D web

「21-家居生成器 Cartoon」

/~46ea3a72se~:/

链接：https://pan.quark.cn/s/287e1a10b0dc

OpenHome3D​ 是「家居生成器 Cartoon」的开源版本 ------ 一款完全运行在浏览器中的单间 DIY 家装玩具。输入一个种子，即可一键生成带全套家具的卡通风格 3D 房间；支持拖拽编辑、模型替换、自定义上传、参数化家具调整，以及房间结构与门窗编辑。

全程 无后端、无账号、无 API Key，所有资源本地加载，打开即用。

---

✨ 特性

🏠 程序化房间生成

• 7 种房型：开间、客厅、卧室、厨房、卫生间、书房、餐厅

• 确定性生成：相同种子 + 相同尺寸 = 完全相同的布局

• 四面外墙 + 隔墙：支持门窗开洞、墙高调整、墙体剖切跟随视角

🎨 卡通渲染（Cel-Shading）

• 统一 4 阶渐变 Toon 材质，1px 描边

• 柔和紫色阴影 + 环境光遮蔽

• 等距视角（4 个预设角 + 顶视图）+ 透视视角

• 像可玩的玩具微缩模型

🪑 家具与模型

• 337 个 CC0 家具模型（Kenney + KayKit）

• 18 个参数化家具：实时调整座深/扶手/半径等

• 统一糖果色板：所有参数化家具共用一套精选配色

• 支持自定义上传 ：.glb/.gltf/.obj/.stl/.ply/.dae，浏览器内转 GLB 并存入 IndexedDB

🛠️ 真实编辑能力

• 点击选中、5cm 网格吸附拖拽（Alt临时关闭吸附）

• 方向键微调、A / E旋转 ±15°

• 右键拖拽平移、复制、删除、模型替换、缩放

• 房间尺寸、墙体、门窗实时编辑

🧱 Neo-Brutalism UI

• 奶油纸底色、粗描边、硬阴影、糖果色按钮

• 中英双语标签

• 响应式侧边栏 + 状态栏 + 顶部栏

---

🚀 快速开始

环境要求

• Node.js ≥ 20

安装与运行

npm install
npm run dev        # 终端会打印本地地址（随机高端口）

打开终端中打印的地址即可使用，无需任何额外配置。

常用命令

命令	说明
npm run dev	启动 Vite 开发服务器（随机高端口）
npm run build	严格类型检查 + 生产构建 → dist/
npm run preview	本地预览生产构建
npm run smoke	布局引擎 146 项测试（确定性、碰撞、门区避让等）
npm run smoke:ui	Headless Chrome 截图 + 控制台错误检查
npm run audit:ui	UI 溢出回归检测（10 种状态 × 2 种视口）
npm run assets	重新下载 Kenney / KayKit 资源并重建模型清单

---

📁 项目结构

index.html                # 入口文件
public/
  brand/                  # Logo / favicon
  models/                 # 337 个 CC0 GLB 模型 + LICENSE
scripts/                  # 资源下载、清单生成、端口管理、测试脚本
src/
  assets/manifest.json    # 自动生成的模型清单（勿手动修改）
  state/                  # Zustand 状态管理（房间 / 家具 / 选择 / 上传）
  models/
    palette.ts            # 统一配色方案（唯一颜色来源）
    registry.ts           # 模型注册表（参数化 + 内置 + 上传）
    parametric/           # 18 个参数化家具组件
  lib/toon.ts             # Cel-Shading 核心逻辑
  gen/                    # 房型定义 / 布局引擎 / 墙体推导
  three/                  # Three.js 场景 / 相机 / 灯光 / 交互
  ui/                     # 侧边栏 / 选择面板 / 顶部栏 / 状态栏 / 模态框

---

🛠 技术栈

• React 19

• Three.js​ + @react-three/fiber + drei + postprocessing

• Zustand（带持久化）

• Vite 7

• TypeScript（严格模式）

• idb-keyval（IndexedDB 封装）

---

📜 资源许可

• Kenney -- Furniture Kit：CC0（LICENSE）

• KayKit -- Furniture & Restaurant Bits：CC0（LICENSE）

所有第三方模型均为 CC0 协议，可自由使用，署名可选。

UI 中已明确标注模型来源（内置 / KENNEY / KAYKIT / 我的上传），不使用任何家具厂商商标。

---

🎨 风格约定

参与贡献时，请遵守以下两条核心风格契约：

1. 渲染风格：仅使用 Toon 材质 + 统一色板 + 1px 描边，禁止 PBR / 写实材质

2. UI 风格：Neo-Brutalism（奶油纸、2px 描边、硬阴影、糖果色点缀）

详细规范见 AGENTS.md。