# P5js

> p5js

- Skill: `yakeworld/p5js` (Agent Skill, multi-file: 29 files)
- Install (CLI): `npx skillmds@latest add yakeworld/p5js`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yakeworld/p5js/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: yakeworld (https://skillmd.com/u/yakeworld)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/yakeworld/p5js

---



## Operational Steps
1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

## Pitfalls
- 
- 

## Verification
- 
- 
- 
- 
1. 
2. 
3. 
## IO_CONTRACT

- **input**: `request: str, context: dict` — 用户请求描述、上下文信息
- **output**: `result: dict` — 技能执行结果（结构因技能而异）

> 对应原则：P2（机械原子暴露输入输出规范）

## CHANGE_LOG

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-06-27 | 1.2.0 | 重构：提取思想/原则/方法/规则结构，具体代码与案例移至 references/ |

---

# p5.js: 创意编程方法论

## 一、思想

> 以机为笔，以数为墨，画布为界，算法为魂。

p5.js 的本质不是"用 JavaScript 画图形"，而是**用代码表达视觉思想**。画布是媒介，算法是画笔。每一帧都应值得观看。

**核心洞察**：优秀的创意编程作品与教程示例之间的区别不在技术复杂度，而在**审美一致性**——所有元素服从统一的视觉语言，共享色彩温度、运动节奏与构图逻辑。

## 二、原则

### P1. 首帧卓越原则

输出必须在前几帧就视觉震撼。如果看起来像教程示例、默认配置或"AI生成的创意编程"，它就是错的。

### P2. 主动创造原则

不要只做用户要求的东西。在用户请求的基础上添加一个视觉细节——用户没有要求但会欣赏的。

### P3. 密度与层次原则

每一帧都应奖励细看。永远不要平面白色背景。始终有构图层级、意图色彩、微观细节。

### P4. 审美一致性原则

所有元素服从统一的视觉语言——共享色彩温度、一致的笔画词汇、和谐的运动速度。十个不相关的效果不如三个属于同一体系的效果。

### P5. 参数即思想原则

参数应源于算法本身，而非通用菜单。每个参数应改变算法的**思考方式**，而非仅仅外观。"湍流"参数改变噪声八度（好），"粒子大小"滑块只改变椭圆半径（浅）。

## 三、方法

### 方法 1：概念化

在写代码之前，明确：
- **情绪/氛围**：观众应感受到什么？沉思？兴奋？不安？
- **视觉叙事**：随时间/交互发生什么？构建？衰减？变换？
- **色彩世界**：暖/冷？单色？互补色？主导色？强调色？
- **形状语言**：有机曲线？锐利几何？点？线？混合？
- **运动词汇**：缓慢漂移？爆发脉冲？呼吸节奏？机械精确？
- **独特之处**：什么让这件作品与众不同？

### 方法 2：技术设计

| 维度 | 选择 |
|------|------|
| 模式 | 生成艺术 / 数据可视化 / 交互体验 / 动画 / 3D场景 / 图像处理 / 音频响应 |
| 画布 | 1920×1080 / 1080×1920 / 1080×1080 / 响应式 |
| 渲染器 | P2D（默认）/ WEBGL（3D/着色器/混合模式）|
| 帧率 | 60fps（交互）/ 30fps（环境动画）/ noLoop()（静态生成）|
| 导出 | 浏览器显示 / PNG / GIF / MP4 / SVG |
| 交互 | 被动 / 鼠标驱动 / 键盘驱动 / 音频响应 / 滚动驱动 |

### 方法 3：编码管线

每个项目遵循 6 阶段路径：

```
概念 → 设计 → 编码 → 预览 → 导出 → 验证
```

1. **概念** — 明确创作愿景：情绪、色彩世界、运动词汇、独特之处
2. **设计** — 选择模式、画布、交互模型、色彩系统、导出格式
3. **编码** — 单文件 HTML，结构：全局变量 → preload() → setup() → draw() → 辅助函数 → 类 → 事件处理
4. **预览** — 浏览器验证，测试分辨率，检查性能
5. **导出** — 捕获输出：PNG / GIF / MP4 / SVG
6. **验证** — 输出是否匹配概念？是否在目标尺寸上视觉震撼？

**编码规范**：
- 始终使用 `randomSeed()` + `noiseSeed()` 保证可复现性
- 使用 HSB 色彩模式（比 RGB 更直观）
- 分离 CONFIG（参数）、PALETTE（颜色）、globals（可变状态）
- 使用类封装实体：Particle 类含 update() + display()
- 使用 `createGraphics()` 离屏缓冲区进行分层构图

### 方法 4：创意元素生成

每个项目至少发明以下之一：
- 匹配情绪的自定义调色板
- 新颖的噪声场组合（如 curl noise + domain warp + feedback）
- 独特的粒子行为（自定义力场、轨迹、生成机制）
- 用户未请求但提升作品的交互机制
- 创造视觉层级的构图技术

**每项目变体规则**（不可使用默认配置）：
- 自定义调色板（3-7色，非原始 fill(255,0,0)）
- 自定义笔画词汇（细 0.5、中 1-2、粗 3-5）
- 背景处理（纹理/渐变/分层，非纯色）
- 运动多样性（主次元素不同速度：1x / 0.3x / 0.1x）

### 方法 5：性能优化

| 优化手段 | 适用场景 | 效果 |
|----------|----------|------|
| 禁用 FES | 所有作品 | 减少多达 10x 开销 |
| Math.* 替代 p5 封装 | 热循环（粒子/像素） | 显著提速 |
| beginShape() 批量绘制 | 数千粒子 | 比逐个 shape 快数十倍 |
| pixelBuffer 直接写入 | 海量粒子 | 最快路径 |
| pixelDensity(1) | 视网膜屏 | 防止 2-4x 过度绘制 |

### 方法 6：导出管线

| 格式 | 方法 | 说明 |
|------|------|------|
| PNG | `saveCanvas('output', 'png')` | keyPressed 中触发 |
| 高分 PNG | Puppeteer 无头捕获 | 3840×2160 批量 |
| GIF | `saveGif('output', 5)` | 捕获 N 秒 |
| 帧序列 | `saveFrames()` + ffmpeg | MP4 视频 |
| MP4 | Puppeteer 帧捕获 + ffmpeg | 确定帧率 |
| SVG | p5.js-svg + `createCanvas(w,h,SVG)` | 矢量输出 |

## 四、规则

### R1. 触发条件

当用户需要：
- p5.js 草图 / 创意编程 / 生成艺术
- 交互式可视化 / 画布动画
- 浏览器端视觉艺术 / 数据可视化
- 着色器效果 / 粒子系统 / 3D 场景
- 音频响应式视觉

### R2. 版本选择

- **p5.js 1.x (1.11.3)**：默认，稳定，库兼容性最广
- **p5.js 2.x (2.2+)**：需要 async setup()、OKLCH/OKLAB 色彩、p5.brush 时选用

### R3. 输出格式

单文件 HTML。结构：
```
globals → preload() → setup() → draw() → helpers → classes → event handlers
```

### R4. 快捷键约定

| 按键 | 功能 |
|------|------|
| S | 保存 PNG |
| G | 保存 GIF |
| R | 重新生成（新种子）|
| Space | 暂停/继续 |

### R5. 无头渲染

Puppeteer 无头渲染必须使用 `noLoop()`，由捕获脚本控制帧前进。

### R6. 实例模式

生产环境推荐使用实例模式（非全局模式），避免污染 window。嵌入多画布或集成框架时必须使用。

### R7. WebGL 注意事项

- 原点在中心，非左上角
- Y 轴反向（WEBGL 中 Y+ 向上，P2D 中 Y+ 向下）
- push()/pop() 包裹每次变换
- texture() 在 rect()/plane() 之前调用

## 五、参考

| 文件 | 内容 |
|------|------|
| `references/visual-effects.md` | 噪声、粒子系统、纹理生成、图像效果 |
| `references/color-systems.md` | 色彩系统、混合模式、调色板设计 |
| `references/interaction.md` | 交互模型、音频输入、鼠标/键盘处理 |
| `references/animation.md` | 动画技术、时间轴、运动渐变 |
| `references/webgl-and-3d.md` | WebGL 场景、着色器、3D 几何 |
| `references/core-api.md` | 核心 API、构图、离屏缓冲区 |
| `references/shapes-and-geometry.md` | 形状语言、贝塞尔曲线、SVG 路径 |
| `references/typography.md` | 字体处理、动态排版 |
| `references/export-pipeline.md` | 导出管线、平台导出、确定帧捕获 |
| `references/troubleshooting.md` | 故障排查、性能优化 |
| `templates/viewer.html` | 交互式生成艺术查看器模板 |
| `scripts/` | 导出/渲染/服务脚本 |
| `BOUNDARY.md` | 技能边界声明 |
| `EVIDENCE_SCHEMA.md` | 技术证据架构 |
| `IO_CONTRACT.md` | 输入输出规范 |

## 六、版本历史

- **v1.0.0** (2026-03): 初始版本，覆盖 7 种模式
- **v1.1.0** (2026-06): 新增 p5.js 2.x 支持说明
- **v1.2.0** (2026-06): 重构为思想/原则/方法/规则结构

## 验证清单 · VERIFICATION

- [ ] 首几帧即有视觉冲击力，非默认配置/纯色背景，所有元素共享统一色彩温度与运动节奏（审美一致性）
- [ ] 使用 `randomSeed()`+`noiseSeed()`，R 键重生成后输出可复现；CONFIG/PALETTE/globals 分离
- [ ] 浏览器预览通过：目标分辨率下无报错，帧率达标（交互 60fps / 环境 30fps），快捷键 S/G/R/Space 可用
- [ ] 含至少一个主动发明的创意元素（自定义调色板/新颖噪声场/独特粒子行为/未要求的交互），且参数改变算法逻辑而非仅外观
- [ ] 导出产物（PNG/GIF/MP4/SVG）在目标尺寸上视觉匹配概念；无头渲染使用 `noLoop()` + Puppeteer 帧控制
- [ ] 性能达标：热循环用 Math.*/beginShape() 批量/pixelBuffer，`pixelDensity(1)` 防止视网膜屏 2-4x 过度绘制

## Golden 集合 · GOLDEN SET

- **Golden Input**: 标准输入样本（覆盖正常路径）
- **Golden Output**: 预期输出（精确匹配或格式校验）
- **Golden Error**: 预期错误信息（覆盖失败路径）

> Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

> 每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

# P5Js

## Genes (策略基因)

> 紧凑策略表示。条件→策略。需要深度时参考完整文档。

- **[PJS-001]** 输出初帧缺乏视觉冲击力或呈现默认配置 → 必须在前几帧实现视觉震撼，确保所有元素服从统一的视觉语言与审美一致性
- **[PJS-002]** 用户请求基础功能但作品显得平庸 → 主动添加一个用户未要求但能提升作品质量的视觉细节或交互机制
- **[PJS-003]** 画面呈现平面化或背景单调 → 构建构图层级与微观细节，使用纹理/渐变/分层背景替代纯色，确保每一帧奖励细看
- **[PJS-004]** 参数设计仅改变外观而非算法逻辑 → 参数应源于算法本身（如改变噪声八度或力场），而非仅调整几何尺寸（如粒子半径）
- **[PJS-005]** 编码前缺乏明确创作方向 → 先定义情绪、色彩世界、形状语言、运动词汇及独特之处，再进入技术设计与编码阶段
- **[PJS-006]** 处理海量粒子或高性能渲染需求 → 禁用帧事件系统、使用 Math.* 替代 p5 封装、采用 beginShape() 批量绘制或 pixelBuffer 直接写入以优化性能
- **[PJS-007]** 需要无头渲染或生产环境集成 → 使用 noLoop() 配合外部脚本控制帧前进，并采用实例模式避免全局变量污染