企业官网建设流程全解析

本文依据仓库 public/avatars-3d/README.md 编写，并对照 HermesWorkspace 前端 3D 世界源码展开。该文档定义了一套「可选 GLB 换装」机制：你只需按 NPC id 命名一个 GLB 模型并放入指定目录，Playground 场景中对应的 voxel（体素）角色身体就会被自动替换为精细的 3D 模型，而角色名牌（portrait-chip nameplate）保持不变。读完本文，你将掌握受支持的 NPC id 清单、Meshy 等工具的 Text-to-3D 生成管线、GLB 的放置/加载路径、尺寸对齐方法、性能预算约束，以及模型缺失时的自动降级行为。

机制总览：从 Voxel 身体到 GLB 模型的「零侵入」替换

HermesWorkspace 的 Playground 是一个基于 Three.js / react-three-fiber 构建的 3D 世界，其角色默认由低多边形体素网格（legs / feet / torso 等 boxGeometry 组合）组成。GLB 换装机制的本质是：只要对应 id 的 GLB 文件存在，渲染路径就切换到 GLB 模型；文件不存在则继续渲染 voxel 身体，不会报错、不会出现坏状态。

从 playground-world-3d.tsx 的 NPC 渲染逻辑可以看到这个分支：

const glbId = npcId || avatar const hasGlb = useGlbAvailable(glbId, isNear || highlight) // ... {hasGlb ? ( // GLB body replaces voxel meshes when /avatars-3d/<id>.glb is present. <PlaygroundNpcGlb avatar={glbId} /> ) : ( <> {/* legs */} <mesh position={[0.13, 0.22, 0]} castShadow>...</mesh> {/* feet */} <mesh position={[0.13, 0.04, 0]} castShadow>...</mesh> {/* torso (robe) — colored per NPC */} <mesh position={[0, 0.7, 0]} castShadow>...</mesh> ... </> )}

也就是说，useGlbAvailable()返回true时渲染<PlaygroundNpcGlb>（GLB 身体），否则渲染默认的体素角色。整个流程对玩家（Player）同样适用——playground-player-glb.tsx 实现了同构的玩家 GLB 替换（默认 id 为player-adventurer，scale={0.92}）。

受支持的 NPC id 清单

文档明确规定了可被识别的 NPC id 全集，共 15 个，分为两组：

奥林匹斯神系（8 个）

村庄职业角色（7 个）

tavernkeeper（酒馆老板）、banker（银行家）、trainer（训练师）、innkeeper（旅店老板）、apothecary（药剂师）、recruiter（招募官）、shopkeeper（店主）。

从源码实现看，id 在进入 URL 构造前会经过一次清洗：playground-npc-glb.tsx 中的candidateUrls()使用id.replace(/[^a-z0-9_-]+/gi, '')剔除非法字符，空结果回退到villager-common。这意味着 id 命名应遵循小写 kebab-case（与 public/assets/hermesworld/characters/README.md 中「lowercase kebab-case ids」的命名规则一致），同时这也对运行时探测到的任意字符串提供了安全兜底。

GLB 生成管线（Text-to-3D）

原文档给出了一套面向 Meshy.ai 的完整生成流程，适用于免费额度场景：

1. 打开 https://www.meshy.ai/（免费档：200 credits/月，约 15 次生成）。
2. 使用Text-to-3D功能。
3. 按角色填写提示词（prompt）。

文档为 8 位神系角色各提供了一条可直接复用的建议 prompt（均要求 stylized low-poly 游戏角色、T-pose、全身、中性光照）：

• athena.glb— "Greek goddess Athena, owl helmet, robed, holding a scroll, stylized low-poly game character, T-pose, full body, neutral lighting"
• apollo.glb— "Greek god Apollo, laurel crown, holding a lyre, golden robe, stylized low-poly game character, T-pose, full body"
• iris.glb— "Greek goddess Iris with rainbow-colored wings, courier outfit, stylized low-poly game character, T-pose, full body"
• nike.glb— "Greek goddess Nike of victory, winged warrior, bronze armor, stylized low-poly game character, T-pose, full body"
• pan.glb— "Greek god Pan, satyr legs, panpipes, leather smith apron, stylized low-poly game character, T-pose, full body"
• chronos.glb— "Personification of time as a Greek archivist, hourglass robe, long beard, stylized low-poly game character, T-pose, full body"
• hermes.glb— "Greek god Hermes, winged sandals, winged helmet, caduceus, traveler robe, stylized low-poly game character, T-pose, full body"
• eros.glb— "Greek god Eros as an apothecary, bow on back, robe with vials, stylized low-poly game character, T-pose, full body"

4. 将风格细化到 "Stylized" 或 "Realistic" 之一——推荐整套 8 个角色使用同一种风格，保证整体视觉一致性。
5. 下载 → "Download Model" → 选择 GLB 格式，8K 纹理可用。
6. 将文件放入public/avatars-3d/<id>.glb，刷新页面即可生效。

补充说明：仓库同时维护了另一条规范路径 —— public/assets/hermesworld/characters/README.md 定义角色资产应放在/public/assets/hermesworld/characters/<id>.glb（例如player-adventurer.glb、guard-knight.glb、villager-common.glb），其推荐管线为 Ready Player Me 人体基底 → Mixamo 动画剪辑 → GLB 导出 → 浏览器端优化，并列出首批需要支持的动画（idle、walk、run、talk、inspect、use）。这两条路径目前同时有效：从 playground-npc-glb.tsx 的候选 URL 数组可以看出，加载时会先探测/assets/hermesworld/characters/<id>.glb，再回退探测/avatars-3d/<id>.glb（legacy 路径），因此新资产建议放规范路径，旧资产无需迁移。

运行时加载机制：HEAD 探测 + 接近触发懒加载

GLB 的加载不是无脑全量拉取，而是经过了精心设计的探测与懒加载：

• HEAD 探测：playground-glb-body.tsx 中的useGlbProbe()对 URL 发起fetch(url, { method: 'HEAD' })，并校验响应状态与 Content-Type：要求r.ok且不是text/html，Content-Type 需命中octet-stream/gltf/binary/ 空串 /application/之一，否则视为缺失。探测结果缓存在模块级probeCacheMap 中，避免重复请求。

• 接近触发：playground-world-3d.tsx 的useGlbAvailable(id, enabled)只有在enabled（isNear || highlight，即玩家靠近 NPC 或该 NPC 被高亮）为真时才发起探测请求，结果同样缓存在模块级_glbPresence。NPC 的「靠近」判定阈值约 2.6 个单位距离（见同文件dist < 2.6的邻近检测逻辑）。

• 错误兜底：GLB 挂载外层包裹了GlbErrorBoundary（捕获渲染错误并标记为 missing）和<Suspense fallback={null}>（加载期间不渲染任何内容），因此即使 GLB 文件损坏或加载失败，也不会拖垮整个 3D 场景。

尺寸与对齐：让 GLB 与体素角色站在同一坐标系

Playground 的体素身体高度约为1.6 个世界单位，脚底位于 y=0。若导入的 GLB 过高或悬浮在空中，需要调整缩放与垂直偏移。原文档指出：在playground-world-3d.tsx中修改<PlaygroundNpcGlb scale={...} yOffset={...}>的调用参数，默认值为scale=1, yOffset=0。

对照当前仓库源码，需要说明两点实际差异：

• 渲染管线中真正承载这两个参数的是OptionalGlbBody（playground-glb-body.tsx），它把scale/yOffset透传给GlbInner，最终体现为<group position={[0, yOffset, 0]} scale={scale}>；
• 当前代码里 playground-npc-glb.tsx 实际传入的是scale={0.95} yOffset={0}，玩家 GLB 为scale={0.92}，这是针对多数生成器输出尺寸的经验校准值。

因此，如果你的 GLB 落地后偏高或偏矮，可以调整PlaygroundNpcGlb/PlaygroundPlayerGlb传入的scale；若模型底部未贴地，则增大yOffset的负值方向或直接调scale。Meshy / Tripo 等工具生成的 GLB 大多已预缩放到接近 1.6 米，通常无需额外调整。

性能预算：每个 GLB 的硬性约束

为避免 3D 场景在低端设备上掉帧，文档给出了明确的资源预算（这也是仓库资产的硬性验收标准）：

• 单文件体积：压缩（gzip）后< 2 MB；
• 三角面数：每个角色约10k 三角形足够，更多属于浪费；
• 纹理：避免 4K，最高使用 1024 或 2048。

除此之外，源码在运行时还会对 GLB 做一轮降本优化（见 playground-glb-body.tsx 的GlbInner）：

• 克隆场景后遍历所有网格，开启frustumCulled（视锥剔除）、关闭castShadow/receiveShadow（阴影投射/接收）；
• 将raycast置为空函数（NPC 点击事件由外层<group>的onPointerDown处理，模型自身不参与射线检测）；
• 将贴图anisotropy设为 2，兼顾斜视角清晰度与采样开销。

这些处理说明：即使放入了高面数的模型，运行时也会自动关闭阴影等重开销特性，配合约 10k 三角面的预算约束，可以稳定跑在浏览器端。

缺失与混合搭配：优雅降级是默认行为

该机制的最后一个设计要点是容错。原文档明确：

如果 GLB 缺失，voxel 身体会自动显示——无报错、无坏状态。混搭完全没问题（只有 Athena 的 GLB？那就只有 Athena 获得升级）。

这与前文分析的代码路径完全吻合：useGlbAvailable()返回false时走体素分支；useGlbProbe()的模块级缓存会在首次探测后记住结果，重复进入场景不会重复请求缺失资源。因此你可以按需逐步为角色追加 GLB，而不是一次性补齐 15 个——每一次追加都独立生效，且不会影响其他仍使用 voxel 身体的 NPC。

小结：一条从资源生产到运行时渲染的完整链路

整体来看，这套可选 GLB 换装机制是一条清晰的可落地链路：Meshy Text-to-3D 生成 → GLB 导出 → 按 NPC id 命名放入public/avatars-3d/<id>.glb（或规范路径public/assets/hermesworld/characters/<id>.glb）→ 前端 HEAD 探测 + 接近触发懒加载 → scale/yOffset 微调 → 体积/面数/纹理预算把关 → voxel 自动降级。它既保证了零代码侵入的资产接入体验，又在运行时提供了缓存、错误边界与性能优化，适合在 HermesWorkspace 的 Playground 中持续推进角色视觉升级。