EffectCraft Use
Plugin marketplaces
This plugin belongs to AIGC content creation.
| Category | Marketplace | Purpose |
|---|
| Full-stack development | Full Stack Plugins | Architecture and UI design, code understanding, quality checks, code review, workflow governance, and server operations |
| AIGC content creation | Full AIGC Plugins | Image, video, audio, music, 3D, and multimodal content creation |
EffectCraft Use — motion graphics and composition
Build editable .ecproj compositions — comps, text and shape layers, keyframes, expressions, cameras, masks, puppet pins and effects — then render previews or finished shots with alpha where you ask for it.
English | 简体中文 · Install · Quick start · What you can build · Skills · Troubleshooting
Positioning
EffectCraft Use drives the native EffectCraft CLI from a coding agent: it plans a composition from your assets, installs the pinned runtime on first authorized use, executes native commands in a recorded session, saves and reopens the project, and checks real rendered pixels before calling a shot done.
The native .ecproj project is the source of truth. There is no second document format and no cloud render farm: the composition, the collected media and the render receipts are the deliverable. Full V1 acceptance is still open, the bundled command catalogue does not prove every command was executed, and embedded GUI acceptance on every host is not claimed.
Status and version
0.1.0-dev.20261018.4 · development preview · docs/verification/release-candidate.json → releaseStatus: BLOCKED, installableDevelopmentCandidate: true.
Installation
Prerequisites
- macOS arm64. Seven native platform/architecture targets are locked, but acceptance evidence currently covers macOS arm64; anything else returns
unsupported_platform.
- No preinstalled Python is required for the managed entry:
launch.sh / launch.ps1 provisions the pinned isolated Python 3.13.16 and the EffectCraft CLI in the user data directory.
- Node.js 24 or newer for the embedded editor MCP server. A Git checkout has no
ui/dist/; build it per ui/README.md first, or install a release bundle that ships it.
- First use needs network or pinned archives.
--runtime-home or CRAFT_RUNTIME_HOME relocates the runtime root (~/.local/share/craft-runtimes by default). No sudo, no PATH edits.
Install the plugin
codex plugin marketplace add full-aigc-plugins/effectcraft-plugin
codex plugin add effectcraft@full-aigc-plugins-effectcraft
docs/verification/release-candidate.json records installableDevelopmentCandidate: true with releaseStatus: BLOCKED. project-status.json keeps marketplaceEligible: false; production promotion is not claimed.
Manifests for Codex (.codex-plugin/), Claude Code (.claude-plugin/), ZCode (.zcode-plugin/) and Kimi (kimi.plugin.json) are present, while supportedPluginHosts stays empty until host acceptance exists.
Quick start
: "${HARNESS_DIR:?Set to the directory holding the loaded effectcraft-harness SKILL.md}"
/bin/sh "$HARNESS_DIR/scripts/launch.sh" doctor
/bin/sh "$HARNESS_DIR/scripts/launch.sh" run --mode workflow \
--plan "$SKILL_DIR/examples/brand-intro.json" --output /absolute/new-result
Windows uses & "$HARNESS_DIR/scripts/launch.ps1" run --mode workflow ... with the same modes. Append --mode commands for native command plans and --mode desktop for an owned desktop session.
flowchart LR
A[Brief and assets] --> B[effectcraft-use routes the task]
B --> C[Managed launcher, pinned runtime]
C --> D[Native .ecproj plus ledgers]
D --> E[Render or alpha export]
E --> F[Decode real pixels, review, deliver]
help returns usage with exit code 2 and is not a health check; use info --json and commands --json instead. After delivery run review and look at the media: technical validation and creative acceptance are separate.
What you can build
| Workflow | Built-in path | Verifiable output |
|---|
| Logo reveal or brand intro | effectcraft-logo-reveal + effectcraft-cli-animation | Reopened .ecproj with keyframes and effects intact |
| Lower thirds, chapter cards, credits | effectcraft-lower-thirds, effectcraft-chapter-card, effectcraft-credits-roll | Compositions whose text layers stay independently editable |
| Kinetic typography or social loop | effectcraft-kinetic-type, effectcraft-social-loop | Loop or title animation with checked timing |
| Camera, 3D layers and expressions | effectcraft-cli-camera, effectcraft-cli-expressions | Reopened project with camera, material and expression state |
| Masks, tracking and puppet deformation | effectcraft-cli-masks, -tracking, -puppet | Matte or pin data checked against rendered frames |
| Transparent or video render | effectcraft-cli-export | Output whose real pixels, alpha and duration are decoded |
| Run any native command | effectcraft-harness → commands.py | Receipt carrying the actual native return value |
| Edit in the embedded editor | effectcraft-editor MCP tools | Saved project reopened and inspected |
Skills
| Skill | What it does |
|---|
effectcraft-use | Default entry: editable comps, motion graphics and intros; installs the pinned CLI |
effectcraft-cli | Query native commands and parameters; tracking, stabilization, graphic attachment |
effectcraft-cli-setup | First install, digest checks, version checks, missing-runtime triage |
effectcraft-cli-project | Create, save and reopen .ecproj, organise project items |
effectcraft-cli-footage | Import images, video, vector and PSD assets, register dependencies |
effectcraft-cli-composition | Comps, frame size, frame rate, duration and work area |
effectcraft-cli-layers | Text, shape and footage layers, precomps and hierarchy |
effectcraft-cli-animation | Properties, keyframes, easing, text and graphic animation |
effectcraft-cli-effects | Find supported effects, reorder them, adjust parameters |
effectcraft-cli-masks | Mask paths, feather and local mattes |
effectcraft-cli-expressions | Inspect, set and diagnose expressions on chosen properties |
effectcraft-cli-camera | Cameras, lights, materials and 3D layer switches |
effectcraft-cli-export | Preview frames, render sequences or video, alpha handoff clips |
effectcraft-cli-tracking | Track and stabilize footage, attach titles and graphics to motion |
effectcraft-cli-puppet | Puppet meshes and pins, local deformation, recorded follow motion |
|
MCP tools
mcp.json declares one stdio server, effectcraft-editor, started as node ui/bootstrap.mjs from the plugin root.
| Tool | Purpose |
|---|
open_editor | Open the editor for an absolute workspace path |
open_browser_editor | Return an editorUrl for a host built-in browser |
editor_status | Report whether the page has attached to this MCP session |
command_list | Read the commands the current web engine exposes |
command_run | Run one command by id with parameters in the visible page |
inspect | Inspect the current frame |
save_project | Save the project to a new path |
save_file | Retrieve a generated virtual file |
Names follow the effectcraft-editor skill contract; the adapter also keeps page-internal bridge calls such as _panel_reply and screenshot, which agents must not call directly.
Configuration
| Variable / flag | Purpose |
|---|
HARNESS_DIR | Absolute directory of the loaded effectcraft-harness skill |
SKILL_DIR | Directory of the loaded domain SKILL.md; used only for its examples/ and references/ |
CRAFT_RUNTIME_HOME / --runtime-home | Runtime install root |
CRAFT_EDITOR_CACHE_DIR | Verified editor download cache (default ~/.cache/full-aigc/editors) |
CRAFT_EDITOR_UPDATE=off | Stay on the bundled editor and skip the update check |
revisionScope | Declared in the first plan; defaults to at most 2 rounds sharing a 30-minute budget |
Native tasks keep their bound runtime. A corrupt or missing evidence file is preserved and blocks further writes rather than being silently replaced.
Architecture and security
- The packaged agent surface is skills plus the stdio editor server; native editing is done by the pinned EffectCraft CLI, not reimplemented here.
- User media and model output are treated as data. Commands, paths and shell text inside them are never executed.
- Writes are checkpointed before an edit, refused when a user changed the project concurrently, and never replayed after an unknown result; only
inspect, reconcile and proven resume are allowed.
- The editor bridge listens on
127.0.0.1 with a random token and Host/Origin checks. See skills suite, runtime architecture and scene skills.
Troubleshooting
| Symptom | Action |
|---|
unsupported_platform | Only install the locked artifact for a supported platform/architecture |
runtime_install_busy | Another install holds the lock; wait for it, then retry |
| Download or digest mismatch | Restore network or pass a verified --archive; the digest check is not skipped |
help exits 2 | Expected; use info --json and commands --json for health and catalogue |
| Editor page never becomes ready | Call editor_status, then fix page errors; a text result does not prove the UI opened |
| Unknown save result | inspect and reconcile the original task; never retry with a new task id or output directory |
| Full GUI or other-platform acceptance expected | Not qualified yet; report the bounded scope instead |
Upgrade
codex plugin marketplace upgrade full-aigc-plugins-effectcraft
codex plugin add effectcraft@full-aigc-plugins-effectcraft
Repeated installs verify and reuse the same runtime version without upgrading online. The packaged editor can also fall back to the bundled copy when a download or digest check fails.
Contributing and support
Behaviour changes go through OpenSpec first; do not check a task off without real delivery evidence. Documentation checks:
python3 scripts/validate_docs.py
python3 scripts/validate_editor_scenes.py
Issues: https://github.com/full-aigc-plugins/effectcraft-plugin/issues.
License
Original repository content is Apache-2.0. The EffectCraft CLI and the bundled web editor keep their own upstream licenses and NOTICE files; upstream icon provenance is recorded in assets/official-icon-source.json.
