Three.js 程序化低多边形资源生成器
此版本要求工作区和 Node.js。使用捆绑的构建器和 CLI 门来收集来自实际资源的证据。
将每个资源(单个或复合体)构建为一个纯的、带种子的函数。实时预览和独立代码导出调用相同的函数,所以用户看到的就是导出的内容。
表面细节: 从实体材质或顶点颜色开始。仅在需要图像贴图来满足请求或可见细节时添加。当原始艺术作品合适时,使用会话的图像生成器,然后将其输出作为构建器的固定输入。
预览选择: 当用户请求预览但未选择模式时,提供快速预览(轨道、平移、检查纹理、播放或擦洗嵌入的剪辑)和完整预览(可编辑参数、装配检查、动画创作或表情)。如果已有快速结果,则共享并使用请求的模式。参见 references/studio-preview.md。
目标: three ≥ r170 作为 ES 模块,对照官方迁移说明检查至 r187(§12 in references/export.md)。
代码在 src/ 中,不在文档中。执行而非重新读取:tsx src/<name>.test.ts(纯测试无需 three)。参考文件列出每个模块的 API。
给出了参考图像? 在编写代码之前阅读 references/reference-matching.md,并在每个构建步骤后运行其循环(§15)。
下一步阅读
| 你正在做的事 | 阅读 | 代码 |
|---|---|---|
| 材质、平面着色、程序化或图像生成的纹理、顶点抖动(§4, §5) | references/look.md | src/lowpoly.ts, src/jitter.ts |
| 自定义几何体、缠绕、镜像部分、覆盖层(§6, §7) | references/geometry.md | src/geometry.ts, src/overlay.ts |
| 生物、船体、机翼、纯三角形内核(§6.2, §6.3) | references/creatures.md | src/tri.ts, src/organic.ts |
| 任何动画内容、人形、挤出、纹理(§6.4 至 §6.7) | references/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| 平面或块状外观、图集、倒角、环境光遮蔽、插槽(§6.8) | references/detail.md | src/detail.ts, src/detailThree.ts |
| 同一文件中的多个子资源(§8) | references/composite.md | |
| 接地、释放、重建、灯光(§9, §10) | references/lifecycle.md | src/lifecycle.ts |
| 代码导出、Three.js 版本(§11, §12) | references/export.md | src/fingerprint.ts |
资源的 .glb 文件(§16) | references/glb-export.md | scripts/export-glb.ts |
是否过重、平台预算、LOD detail(§17) | references/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| 装配、动画剪辑、漂移、表情(§18) | references/rig-check.md | scripts/rig-check.ts |
| 快速 GLB 查看器或完整预览工作室 | references/studio-preview.md | 快速预览 HTML |
| 完整小例子 | references/examples.md | |
| 在说资源完成前:QA 门、审查图像(§13) | references/qa-gates.md | scripts/qa-asset.ts |
0. 约定(一次性决定,全局应用)
| 主题 | 规则 |
|---|---|
| 单位 | 1 单位 = 1 米 |
| 轴 | Y 向上,右手系 |
| 前方 | +Z(与 glTF 和 Object3D.lookAt 相同) |
| 侧面 | 前方为 +Z 且上方为 +Y 时,资源的右侧是 −X,左侧是 +X(右侧 = 前方 × 上方) |
| 枢轴 | 原点位于足迹中心,最低点位于 Y = 0(参见 §9) |
| 面名称 | 按轴命名面(+X face, top),永远不要用 port/starboard/left/right,以避免规则与轴矛盾 |
| 对称性 | 构建一侧,通过 PartBuilder.add 或 mirrorTris 镜像副本(§6.1)。裸用的 applyMatrix4 带负缩放会导致缠绕面朝内 |
为什么这很重要:将 "bow = +Z" 与 "starboard = +X" 配对是镜像的,用此配对构建的船体侧面会交换。前方为 +Z 时,右舷是 −X,左舷是 +X。
1. 一个管线,一个真理源
参数模式(默认值、范围)→ resolveParams() → build…Asset() → THREE.Group
- 默认值和范围仅存在于模式中。
build…Asset(rawParams)自行调用resolveParams。三个竞争的默认值(params.seed || 12345、模式的default: 42、复合体的?? 101)会使预览、预设和导出代码不一致。 build…Asset是纯函数:相同的已解析参数产生完全相同的几何体。没有Math.random、Date.now、DOM 访问或模块级可变状态。- 正常导入
THREE。不要注入THREEInstance:辅助函数使用模块导入,所以注入仅部分生效且隐藏了错误。导出步骤提供导入行(§11)。 - 给每个构建器和参数列表一个唯一名称(
buildTreeAsset,treeParameters)。通用名称buildAsset会在组合体中导入两个生成器时发生冲突。 - 对于自定义几何体(生物、船体、机翼),将形状逻辑保留在纯三角形数组上的纯函数中,并让 THREE 在最后包装结果(§6.2)。仅包含原始几何体的道具可以保留在
PartBuilder上。
类型:src/types.ts(ParamDef、AssetGeneratorSchema)。
工作示例(树):references/examples.md。
2. 确定性
可复现的输出是种子的全部意义,因此保护它:
- 使用
??,永远不要使用||来处理种子和任何数值回退。seed || 12345会静默将种子0变为12345。 - 为每个特征提供自己的分叉流。使用一个共享的
rng,更改segments或切换hasFruits会移动每个后续随机数并打乱资源的无关部分。 - 以固定顺序迭代(数组,而非未知顺序的对象键,或插入顺序不同的
Set)。
代码:src/prng.ts。API:
export function hashString(str: string)export function createPRNG(seed = 1)export type Rng = ReturnType<typeof createPRNG>;
3. 参数
resolveParams 应用默认值、强制类型、限制到 min/max、对齐到 step,并拒绝无效颜色和选择。在 UI、预设和 build…Asset 中使用它,这样没有消费者能产生 NaN 或超出范围的几何体。
代码:src/params.ts。API:
-
export function resolveParams(schema: { parameters: ParamDef[] }, input: Record<string, unknown> = {}) -
在解析后,应用派生约束,以便滑块组合不会产生退化的形状(例如
trunkRadius = Math.min(trunkRadius, crownRadius * 0.6))。 -
保持
seed最大为 99999 或更高。组合构建器派生子种子为fork(label).seed % 100000;较小的最大会将其全部钳制到相同值。 -
切换开关(
hasFruits,hasTurrets)改变构建的内容,从不改变其他部分接收的随机数(§2)。 -
细节切换(
aoStrength,bevel,atlasOn)是普通参数。它们改变细节传递添加的内容,从不改变其他部分接收的随机数。 -
图集流是分叉的。 从
rng.fork('atlas')生成图集,因此切换atlasOn会保持其他所有部分不变(references/detail.md)。
13. 检查清单(按资源勾选,不要预勾选发货)
运行门,然后查看。 npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric 用于纯内核,或 --tris tris.json 用于最终接地资源(用法和门列表:references/qa-gates.md)。它打印 Q1 到 Q10,写入 review.png 并以 @@RESULT 行结束。修复第一个失败的门并重新运行。
完成规则。 在 qa-asset 通过当前构建(或每个失败的门都有其原因命名)、review.png 使用查看工具打开且每个面板的一行说明看到了什么、并且所有列为 UNVERIFIED 或 not checked 的内容在回答中重复之前,永远不要报告资源完成。以最后一次运行的门表结束。
确定性 and 参数
- 默认值和范围仅存在于模式中;
build…Asset调用resolveParams - 种子使用
??;种子0工作;没有Math.random或Date.now - 每个特征有自己的分叉流;切换不重新排列其他部分
- 派生约束阻止退化形状;子种子适合种子范围
参考(仅当用户提供了图像时)
-
ref-spec.md编写一次,ref.json制作,mask PNG 检查;ref-compare在每个构建步骤后运行;门表(§15)在回答中
几何体和外观
- 轴遵循 §0;面按轴描述;右 = −X 当前方 = +Z 时
- 自定义几何体有正的
signedVolume,镜像后也是如此;DoubleSide仅用于零厚度片状体 - 镜像部分通过
add()/addTris或mirrorTris,永远不要使用裸的负缩放applyMatrix4 - 自定义几何体和生物形状存在于纯三角形核中,带有 Node 测试(确定性、符号体积、流隔离)
- 部分通过
bakeFlat+paint;每三角形颜色函数是纯的 - 抖动在
add()之前应用,接缝焊接,边界体积重新计算 - 金属部件有环境贴图或降低的
metalness - 覆盖层使用恒定距离内陷和小的抬升以防止 Z 冲突
装配、人形、纹理(仅当适用时)
- 运动部件是来自
RigBuilder的骨骼,在休息姿势下创作;静态部件保持合并;骨骼 ≤ 约 12 个 - 左/右骨骼来自
mirrorBone+ 镜像矩阵;剪辑使用AnimationMixer在装配根节点上 - 肢体链通过
twoBoneIK或固定点链;脚和手有明确的向前/向上方向 - 挤出和放样部件有正的
signedVolume,镜像后也是如此 - UV 默认关闭,除非使用纹理;使用纹理时,为使用该材质的每个部件设置
PartBuilder({ uv }),并且disposeAsset释放map
细节传递(仅当适用时)
- 图集单元格遵循约定(单元格 0 左上角);使用纹理材质的每个部分都有 UV;粗糙度/法线贴图为
NoColorSpace且roughness: 1 - 图集从分叉流(
seededAtlas)生成,或作为参数注入;构建器从不加载文件或接触 DOM - 倒角和雕刻部分有正的
signedVolume;雕刻量保持半径 > 0 - 环境光遮蔽应用一次(装配使用
aoShade每部分,静态合并使用applyAO),且绝不暗于 0.35 的地板 - 小细节来自
raycastTris/scatterOnSurface+placeTris带sink;镜像侧使用mirrorHit
复合体
- 唯一的导出构建器名称;参数命名空间并通过
pickParams切片 - 放置使用足迹、固定优先级顺序和有界尝试次数
- 跳过的项是确定性的;重复对象被克隆或实例化
质量保证(每个资源)
-
scripts/qa-asset.ts在当前构建上退出 0;review.png已查看,每个面板一个发现;UNVERIFIED 项已列出;门表在回答中
生命周期和导出
- 包装组将资源接地在 Y = 0;每次重建时调用
disposeAsset - 网格已命名;三角形计数在预算内
- 导出器使用真实的 TS 转译器,仅包含一次辅助函数,且除
three外无任何导入(仅当使用mergeGeometries时使用three/addons) - 请求了 GLB:在 §16 中选择导出路径。报告文件,对其字节执行的检查,以及任何未检查的视觉或导入阶段。
- 给出了平台或添加了
detail:scripts/mesh-stats.ts(--lods用于 LOD)退出 0,命名了配置文件和种类,重复了not checked;detail默认值 2 保持现有资源不变 - 导出目标(模块、导入映射、经典全局)与代码运行位置匹配
- 奇偶性测试通过:
generate(params)和导出的模块给出相同的指纹
14. 最小化单个资源(当完整模式过度时)
第一个资约 290 行主要是固定基础设施(prng.ts, lowpoly.ts, params.ts),而非每个资源的成本。将其编写为共享模块一次,永远不要内联到资源文件中。对于一次性道具,跳过模式和 resolveParams,保留 PRNG(确定性仍然重要),并仅使用实际使用的辅助函数导出(helpers: [rawPrng, rawLowpoly])。一个完整的资源大约 30 行:
import * as THREE from 'three';
import { createPRNG } from './prng';
import { PartBuilder, lowPolyMaterial } from './lowpoly';
import { groundAsset } from './lifecycle';
export function buildCrateAsset(raw: { seed?: number; size?: number } = {}) {
const seed = raw.seed ?? 42, size = Math.min(Math.max(Number(raw.size ?? 1) || 1, 0.3), 3);
const rng = createPRNG(seed).fork('planks');
const wood = new PartBuilder();
wood.add(new THREE.BoxGeometry(size, size, size), () => (rng() < 0.5 ? '#8a6a45' : '#7a5c3b')); // 每面颜色,自己的流
for (const s of [-1, 1]) // 角落撑条
wood.add(new THREE.BoxGeometry(size * 0.08, size * 1.02, size * 1.02), '#5b4329', new THREE.Matrix4().makeTranslation(s * size * 0.46, 0, 0));
const content = new THREE.Group();
content.add(wood.build(lowPolyMaterial({ roughness: 0.9 }), { name: 'crate' }));
return groundAsset(content);
}
一旦它获得滑块、预设或用在复合体内,立即提升到完整模式形式(§1)。
15. 参考匹配(当用户提供图像、截图或草图时)
完整流程和脚本:references/reference-matching.md。规则按顺序:
- 一次性摄入。 查看参考一次,编写
ref-spec.md(最多 15 行:朝向、测量比例、部分、调色板、3 个标志性特征、超出范围),运行scripts/ref-intake.ts,查看 mask PNG 一次。之后,永远不要重新读取图像:根据规范和ref.json工作。 - 从粗略到精细构建,每个步骤后比较。 阻挡(G1 比例,G2 方面)→ 轮廓(G2 IoU ≥ 0.85 每个视图)→ 颜色(G3 调色板)→ 细节(G4 标志性特征)。在每个步骤后运行
scripts/ref-compare.ts;耗时不到一秒。 - 数字优先于图片。 每轮仅修复第一个失败的门,更改一个参数组,再次比较。
…
[已截断以进行翻译]