Gridvana user guide

Launch Gridvana and press ⌘N (Ctrl+N on Windows, or choose “New Canvas”) to create a project; canvas width and height can be anything from 1 to 4096. Click “Create Canvas” and start painting on the grid.

The app autosaves as you work: after a crash, the next launch offers to recover your unsaved project (or you can discard it). Projects are stored in .gvn format with RGBA pixel data and full layer/frame structure.

• Select (hold Space to temporarily pan the canvas)
• Magic wand: select pixels by connected region
• Select by color: grab all same-color pixels on the canvas
• Brush, eraser, paint bucket, color picker
• Shape tools: rectangle / outline / circle / outline circle / line

The color panel offers both foreground and background colors (swappable in one click) and keeps a history of used colors, so you can pick up where you left off.

Gridvana supports paint, background, reference, and group layers. Layers can have a parent group, visibility, locking, opacity, and Normal, Multiply, Screen, or Overlay blending. Group layers organize content and do not contain cels themselves.

Timeline cels can be multi-selected, dragged, copied, pasted, deleted, linked, and unlinked; linking shares content across frame positions. Onion skinning can be limited to the active layer, while sprite sheets can use visible, all, or active layers.

Add, duplicate, remove, and drag frames on the timeline, and set each frame's duration in milliseconds. Use “+ Tag” to name a range; tags can play forward, in reverse, or Ping-Pong, and their ranges are draggable.

Onion skinning has separate previous/next frame counts, overall opacity, previous/next tinting, and an active-layer-only option. The live preview panel can be shown, hidden, and dragged.

• Box, wand, and color selections combine implicitly: Shift adds, Option/Alt subtracts, and Shift+Option/Alt intersects
• Drag inside a selection to move it; use the on-canvas corner handles to scale and the rotation handle to turn in 90° steps
• ⌘/Ctrl + X / C / V / D: cut, copy, floating paste, duplicate
• ⇧H / ⇧V / ⇧R / ⇧L: flip horizontally / vertically, rotate clockwise / counterclockwise
• ⌘/Ctrl + A selects all, ⌘⇧I / Ctrl+Shift+I inverts, Delete removes selected pixels, and arrow keys nudge by one pixel

Pasted pixels remain floating until you deselect, so moving or transforming them does not disturb the pixels underneath. On square grids, the canvas menu also offers “Crop to selection”, “Trim transparent edges”, and “Canvas size…”.

• PNG sequence: one PNG per frame; a single-frame project produces one PNG
• Animated GIF: preserves frame timing, with the active tag controlling range and playback order
• Sprite sheet + JSON: all frames or the active tag, using visible, all, or active layers
• Sprite sheet options: horizontal / vertical / fixed rows or columns, 1×–16× scale, transparent-edge trimming, empty-frame policy, extrusion, and Array / Hash JSON

The export panel estimates sprite-sheet dimensions and shows frame thumbnails before writing both the PNG atlas and JSON frame, duration, and tag metadata. Reference layers are excluded from regular PNG and GIF exports.

Under Settings → AI Agent, enable the panel, choose Codex or Claude, and configure its executable plus optional profile, model, or reasoning effort. Gridvana then launches the agent's interactive terminal in the app. “Allow by default” controls whether that agent skips its normal approval prompts.

The embedded MCP service starts with Gridvana and listens only on loopback. Agents can read the project summary, current selection, active-frame PNG, and edit-operation schema. Writes follow start, preview, apply, commit or rollback; only one write session can be active, and out-of-session project changes produce a revision conflict.

Preview and apply operate on a working copy. Only commit replaces the current project and records the change in the shared undo history. Codex or Claude handles MCP tool approval in its own terminal.

The most common shortcuts are listed below for both macOS and Windows; if one clashes with the system, adjust it in macOS System Settings → Keyboard or the equivalent Windows setting.

Project files use the .gvn format (schema V6), storing RGBA pixels plus the full layer, frame and tag structure, with autosave and crash recovery.

The app writes a recovery file every 30 seconds; after an abnormal exit, the next launch can recover or discard it. Settings cover language & region, AI Agent, and MCP service options, while the status bar shows project save and MCP state.