Mori Sprite Studio
English · 繁體中文
Web tool to build 1024×1024 4×4 sprite animation packs from a single character reference image.
AI-powered. Browser-only. Transparent backgrounds. Multiple export formats.
▶ Try the live app · Docs / screenshots · Buy me a coffee
What it does
You give it one reference image of your character. It produces a complete sprite animation pack for mori-desktop — 6 required + 2 optional animated states, each a 1024×1024 4×4 sprite sheet that the floating window plays back.
| Required (6) | Optional (2) |
|---|
| idle / sleeping / recording / thinking / done / error | walking / dragging |
It's built for Mori — yazelin's 森林精靈 (forest spirit) Jarvis-style AI partner who lives on the desktop. "Iron Man 有 Jarvis,我有 Mori。" This studio makes Mori's visible body — her sprite form — that the mori-desktop floating window animates.
The studio also works for any character you want to give a visible form to: your own AI partner / personal spirit / streamer overlay companion / character mascot. The Mori demo is one example of what's possible.
You can also export each state as APNG, GIF, WebM, or just the raw sheet PNG — useful for LINE animated stickers, Discord, OBS overlays, video editing, etc.
Workflow
[character ref image]
│
│ (AI · 1 call → 6-cell grid)
▼
[6 static base poses] ← editable / re-rollable per state
│
│ (AI · 6 calls, one per state)
▼
[6 sprite sheets, 4×4 each] ← editable per cell, normalize across states
│
│ (optional) walking + dragging
▼
[+2 cyclic-locomotion sheets] ← W / Dr standalone pipeline (no pre-tile)
│
│ (manual sort: 反向 + 換位)
▼
[hand-tuned gait cycle]
│
│ (bake transforms + zip)
▼
[mori.moripack.zip] → mori-desktop
│
│ (per state, optional)
▼
[mori-{state}.png / .gif / .webm] → LINE / Discord / OBS
- Upload character ref — any PNG/JPG of your character (cropped, any background).
- Generate 6 statics — one AI call produces a 3×2 grid the tool splits into 6 state poses (idle / sleeping / recording / thinking / done / error).
- Per-state animation (6 required states) — click
生 <state> 動畫 to produce the 4×4 sprite sheet. Uses pre-tiled placeholder + multi-anchor identity reference to keep the character locked in position with subtle motion (blink, breath, gesture).
- Optional: walking + dragging — separate W / Dr pipeline (NO pre-tile, since cyclic locomotion needs free per-frame design). Generate neutral full-body static → 4×4 gait/swing sheet → manually reorder cells with reverse + swap buttons to get a clean cycle.
- Fine-tune — click any cell to regen just that frame; adjust loop duration / mode; normalize size across states; per-state scale/offset sliders with reference guides; manual upload / download of any sheet for Photoshop round-trip.
- Backdrop (optional) — upload Light + Dark backdrop PNGs that ship inside the pack. Use 桌面預覽 view to preview the 6+2 states layered on backdrop with shape (round/rounded/square) + theme (light/dark) toggles.
- Export
.moripack.zip — drop into mori-desktop's character folder.
Features
Generation
- 3 AI providers, all BYOK (bring your own key): Google Gemini Direct (AI Studio key, default), Codex-Image (your ChatGPT Plus/Pro quota via yazelin/codex-image-service), Vertex Gemini
- Anti-jitter: pre-tiled placeholder sheet as AI reference locks character position across all 16 frames (idle-family states)
- Anti-character-drift: multi-anchor identity reference (sends all other state staticBases as outfit anchors)
- Anatomy-agnostic prompts: works for humanoid / plant / robot / blob / gem characters — semantics describe motion abstractly
- Two one-shot sub-patterns: BURST-AND-SETTLE (done celebrations) vs SUSTAINED-ENERGY (error / panic)
- BYOG path: copy prompt + reference, run AI yourself, upload result
Walking + Dragging (optional cyclic-locomotion states)
- Dedicated W / Dr standalone pipeline — no pre-tile (which would lock the character to one pose). AI designs all 16 cells freely from character ref + neutral standing static.
- Embedded explicit gait/swing cycle structure in template (16-frame breakdown: cell 1 = left foot fwd, cell 7 = right foot fwd, etc.)
- Strong identity lock: 'character design / hair / clothes / art style stay locked across all 16 cells, ONLY legs + arms + body tilt change'
- Walking sprite designed facing RIGHT — mori-desktop engine mirrors via
scaleX(-1) for leftward motion
Manual cell sorting (post-generation tuning)
- 反向順序 — one-click reverse all 16 cells (rescues sheets that play in reverse direction)
- 換位模式 — toggle on, click cell A → click cell B → contents swap. Stay on for multiple swaps. Hand-tune the gait order until the walk looks right.
桌面預覽 view (desktop simulation)
- 6+2 floating-widget mockups laid out simultaneously, exactly matching mori-desktop's render:
- 200×200 stage with backdrop (
object-cover cover full window)
- 130×130 sprite centered (
drop-shadow matches floating.css)
- 1px outline (matches XShape clip)
- Real 3-layer backdrop composition (vignette + PNG + base gradient — copied 1:1 from mori-desktop's computed style)
- Independent toggles: mori-desktop App theme (light/dark backdrop) × OS theme (light/dark wallpaper) × shape (circle/rounded/square) × backplate mode (logo/plain)
- Inline technical explainer: why backdrop exists at all (Linux X11 + WebKit2GTK alpha-compositing bug workaround), how the 3-tier backplate fallback chain works
Editing
- Per-cell regeneration with
prev frame + next frame + staticBase references for smooth interpolation
- Editable per-state prompt templates + per-cell notes
- Pose Note per state
- Loop mode (loop / one-shot) + duration slider per state
Cleanup
- Configurable chroma key (green, magenta, blue, cyan, yellow, or a custom vivid color) with conservative/balanced/aggressive tolerance
- Coverage-based alpha matte preserves semi-transparent edges such as hair; edge-only despill reduces color halos
- Edge erosion (0-10 px) removes residual chroma at each cell boundary
- Re-chroma button replays from raw AI output (non-destructive — bump erosion up/down at will)
Cross-state alignment
- One-click
Normalize scans every state's character bbox and computes per-state transform (scale + offset) so the character lands at the same size + center across all 6 states
- Per-state fine-tune sliders for scale / offsetX / offsetY
- Reference guide overlay on Loop preview for visual alignment
Export
.moripack.zip — character pack for mori-desktop (manifest + 6 required sheets + 0/1/2 optional walking/dragging + 2 backdrops)- Per state: APNG (transparent, LINE/Discord), GIF (universal, 1-bit alpha), WebM (VP9 + alpha, OBS overlay)
- Raw sheet download (1024×1024 PNG) for external editing
.moriproject.zip save/load — full author state (sheets + raw + settings) for resuming work or sharing
Demo loader
- One-click
✦ 載入 Mori 預設範本 button on the project page — loads a fully-configured Mori character (27 MB) so you can play around without generating from scratch. Confirmation dialog warns about overwriting current data.
Per-character backdrop
- Upload Light + Dark backdrop PNGs, ships inside
.moripack per mori-desktop PR #107 3-tier backplate chain
Quick start
Use the live app
- Open https://mori-sprite-studio.vercel.app
- Click
✦ 載入 Mori Demo on the project page (one-click loads a fully-configured Mori character pack — 22 MB)
- Browse around, see how it works
- To make your own: clear data (or use incognito), upload your character ref, click 生 6 狀態靜態 → per-state 生動畫
All providers are BYOK (bring your own key) — the free Author Fallback trial channel has been discontinued. Pick a provider in the sidebar's AI Provider section and fill in your own key (Google Gemini Direct only needs a free AI Studio API key).
Self-host
git clone https://github.com/yazelin/mori-sprite-studio
cd mori-sprite-studio
npm install
npm run dev # Vite dev server
Deploy to Vercel:
vercel --prod
Set the same env vars in Vercel Dashboard → Settings → Environment Variables for production.
Architecture
| Layer | Tech |
|---|
| UI | Vite + React 19 + TypeScript + Tailwind CSS + shadcn/ui |
| State | Zustand + IndexedDB (idb-keyval) for Blob-native persistence |
| AI providers | abstract ImageProvider interface, 3 BYOK impls (Google Gemini / Codex-Image / Vertex Gemini) |
| Chroma key | Coverage-based alpha matte + enclosed-detail recovery + edge-only despill + optional erosion |
| Sprite-sheet anim preview | Canvas + requestAnimationFrame (16-frame row-major) |
| Export encoders | upng-js (APNG), gifenc (GIF), MediaRecorder + VP9 (WebM), JSZip (.moripack / .moriproject) |
| Server-side | none — pure static frontend, all AI calls go browser → your provider (BYOK) |
Output spec: 1024×1024 PNG-32, 4×4 grid, 256×256 per cell, row-major frame order, transparent background. Conforms to mori-desktop's character-pack.md v1.0.
File formats
| Format | What it's for | Contents |
|---|
.moripack.zip | Consumer format — drop into mori-desktop's character folder | manifest.json + sprites/{6 states}.png + backdrop-{light,dark}.png |
.moriproject.zip | Author format — resume editing later / share configured starting point | project.json + character-ref.png + sprites/{state}/{sheet,raw-sheet,static-base,raw-static-base}.png + backdrops |
| APNG (.png) | Transparent + looping. LINE animated stickers / Discord / Slack / Twitter inline | Standard APNG with acTL/fcTL chunks |
| GIF (.gif) | Universal compatibility (Mac Preview, Windows Photos animate it natively). 1-bit alpha so edges are slightly crusty | Standard GIF89a |
| WebM (.webm) | VP9 + alpha channel. OBS streaming overlays, QuickTime, browsers. Records 3 loops | VP9 codec via MediaRecorder |
| Raw sheet (.png) | The 1024×1024 4×4 sheet itself. For external editing / inspection | PNG-32 RGBA |
Per-state details (out-of-the-box defaults for the Mori character)
| State | Required | Loop mode | Duration | Pose hint |
|---|
| idle | yes | loop | 3000 ms | Standing front-facing, gentle smile, calm welcoming |
| sleeping | yes | loop | 5000 ms | Cross-legged, eyes closed, hands in lap, floating Z |
| recording | yes | loop | 1500 ms | Hand cupped to ear (LISTENING to user, not holding a mic), wide alert eyes |
| thinking | yes | loop | 2000 ms | Finger to temple, eyes glancing up, thought sparkles |
| done | yes | one-shot (sub-pattern A burst-and-settle) | 1800 ms | Both hands raised in victory cheer, joyful ^v^ smile |
| error | yes | one-shot (sub-pattern B sustained-energy) | 2000 ms | Hands to head in cute distressed "oh no!" pose, tear-drop / tension lines |
| walking | opt | loop | 2500 ms | Neutral full-body standing reference (facing right). Actual gait cycle rendered in 16 frames via W template. |
| dragging | opt | loop | 1600 ms | Neutral full-body reference (feet planted in static, suspended swing in 16-frame animation via Dr template). |
Required = mori-desktop expects these 6. Optional = if missing, mori-desktop falls back to idle.png + CSS transforms.
State semantics are editable per project — see src/defaults/semantics.ts for defaults.
License
The studio code: MIT.
The generated character pack (sprites you make): your work, your choice of license. The Mori reference character bundled as demo is CC-BY-NC-SA-4.0 (attribute, non-commercial, share-alike).
Support
Building this is running on love + caffeine. If you find it useful:
This is self-funded out of pocket. Coffee = direct support for:
- Vercel / domain costs
- Time + caffeine to keep building
You can also ⭐ this repo + share with anyone building their own AI companion / desktop spirit.
Using with codex-image-service (use your own ChatGPT subscription quota)
If you have a ChatGPT Plus / Pro subscription, you can pair this studio with codex-image-service — a FastAPI wrapper that exposes Codex CLI's $imagegen as an HTTP endpoint, so your subscription's image-gen quota powers studio's generations.
Three ways to combine them:
| Setup | What you need | When it makes sense |
|---|
| A. Studio (hosted) + your own Gemini key | A free AI Studio API key | New users, exploring, low-volume |
| B. Studio (hosted) + your own codex-image-service | Run codex-image-service somewhere reachable + issue yourself a Bearer key | You have ChatGPT Plus + want unlimited use |
| C. Both self-hosted | Clone + run both repos locally | Full control, offline, no external dependencies |
B / C setup
- Deploy / run codex-image-service (repo instructions)
- In its admin UI, generate a Bearer API key (
cimg_…)
- In studio's sidebar → AI Provider section → select Codex-Image
- Fill in:
- Base URL: your codex-image-service URL (e.g.
https://your-domain.example/codex-image)
- API Key: the
cimg_… you just issued
- Quality:
auto (default) or low / medium / high
- Generate as normal — calls go through your codex-image-service, consuming your ChatGPT subscription's image quota
CORS reminder
If you self-host both, codex-image-service must allow your studio's origin via CORS. yazelin's deployment already does (Access-Control-Allow-Origin reflects request origin); for new self-hosts, see codex-image-service repo for CORS middleware setup.
Related projects
- mori-desktop — 森林精靈 Mori 的桌面身體. yazelin's Jarvis-style AI partner. Rust + Tauri 2 + Whisper(耳)+ LLM(腦). This studio produces her visible sprite form.
- world-tree — Mori's origin / 世界樹. Where Mori comes from.
- codex-image-service — self-host ChatGPT Plus/Pro quota as image-gen API. Pairs naturally with this studio (see section above).
- line-sticker-studio — sister tool, LINE sticker authoring (some prompt engineering patterns shared)
- emoji-slot-machine — sister tool, 3×3 emoji slot machine generator (some sprite-sheet animation patterns shared)
Made by yazelin
