Iki

息 (breath) · 生き (life) · 粋 (chic)

Iki is an open 2D rig puppet animation engine for the web — a from-scratch
alternative to Live2D and Inochi2D. You author a
character as layered parts wired to a small set of parameters, and the runtime
animates it in WebGL. A host (such as Charivo)
drives those parameters from lip-sync, gaze, blink, and expressions.

Status: early, but real. The runtime renders parameter-driven color quads,
atlas-sampled texture parts, warp-mesh and grid deformation, stencil clipping
masks, and spring/chain physics. The editor authors parts, deformers, and
physics rigs; the generator rigs a character from role-named PNG/PSD layers,
including through an MCP server that AI agents can drive.

Why

• Open format. The .iki model is a plain, documented schema you own —
  which is what makes AI-driven model generation tractable.
• Web-native. WebGL runtime, TypeScript, no native toolchain.
• Host-agnostic. The engine knows nothing about Charivo or any host; it
  just plays .iki models. Charivo consumes it through a thin render-iki
  adapter, the same way it consumes the Live2D SDK today.

How Iki compares

Live2D Cubism is the industry standard, and it is far more mature than Iki in
every dimension that matters to an artist — editor, tooling, ecosystem, and the
quality ceiling of what you can rig with it. Inochi2D
is the established open-source project in this space. Iki is not trying to
replace either. It exists because three things it wanted never lined up in one
place:

• A format you own. .iki is plain JSON with a documented schema and a
  fail-fast validator. You can read a model in a text editor, diff it in git,
  and generate one from a script.
• Web-first, no native toolchain. TypeScript and WebGL2. npm install and
  it runs in a browser — no SDK download, nothing to compile for the runtime.
• Rigging an agent can drive. Because the format is open and small, an AI
  agent can take role-named PNG layers to a rigged, animating model through an
  MCP server. That is the part Iki is really exploring.

If you need production-grade 2D rigging today, use Cubism. If you want an open
web format you can script against, that is what this is.

Packages

Install

npm install @ikijs/engine @ikijs/format

@ikijs/editor is for building authoring tools; @ikijs/mcp runs as a
server (npx -y @ikijs/mcp) rather than being imported.

Quick start (this repo)

pnpm install
pnpm build
pnpm playground   # open the Vite URL and drag the sliders

The .iki model

A model is a flat list of parts composited back-to-front, plus parameters wired
to those parts through linear bindings:

import { StandardParameter, type IkiModel } from "@ikijs/format";

const model: IkiModel = {
  version: 1,
  name: "Hello",
  canvas: { width: 1000, height: 1000 },
  parameters: [{ id: StandardParameter.MouthOpen, min: 0, max: 1, default: 0 }],
  parts: [
    {
      id: "mouth",
      color: [0.78, 0.32, 0.36, 1], // solid fill, or tint multiplier when a texture is present
      width: 150,
      height: 34,
      order: 0,
      transform: { x: 0, y: -150 },
      bindings: [
        {
          parameter: StandardParameter.MouthOpen,
          channel: "scaleY",
          from: 0,
          to: 3,
        },
      ],
    },
  ],
};

Stick to the StandardParameter ids (ParamMouthOpenY, ParamAngleX, …) so
any host can drive any model without per-model wiring. Left/Right in those
ids name the character's side, so the character's left eye is the part at
positive x (the viewer's right).

Stability: IKI_FORMAT_VERSION identifies the .iki contract, and from
1.0 on, any breaking schema change bumps it. Until then the v1 schema is still
settling: a 0.x release may tighten validation and reject a model an earlier
one accepted (canvas extents must now be > 0, for instance). Such changes
are called out in the changelog. The TypeScript surface can likewise shift
between 0.x minors.

FAQ

Can I use this commercially? Yes — MIT, for the engine, the format and the
tooling. Models you make are yours.

Can it load Live2D models? No. .moc3 is a proprietary compiled format;
Iki has its own open schema and no importer for it.

Is it production ready? Not yet — the packages are published from 0.1.0 and
the v1 schema is still settling. See Stability above for what that means for
a model you save today.

Do I need the editor to use it? No. @ikijs/engine + @ikijs/format are
enough to play a model. The editor packages are for building authoring tools.

How do I make a model? Either hand-write the JSON — it is small, see above —
or feed role-named PNG layers to the auto-rigger in
@ikijs/editor / @ikijs/mcp, which
wires up blink, gaze, lip-sync, head-turn and brows for you.

Roadmap

ROADMAP.md tracks what has landed and what is deferred.

License

MIT © Zeikar

Built with HyperClaude — Claude builds, Codex critiques.