Community图像github.com

threejs-asset-generator

在 Three.js r170+ 中生成程序化低多边形 3D 资源,包含确定性种子构建器、参数模式、平面着色顶点颜色网格、自定义几何体(含正确缠绕)、镜像部件、装配的双足和生物内核、复合体、纹理、独立代码导出,以及与参考图像匹配。不用于加载 glTF 文件。

threejs-asset-generator 是什么?

这是一个专用于 Three.js 的程序化低多边形(low-poly)资源生成器技能。它允许用户通过定义纯函数和参数模式,以确定性方式创建 3D 资源。核心原理是所有资源皆由带种子的纯函数构建,确保相同参数生成完全相同的结果,支持预览、导出和版本控制。该技能适用于 Three.js r170 及以上版本,并会参考官方迁移指南确保兼容性。它支持快速预览(轨道、纹理检查、动画播放)和完整预览(参数编辑、装配检查、动画创作)。技能详细规定了坐标约定(Y 轴向上,右手系,+Z 为前方)、面命名规则(按轴命名而非左右舷)、对称构建方式(通过 `PartBuilder.add` 或 `mirrorTris` 添加镜像部分),并强调使用分叉的随机数流保证每个特征的确定性不受其他特征开关影响。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Luciansvon/ThreeJS-modeling-skill/tree/HEAD/threejs-asset-generator

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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.mdsrc/lowpoly.ts, src/jitter.ts
自定义几何体、缠绕、镜像部分、覆盖层(§6, §7)references/geometry.mdsrc/geometry.ts, src/overlay.ts
生物、船体、机翼、纯三角形内核(§6.2, §6.3)references/creatures.mdsrc/tri.ts, src/organic.ts
任何动画内容、人形、挤出、纹理(§6.4 至 §6.7)references/rigging-biped.mdsrc/rig.ts, src/biped.ts, src/texture.ts
平面或块状外观、图集、倒角、环境光遮蔽、插槽(§6.8)references/detail.mdsrc/detail.ts, src/detailThree.ts
同一文件中的多个子资源(§8)references/composite.md
接地、释放、重建、灯光(§9, §10)references/lifecycle.mdsrc/lifecycle.ts
代码导出、Three.js 版本(§11, §12)references/export.mdsrc/fingerprint.ts
资源的 .glb 文件(§16)references/glb-export.mdscripts/export-glb.ts
是否过重、平台预算、LOD detail(§17)references/budget.mdscripts/mesh-stats.ts, src/lod.ts
装配、动画剪辑、漂移、表情(§18)references/rig-check.mdscripts/rig-check.ts
快速 GLB 查看器或完整预览工作室references/studio-preview.md快速预览 HTML
完整小例子references/examples.md
在说资源完成前:QA 门、审查图像(§13)references/qa-gates.mdscripts/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。规则按顺序:

  1. 一次性摄入。 查看参考一次,编写 ref-spec.md(最多 15 行:朝向、测量比例、部分、调色板、3 个标志性特征、超出范围),运行 scripts/ref-intake.ts,查看 mask PNG 一次。之后,永远不要重新读取图像:根据规范和 ref.json 工作。
  2. 从粗略到精细构建,每个步骤后比较。 阻挡(G1 比例,G2 方面)→ 轮廓(G2 IoU ≥ 0.85 每个视图)→ 颜色(G3 调色板)→ 细节(G4 标志性特征)。在每个步骤后运行 scripts/ref-compare.ts;耗时不到一秒。
  3. 数字优先于图片。 每轮仅修复第一个失败的门,更改一个参数组,再次比较。

…

[已截断以进行翻译]

相关技能