# API de scripts Lua do pxstud.io — Slices

> Parte da referência de scripts Lua do pxstud.io, cuja visão geral (https://pxstud.io/pt-br/docs/scripting.md) explica as convenções. Os grupos de opções e os tipos a que ela remete estão em https://pxstud.io/pt-br/docs/scripting/option-groups.md e https://pxstud.io/pt-br/docs/scripting/types.md. Tudo em um único arquivo (em inglês): https://pxstud.io/llms-full.txt. O índice de todo o site (em inglês): https://pxstud.io/llms.txt.

### Slices
Retângulos nomeados, p. ex. para regiões de exportação ou hitboxes. Um slice também pode ser um 9-slice (um retângulo central) e ter um ponto de pivô; ambos são relativos ao canto superior esquerdo do slice, como no Aseprite, e se movem com ele quando a tela é redimensionada, cortada ou girada.

#### `app.addSlice(name, x, y, width, height, opts?)` — altera, desfazível
Adiciona um novo slice retangular nomeado, opcionalmente um 9-slice (center) e/ou com um pivô.

- `name` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)
- `opts` (table, opcional)
  - `center` ({ x, y, width, height }) — O centro do 9-slice { x, y, width, height }, relativo à origem do slice: dentro do slice, com tamanho positivo.
  - `pivot` ({ x, y }) — O ponto de pivô { x, y }, relativo à origem do slice (pode ficar fora do slice).

Retorna (string): O id do novo slice.

#### `app.getSlices(frameId?)` — lê
Todos os slices como { id, name, x, y, width, height, center = { x, y, width, height } (slices de 9 fatias), pivot = { x, y } (slices com pivô), keyFrameIds (quadros em que o slice tem sua própria chave, somente slices com chaves por quadro) }. center e pivot são relativos à origem do slice. Passe um id de quadro para obter a geometria em vigor naquele quadro.

- `frameId` (string, opcional) — Quadro em que ler os slices (um slice pode mudar de limites, centro e pivô por quadro); omita para os do primeiro quadro.

Retorna (table): Array de tabelas de slice.

#### `app.removeSlice(sliceId)` — altera, desfazível
Remove um slice.

- `sliceId` (string)

Não retorna nada.

#### `app.removeSliceKey(sliceId, frameId)` — altera, desfazível
Remove a key de um slice em um quadro (não no primeiro quadro, que guarda a geometria própria do slice): a partir desse quadro, a geometria da key anterior volta a valer. Gera erro quando o slice não tem key nesse quadro.

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

Não retorna nada.

#### `app.updateSlice(sliceId, props, frameId?)` — altera, desfazível
Atualiza uma ou mais propriedades de um slice. Redimensionar um 9-slice mantém o centro só se ele ainda couber; caso contrário, passe também um novo center (ou false). Com um frameId depois do primeiro quadro, x, y, width, height, center e pivot editam a key do slice nesse quadro (criando uma: a nova geometria vale a partir desse quadro, até a próxima key); name vale sempre para o slice todo.

- `sliceId` (string)
- `props` (table) — Chaves omitidas não são alteradas.
  - `name` (string) — O nome do slice.
  - `x` (integer) — Borda esquerda, em pixels do sprite.
  - `y` (integer) — Borda superior, em pixels do sprite.
  - `width` (integer ≥ 1) — Largura em pixels.
  - `height` (integer ≥ 1) — Altura em pixels.
  - `center` ({ x, y, width, height } or false) — O centro do 9-slice { x, y, width, height }, relativo à origem do slice: dentro do slice, com tamanho positivo. false o remove.
  - `pivot` ({ x, y } or false) — O ponto de pivô { x, y }, relativo à origem do slice (pode ficar fora do slice). false o remove.
- `frameId` (string, opcional) — O quadro em que a geometria se aplica; omitido ou o primeiro quadro edita a geometria própria do slice.

Não retorna nada.