Quickstart: Customize and Publish

Run The Living Index locally, customize content and scene layout, save generated project artifacts, validate, and publish through GitHub Actions.

Prerequisites / 准备

• Node.js >=22.13.0
• npm
• Git
• A cloned fork or copy of ACondaway/HOME-3D
• Cloudflare secrets already configured in GitHub for automatic deployment

1. Install and run / 安装与启动

git clone https://github.com/ACondaway/HOME-3D.git
cd HOME-3D
npm install
npm run dev

使用终端打印的 URL。端口 3000 被占用时，开发服务器可能自动改用 3001。

Use the URL printed in the terminal. If port 3000 is occupied, the server may select 3001.

http://localhost:3000/?studio=1

保存和上传接口只存在于本地 Vite 开发服务器，并接受 loopback host/origin，例如 localhost、127.x.x.x 和 ::1。

Save and upload endpoints exist only in the local Vite server and accept loopback hosts/origins such as localhost, 127.x.x.x, and ::1.

2. Customize profile and content / 编辑资料与内容

In Profile:

• replace display name and intro copy;
• set the city;
• set the author’s IANA timezone or GMT/UTC fixed offset.

In Digital assets:

• edit Chinese and English separately;
• configure mirror bio, portrait, alt text, and social buttons;
• upload every camera-page photo and choose one Spotlight;
• add text, media, or links cards.

All photos remain visible. Clicking any photo opens its instant-photo dialog. Spotlight adds ordering and a dedicated editorial column; it does not hide the other photos.

所有照片都会展示。Spotlight 只增加排序与专属文字栏，不会隐藏其他照片。

3. Compose the scene / 编辑场景

In Scene layout you can:

• move, rotate, and scale built-ins;
• disable a built-in and reactivate it later;
• replace only a built-in’s visual with a GLB;
• add custom decorative or interactive GLBs;
• edit interactive custom content with the same card system.

Drag placement has three modes:

Mode	Effect
Plane	X and Z
Height	Y
Heading	Y-axis rotation; Shift snaps to 15°

Scale remains a numeric control.

拖动结果只是 placement preview。点击 Confirm placement 后才进入 Studio 草稿；完成或取消当前摆放后，才能保存、导入、导出或复制 JSON。

A drag is only a placement preview. It enters the Studio draft after Confirm placement. Finish or cancel the placement before saving, importing, exporting, or copying JSON.

4. Understand uploads / 理解上传

Images write immediately to:

public/uploads/profile
public/uploads/photography
public/uploads/cards

GLBs first stage in:

.content-studio-cache/models

They preview through their future /uploads/models/<uuid>.glb URL. Only models still referenced when you click Save to project move into public/uploads/models.

GLB 会先以未来 URL 进行预览；只有保存时仍被引用的模型才进入 public/uploads/models。

5. Save to the repository / 保存到代码仓库

Save to project performs one local transaction:

public/content/site-content.json
app/generated/scene-config.ts
public/uploads/models/<final-referenced-models>

It also clears uncommitted staged models and removes only previously saved GLBs that the new saved scene no longer references.

它还会清空未提交暂存，并只删除“上一份保存场景引用、下一份不再引用”的已发布 GLB。

The browser draft living-index.content-draft.v1 exists only for ?studio=1. Normal published routes ignore it. Reset draft returns Studio to the published state.

浏览器草稿只服务 ?studio=1。普通发布路由忽略它；Reset draft 会让 Studio 回到已发布状态。

6. Validate / 验证

npm run typecheck
npm run lint
npm test
git diff --check

Manually check:

• Chinese and English content;
• portrait and social icons;
• every photo and Spotlight;
• plane, height, and heading placement;
• decorative assets cannot open content;
• interactive assets work through both 3D and the semantic index;
• imported PBR GLBs respond to day/night lighting;
• a normal route without ?studio=1 matches committed content.

7. Commit and publish / 提交与发布

git status --short
git add public/content/site-content.json app/generated/scene-config.ts
git add public/uploads/<specific-files-used-by-this-change>
git diff --cached --check
git commit -m "Customize content and scene"
git push origin main

GitHub Actions runs validation and deploys the Cloudflare Worker. Do not use a direct local deployment for routine updates.

GitHub Actions 会完成验证与 Cloudflare Worker 部署。日常更新不要直接从本机部署。

Import and export / 导入与导出

JSON import/export does not include image or GLB binaries and does not regenerate scene source by itself. To migrate content:

1. copy the referenced uploads;
2. import JSON in a local ?studio=1;
3. click Save to project;
4. validate and commit all resulting files together.

JSON 导入/导出不是完整备份。它不包含二进制资源，也不会单独生成场景源码。