# API de scripts Lua do pxstud.io — Aleatório

> 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.

### Aleatório
Números aleatórios com seed, calculados dentro do script (sem ida e volta a cada chamada). A mesma seed dá os mesmos resultados, então um script pode ser executado de novo, desfeito e refeito, ou compartilhado, e ter sempre a mesma aparência. Prefira estas funções a math.random, que muda a cada execução. Os geradores são objetos: chame seus métodos com dois-pontos (rng:int(1, 6)).

#### `app.random.hash(x, y, seed?)` — pura
Um float sem estado em [0, 1) a partir de entradas inteiras (um hash de avalanche inteiro): o mesmo (x, y, seed) sempre dá o mesmo valor, em qualquer ordem. Para ruído por pixel ou dithering sem um gerador.

- `x` (number) — Inteiro (arredondado para baixo).
- `y` (number) — Inteiro (arredondado para baixo).
- `seed` (number, opcional) — Padrão 0.

Retorna (number): Um float, 0 <= x < 1.

#### `app.random.new(seed)` — pura
Cria um gerador aleatório com seed (mulberry32, o mesmo algoritmo que o spray e o embaralhar do editor usam). A mesma seed sempre dá a mesma sequência. Prefira-o a math.random, que é diferente a cada execução. Use os métodos com dois-pontos: local rng = app.random.new(app.config.seed); rng:int(1, 6).

- `seed` (number) — Um inteiro 0-4294967295. Floats são arredondados para baixo; qualquer outra coisa é reduzida a 32 bits.

Retorna (table): Um objeto gerador; chame seus métodos com dois-pontos.

#### `app.random.seed()` — pura
Uma seed inteira aleatória nova, 0-4294967295. NÃO é determinística: muda a cada execução, então imprima-a ou guarde-a se quiser reproduzir o resultado. Use-a quando o usuário deixar o campo de seed vazio: app.random.new(app.config.seed or app.random.seed()).

Retorna (number): Um inteiro 0-4294967295.

#### `rng:chance(p)` — pura
true com probabilidade p.

- `p` (number) — Probabilidade 0-1.

Retorna (boolean): true ou false.

#### `rng:fork(label)` — pura
Um gerador filho independente, derivado de forma determinística do estado atual deste gerador e do rótulo, SEM avançar este. Dê a cada recurso o seu próprio fork (rng:fork("leaves")) para que adicionar um recurso não altere todos os sorteios seguintes. Fazer fork duas vezes no mesmo ponto com o mesmo rótulo dá filhos idênticos.

- `label` (string) — Uma string ou um número que nomeia o filho.

Retorna (table): Um objeto gerador; chame seus métodos com dois-pontos.

#### `rng:int(lo, hi)` — pura
Um inteiro aleatório de lo a hi, ambos incluídos.

- `lo` (number) — Menor resultado (arredondado para baixo).
- `hi` (number) — Maior resultado, inclusive (arredondado para baixo); pelo menos lo.

Retorna (number): Um inteiro, lo <= x <= hi.

#### `rng:next()` — pura
O próximo float em [0, 1).

Retorna (number): Um float, 0 <= x < 1.

#### `rng:normal(mean?, sd?)` — pura
Um float com distribuição normal (Box-Muller). Usa dois sorteios por chamada.

- `mean` (number, opcional) — Padrão 0.
- `sd` (number, opcional) — Desvio padrão; padrão 1.

Retorna (number): Um float em torno de mean.

#### `rng:pick(list)` — pura
Um elemento aleatório da lista; nil para uma lista vazia (e o gerador não avança).

- `list` (table) — Uma lista (1..#list).

Retorna (table): Um elemento da lista, ou nil.

#### `rng:range(a, b)` — pura
Um float aleatório de a até b (sem incluir b).

- `a` (number)
- `b` (number)

Retorna (number): Um float em [a, b).

#### `rng:shuffle(list)` — pura
Uma nova lista com os mesmos elementos em ordem aleatória (Fisher-Yates). A lista de entrada não é alterada.

- `list` (table) — Uma lista (1..#list).

Retorna (table): Uma nova lista embaralhada.