Rive Script Builder

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.

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.

Workflow

Phase 0: Live Docs Lookup (Default)

Default lookup order:

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

Context7 MCP primary call:

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:

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):

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/.

Phase 1: Scope and Route

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.

Phase 2: Clarify Uncertainty

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.

Phase 3: Present Pending Plan

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.

Phase 4: Implement After Approval

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.

Phase 5: Deliver With Integration Guidance

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.

Protocol and API Guardrails

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.

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