Sync MagicPixel art to your game

The CLI detects your engine from marker files in the project root and picks a sensible outDir automatically. No Vite plugin, no package.json, and no typed index.ts — just PNGs where your engine expects them.

Run these from your game project root (where the marker file lives). The package is @magicpixelart/cli and the command it installs is magicpixel:

npx @magicpixelart/cli@latest start
npx @magicpixelart/cli sync --watch

start creates the config, logs you in, and runs the first sync (including your game sprites). Always pass the full package name: magicpixel is the binary the package installs, not a package on npm, so the short magicpixel … form only works after npm i -D @magicpixelart/cli in that project. The first npx run asks to install the package — answer yes, or use npx -y @magicpixelart/cli … in CI.

• Godot & Unity: PNGs auto-import when files change — leave sync --watch running in a terminal while you edit in MagicPixel.
• GameMaker: files land in Included Files, but the IDE does not auto-refresh — use Refresh Included Files after each sync (the CLI reminds you at init time).
• Verify setup: npx @magicpixelart/cli doctor --json reports "framework": "Godot" (or Unity / GameMaker) and your outDir.

Use sprites in-engine via each engine's normal PNG path (e.g. Godot res://assets/magicpixel/…, Unity Assets/MagicPixel/…). For Godot and GameMaker the CLI leaves sidecar metadata (.import, .yy) to the engine on first import; for Unity both the CLI and the in-app sync write tuned .meta files for you.

For Vite / React / Next and other JavaScript projects — without the AI quickstart prompt. Game engines: see Game engines.

Option A — Vite plugin (recommended)

npm i -D @magicpixelart/vite

The plugin bundles @magicpixelart/cli. Add it to your Vite config:

// vite.config.ts
import { defineConfig } from 'vite';
import { magicpixel } from '@magicpixelart/vite';

export default defineConfig({
  plugins: [/* your existing plugins */, magicpixel()],
});

Then authenticate once:

npx @magicpixelart/cli start

start detects your framework, writes magicpixel.json, prompts for your API key, runs the first sync, and offers a magicpixel:watch npm script. After that, keep starting your game normally. The plugin runs the watcher with your dev server, so every artboard you explicitly Sync in MagicPixel arrives within ~2 seconds — no sync command after each change. Vite HMR picks it up automatically.

Option B — CLI only (non-Vite, CI)

npm i -D @magicpixelart/cli
npx @magicpixelart/cli start                # one-time auth + initial sync
npx @magicpixelart/cli sync --watch         # keep assets fresh while you work

start stores your key in .magicpixel/credentials (mode 0600, auto-gitignored). For CI, set MAGICPIXEL_API_KEY in the environment instead — it takes precedence over the credentials file.

Lives at the project root. Edit by hand or via magicpixel add <glob> / magicpixel remove <glob>.

{
  "outDir": "src/assets/magicpixel",
  "include": ["rabbit/**", "ui/icons/*"],
  "exclude": ["**/wip-*"],
  "emitIndex": true
}

init detects your project kind and suggests outDir. Defaults:

State (.magicpixel/state.json) tracks lastSync. Add .magicpixel/ to .gitignore (init offers to do this).

sync flags

Each successful sync prints a per-file change list (+ added, ~ modified, ↪ renamed, - pruned). sync --watch exits 2 after 5 consecutive auth failures so process supervisors can detect a revoked key.

The CLI is built on a small REST API — reads for pulling sprites down, plus a write-back endpoint for pushing disk edits home. Use it directly when you can't run Node (game-engine plugins, scripts in other languages, etc.).

Authentication

All requests need an API key in the Authorization header. Create keys in Settings → API Keys.

Authorization: Bearer mp_live_abc123...

Each key is bound to a single project and only sees that project's assets. Revoke anytime from Settings.

Base URL

https://sddsilidjhvtvejzvolx.supabase.co/functions/v1

List assets (manifest)

List the assets your key can see. Designed for diffing against disk before downloading only what actually changed.

Query parameters

Response (200 OK)

{
  "items": [
    {
      "id": "e5f6a7b8-...",
      "key": "rabbit/ear-left",
      "name": "Ear Left",
      "folder": "rabbit",
      "slug": "ear-left",
      "width": 64,
      "height": 64,
      "sha256": "a1b2c3...",
      "size_bytes": 482,
      "updated_at": "2025-01-15T12:00:00Z",
      "download_url": "https://sddsilidjhvtvejzvolx.supabase.co/functions/v1/integration-assets?key=rabbit%2Fear-left"
    }
  ],
  "nextCursor": "MjAyNS0w...",
  "count": 1
}

When nextCursor is non-null, pass it back as ?cursor= to fetch the next page. Compare sha256 against the version on disk to decide whether to re-download.

Download asset

Download an asset as a raw PNG. Address it by stable key (recommended) or by assetId.

Query parameters

Example

# Address by key (recommended):
curl -o ear-left.png \
  -H "Authorization: Bearer mp_live_abc123..." \
  "https://sddsilidjhvtvejzvolx.supabase.co/functions/v1/integration-assets?key=rabbit/ear-left"

# Or by asset ID:
curl -o sprite.png \
  -H "Authorization: Bearer mp_live_abc123..." \
  "https://sddsilidjhvtvejzvolx.supabase.co/functions/v1/integration-assets?assetId=e5f6a7b8-..."

Write sprites back (beta)

Push a PNG edited on disk back into MagicPixel — the write half of two-way Unity sync. Send up to 20 sprites per request (16 MB of PNG data total, 4096px per side). Each sprite either updates a known artboard (assetId + layerIdx) or adopts a new file into the library by its disk path (path). Sprites that target the same document are applied together in one write.

Body parameters (per sprite)

Response (200 OK)

{
  "results": [
    { "key": "props/rock-a", "status": "updated", "assetId": "e5f6...", "layerIdx": 1, "sha256": "a1b2..." },
    { "key": "props/rock-b", "status": "unchanged", "assetId": "e5f6...", "layerIdx": 2, "sha256": "c3d4..." },
    { "key": "props/rock-c", "status": "conflict", "reason": "cloud-changed", "assetId": "e5f6...", "layerIdx": 3, "sha256": "9f8e..." }
  ]
}

Per-sprite status is updated, created, unchanged, conflict, or error — the request itself still returns 200, so read every result. Conflict reasons: cloud-changed (someone saved in the editor — a cloud-changed result carries the live sha256, so you can re-send with it as baseSha256 to keep your copy), would-flatten (layered or animated artboard; pass flatten to accept the flattening), legacy-document, and not-found. A lost conflict never writes: your cloud document is left byte-for-byte intact.

Error handling

All error responses use a consistent JSON shape:

{
  "error": "Human-readable error message"
}

Every response also carries an X-Request-Id header — include it when reaching out for support and we can grep the edge logs in one shot.

Unexpected CLI failures (5xx server errors, uncaught exceptions) are reported fire-and-forget so we can fix issues before you have to file them. We send: the error message + stack, command name, CLI version, Node version, OS platform, and the request id from the failed call. We never send file paths, asset names, configuration, environment variables, or your API key.

Opt out with MAGICPIXEL_TELEMETRY=0. Reporting is also automatically skipped when no API key is configured or when endpoint in magicpixel.json points at a non-canonical host.