yakeworld Operational Steps
- 确认输入参数完整
- 执行核心操作（参考本目录下的 scripts/ 或 references/）
- 验证输出符合契约
- 保存结果并报告
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 阶段路径：
概念 → 设计 → 编码 → 预览 → 导出 → 验证
- 概念 — 明确创作愿景：情绪、色彩世界、运动词汇、独特之处
- 设计 — 选择模式、画布、交互模型、色彩系统、导出格式
- 编码 — 单文件 HTML，结构：全局变量 → preload() → setup() → draw() → 辅助函数 → 类 → 事件处理
- 预览 — 浏览器验证，测试分辨率，检查性能
- 导出 — 捕获输出：PNG / GIF / MP4 / SVG
- 验证 — 输出是否匹配概念？是否在目标尺寸上视觉震撼？
编码规范：
- 始终使用
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() 配合外部脚本控制帧前进，并采用实例模式避免全局变量污染