# Make game assets with Rosebud: instructions for coding agents

Use these steps when a person asks you to make art, sprites, skyboxes, 3D models, sound effects or music for their game with Rosebud. Assets are paid for with the person's Rosebud credits, at the same prices as the website. Every `rosebud` command except `--help` and `--version` prints one JSON object: results on stdout, errors on stderr.

Human-readable guide and model list: [Game assets for coding agents](https://rosebud.ai/developers/assets).

## 1. Install the CLI

```sh
npm install --global @rosebudai/cli
```

It needs Node.js 22 or later. If you can't install globally, replace `rosebud` in every command below with `npx --yes @rosebudai/cli`.

## 2. Sign in once

```sh
rosebud whoami
```

If it reports `"status": "active"`, skip to step 3. Otherwise run:

```sh
rosebud login --agent-client claude-code
```

- Set `--agent-client` to `claude-code`, `codex`, `cursor`, `gemini-cli` or `other`, so the person can tell which agent is asking.
- Give the person the `approval_url` it prints. They open it, sign in and select **Allow**. There is no API key to copy.
- The link is private and expires after 30 minutes. Don't put it in commits, issues, shared logs or the game.
- Run `rosebud whoami` again after they approve. Continue only when it reports `"status": "active"`. It also shows the person's credit balance.
- If `login` reports an existing pending login, give the person that `approval_url` again. Run `rosebud logout` first only to switch accounts.
- The same sign-in covers publishing. Once it's active, `rosebud publish` puts the game straight into the person's account, with no claim link to hand over. See the [publishing guide](https://rosebud.ai/developer-publishing/AGENTS.md).

## 3. Choose a model

```sh
rosebud assets models --category image
```

Categories are `image`, `skybox`, `model_3d`, `sound_effect` and `music`. Each model lists its inputs, price and license. Pick the cheapest model that fits the request, and read its inputs: `--prompt` fills `prompt`, and `--input name=value` sets any other input it lists (repeat it for several).

## 4. Check the price, then make the asset

```sh
rosebud assets quote --model flux-2-flash --prompt 'mossy stone tile, top-down' --input asset_type=sprite
rosebud assets create --model flux-2-flash --prompt 'mossy stone tile, top-down' --input asset_type=sprite \
  --max-credits 300 --out ./assets/stone-tile.png
```

- Quotes are free. Tell the person the price before you make several assets or anything expensive, unless they gave you a budget.
- Always pass `--max-credits` with the price you expect. `create` refuses a higher quote before anything is charged.
- `create` waits for the file (up to 10 minutes by default) and saves it to `--out`. It never replaces an existing file unless you pass `--force`.
- Save files where the game loads them. If the game will be published with Rosebud's free hosting, keep media inside `assets/` with lowercase names using letters, numbers and hyphens.
- Credits are charged when a job starts and returned if generation fails.

## What comes back

- **Images**: Flux 2 Flash backgrounds and textures are 1024×1024, with no size or aspect-ratio input, so crop or scale them in the game. Transparent types (`sprite`, `icon`, `character_portrait` and the like) are cropped to their content, so their sizes vary. PNGs run 1–2 MB each; add `--input output_format=webp` when the game will be hosted, since a hosted build must fit in 10 MiB zipped.
- `texture_tile` images are close to seamless but not exact. Check the edges before tiling them across a large surface.
- Image models take no reference image. To keep a character the same across poses or expressions, repeat the same description and the same `--input seed=<n>`, changing only the pose or expression. A `quote` shows a sample seed; `create` picks its own unless you pass one.
- There is no animation model yet. A sprite sheet asked of an image model often comes back in a different grid or frame count than requested, so slice it by content rather than by a fixed grid.
- **3D models** (`rosie-3d`) are GLB files about 1 unit along their longest side, Y up, facing +Z, with the base at y = 0. They use the `KHR_mesh_quantization` and `EXT_texture_webp` extensions, which three.js loads. Humanoid characters usually come back rigged, with a Mixamo-style skeleton and about 80 animation clips such as `Idle`, `Walk`, `Run` and `Death01`; read the clip names from the file. Metallic surfaces render nearly black without an environment map; a skybox set as the scene's environment lights them.
- **Sound effects** are 0.5–5 second MP3s. Ask for one sound per clip, since a second event in the same prompt is usually dropped. Loudness varies between clips, so set each one's volume in the game.
- **Music** is at most 30 seconds and may fade out at the end even when the prompt asks for a loop. Trim the fade before looping it.
- **Give every game with sound a mute button and a volume control**, and start music quieter than effects. People often play with others around, on a call or in class.

## 5. Use and hand off

Wire the files into the game and check they load. Then tell the person what you made, the credits it cost, and that every file is also in [My assets](https://rosebud.ai/assets), where they can download or reuse it.

To reuse something the person already has, search their assets and download it:

```sh
rosebud assets list --query 'stone tile'
rosebud assets download <asset_id> --out ./assets/stone-tile.png
```

## Rules

- Make one asset per command, and make variations by changing the prompt or inputs. Identical `create` commands run one at a time.
- Run a few commands at a time, not dozens. Requests from one account share a rate limit; the CLI waits it out for up to a minute before it reports `throttled`.
- If a command exits with code 4, run the identical command again. It resumes the same job and won't pay twice.
- Don't retry when the person is out of credits. Tell them instead.
- Don't edit files in `~/.config/rosebud/credentials`. Set `ROSEBUD_CREDENTIALS_DIR` to keep credentials in another folder.

## Exit codes and common errors

| Exit | Meaning                                                   | What to do                              |
| ---- | --------------------------------------------------------- | --------------------------------------- |
| 0    | Success                                                   | Continue                                |
| 2    | Bad command or input, or a quote above `--max-credits`    | Fix the input and run the command again |
| 3    | Rosebud rejected the request or the job failed            | Read `error.code` and fix the cause     |
| 4    | The outcome is unknown, for example after a lost response | Run the identical command again         |

| `error.code`           | Fix                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `invalid_key`          | The sign-in is pending, expired or disconnected. Run `rosebud whoami`, then step 2    |
| `insufficient_credits` | Tell the person they need more credits. Don't retry                                   |
| `job_unfinished`       | The wait ran out. Run the identical command again to keep waiting for the same job    |
| `throttled`            | Too many requests at once. Wait `retry_after_seconds`, then run the identical command |
| `state_locked`         | An identical `create` is already running. Wait for it, or change the prompt or inputs |