Asset Toolbox

• ---

  Introduction

  The Asset Toolbox is a set of 32 free tools inside the Ludo CLI for the chores around game assets: cutting and checking spritesheets, finding a sprite's pivot and collider, writing Godot, Unity and Phaser files, recoloring pixel art, cutting tilesets, checking a sound's loudness and loop, and listing what an asset folder still lacks.

  • Free: no account, no login, no API key and no credits. The CLI is open source (MIT).
  • Local: every tool runs on your machine and works offline.
  • Made for coding agents: Claude Code, Codex, Cursor or any agent that runs commands can use the tools in your project, and so can you from a terminal.
  • Any assets: the tools work on your own art and sounds, and on what you made with Ludo.

  Every tool is ludo toolbox <group> <tool>, in five groups: sprite, image, audio, model and asset. ludo toolbox lists them, and ludo toolbox <group> <tool> --help gives a tool's flags. The Asset Toolbox page shows real runs of each.

• ---

  Installing

  The toolbox ships in the Ludo CLI, version 0.2.0 or later. It needs Node.js 20 or later.

  npm install -g @ludoai/cli
  

  Then teach your coding agent the tools, so it reaches for them instead of writing its own image script:

  Agent	Command
  Claude Code	ludo skill install (or ludo skill install --project to share it through the repository)
  Codex, Cursor, GitHub Copilot	npx skills add Ludo-AI/ludo-cli
  Gemini CLI	gemini extensions install https://github.com/Ludo-AI/ludo-cli

  Run ludo toolbox to check it works. To try one tool without installing, prefix it with npx @ludoai/cli, for example npx @ludoai/cli toolbox sprite slice walk.png.

  After a CLI update, the CLI brings the Claude Code skill it installed up to date on its own, and says when a project's copy in .claude/skills is older (ludo skill install --project updates it).

• ---

  Setting a Character Up for an Engine

  These four tools give the numbers an engine needs, measured from the art:

  Tool	What it gives
  sprite metrics <sheet>	Each frame's bounds, body, ground line and centre of mass, and a pivot on the ground line between the feet, with engine values. --overlay draws it on the frames to check by eye.
  sprite collide <sheet>	Collision shapes for the body: a box and a capsule (and on request a hull or outline), for Godot, Unity, Phaser Arcade and Box2D. The sword held out stays out of the box.
  sprite compare <sheets...>	One character's sheets side by side: how big each is drawn, one pixels per unit for all of them, frame size, ground, pivot and fps. --reference walk.png=1.8m sets the character's height in the game. A sheet drawn at another size is flagged.
  sprite export <sheet> --engine godot|unity|texturepacker	The engine files, next to the sheet.

  sprite export writes:

  • --engine texturepacker: a TexturePacker JSON atlas for PixiJS and Phaser. In Phaser, load it with load.aseprite, then anims.createFromAseprite.
  • --engine godot: a Godot 4 SpriteFrames .tres for an AnimatedSprite2D.
  • --engine unity: the sheet's .png.meta, which imports it sliced into one sprite per frame, and an .anim clip. In a Unity project, export a sheet under Assets/.

  Add --pivot feet and --ppu <n> (from sprite compare) to export with the pivot on the feet and one pixels per unit for the whole character. Every tool that writes a sheet also takes --engine.

• ---

  Spritesheets

  Tool	What it does
  sprite slice <sheet>	Cut a spritesheet into one PNG per frame
  sprite join <frames...>	Put frames back together into one spritesheet
  sprite frames <sheet>	Drop, reorder, reverse, ping-pong or hold frames
  sprite loop <sheet> [<sheet>...]	How well an animation loops (0 to 1), or which of several takes loops best
  sprite gif <sheet>	Turn a spritesheet into an animated GIF
  sprite pack <sheets...>	Bring several animations of one character to one size and ground line, in one frame size
  sprite sequence <sheets...>	Chain animations one after another (idle, jump, land) so the moves join up
  sprite from-video <video>	Turn a video clip into a spritesheet
  sprite video <sheet>	Turn a spritesheet into a video: WebM or MOV with transparency, or MP4

  A sheet's grid comes from the stamp the Ludo CLI writes on the sheets it downloads, or is detected from the image. When the toolbox can't tell the grid, it stops with exit code 12 instead of guessing: pass --grid <cols>x<rows>. A GIF or an animated WebP reads as a sheet of its frames. sprite from-video and sprite video need ffmpeg.

  sprite pack is the command-line counterpart of the Sprite Generator's Animation Pack: one frame size and one ground line for the engine. --manifest re-runs a pack from its pack.json.

• ---

  Images and Tiles

  On a spritesheet, every frame gets the same edit, so the animation stays aligned.

  Tool	What it does
  image trim / image pad	Cut away the empty border, or add one (pad can put back what trim cut)
  image extrude	Repeat the edge pixels outward, so frames or tiles do not bleed
  image scale	Scale up or down: pixel-perfect by whole factors, or by any factor
  image flip / image rotate	Mirror left-right or upside down; turn by 90, 180 or 270 degrees
  image palette	List an image's colours, most used first, and save them as a palette file
  image recolor	Map art onto a given palette (--palette, a Lospec .hex, .gpl, .pal or a palette image), or swap one palette for another (--swap A --to B): the same enemy in four teams
  image outline / image shadow	Draw an outline around the art, or a drop shadow under it
  image tiles <tileset>	Cut a tileset into tiles, or write the tileset files Tiled, Godot and Unity read
  image repeat <tile>	Lay a tile out N x M times, and say whether its edges meet without a seam
  image convert	Save an image as PNG or lossless WebP
  image contact <images...>	One PNG of several images side by side, each labelled with its name and size

  In shells such as bash, quote hex colours: --color '#ffffff'.

• ---

  Audio

  Tool	What it does
  audio info <sound>	Length, loudness (LUFS), true peak, silence at the ends, and whether it clicks when looped. For music, the tempo, with its double or half.
  audio trim <sound>	Cut the silence off a sound's start and end
  audio convert <sound> --to ogg|mp3|flac|wav	Save a sound in another format (OGG for Godot and Unity)

  WAV and MP3 are read and written by the CLI itself; the other formats need ffmpeg. Ludo's own sounds come loudness-matched, and its sound effects trimmed.

• ---

  3D Models

  ludo toolbox model info <model.glb> says what is in a glTF or GLB model before you rig, animate or import it: meshes, triangles, size, textures, rig and animations.

  For a rigged model it also says which way it faces, and for each clip whether it returns to its first pose (a still, or a loop with a seam) and, for a walk or run, how fast it moves.

• ---

  Asset Folders

  ludo toolbox asset manifest <folder> goes through a game's asset folder and says what each file is (spritesheet, image, texture, sound effect, music, voice, ambience, model or video) and why, with its size, frames, fps or length. It groups each character's animations, and finds duplicates.

  It also lists what the folder lacks next to the rest of it, each with the Ludo command that makes it: an animation most of the other characters have, sheets without their sound, a model with no rig or no animation. Nothing is generated; the commands are suggestions.

  --emit writes loaders for the folder: phaser gives an assets-pack.json for this.load.pack and an assets.ts with typed keys, a preload(scene) and each sheet's frames and fps for anims.create; pixi gives a PixiJS 8 manifest for Assets.init; json gives the manifest itself. For Godot and Unity, sprite export writes each sheet's engine files.

• ---

  Using It With a Coding Agent

  At a terminal the tools print short lines for people. When an agent runs them (or with --json), they print one JSON object: the files written (files), the numbers measured, and at most one suggested next step in hint ({text, command}). The next step can be another toolbox tool, or a Ludo command when the job is generating something new. --quiet drops it.

  Outputs get new names instead of replacing your files, with two exceptions: engine files such as a Unity .meta and the loaders from --emit are rewritten in place, and --in-place is there when you want it.

  Exit codes: 0 done, 2 a usage error (a wrong flag, or a file that won't open), 12 an input the toolbox can't use or a grid it can't tell.

• ---

  What the Toolbox Does Not Do

  The toolbox measures, prepares and converts assets you already have. It does not generate anything, and it does not repair Ludo's results.

  • Pixel art conversion is a Ludo feature: Convert to Pixel Art in the Image Generator, or ludo image convert-to-pixel-art from the CLI.
  • Background removal is a Ludo feature: Remove Background in the web app, or ludo image remove-background.
  • New art, animations, 3D models and sound come from Ludo's generators. The same CLI generates them once you run ludo login; generating from the CLI, API or MCP needs a plan with API access (Pro or Studio) and uses credits. ludo pricing lists the plans, no login needed.

• ---

  Privacy and Telemetry

  To see how the CLI is used and where it breaks, it sends Ludo a short record of each command when it finishes:

  • the command, its exit code and how long it took;
  • the names of the flags used, never their values;
  • the CLI, Node and OS versions, whether it ran at a terminal or in CI, and which coding agent ran it;
  • for toolbox tools, how many files they read and in which format, the frame count, whether a sheet was made by Ludo, the engine, which next step they suggested, and for asset manifest how many gaps it found and of which kinds;
  • a random install id, and your account when you are logged in.

  It never includes file names, paths, flag values or file contents. The tools work offline: the record waits and is sent with a later command, giving up after a second rather than holding the command up. To turn it off, set LUDO_TELEMETRY=0 (or DO_NOT_TRACK=1).