# InstaSpawn for AI assistants

InstaSpawn is a Roblox Studio plugin that turns a character model into a rigged R15 character. This page is for an AI
assistant that works in Roblox Studio through Roblox's Studio MCP server. With it, you can run InstaSpawn for the
user. They can say "rig every character in this folder" and you do the work, with no clicking on their part.

## The door

While InstaSpawn is installed and Studio is open, the plugin keeps one `BindableFunction` called `InstaSpawnAPI` in
`StudioService`. Call it from the MCP server's `execute_luau` tool (Edit data model):

```lua
local api = game:GetService("StudioService"):FindFirstChild("InstaSpawnAPI")
if not api then
	return "InstaSpawn isn't running. Ask the user to install or turn on InstaSpawn (Plugins > Manage Plugins)."
end
local res = api:Invoke({ cmd = "status" })
return game:GetService("HttpService"):JSONEncode(res)
```

- Every call is `api:Invoke({ cmd = "<command>", args = { ... } })`.
- Every answer is a plain table. It is either `{ ok = true, ... }` or `{ ok = false, error = "<what to do next>" }`.
- Answers hold only plain data: strings, numbers, booleans, lists, and named fields. They never hold Instances.
- Errors are sentences meant to be passed on or acted on. Read them.
- Any command except `help` opens the InstaSpawn window if it's closed, so the user can watch. Opening the window also
  starts the Pro check. Right after Studio starts, `status.pro_checking` may be true for a few seconds.
- `{ cmd = "help" }` lists every command with its arguments.

## Recommended workflow

1. **Check `status`.**
   - `export.ready` tells you whether exporting is set up on this computer.
   - `pro` tells you whether Pro is on.
   - `model` tells you whether a model is open.
2. **If `export.ready` is false**, export needs a one-time setup on this computer. `export.todo` lists the steps still
   left, in plain words. Walk the user through them:
   - **Turn on saving in Studio.** In File > Beta Features, the user ticks "CreateAssetAsync Lua API", then restarts
     Studio. You can't do this step for them.
   - **Add the InstaSpawn Exporter** (only for the Creator Store version, `export.needs_exporter`). There are two ways:
     - Run `add_exporter`. It puts the Exporter in ServerStorage and selects it. If Studio asks whether InstaSpawn may
       add a script, the user chooses Allow. Then, in the Explorer, the user right-clicks "InstaSpawn Exporter" and
       picks Save as Local Plugin.
     - If you can write files on the user's computer, run `exporter_source` and save its `source` as
       `InstaSpawnExporter.lua` in the user's Studio Plugins folder. On Windows that's `%LOCALAPPDATA%\Roblox\Plugins`;
       on macOS it's `~/Documents/Roblox/Plugins`. Studio loads it as a local plugin.
   - **Updates.** When `export.exporter_outdated` is true, do the same step again to update it.
   - **Roblox's own prompts.** Studio may ask for permission along the way (for example, to let InstaSpawn add a
     script). Those are the user's to answer, every time.
3. **Saving.** An export saves its meshes and images straight away: to the user's account, or to the group that owns
   the place. There's no Save window to press. The Exporter prints what it saved, and where, in the Output.
   Roblox's own permission prompts still show, and are the user's to answer.
4. **Get a model in.**
   - A plugin can't open a file picker on your behalf. Model files (FBX, OBJ, GLB, glTF) can only be opened by the user,
     with Open model in the InstaSpawn window.
   - For a model already in the place (imported with File > Import 3D), use `open_selected`.
   - To try things out, use `try_sample`.
5. **Slice.**
   - In Simple mode, a model opened with no preset gets its cut points placed by InstaSpawn. `open_selected` and
     `try_sample` wait for that and say how it went (`auto_placed`, `parts`); `auto_place` places them again.
   - Have the user check the points (or the rings, in Advanced, Pro) on the first model and move any that are off.
     Then they save a preset, or you call `save_preset { name = "..." }` once they're happy.
   - Check `status.parts.problems`. Every part has to be cut (none missing, none too big, none named wrongly) before
     it can export.
6. **Rig and export.** Call `rig { mode = "rigid" }` (or skinned, with Pro), then `export {}`. The export runs as a job:
   follow it with `status.batch`.
7. **For a whole folder**, use one model's preset for the rest:
   ```lua
   api:Invoke({ cmd = "rig_folder", args = {
   	folder = "Workspace.Characters",
   	preset = "Knight",
   	rig = { mode = "rigid" },
   	export = { size = "default" },
   } })
   ```
   Then poll `status` until `batch.state` is no longer `"running"`, and report `batch.results` to the user.

## Commands

The rows marked **Pro** need InstaSpawn Pro. Without it they answer
`{ ok = false, error = "This needs InstaSpawn Pro: get it at instaspawn.com" }`.

A command that changes the model can't run while a job is running. It answers with an error that says to wait or to
stop the job with `cancel_batch`.

### Finding out

| Command | Args | Returns |
|---|---|---|
| `help` | none | `commands` = list of `{ name, args, about, pro }`; `notes` |
| `status` | none | See below |
| `list_presets` | none | `presets` = list of `{ name, model, saved }` (saved is a Unix time), newest first |

`status` returns these fields:

| Field | What it holds |
|---|---|
| `version` | The plugin version |
| `pro`, `pro_checking` | Whether Pro is on, and whether it's still being checked |
| `export` | `ready`, `needs_exporter`, `beta_on`, `exporter_added`, `exporter_installed`, `exporter_outdated`, `todo` (a list of sentences), `exporting` |
| `model` | `{ name, triangles }`, or nothing when no model is open |
| `step` | 1, 2 or 3 |
| `mode` | `"simple"` or `"advanced"` |
| `advanced` | `placing_rings`, `cutting`, `ready`, `problem` |
| `rig` | `mode`, `layout`, `blend`, `falloff`, `joints`, `ball_radius`, `ball_shape` |
| `parts` | `missing`, `too_big` and `wrong` (lists of part names); `problems` (sentences, including holes in the model's surface); `blocking` |
| `cages` | `on`, `fitted`, `current` (fitted to the slices as they are now), `fitting`, `progress` (0 to 1), `eta_s`, `problem`, `markers_checked`, and in step 3 `markers` (see `auto_markers`) |
| `trying_on` | List of `{ slot, item }` |
| `message` | The window's status line |
| `batch` | The last job (see Jobs) |

### Opening

| Command | Args | What it does |
|---|---|---|
| `open_selected` | `path?` | Opens a model that's already in the place: the model selected in the Explorer, or the one at `path`. See the notes below the table. Returns `model`, `triangles`, `preset_loaded` (the preset last used on this model was put back), `auto_placed`, `parts` and `note`. |
| `try_sample` | none | Opens the sample character that comes with InstaSpawn. Returns `model`, `triangles`, `auto_placed` and `parts`. |

Notes on `open_selected`:
- `path` is written like `"Workspace.Characters.Knight"`. Use `/` as the separator (`"Workspace/Characters/Knight"`)
  when a name has a dot in it.
- The model's visible MeshParts are read as one mesh, where they stand.
- Only one texture is used: the one on the largest textured part. `note` says so when the model has more than one.
- Studio only lets plugins read meshes uploaded by the user or by the place's owner.
- With no preset for the model, in Simple mode, InstaSpawn places the cut points by itself before answering.
  `auto_placed` is `{ placed, untouched, whole, pose, adjusted, trial_cuts }`, or nothing when a preset was loaded
  (or in Advanced mode). `placed = false` means the points couldn't be placed and are at their starting places; ask the
  user to check the model stands upright, facing forward. `whole = false` means the model is in separate pieces, so
  some points may need moving by hand.

### Models that already come in their 15 body parts

Some characters come with each body part as its own piece, like Roblox's own R15 bodies. InstaSpawn reads which piece
is which part from where the pieces are and what they touch (never from names in the file); small extra pieces (eyes,
teeth, a tongue) join the part nearest them. Such a model isn't cut:
- Answers carry `body_parts = true` (`open_selected`, `try_sample`, `parts`), and `status.body_parts` is
  `{ usable, note }`. `note` is the sentence to pass on to the user.
- Step 1 has no points or rings for it. `auto_place`, `advanced` and `auto_rings` answer `ok = false` with the reason.
- If every part is green (`usable = true`), steps 2 and 3, cages and export work on the model's own parts as usual.
- If a part is over 20,000 triangles, more than one Roblox mesh holds, steps 2 and 3 wait: `set_step` answers
  `ok = false` saying which parts. The user reduces them in a 3D app and opens the model again.
- `rig_folder` and `export_many` use such a model's parts as they are (no preset or placed points), with a `note`.
- A model facing away isn't taken as one (left and right would swap): the user turns it to face forward.

### Slicing (step 1)

| Command | Args | What it does |
|---|---|---|
| `auto_place` | `discard_cages?` | Simple mode: places the cut points on the open model by itself (the same as opening a model with no preset, and as Reset in step 1). See the notes below the table. |
| `apply_preset` | `name` | Puts a saved preset on the open model. A preset holds the points or rings and every setting. Returns `mode`, `parts`, and `pending` if the cut is still coming. |
| `save_preset` | `name` | Saves the open model's set-up as a preset. A preset that already has this name is replaced. |
| `advanced` **Pro** | `on`, `discard_cages?` | Switches between Simple (`on = false`) and Advanced, which uses 3D rings. |
| `auto_rings` **Pro** | `discard_cages?` | In Advanced, puts every ring back where InstaSpawn places it on this model by itself. This is the same as Reset in step 1. |
| `set_step` | `step` | Goes to step 1, 2 or 3. Step 3 is **Pro**. |

Notes on `auto_place`:
- It returns `all_green`, `green` (the parts cut cleanly), `red` (a list of `{ part, state }`, where `state` is
  `"missing"`, `"too_big"` or `"wrong"`), `parts`, and `info` (`whole`, `pose`, `trial_cuts`, `adjusted`).
- When `all_green` is false, or a point looks off, the user moves the points next to the red parts by hand.
- In Advanced mode use `auto_rings` instead.
- If the points can't be placed (the model isn't upright and facing forward), it answers `ok = false` and the points go
  back to their starting places.

If clothing cages are fitted, changing the slices throws them away. `auto_place`, `advanced` and `auto_rings` refuse to do that
unless you pass `discard_cages = true`. Ask the user before you do.

Advanced cuts and cage fitting need a connection to instaspawn.com. They take a moment. When an answer has
`pending = true`, poll `status` until `advanced.cutting` is false.

### Rigging (step 2)

| Command | Args | What it does |
|---|---|---|
| `rig` | `mode`, `layout?`, `blend?`, `falloff?`, `joints?`, `ball_radius?`, `ball_shape?` | Goes to step 2 with this rig. See the notes below the table. |

Notes on `rig`:
- `mode` is `"rigid"` (separate parts) or `"skinned"` (**Pro**).
- With skinned, `layout` is `"s15"` (15 parts) or `"s1"` (a single mesh, only up to 20,000 triangles).
- `blend` (0 to 3) and `falloff` (0 to 1) are the weight-paint dials.
- With rigid, `joints` is `"flat"` or `"ball"` (**Pro**). `ball_radius` (0 to 1.5) and `ball_shape` (0 to 1) shape the
  ball joints.

### Step 3 (Pro)

| Command | Args | What it does |
|---|---|---|
| `attachments` | `reset?` | Lists the 18 R15 attachments as `{ name, part, custom }`. See the notes below. |
| `auto_markers` | `discard_cages?` | Places the eye and mouth markers on the head by itself (as the Clothing tab does when they first show, and as its Reset does) and says how sure it is of each. See the notes below. |
| `fit_cages` | `markers_ok?` | Fits layered-clothing cages to the character. See the notes below. |
| `adjust_cages` | `whole_body?`, or `part` with `fit?`, `smooth?`, `move?`, `rotate?`, `stretch?`, `reset?` | Loosens or tightens the cages, as the Clothing tab's controls do. See the notes below. |
| `try_on` | `list = true`, or `slot` + `item`, or `clear = true` | Previews gear or clothing. See the notes below. |

Notes on `attachments`:
- InstaSpawn places every attachment by itself.
- `reset = true` puts any attachment the user moved back where InstaSpawn places it, and sets Accessory size back to
  100%.

Notes on `auto_markers`:
- The first time the Clothing tab shows the markers on a head nobody has marked (no preset brought them, nobody moved
  or confirmed them), InstaSpawn places them by itself. Markers placed that way and not moved since follow the head
  when the slices, Turn or Tip change it. `auto_markers` places them again, over any the user moved.
- It returns `placed` and `markers`: `eyeL`, `eyeR` and `mouth`, each `{ state, at }`. `state` is `"found"`,
  `"unsure"` (placed where the face suggests, but check it), `"not found"` (placed where a face usually has it),
  `"set"` (moved by the user, or brought by a preset) or `"default"` (where the markers start: they couldn't be placed).
  `at` is `{ across, up }` on the head (across in half-widths from its middle, towards the character's left; up from
  its bottom in heights).
- `placed = false` means the markers couldn't be placed, and they are where they start: have the user move each one
  into place (or try again later). A `note` names any marker that isn't `"found"`: have the user check those on the
  Clothing tab.
- If the cages are already fitted, it refuses unless you pass `discard_cages = true` (the cages are thrown away).

Notes on `fit_cages`:
- The fit uses three markers: one line through each eye and one through the mouth. InstaSpawn places them by itself
  (see `auto_markers`), and the answer carries `markers` as `auto_markers` reports them. Ask the user to check them on
  the Clothing tab first. Then pass `markers_ok = true`, which confirms them as they are.
- Fitting takes a while. Poll `status.cages` until `fitting` is false. When it's done, `current` is true, or `problem`
  says what went wrong.

Notes on `adjust_cages`:
- `whole_body` and `fit` go from -1 (tighter) to 1 (looser). `smooth` goes from 0 to 1.
- `move` is `{ x, y, z }` in studs at the Default size. `rotate` is in degrees. `stretch` is a factor, where 1 means as
  fitted.
- `part` is an R15 part name.
- While symmetry is on, a change to a left or right part is mirrored to the other side.

Notes on `try_on`:
- It's a preview only.
- `list = true` lists the slots and the items for each.
- Gear goes on an attachment slot, such as `RightGripAttachment`.
- Clothing goes on over fitted cages. Its slot is the part it's mainly worn on, such as `UpperTorso`.
- Set `item = "none"` to take something off.
- Nothing you try on is exported unless `export_full` asks for it.

### Exporting

An export uploads the parts and the texture to the user's Roblox account, then builds the rigged character in the
place. It lands in front of the camera, or in StarterPlayer as `StarterCharacter` when `starter` is set. It is selected
when it's done.

| Command | Args | What it does |
|---|---|---|
| `export` | `name?`, `size?`, `factor?`, `height?`, `starter?`, `test_animation?` | The same export as the Export window. See the notes below the table. Starts a job and returns `{ job }`. |
| `export_full` **Pro** | As `export`, plus `cages?` (default true), `worn?`, `gear?` | Also exports the clothing cages, the clothing tried on (`worn`, which needs the cages), and the gear tried on. |

Notes on `export`:
- `size` is one of `"child"`, `"default"`, `"big"`, `"boss"`, `"original"` or `"custom"`. The first four are measured
  from a standard Roblox character, at the neck.
- `factor` goes with `custom`. For example, `3.57` turns meters into studs.
- `height` is in studs and overrides `size`.
- If export isn't set up yet, it answers `ok = false`, with the steps in `setup`.
- It refuses, saying why, while any part is missing, too big, or named wrongly.

### Many models (jobs)

| Command | Args | What it does |
|---|---|---|
| `rig_folder` | `folder`, `preset?`, `rig?`, `cages?` (**Pro**), `export?` | Works through every Model in `folder`. See the notes below the table. |
| `export_many` | `models` (list of paths), `preset?`, `rig?`, `cages?`, `export?` | The same, for a list of models. Each one uses the preset last used on it, or points InstaSpawn places by itself when it has none. |
| `cancel_batch` | none | Stops the job after the model it's on. An upload that's under way finishes. |

Notes on `rig_folder`:
- For each model, it opens it, puts the preset on (by default, the preset last used on that model), rigs it with `rig`
  (the same fields as the `rig` command), fits cages if `cages = true`, and exports it with `export`.
- Without `preset`, a model that has never had a preset saved or loaded on it gets its cut points placed by InstaSpawn
  (in Advanced mode, its rings), and its result has a `note` saying so. If the points can't be placed, or a part isn't
  cut cleanly after placing, that model fails with a sentence saying why, and the job goes on.
- With `cages = true`, the eye and mouth markers are confirmed as they stand: the preset's, or, for a model nobody has
  marked, the ones InstaSpawn places by itself. Each result then has `markers` (as `auto_markers` reports them). Check
  one model's fit with the user first.
- `export` takes the same fields as the `export` command, except `name` and `starter`. Pass `export = false` to rig
  without exporting.
- A model that fails is reported, and the job goes on to the next one.
- Exports are placed in a row, 8 studs apart.

`status.batch` follows the last job. It holds `{ id, kind, state, done, total, current, eta_s, results, error }`.
- `state` is `"running"`, `"done"`, `"stopped"` or `"failed"`.
- `results` is a list of `{ name, path, ok, error?, exported_as?, note?, markers? }`. `exported_as` is the built model's full name
  in the place.

### Setup and settings

| Command | Args | What it does |
|---|---|---|
| `add_exporter` | none | Export setup step 2: puts the InstaSpawn Exporter in ServerStorage and selects it. |
| `exporter_source` | none | Returns `{ file_name, version, source }`: the Exporter's code, to save in the user's Plugins folder. |
| `set_auto_confirm` | `on` | Not needed any more: exports never wait on a Save window. Kept so older scripts aren't refused. |

## What needs Pro

These commands and options need Pro:
- Advanced mode (`advanced`, `auto_rings`)
- Skinned rigs and ball joints
- Step 3: `attachments`, `auto_markers`, `fit_cages`, `adjust_cages`, `try_on`
- `export_full`, and the `cages`, `worn` and `gear` options anywhere

Everything else is free. Pro is bought at instaspawn.com, and the user turns it on in the InstaSpawn window.

## Limits

- **Uploads.** Roblox takes about 30 uploads a minute. An export uploads one mesh per part, plus the texture, plus the
  cages when they're exported. InstaSpawn paces uploads to 29 a minute and retries one that Roblox turns away for
  going too fast, so a big batch takes several minutes. Tell the user roughly how long.
- **Triangles.** A model can have at most 50,000 triangles. One part can't be over 20,000, and a single-mesh skinned
  rig can't be over 20,000 in total.
- **Files.** FBX (binary), OBJ, GLB and glTF (with its data inside) are read only through the user's own file picker,
  with Open model in the window. An assistant can't open a file itself. Have the user import models into the place
  (File > Import 3D) and use `open_selected` or `rig_folder`, or have them open each file in InstaSpawn.
- **Meshes from the place.** Studio lets plugins read only meshes uploaded by the user or by the place's owner. The
  place must allow the mesh tools: in File > Game Settings > Security, turn on "Allow Mesh & Image APIs".
- **Web access.** Advanced cuts and cage fitting need InstaSpawn to be allowed to connect to instaspawn.com
  (Plugins > Manage Plugins).
