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

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]

Loading

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
effectcraft-harness	The single execution channel: bootstrap, launch, workflow, commands
effectcraft-editor	Open the real editor UI and keep one session for all edits
effectcraft-kinetic-type	Typographic rhythm for titles and short copy
effectcraft-logo-reveal	Logo entrance, hold and outro
effectcraft-lower-thirds	Name and role bars with brand marks
effectcraft-motion-export	Output checks on duration, frame rate and codec
effectcraft-screen-composite	Layer, mask and screen-content replacement
effectcraft-social-loop	Short loops and cover frames for social formats
effectcraft-chapter-card	Chapter title divider cards
effectcraft-countdown-intro	3–2–1 countdown openers
effectcraft-credits-roll	End credit rolls

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.