Sprat-gui

GUI frontend for sprat-cli to generate spritesheets and related metadata (for example animations and hitboxes).

Use this app if you need to:

1. Detect individual frames in a single image automatically or manually.
2. Build sprite sheet layouts from a folder of images.
3. Edit pivots and markers per sprite visually.
4. Create animation timelines quickly from frame naming patterns.
5. Preview and export animations (GIF/video) without manual scripting.
6. Save/load complete project state (.json or .zip).

If your workflow is already fully automated by scripts and CI, this may be unnecessary. If you need fast visual iteration for game/UI assets, this is likely useful.

What it does (and why you might need it)

• Frame detection (spratframes integration)
  Automatically identifies individual frames in a sprite sheet or strip when you load a single image, with support for manual splitting and selection.

• Layout generation (spratlayout integration)
  Generates atlas layout data from your image folder, so you avoid hand-maintained packing metadata.

• Sprite editing (pivot + markers)
  Lets you place gameplay/UI anchors directly on frames, reducing downstream guesswork in engine integration and capturing marker positions for collision zones or entity spawn points (e.g., muzzle origins for bullets).

• Timeline authoring
  Supports manual frame ordering and automatic timeline generation from names like Run (0), Run (1), etc.

• Animation test panel
  Play/step through timelines with FPS and zoom controls to validate motion before export.

• Animation export
  Exports to GIF (ImageMagick) and video formats (FFmpeg) for quick validation and sharing.

• Project persistence
  Save and load full project state (layout options, markers, timelines) to continue work later.

• CLI tools configuration/installation UI
  Configure binary paths in Settings or install required CLI tools from the app.

Requirements

• Qt 6 (Core, Gui, Widgets, Concurrent)
• CMake >= 3.16
• C++17 compiler
• Sprat CLI tools:
  • spratframes
  • spratlayout
  • spratpack
  • spratconvert (optional for format transforms) (If the app detects them missing it can run the bundled installer and drop binaries into ~/.local/bin.)
  • If you already have the sprat-cli repository checked out as a sibling to this project (for example ../sprat-cli), build that copy and the GUI will automatically pick up spratframes, spratlayout, spratpack, and spratconvert from it, or let you point Settings directly at those binaries.
• Optional export tools:
  • ImageMagick (magick or convert) for GIF
  • FFmpeg (ffmpeg) for video
• Optional archive tools:
  • zip (save .zip projects)
  • unzip (load .zip projects)

When the installer downloads the CLI tools for you, it clones the latest main branch of sprat-cli (git clone --depth 1 --branch main https://github.com/pedroac/sprat-cli.git) before building.

Local CLI development

Place the sprat-cli repository beside this project (for example, at ../sprat-cli) so the GUI can work with the same source tree. After building that repo (for example cmake -S ../sprat-cli -B ../sprat-cli/build && cmake --build ../sprat-cli/build), Sprat GUI auto-detects the generated spratframes, spratlayout, spratpack, and spratconvert binaries, or you can point the Settings dialog at the directory.

Manual frame editing

Use the layout canvas context menu to manage individual frames without reloading an entire folder. Right-click an empty area, choose Add Frames..., and pick one or more image files. The GUI writes a temporary plaintext list that spratlayout already understands (the same list-file input described in the sprat-cli README) and runs the layout using that list, so you can mix files from anywhere on disk. Right-clicking a sprite exposes a Remove Frame action for the frame under the cursor; if that frame is referenced by existing timelines you are warned that timelines will drop those entries before removal proceeds.

Build

Default build (updates DEPENDENCIES from remote tags, configures, builds, then runs tests):

sh build.sh

build.sh behavior:

• Updates DEPENDENCIES to the newest published sprat-cli release tag if network access is available.
• Configures with cmake -B build -S ..
• Builds with cmake --build build.
• Runs tests with ctest --test-dir build --output-on-failure.

Manual build (does not modify DEPENDENCIES):

cmake -S . -B build
cmake --build build --parallel
ctest --test-dir build --output-on-failure

Run:

./build/sprat-gui

Quick start

1. Launch the app.
2. Open Settings and verify CLI tool paths (or use install action).
3. Click Load Images Folder and select your frames directory.
4. Adjust layout options (profile/padding/trim).
5. Select sprites to edit pivots/markers.
6. Create timelines manually or generate from frame names.
7. Test animation in the Animation panel.
8. Save project (.json or .zip) or export animation.

UI workflow

• CLI Tools / Settings

  • On first launch the toolbar shows “CLI missing”; click Settings to point to spratframes, spratlayout, spratpack, and optionally spratconvert, or use the “Install CLI Tools” button to download/build into ~/.local/bin.
  • Settings also exposes canvas/marker colors and border styles that apply immediately and persist.
  • 

• Loading frame folders

  • Use the “Load Images Folder” toolbar action or drop a directory/ZIP/project file onto the window.
  • When loading a ZIP with multiple image directories, the app prompts you to choose the folder to import.
  • 
  • Use the profile selector to switch layout behavior, choose source resolution when needed, ...
  • 
  • ... and use the Manage Profiles action to edit profile rules.
  • 
  • The layout canvas lists all frames; search the frame list by name to filter sprites for quicker edits.
  • 
  • Adjust profile/padding/trim controls, zoom/scroll the canvas, and move the viewport with scrollbars or mouse drag. Clipboard cut/copy/paste works while managing frames.
  • 

• Frames detection

  • When you drag and drop a single image file (like a sprite sheet or a strip), the app automatically runs spratframes to detect individual frames.
  • A dedicated dialog opens showing the identified frames. You can select exactly which ones to import.
  • 
  • Splitting frames: If the automatic detection merges two or more frames, use the Split Mode (right-click a frame or use the toolbar in the detection dialog) to manually divide them.
  • 
  • Click on a frame to place a splitting line; the view supports zoom for exact placement (CTRL + mouse wheel).
  • 
  • Once satisfied, accept the detection to extract and load the frames into your project.
  • 

• Sprite sheet layout editing

  • Select a sprite to see its preview details; use zoom/scroll controls inside the preview canvas.
  • Rename the sprite, adjust its pivot (X/Y spins), or switch between markers (point/circle/rectangle/polygon) via the handle dropdown.
  • Markers show handles for precision; add/edit points, circles, rectangles, or polygons using the markers dialog and context menus—marker info is also copied to clipboard.
  • 
  • 
  • 
  • 
  • 
  • 
  • Right-click pivot/marker handles to open context actions, including Apply to Selected Frames (applies from the active source sprite to the current multi-selection in the layout canvas).
  • 

• Animation authoring

  • Timelines panel lets you add simple names, remove, rename, and select timelines.
  • Drag frames from the layout into the timeline list; reorder via drop or context actions; duplicate/remove frames with toolbar buttons.
  • Animation test area exposes play/pause/step controls plus timeline FPS and zoom controls.
  • The animation test area auto-sizes to the widest/tallest frame in the current timeline, keeps frames fully visible, and uses scrollbars when content exceeds the viewport.
  • Animation test preview supports wheel scrolling, Ctrl+Wheel zoom, and panning (Middle Mouse Drag or Space + Left Drag).
  • Use “Save Animation…” (right-click preview) after choosing ImageMagick/FFmpeg toolchains.
  • 

• Project save/load

  • Save projects as .json or .zip and pick exactly which data blocks to persist.
  • Use load actions to resume layout, timelines, and editor context from a saved project.
  • 

Keyboard and pointer controls

• Layout canvas selection

  • Ctrl + A: select all sprites in the canvas.
  • Left/Right/Up/Down: navigate selection from the current sprite.
  • Shift + Arrows: extend selection while navigating.
  • Arrow navigation does not wrap at edges.
  • If there is no valid frame in the pressed direction, selection does not change.
  • Home / End: jump to the first / last frame in the current row.

• Selected frame editor

  • Right Click on pivot/marker: opens context actions for alignment/apply operations.
  • Delete/Backspace: removes selected polygon vertex when applicable.
  • Ctrl + Wheel: zoom selected frame preview.
  • Space + Drag or Middle Mouse Drag: pan selected frame preview.

• Animation test preview

  • Wheel: scroll preview viewport.
  • Ctrl + Wheel: change animation preview zoom.
  • Space + Left Drag or Middle Mouse Drag: pan preview viewport.
  • Right Click: export/copy frame menu.

Timeline auto-generation naming

Supported patterns:

<Name> (<Index>)
<Name> [<Index>]
<Name>_<Index>
<Name> <Index>
<Name>-<Index>
<Name><Index>

Examples:

• Idle (0), Idle (001), Idle [2]
• Run_0, Run 01, Run-2, Punch3

Generation behavior:

• Creates timeline <Name> if it does not exist.
• Adds frames whose names end with a numeric index in one of the supported patterns.
• Sorts frames by <Index>.
• If a timeline exists, you can choose Replace, Merge, or Ignore.

Project structure (high-level)

• src/App/MainWindow/ — UI composition and event delegation
• src/SpriteSheetLayout/ — layout canvas/parser/sprite model UI item
• src/SelectedSpriteFrame/ — selected-frame preview/overlay/markers flow
• src/Animation/ — animation playback/export logic
• src/Animation/Timelines/ — timeline building and operations
• src/Project/ — project load/save/payload/autosave
• src/CLITools/ — CLI discovery/config/install helpers
• src/Settings/ — settings dialog/coordinator
• src/Core/ — shared models

Troubleshooting

• “CLI missing” at startup
  Open Settings and set absolute paths for Sprat binaries (spratframes, spratlayout, spratpack, optional spratconvert), or install them from the app.

• Cannot save/load .zip project
  Ensure zip/unzip are installed and available in PATH.

• Animation export disabled or failing
  Install ImageMagick and/or FFmpeg, then restart the app.

• Translations are not generated during build
  Install Qt6 LinguistTools. Without it, the app still builds, but automatic .ts/.qm generation is skipped.

Contributing

• Report bugs
  Open an issue with reproduction steps, expected behavior, actual behavior, OS, and logs/screenshots when available.

• Suggestions / feature requests
  Open an issue describing the workflow problem first, then proposed behavior and tradeoffs.

• Pull requests
  PRs are welcome. Keep changes focused, include rationale, and add tests or manual validation notes for behavior changes.

• Translations (Qt)
  User-facing GUI strings should use Qt translation APIs (tr(...) in QObject classes, QCoreApplication::translate(...) in non-QObject code). Translation catalogs live in i18n/:

  • i18n/sprat-gui_en.ts Typical workflow:
  1. Update code strings using tr/translate.
  2. Run lupdate to refresh .ts entries.
  3. Translate in Qt Linguist.
  4. Run lrelease to generate .qm files.
  5. Verify by launching with a target locale (the app auto-loads sprat-gui_<locale>.qm from ./i18n or the app directory). Note: if Qt6LinguistTools is not installed, CMake still builds the app but skips automatic .ts/.qm generation.

• Packages / binaries
  Contributions for distribution packages and CI release flows are welcome, including:

  • Debian/Ubuntu (.deb)
  • RPM-based distros (.rpm)
  • Windows binaries/installers
  • macOS app/bundles

• Forks / alternative frontends
  Forks are encouraged (for example, a GTK+ frontend variant) as long as they clearly document compatibility and maintenance scope.

• AI-assisted work
  Development on this project has been assisted with Codex and Gemini; all changes are reviewed and manually adjusted since AI output is not perfect.

Attribution

• Screenshots using the “Adventurer Girl – Free Sprite” pack by pzUGH from OpenGameArt (https://opengameart.org/content/adventurer-girl-free-sprite), reused under the original license.
• Core CLI tooling comes from the sprat-cli repository.

License

MIT. See LICENSE.

Support