three-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Three.js / R3F Audit

Three.js / R3F 审计

Purpose

目的

A curated catalog of WebGL performance and correctness checks for Three.js and React Three Fiber projects. Each check is one self-contained file describing what to look for, why it matters, and how to fix it. The skill walks you through running them against a target codebase and producing a structured findings report.
This is not a linter — most checks need contextual judgment, not just pattern-matching. The agent is expected to read the offending code and reason about whether the pattern actually applies in this scene.
Detection commands assume
rg
(ripgrep) and
jq
are on
PATH
. Substitute
grep -rn
and a manual read of
package.json
where they are not.
这是一份针对Three.js和React Three Fiber项目的WebGL性能与正确性检查清单。每项检查都是一个独立文件,说明检查内容、影响原因及修复方法。本技能将引导你针对目标代码库执行这些检查,并生成结构化的审计结果报告。
这不是代码检查工具(linter)——大多数检查需要结合上下文判断,而非仅依赖模式匹配。Agent需要阅读问题代码并分析该模式是否确实适用于当前场景。
检测命令假设环境变量
PATH
中已配置
rg
(ripgrep)和
jq
。若未配置,可替换为
grep -rn
并手动读取
package.json
。

When to Use This Skill

适用场景

  • Reviewing a 3D scene's performance, or before shipping a Three.js / R3F build
  • Investigating a frame-rate regression, especially one that tracks window size
  • Reviewing a change that touches renderer setup,
    useFrame
    , materials, shadows, instancing, or texture loading
  • 审查3D场景性能,或在Three.js / R3F项目发布前进行检查
  • 排查帧率下降问题,尤其是与窗口大小相关的帧率回归
  • 审查涉及渲染器设置、
    useFrame
    、材质、阴影、实例化或纹理加载的代码变更

Workflow

工作流程

Step 1 — Confirm the project actually uses Three.js / R3F

步骤1 — 确认项目是否使用Three.js / R3F

bash
jq -r '
  ((.dependencies // {}) + (.devDependencies // {}) + (.peerDependencies // {}))
  | to_entries
  | map(select(.key | test("^(three$|@react-three/)")))
  | .[].key
' package.json 2>/dev/null
If nothing matches, stop and tell the user the audit doesn't apply.
bash
jq -r '
  ((.dependencies // {}) + (.devDependencies // {}) + (.peerDependencies // {}))
  | to_entries
  | map(select(.key | test("^(three$|@react-three/)")))
  | .[].key
' package.json 2>/dev/null
若没有匹配结果,停止操作并告知用户本审计不适用。

Step 2 — Find renderer entry points

步骤2 — 查找渲染器入口点

These are the anchors most checks key off of:
bash
undefined
这些是大多数检查的核心锚点:
bash
undefined

Vanilla Three.js renderer construction

原生Three.js渲染器构造

rg -n 'new\s+(THREE.)?WebGLRenderer\b' --type ts --type tsx --type js --type jsx
rg -n 'new\s+(THREE.)?WebGLRenderer\b' --type ts --type tsx --type js --type jsx

React Three Fiber Canvas mounts

React Three Fiber Canvas挂载

rg -n '<\s*Canvas\b' --type tsx --type jsx
rg -n '<\s*Canvas\b' --type tsx --type jsx

R3F imperative GL access

R3F命令式GL访问

rg -n "useThree(|gl\s*[:=]" --type tsx --type jsx

Note the file paths — each check refers back to them.
rg -n "useThree(|gl\s*[:=]" --type tsx --type jsx

记录文件路径——每项检查都会引用这些路径。

Step 3 — Decide which conditional checks apply

步骤3 — 确定适用的条件检查项

The convention checks encode project conventions, not Three.js rules. Running them against a project that never adopted the convention produces noise, so activate each one only on its signal:
bash
undefined
约定检查项基于项目约定而非Three.js规则。若项目未采用相关约定,执行这些检查会产生无效结果,因此仅在检测到信号时激活对应检查项:
bash
undefined

useframe-priority — is a priority argument used anywhere?

useframe-priority — 是否使用了优先级参数?

rg -n 'useFrame([^)]},\s-?\d' --type tsx --type jsx
rg -n 'useFrame([^)]},\s-?\d' --type tsx --type jsx

scene-dom-separation — is there a scene directory distinct from components?

scene-dom-separation — 是否存在与components目录分离的scene目录?

ls -d src/scene src/three src/webgl src/components 2>/dev/null
ls -d src/scene src/three src/webgl src/components 2>/dev/null

store-wiring — is there an external atom store?

store-wiring — 是否使用外部原子状态库?

jq -r '((.dependencies // {}) + (.devDependencies // {})) | keys[]' package.json 2>/dev/null
| rg 'nanostores|zustand|jotai|valtio'

No signal → skip that check and say so in the report's skipped list. Each check
file restates its own activation condition; follow that over this summary if
they disagree.
jq -r '((.dependencies // {}) + (.devDependencies // {})) | keys[]' package.json 2>/dev/null
| rg 'nanostores|zustand|jotai|valtio'

若无信号→跳过该检查项,并在报告的跳过列表中说明。每个检查文件都会重新说明其激活条件,若与本摘要冲突,以检查文件中的条件为准。

Step 4 — Run checks from the catalog

步骤4 — 执行清单中的检查项

For each row in the Checks tables below, open
references/checks/<name>.md
and follow its detection and assessment guidance. If the user passed
--check=<name>
, run only that one.
Read every candidate site before reporting it. Most checks list legitimate uses of the pattern they detect — a grep hit is a candidate, not a finding.
对于下方检查项表格中的每一行,打开
references/checks/<name>.md
并遵循其检测和评估指南。若用户传入
--check=<name>
,则仅执行该检查项。
在报告前需阅读所有候选代码位置。大多数检查项会列出检测模式的合法使用场景——grep命中仅为候选,而非确定问题。

Step 5 — Report findings

步骤5 — 报告审计结果

Group findings by severity (
high
,
medium
,
low
) and emit one section per check that produced a finding. Format:
markdown
undefined
按严重程度(
high
、
medium
、
low
)分组结果,每个产生结果的检查项对应一个章节。格式如下:
markdown
undefined

<check-name> — <severity>

<检查项名称> — <严重程度>

Where: <file>:<line> [+ more]
What's wrong: <one sentence>
Suggested fix: ```<lang> <canonical pattern> ```
Why it matters: <one sentence on the user-visible impact>

Each check file ends with a **How to report this finding** section — use its
wording so findings from different checks read consistently.

Skip checks that produced no finding (don't pad the report). End with a tally:
`<N> findings: <high> high, <medium> medium, <low> low`, followed by one line
naming any conditional checks skipped for lack of a signal.
位置: <文件>:<行号> [更多位置]
问题描述: <一句话说明>
建议修复方案: ```<语言> <标准修复代码> ```
影响说明: <一句话说明对用户的可见影响>

每个检查文件末尾都有**如何报告该结果**章节——使用其中的表述,确保不同检查项的结果报告风格一致。

跳过未产生结果的检查项(不要填充报告)。结尾添加统计信息:`<N> 项问题: <high> 高风险, <medium> 中风险, <low> 低风险`,随后用一行说明因无信号而跳过的条件检查项。

Lens Mode

透镜模式

review:changes-review
invokes this skill as a stack lens when the diff touches Three.js or R3F files. In that mode:
  • The caller supplies the scope. Audit exactly the files it resolved and no more — a whole-scene audit returns findings the run cannot attribute to the change
  • Skip Step 1's project detection; the caller already matched on the imports
  • Return findings in the shape the caller asked for, not the report format above
  • Conditional convention checks map to the caller's lowest severity
Standalone invocation is unaffected and stays the primary path.
当代码变更涉及Three.js或R3F文件时,
review:changes-review
会将本技能作为堆栈透镜调用。在此模式下:
  • 调用方会提供检查范围。仅审计其指定的文件,不要进行全场景审计(否则会返回无法归因于本次变更的结果)
  • 跳过步骤1的项目检测——调用方已通过导入匹配确认项目类型
  • 按照调用方要求的格式返回结果,而非上述报告格式
  • 条件约定检查项映射为调用方指定的最低严重程度
独立调用不受影响,仍遵循主流程。

Checks

检查项

Catalog of checks. Each one is defined in
references/checks/<name>.md
.
检查项清单。每个检查项都定义在
references/checks/<name>.md
中。

Performance and correctness

性能与正确性

CheckTopicSeverity
dpr-cap
Cap
devicePixelRatio
by a pixel budget so Retina/fullscreen doesn't quadruple GPU fillrate
High (perf)
fillrate-overdraw
Stacked transparency and post-processing passes shading the same pixels many times overHigh (perf)
render-loop-allocations
new Vector3
and friends inside
useFrame
, producing GC hitches
High (perf)
resource-disposal
Geometries, materials, textures, and render targets leaking VRAM without
.dispose()
High (memory)
useframe-workload
setState
, scene lookups, and raycasts running every frame when they don't need to
High (perf)
asset-reuse
A distinct geometry/material per object where one shared instance would doMedium (perf/memory)
instancing
Hundreds of identical meshes that should be one
InstancedMesh
Medium (perf)
shadow-cost
Shadow map resolution, casting light count, and shadow cameras fitted to nothingMedium (perf)
material-recompiles
Shader-define changes at runtime causing main-thread GLSL recompilesMedium (perf)
texture-budget
Oversized or uncompressed textures, wrong colour space, mipmaps disabledMedium (memory/perf)
frustum-culling
Culling disabled, stale bounding volumes, or one merged mesh spanning the sceneMedium (perf)
检查项主题严重程度
dpr-cap
通过像素预算限制
devicePixelRatio
,避免Retina/全屏场景下GPU填充率飙升至4倍
高(性能)
fillrate-overdraw
堆叠的透明效果和后期处理通道导致同一像素被多次着色高(性能)
render-loop-allocations
在
useFrame
内执行
new Vector3
等操作,导致GC卡顿
高(性能)
resource-disposal
几何体、材质、纹理和渲染目标未调用
.dispose()
导致VRAM泄漏
高(内存)
useframe-workload
setState
、场景查找和射线检测在每帧执行,但实际无需频繁运行
高(性能)
asset-reuse
每个对象使用独立的几何体/材质,而实际上可共享单个实例中(性能/内存)
instancing
数百个相同网格应合并为一个
InstancedMesh
中(性能)
shadow-cost
阴影贴图分辨率、投射光源数量及阴影相机设置不合理中(性能)
material-recompiles
运行时修改着色器定义导致主线程GLSL重新编译中(性能)
texture-budget
纹理尺寸过大、未压缩、颜色空间错误或禁用mipmaps中(内存/性能)
frustum-culling
剔除功能禁用、边界盒过期或单个合并网格覆盖整个场景中(性能)

Project conventions (conditional)

项目约定(条件性)

Run only when Step 3 found the activation signal.
CheckTopicSeverity
store-wiring
Atom store reads that don't subscribe, and unbatched related writesMedium (perf/convention)
useframe-priority
Gameplay at priority 1, effects at priority 2, so effects don't sample stale transformsMedium (correctness/convention)
scene-dom-separation
3D components under
src/scene/
, DOM/HUD under
src/components/
, never mixed in one file
Low (convention)
仅在步骤3检测到激活信号时执行。
检查项主题严重程度
store-wiring
原子状态库读取未订阅,以及相关写入未批量处理中(性能/约定)
useframe-priority
游戏逻辑优先级设为1,特效优先级设为2,避免特效采样过时变换中(正确性/约定)
scene-dom-separation
3D组件放在
src/scene/
,DOM/HUD放在
src/components/
,禁止在同一文件混合
低(约定)

Severity Guide

严重程度指南

  • High — measurable frame-rate or memory impact under realistic load, or a correctness bug that ships visible artifacts. Worth fixing before release.
  • Medium — perf hit on stress paths or older hardware, or a fragile pattern that's likely to break later. Worth scheduling.
  • Low — minor cleanup, style nit, or a pattern that's only suspect in unusual scenes. Note it; don't block on it.
The severity in the table is the check's default. Adjust it for the scene you are looking at and say why — 300 unshared materials in a 12-object scene is still low.
  • 高风险 — 在实际负载下可测量到帧率或内存影响,或存在会导致可见缺陷的正确性问题。发布前必须修复。
  • 中风险 — 在压力场景或旧硬件上存在性能损耗,或属于易出问题的脆弱模式。需安排修复。
  • 低风险 — 轻微清理项、风格问题,或仅在特殊场景下存在风险的模式。记录即可,无需阻塞发布。
表格中的严重程度为检查项的默认值。可根据当前场景调整,并说明原因——例如在仅含12个对象的场景中,300个未共享材质仍属于低风险。

Adding a New Check

添加新检查项

  1. Create
    references/checks/<name>.md
    using the existing checks as a template. Required sections: What it is, Why it matters, How to detect, Anti-patterns, Canonical fix, Notes, and How to report this finding.
  2. Append a row to the appropriate Checks table above with topic and severity.
  3. If the check is conditional on a project convention, state the activation signal in a
    **Conditional:**
    line in its header block and add the detection command to Step 3.
  4. If the check needs special detection (beyond grep + read), describe it in the check file itself rather than baking shell scripts into the skill — keeps each check portable across Claude / Codex / future hosts.
  1. 以现有检查项为模板,创建
    references/checks/<name>.md
    。必填章节:检查内容、影响原因、检测方法、反模式、标准修复方案、注意事项和如何报告该结果。
  2. 在上方对应的检查项表格中添加一行,包含主题和严重程度。
  3. 若检查项为基于项目约定的条件性检查,在其头部块中添加
    **条件:**
    行说明激活信号,并将检测命令添加到步骤3中。
  4. 若检查项需要特殊检测(超出grep+人工阅读),在检查文件中说明,而非将shell脚本硬编码到技能中——确保每个检查项可在Claude/Codex/未来宿主环境中移植。

Out of Scope

超出范围

  • GLSL shader correctness (covered by shader-specific tooling)
  • Model authoring — mesh topology, UV layout, rigging, DCC export settings
  • Browser-level perf tracing (use Chrome DevTools / Spector.js directly)
  • General React patterns — effects, memoization, state architecture (use
    react-audit
    ; this skill only covers React as it meets the Canvas)
The audit reads the JS/TS source. The one exception is
texture-budget
, which also sizes the texture files on disk, because how a texture is delivered — dimensions, format, colour space — is a renderer concern that the source alone cannot answer. How it was authored is not.
  • GLSL着色器正确性(由着色器专用工具覆盖)
  • 模型创作——网格拓扑、UV布局、绑定、DCC导出设置
  • 浏览器级性能追踪(直接使用Chrome DevTools / Spector.js)
  • 通用React模式——副作用、 memoization、状态架构(使用
    react-audit
    ;本技能仅覆盖与Canvas交互的React部分)
本审计仅读取JS/TS源码。唯一例外是
texture-budget
,它还会检查磁盘上的纹理文件大小,因为纹理的交付方式——尺寸、格式、颜色空间——属于渲染器相关问题,仅通过源码无法完全判断。但纹理的创作方式不在本审计范围内。