# pxstud.io Lua scripting API — Slices

> Part of the pxstud.io Lua scripting reference, whose overview (https://pxstud.io/docs/scripting.md) explains its conventions. The option groups and types it refers to are in https://pxstud.io/docs/scripting/option-groups.md and https://pxstud.io/docs/scripting/types.md. Everything in one file: https://pxstud.io/llms-full.txt. The whole site's index: https://pxstud.io/llms.txt.

### Slices
Named rectangles, e.g. for export regions or hitboxes. A slice can also be a 9-slice (a center rectangle) and carry a pivot point; both are relative to the slice's top-left corner, as in Aseprite, and move with it when the canvas is resized, cropped or rotated.

#### `app.addSlice(name, x, y, width, height, opts?)` — changes, undoable
Adds a new named rectangular slice, optionally a 9-slice (center) and/or with a pivot.

- `name` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)
- `opts` (table, optional)
  - `center` ({ x, y, width, height }) — The 9-slice centre { x, y, width, height }, relative to the slice's origin: inside the slice, positive size.
  - `pivot` ({ x, y }) — The pivot point { x, y }, relative to the slice's origin (may lie outside the slice).

Returns (string): The new slice's id.

#### `app.getSlices(frameId?)` — reads
Every slice as { id, name, x, y, width, height, center = { x, y, width, height } (9-slice slices), pivot = { x, y } (slices with a pivot), keyFrameIds (frames where the slice has its own key, slices with per-frame keys only) }. center and pivot are relative to the slice's origin. Pass a frame id for the geometry in effect on that frame.

- `frameId` (string, optional) — Frame to read the slices at (a slice can change bounds, centre and pivot per frame); omit for the first frame's.

Returns (table): Array of slice tables.

#### `app.removeSlice(sliceId)` — changes, undoable
Removes a slice.

- `sliceId` (string)

Returns nothing.

#### `app.removeSliceKey(sliceId, frameId)` — changes, undoable
Removes a slice's key at a frame (not the first frame, which holds the slice's own geometry): from that frame on, the previous key's geometry applies again. Errors when the slice has no key on that frame.

- `sliceId` (string)
- `frameId` (string)

Returns nothing.

#### `app.updateSlice(sliceId, props, frameId?)` — changes, undoable
Updates one or more properties of a slice. Resizing a 9-slice keeps its center only if it still fits; otherwise pass a new center (or false) too. With a frameId past the first frame, x, y, width, height, center and pivot edit the slice's key on that frame (creating one: the new geometry holds from that frame on, until the next key); name is always slice-wide.

- `sliceId` (string)
- `props` (table) — Omitted keys are left unchanged.
  - `name` (string) — The slice's name.
  - `x` (integer) — Left edge, in sprite pixels.
  - `y` (integer) — Top edge, in sprite pixels.
  - `width` (integer ≥ 1) — Width in pixels.
  - `height` (integer ≥ 1) — Height in pixels.
  - `center` ({ x, y, width, height } or false) — The 9-slice centre { x, y, width, height }, relative to the slice's origin: inside the slice, positive size. false clears it.
  - `pivot` ({ x, y } or false) — The pivot point { x, y }, relative to the slice's origin (may lie outside the slice). false clears it.
- `frameId` (string, optional) — The frame the geometry applies at; omitted or the first frame edits the slice's own geometry.

Returns nothing.