Design & Motion · iart-ai/webgl-animation-skills
particle-system
This skill should be used when the user asks to "build a particle system", "make confetti/snow/smoke/sparks", "create a connected-dot/constellation network background", "add a flow-field or curl-noise particle effect", "render thousands of GPU particles with Three.js Points", or "animate emitters with forces". Covers per-particle integration, forces, flow fields, burst/continuous emission, spatial-grid connected dots, and GPU points + shaders.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
Capabilities rely entirely on "inline runnable code + rules": SKILL.md directly provides per-particle state integration loops, force functions, flow fields / curl noise, spatial grid connections, and GPU Points shader snippets—ready to copy and run without libraries or build steps.
skills/particle-system/SKILL.md
Drive many small elements with simple per-particle rules to get emergent, organic motion. Use 2D canvas for hundreds, GPU `Points` for thousands.
What is happening here: Breaks down "particle effects" into a core pipeline (per-particle updates) plus combinable components; the main text serves as the recipe, while references provide complete runnable systems.
Stability depends on integration scheme rather than parameter tuning: Explicitly requires semi-implicit Euler (update velocity first, then update position with new velocity) and dt clamping, reasoned respectively by stability under spring/damping forces and preventing simulation blowups after browser tab throttling.
skills/particle-system/SKILL.md
Prefer **semi-implicit Euler** (update velocity first, then position with the new velocity, as above) — it is stable for the spring/drag forces particles use. Use a fixed or clamped `dt` (`Math.min(dt, 1/30)`) so a stalled tab does not explode the simulation.
What is happening here: Explains "why it's written this way" rather than just providing code; reference canvas boilerplate includes this as a comment: `const dt = Math.min((now - last) / 1000, 1 / 30); // clamp dt`.
Performance bottlenecks are identified with data structure solutions: Connected-dot networks avoid pairwise comparisons by bucketing particles into radius-based cells and checking only 8 neighboring cells, reducing complexity from O(n²) to near O(n).
skills/particle-system/SKILL.md
Naively checking every pair is O(n²) and dies past ~300 particles. Use a **uniform spatial grid**: bin particles by cell, only compare against the 8 neighboring cells.
What is happening here: Provides quantitative thresholds (must switch algorithms above ~300 particles) with copyable implementations, turning "whether to switch implementations" into a decidable problem.
The path to tens of thousands of particles is moving animation into the vertex shader: Positions are fed into BufferGeometry and rendered as Points, along with two specific switches for a "glowing dot" look—additive blending + disabling depth writes, and discarding pixels via gl_PointCoord distance to clip squares into circles.
skills/particle-system/SKILL.md
`AdditiveBlending` + `depthWrite: false` gives the glowing-particle look. `discard` on `gl_PointCoord` distance makes square points round.
What is happening here: The GPU variant alters where data lives (per-particle attributes in vertex buffers, time passed as a single uniform), so it is presented separately rather than just as a "faster version of the same thing".
Deliverables are restricted to single-file HTML without bundlers: Inline 2D canvas, or GPU mode referencing three from a CDN via importmap—one render loop, zero build steps.
skills/particle-system/SKILL.md
For a self-contained particle effect (constellation background, confetti burst, flow field, GPU points) the deliverable is **one HTML file that opens directly in a browser** — canvas 2D inline, or Three.js from a CDN via an importmap for GPU `Points`, one render loop, no build step.
What is happening here: Locks in the deliverable tier (single-file is the right tier), avoiding project scaffolding overhead for particle effects.
Determinism is the prerequisite for verification: Uses seeded PRNG (mulberry32) instead of raw Math.random, making `?t=N` freeze-frames reproducible—the same N yields the exact same pixels, making screenshot verification viable.
skills/particle-system/SKILL.md
**Seed the RNG** — replace bare `Math.random()` with a seeded PRNG (e.g. mulberry32) so spawn positions, angles, and bursts reproduce frame-for-frame.
What is happening here: The harness section provides `let rng = mulberry32(1234);` paired with a fixed time step (`const step = 1 / 60`) before rendering a single frame.
2Core Capabilities
012D canvas particle effect family: confetti / snow / smoke / sparks (differentiated by gravity, drag, lifespan, rotation, and shape)
02Composable force system (gravity, drag, attraction/repulsion, homing spring), where a force = function returning acceleration
03Flow fields and curl noise (divergence-free, fluid-like) with support for time evolution
04Connected-dot / constellation network: spatial grid + distance-based fadeout lines with near-linear complexity
05GPU particles (Three.js Points + ShaderMaterial, animated inside vertex shader, supporting per-particle attributes like life/seed)
06Two emission models: one-shot burst (cone-randomized + upward bias) and continuous emission (steady-state rate + death recycling/respawn)
07Deterministic freeze harness (?t=N reseeding + fixed stepping + single-frame render + window.__ready) and pre-completion checklist (including reduced-motion fallback and dispose lifecycle)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | npx playwright screenshot（验证回路：打开本地 file:// 页面并截冻结帧） |
| cli | 仓库根共享脚本 scripts/seek-shot.sh、scripts/contact-sheet.sh（截图与拼图；不在 skill 目录内） |
| cli | ffmpeg / ffprobe（contact-sheet.sh 用 hstack 拼图；probe-mp4.sh 读编码参数） |
| network | 交付 HTML 经 importmap 从 CDN 取 three（GPU Points 分支）——产物期引用，由浏览器拉取 |
| package | simplex-noise（流场/curl 噪声示例引用的噪声库，注释中点名） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local scripts or commands: (SKILL.md instruction) npx playwright screenshot --wait-for-timeout=600 "file://$PWD/
- 网络端点: Declares external network access: No network calls exist in skill directory code; runtime network surface comes from toolchain: `npx playwright` pulls playw from npm registry on first run
- 本地工作目录: File I/O and artifact output: Core deliverable: single particles.html (created by agent per output contract)
Audit Notes: Evaluation target = the skill directory itself, containing only SKILL.md and a markdown reference (plus a 0-byte README.md): no bundled scripts, no credential reads, no endpoint calls, and no exfiltration of user assets; instruction surface is entirely "write a local HTML file". Runtime only touches local tools (`npx playwright screenshot` opens local file:// pages; repository root scripts perform local screenshots and ffmpeg contact sheet stitching); runtime HTML fetching three via importmap from CDN is browser-side fetching (per paradigm, "runtime artifact dependencies are not graded", recorded in reason only). Points to note: 1) `npx playwright` fetches remote packages and downloads Chromium on first run (one-time tool acquisition, unpinned version, constituting a supply-chain touchpoint; can be fully eliminated by using locally pre-installed Playwright); 2) Referenced scripts/seek-shot.sh and scripts/contact-sheet.sh reside in the repo root rather than the skill directory, resulting in dangling references if only the skill directory is installed; 3) WebGL/GPU dependency: headless environments require swiftshader, otherwise particle pages may render blank, which should be diagnosed via the SKILL.md artifact checklist rather than assuming implementation failure. None of these trigger Yellow (no routine external data transmission) or Orange criteria; a full-repo scan confirmed no Red-tier behaviors such as sandboxing bypass, TLS disabling, or automated detection evasion.
5Second-Pass Verification
- [ok] 「skill 目录内无脚本」是否成立（决定蓝而非黄/橙的关键） — 文件清单实证：skills/particle-system/ 下只有 SKILL.md、README.md(0 B)、references/particle-recipes.md。SKILL.md 提到的 `scripts/seek-shot.sh` 实际位于仓库根 scripts/，并非 skill 自有资产；因此判级对象内确实没有可执行代码。已在 reason/risks 记录「单装 skill 目录会使引用悬空」。
- [ok] 是否存在凭证或环境变量读取 — 全仓正则 `process.env|API_KEY|TOKEN|SECRET|Authorization` 在三个 iart 仓内零命中（唯一命中在 javascript-animation-skills 的 soundtrack/references/ai-music.md，属另一 skill）。本 skill 的 credential_reads 为空成立。
- [ok] 是否有比蓝更高的触发条件被漏掉（红档特征） — 对 `sandbox|automationcontrolled|no-verify|stealth|bypass|ignoreHTTPSErrors|dangerously` 全仓扫描零命中；不存在关沙箱、关 TLS、绕过自动化侦测或任意代码执行面。
- [ok] GPU / 无头渲染前提是否真的写进文档（任务特别提示项） — SKILL.md 验证段原文承认这是环境前提并把归因从代码上摘开：'For GPU points, WebGL needs a GPU context; Playwright/Chromium supplies one (swiftshader) headless.'；完成清单第 1 条也要求无 WebGL 错误。
- [ok] 「O(n) 连接点」与「?t=N 可复现」两条能力声明是否与代码相符 — 空间网格实现（`cell = radius` 分桶、只查 3×3 邻域）与声明一致；harness 要求 seeded PRNG + 固定步进（`const step = 1 / 60`）再渲单帧，确实保证同 N 同像素。无夸大。
- [ok] reference 描述是否逐条落地 — references/particle-recipes.md 开篇即 'Complete, runnable systems for canvas and GPU particles.'，与 SKILL.md 末尾列出的能力项（confetti/snow/smoke、鼠标吸引排斥、simplex 流场与 curl、空间网格星座、GPU Points）在文件内可逐节验证。
6Verdict & Scenarios
Best for: Ideal for scenarios generating motion via code, such as particle/constellation backgrounds, confetti/sparks bursts, snow/rain, smoke, flow field or curl noise vortices, and GPU point clouds with tens of thousands of particles. Delivered as standalone, double-clickable single-file HTML, also suitable for embedding into existing pages (docs provide cleanup requirements for dispose and rAF cancellation). Suitable for users who accept headless browser screenshot verification and have WebGL available (or software rendering fallbacks).
Not for: Not suitable for: 1) Particles requiring real assets or video compositing (this skill only outputs HTML, without encoding or muxing); 2) Ultra-scale simulations requiring backend or cluster compute (GPU path is limited to per-vertex shader animation); 3) Commercial releases requiring strict version locking and offline builds (must self-host three and pin versions); 4) Environments installing only the isolated skill directory without repository-root scripts/ (verification script paths will dangle and require manual command replacement); 5) Purely decorative particle use-cases requiring zero-motion accessibility where static fallbacks must be customized independently (documentation only requires reduced-motion degradation).
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload particle-system.tar.gz
sha256:
Option B · Copy Guide for Agentd8271a602d6dd44b…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 50697d659f.