rive-script-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rive Script Builder

Rive脚本构建工具

Build Rive Luau scripts with a strict clarification-first workflow.

Knowledge policy:

Prefer Context7 MCP lookup first (library:
```
/rive-app/rive-docs
```
).
If Context7 is unavailable, fall back to
```
sync_rive_docs.py
```
online/cache/offline chain.
Never invent APIs, lifecycle methods, or editor menus.

遵循严格的「先澄清再构建」工作流，创建Rive Luau脚本。

知识策略：

优先使用Context7 MCP查询（库路径：
```
/rive-app/rive-docs
```
）。
若Context7不可用，则降级使用
```
sync_rive_docs.py
```
的在线/缓存/离线查询链。
绝不凭空创造API、生命周期方法或编辑器菜单。

Non-Negotiable Contract

不可协商的规则

Parse user goal and recommend protocol(s) first.
Ask only high-impact unresolved questions.
Provide a "pending implementation plan" before writing code.
Wait for explicit approval (for example: "同意", "开始写", "approved", "go ahead").
After approval, output:

Luau script code
Rive editor wiring steps
Debug and test suggestions

Follow the user's language automatically.
If approval is missing, do not output final script code.

首先解析用户目标并推荐适用的协议。
仅询问对实现决策有重大影响的未解决问题。
在编写代码前，提供一份「待实现计划」。
等待用户明确批准（例如：「同意」、「开始写」、「approved」、「go ahead」）。
获得批准后，输出以下内容：

Luau脚本代码
Rive编辑器连接步骤
调试与测试建议

自动适配用户使用的语言。
若未获得批准，不得输出最终脚本代码。

Workflow

工作流

Phase 0: Live Docs Lookup (Default)

阶段0：实时文档查询（默认）

Default lookup order:

Context7 MCP (primary)
```
scripts/sync_rive_docs.py
```
(secondary fallback)

Context7 MCP primary call:

text

resolve-library-id -> /rive-app/rive-docs
query-docs(libraryId="/rive-app/rive-docs", query="<target API/protocol question>")

Query templates:

```
docs/context7-query-recipes.md
```

Fallback lookup commands:

bash

python3 "$CODEX_HOME/skills/rive-script-builder/scripts/sync_rive_docs.py" search --source auto --query "PathEffect"
python3 "$CODEX_HOME/skills/rive-script-builder/scripts/sync_rive_docs.py" show --source auto --path scripting/protocols/path-effect-scripts.mdx

Optional cache prewarm (recommended, not required):

bash

python3 "$CODEX_HOME/skills/rive-script-builder/scripts/sync_rive_docs.py" sync

auto

fallback chain:

```
search
```
: online -> cache -> offline
```
show
```
: online -> cache

If fallback happens, keep the reason explicit in output. See

docs/live-docs-workflow.md

. Offline knowledge includes full upstream mirror at

docs/source-scripting/

默认查询顺序：

Context7 MCP（首选）
```
scripts/sync_rive_docs.py
```
（备用降级方案）

Context7 MCP首选调用方式：

text

resolve-library-id -> /rive-app/rive-docs
query-docs(libraryId="/rive-app/rive-docs", query="<目标API/协议问题>")

查询模板：

```
docs/context7-query-recipes.md
```

备用查询命令：

bash

python3 "$CODEX_HOME/skills/rive-script-builder/scripts/sync_rive_docs.py" search --source auto --query "PathEffect"
python3 "$CODEX_HOME/skills/rive-script-builder/scripts/sync_rive_docs.py" show --source auto --path scripting/protocols/path-effect-scripts.mdx

可选的缓存预热（推荐，但非强制）：

bash

python3 "$CODEX_HOME/skills/rive-script-builder/scripts/sync_rive_docs.py" sync

auto

降级链：

```
search
```
：在线→缓存→离线
```
show
```
：在线→缓存

若触发降级查询，需在输出中明确说明原因。详情见

docs/live-docs-workflow.md

。离线知识库包含

docs/source-scripting/

路径下的完整上游镜像。

Phase 1: Scope and Route

阶段1：范围界定与路由

Identify target protocol using
```
docs/protocol-router.md
```
.
Use
```
docs/api-signature-cheatsheet.md
```
to lock exact method signatures.
If exact API details are ambiguous, check matching files in
```
docs/source-scripting/api-reference/
```
.

For data-driven scripts, align with

docs/data-binding-deep-dive.md

and

docs/script-inputs-deep-dive.md

If multiple protocols are needed, propose the smallest viable combination and explain why.
State assumptions explicitly.

使用
```
docs/protocol-router.md
```
确定目标协议。
借助
```
docs/api-signature-cheatsheet.md
```
锁定精确的方法签名。
若API细节存在歧义，检查
```
docs/source-scripting/api-reference/
```
下的对应文件。

对于数据驱动的脚本，需与

docs/data-binding-deep-dive.md

和

docs/script-inputs-deep-dive.md

保持一致。

若需要多个协议，建议使用最小可行组合并说明原因。
明确列出所有假设条件。

Phase 2: Clarify Uncertainty

阶段2：澄清不确定性

Ask only questions that change implementation decisions.
Use
```
docs/clarification-checklists.md
```
.
For interaction-heavy requests, use
```
docs/pointer-events-playbook.md
```
to narrow unresolved event-routing details.
Skip questions already answered by user context.

仅询问会改变实现决策的问题。
参考
```
docs/clarification-checklists.md
```
。
对于交互密集型请求，使用
```
docs/pointer-events-playbook.md
```
缩小未解决的事件路由细节范围。
跳过已被用户上下文回答的问题。

Phase 3: Present Pending Plan

阶段3：提交待实现计划

Present this structure before coding:

Goal understanding
Recommended protocol(s) and rationale
Assumptions and constraints
Implementation outline (functions, inputs, data flow)
Rive wiring steps
Debug and test plan
Explicit confirmation request

If user does not approve, keep refining plan only.

在编码前，需提交以下结构的计划：

目标理解
推荐的协议及理由
假设与约束条件
实现大纲（函数、输入、数据流）
Rive连接步骤
调试与测试计划
明确的确认请求

若用户未批准，仅需持续优化计划。

Phase 4: Implement After Approval

阶段4：获批准后实现

Generate minimal, runnable, typed Luau script first.
Extend with requested behavior only.
Reuse templates from
```
references/scaffold-templates.md
```
.
For common tasks, start from
```
references/case-recipes.md
```
and adapt.
Keep protocol lifecycle contracts valid.

首先生成最小化、可运行、带类型的Luau脚本。
仅根据请求扩展功能。
复用
```
references/scaffold-templates.md
```
中的模板。
对于常见任务，从
```
references/case-recipes.md
```
入手并进行适配。
确保符合协议的生命周期约定。

Phase 5: Deliver With Integration Guidance

阶段5：交付时提供集成指导

Always include:

Final Luau code
Editor wiring instructions (where to attach, bind, and run)
Debug checklist (Problems and Console)
Test suggestions (especially Test scripts for Util logic)

Use

docs/editor-wiring-recipes.md

and

docs/debug-test-playbook.md

. Use

docs/path-api-performance-notes.md

for path-heavy scripts. Use

docs/quality-gates.md

as final quality checklist.

必须包含以下内容：

最终Luau代码
编辑器连接说明（附加、绑定和运行的位置）
调试检查清单（问题与控制台）
测试建议（尤其是针对Util逻辑的Test脚本）

参考

docs/editor-wiring-recipes.md

和

docs/debug-test-playbook.md

。针对路径密集型脚本，参考

docs/path-api-performance-notes.md

。将

docs/quality-gates.md

作为最终质量检查清单。

Protocol and API Guardrails

协议与API约束

Never invent lifecycle functions, interfaces, or editor paths.
Keep
```
TransitionCondition.evaluate
```
fast and side-effect free.
Use
```
ListenerAction.perform
```
for side effects.
For
```
PathEffect
```
, keep
```
update
```
deterministic; use
```
advance
```
only for time-based behavior.
Remember: scripts cannot set normal input values; use context or view model access for writable data.
Remove long-lived listeners when no longer needed to avoid leaks.
Check
```
docs/common-errors-and-fixes.md
```
before final handoff.
If required details are missing, ask before coding.

绝不凭空创造生命周期函数、接口或编辑器路径。
保持
```
TransitionCondition.evaluate
```
执行快速且无副作用。
使用
```
ListenerAction.perform
```
处理副作用。
对于
```
PathEffect
```
，确保
```
update
```
方法具有确定性；仅在基于时间的行为中使用
```
advance
```
。
注意：脚本无法设置普通输入值；如需写入数据，请使用上下文或视图模型访问。
不再需要长生命周期监听器时，需将其移除以避免内存泄漏。
在最终交付前，检查
```
docs/common-errors-and-fixes.md
```
。
若缺少必要细节，需在编码前询问用户。

Output Format

输出格式

Before approval:

Understanding
Open questions
Pending plan
Confirmation prompt

After approval:

Script code
Wiring steps
Debug plan
Test plan

批准前：

目标理解
未解决问题
待实现计划
确认请求

批准后：

脚本代码
连接步骤
调试计划
测试计划

Docs and References Map

文档与参考映射

Live docs sync and fallback rules:
```
docs/live-docs-workflow.md
```
Cross-platform publishing guidance:
```
docs/publish-cross-platform.md
```
Protocol routing and method contracts:
```
docs/protocol-router.md
```
Signature and API quick reference:
```
docs/api-signature-cheatsheet.md
```
Clarification questions by protocol:
```
docs/clarification-checklists.md
```
Data binding deep dive:
```
docs/data-binding-deep-dive.md
```
Script inputs deep dive:
```
docs/script-inputs-deep-dive.md
```
Pointer events playbook:
```
docs/pointer-events-playbook.md
```
Path API and performance notes:
```
docs/path-api-performance-notes.md
```
Final quality gates:
```
docs/quality-gates.md
```
Context7 query templates:
```
docs/context7-query-recipes.md
```
Full mirror index:
```
docs/source-scripting-index.md
```
Full upstream mirror folder:
```
docs/source-scripting/
```
Editor attach and binding steps:
```
docs/editor-wiring-recipes.md
```
Debug and test workflow:
```
docs/debug-test-playbook.md
```
Common errors and fixes:
```
docs/common-errors-and-fixes.md
```
Minimal Luau templates:
```
references/scaffold-templates.md
```
Practical case recipes:
```
references/case-recipes.md
```

实时文档同步与降级规则：
```
docs/live-docs-workflow.md
```
跨平台发布指南：
```
docs/publish-cross-platform.md
```
协议路由与方法约定：
```
docs/protocol-router.md
```
签名与API速查：
```
docs/api-signature-cheatsheet.md
```
按协议分类的澄清问题清单：
```
docs/clarification-checklists.md
```
数据绑定深度解析：
```
docs/data-binding-deep-dive.md
```
脚本输入深度解析：
```
docs/script-inputs-deep-dive.md
```
指针事件指南：
```
docs/pointer-events-playbook.md
```
路径API与性能说明：
```
docs/path-api-performance-notes.md
```
最终质量检查标准：
```
docs/quality-gates.md
```
Context7查询模板：
```
docs/context7-query-recipes.md
```
完整镜像索引：
```
docs/source-scripting-index.md
```
完整上游镜像文件夹：
```
docs/source-scripting/
```
编辑器附加与绑定步骤：
```
docs/editor-wiring-recipes.md
```
调试与测试工作流：
```
docs/debug-test-playbook.md
```
常见错误与修复：
```
docs/common-errors-and-fixes.md
```
最小化Luau模板：
```
references/scaffold-templates.md
```
实用案例参考：
```
references/case-recipes.md
```