Skip to content

zedalleys/anime-kinetix-codex-plugin

v1.1.2

Create and preview Anime.js animations and Matter.js physics scenes, then export editable HTML.

Anime Kinetix

Anime Kinetix is a Codex plugin and browser playground for creating editable web motion. Use Anime.js for scripted animations and Matter.js for 2D scenes whose motion comes from gravity and collisions. Generate a complete HTML file in Codex or tune and preview it in the browser.

EngineAvailable scenesControls
Anime.js 4.5.0Slide in, pulse, staggered entrance, orbitPreset, duration, easing, stagger delay, loop
Matter.js 0.20.0Bouncing circles and squaresGravity, bounciness, shape count, play, pause, reset

The Codex tools and local preview run with Node.js 22 or newer. The local preview uses the libraries bundled in this repository. Exported HTML loads the selected engine from a version-pinned jsDelivr URL and needs internet access on first load.

Install in Codex

Install Node.js 22 or newer and make sure node --version works in the environment where Codex runs. With a Codex CLI that supports plugins, run:

codex plugin marketplace add https://github.com/zedalleys/anime-kinetix-codex-plugin
codex plugin add anime-kinetix-codex-plugin@anime-kinetix

Open a new Codex session and try:

  • “Create an 800 ms staggered entrance with 100 ms between tiles. Save it as entrance.html.”
  • “Make 8 shapes bounce with gravity 1.2 and bounciness 0.8. Save the editable scene as bounce.html.”
  • “List the available animation and physics presets.”

To install from a checkout, pass its absolute path to codex plugin marketplace add in place of the GitHub URL. Use codex plugin list --marketplace anime-kinetix to check installation.

Run the browser playground

git clone https://github.com/zedalleys/anime-kinetix-codex-plugin.git
cd anime-kinetix-codex-plugin
npm run preview

Open the local playground. Choose an engine, adjust its settings, and select Update preview. Once the preview reflects your changes, Copy HTML copies the source and Download HTML saves it. Open the exported file in a browser or edit the settings and styles in a text editor.

Use ANIME_KINETIX_PORT=4180 npm run preview if port 4179 is already in use. The preview binds to loopback.

Playback and reduced motion

The playground and exported examples respect the browser's reduced-motion preference at startup. Use Play to start explicitly. In Matter.js scenes, Pause freezes the scene, Play resumes it, and Reset returns all shapes to their starting positions and pauses playback. Anime.js previews offer Play to restart and Pause/Resume during playback.

Codex tool reference

The plugin registers a local MCP server named anime-kinetix. It uses standard input and output and starts with Codex. Each generator returns an HTML document as text. Ask Codex to save that text to a file if you want a file in your workspace.

Anime.js

list_animation_presets takes no arguments and returns the available presets, supported settings, and defaults.

generate_animation_html accepts:

SettingValuesDefault
presetslide-in, pulse, stagger, orbitstagger
durationInteger from 150 to 3000 ms, per element850
easelinear, outCubic, inOutSine, outBack, outElasticoutCubic
staggerInteger from 0 to 500 ms, used by the stagger preset90
loopBooleanfalse
{
  "preset": "stagger",
  "duration": 800,
  "ease": "outCubic",
  "stagger": 100,
  "loop": false
}

Matter.js

list_physics_presets takes no arguments and returns the engine version, the bouncing-shapes scene, supported settings, and defaults.

generate_physics_html accepts:

SettingValuesDefault
gravityNumber from 0 to 2. At 0, shapes keep their initial motion without falling.1
restitutionNumber from 0 to 0.95. Larger values increase bounce.0.75
countInteger from 2 to 126
{
  "gravity": 1.2,
  "restitution": 0.8,
  "count": 8
}

Omitted settings use their defaults. Generator calls return an error for unknown fields, invalid types, or values outside the supported range.

Extend the plugin

PathPurpose
page.htmlBrowser controls, embedded preview, and copy/download actions
dist/server/motion.jsAnime.js preset schemas and HTML generator
dist/server/physics.jsMatter.js scene schema, simulation, and HTML generator
dist/server/mcp.jsShared MCP tool definitions, validation errors, and dispatch
dist/server/index.jsWorker entry point for the web playground and its HTTP MCP endpoint
server/stdio.jsCodex stdio entry point
skills/anime-kinetix/SKILL.mdCodex workflow guidance
build.mjsEmbeds browser assets and engine bundles in the Site worker
test/plugin.test.jsTests both transports, tool discovery, HTML generation, and invalid inputs

Run npm test to rebuild the embedded assets and run the tests. Run npm run build after changing browser assets before committing the generated worker assets. The source tree includes the existing Sites configuration. Pushing source to GitHub and deploying a new version of the hosted playground are separate operations.

For new physics scenes, keep the tool schema and browser controls in sync. The current scene advances Matter.js in fixed 60 Hz steps, caps catch-up after an inactive tab, and uses each body's coordinates and angle to place its SVG shape. For a hybrid scene, let Matter.js own the positions and angles of colliding bodies. Use Anime.js for scripted properties such as interface transitions, opacity, and color.

Troubleshooting

SymptomWhat to check
Codex does not show the toolsVerify Node.js is available on Codex's PATH, check the marketplace listing, and start a new session.
The preview server reports that its port is in useStart it with a different ANIME_KINETIX_PORT.
A preview loads in a paused stateCheck the system/browser reduced-motion preference and select Play if you want to start it.
Copy failsUse Download HTML, which works without clipboard access.
An exported demo cannot load its engineCheck internet/CDN access, or download the pinned engine and update the HTML to use your own hosted copy.

Roadmap and library choices

Matter.js is the best immediate addition. It adds gravity, collisions, and emergent motion to the existing browser and HTML export workflow. PixiJS is the next choice when scenes need many particles, richer effects, or a high-throughput renderer. Tone.js fits when a preset needs synchronized sound or synthesized impact effects. Start audio only after the viewer chooses to enable it.

ProjectFit for Anime Kinetix
Anime.jsCore engine for scripted UI or DOM motion, easings, and timelines.
Matter.jsIntegrated for rigid-body physics. Constraints and additional scenes fit the same workflow.
PixiJSNext renderer for particles, filters, or dense sprites. Matter.js can continue to supply physics coordinates.
Tone.jsOptional browser audio for sound cues, beats, and synchronized effects.
react-springUseful for a React-specific motion export target, with overlap in the current playback workflow.
p5.jsUseful for a dedicated generative-art or sketch workflow.
D3Useful for animated charts and data-driven motion presets.
OpenToonzDesktop animation studio suited to a separate asset-authoring workflow.
Hunyuan3D-23D asset generation for a separate model pipeline.
TRELLISAnother option for generating 3D assets in a separate inference workflow.
LTX-2Audio/video generation that would need a separate inference and media workflow.
LivePortraitPortrait animation for a dedicated image/video workflow.
RIFEFrame interpolation for a future rendered-video export workflow.
MusicGenGenerated soundtracks for a future media workflow. Check the model-weight license for the intended use.

Open-source availability does not make model inference or hosting cost-free. GPU requirements and model-weight licenses vary by project.

Related project and third-party licenses

The Claude plugin is the companion for Claude Code.

The bundled runtimes are distributed under their respective MIT licenses. See the Anime.js license and the Matter.js license.