Guia para iniciantes de Sift Roblox: configuração do Luau e fundamentos da API

Sift Roblox é uma biblioteca para desenvolvedores que trabalham com dados imutáveis em Luau e roblox-ts. Ela não é uma experiência jogável do Roblox, um sistema de personagens ou uma mecânica de progressão. Em vez disso, oferece aos criadores funções utilitárias para atualizar arrays, dicionários e conjuntos sem modificar diretamente os dados originais.

O projeto é fortemente baseado na biblioteca Llama, que não é mais mantida. O Sift segue uma finalidade semelhante, mas utiliza tipos nativos do Luau, testes reorganizados, documentação gerada e definições de tipos integradas para TypeScript. Essas diferenças tornam a biblioteca útil para projetos que precisam de atualizações de estado previsíveis ou utilitários de dados compartilhados.

A ideia central é simples: em vez de alterar uma tabela no local, crie um resultado atualizado preservando o valor original. Esse padrão pode tornar mais fáceis de entender os dados do inventário, as configurações dos jogadores, os objetos de configuração e o estado replicado.

O Sift pode ser adicionado a um projeto de desenvolvimento do Roblox de várias maneiras. A melhor escolha depende de como sua equipe gerencia as dependências. O Wally é adequado para fluxos de trabalho de pacotes via linha de comando, projetos roblox-ts podem usar npm, e a instalação manual funciona quando você prefere colocar o modelo diretamente no Studio.

A documentação de referência identifica o Sift como disponível por meio do Wally, Itch.io, Biblioteca do Roblox e releases do GitHub. Ela também observa que o projeto é gratuito e de código aberto, enquanto uma página no Itch.io pode ser usada para patrocínio opcional.

Configuração do Wally

Em um projeto Wally, adicione a dependência à seção [dependencies] do arquivo wally.toml. O formato documentado usa um marcador de versão v0.x:

[dependencies]
Sift = "csqrl/sift@0.0.X"

Substitua 0.0.X pela versão que pretende usar e execute:

wally install

Mantenha a versão selecionada visível na configuração do projeto. Isso facilita reproduzir o mesmo conjunto de dependências em diferentes máquinas e reduz a confusão quando uma nova release menor altera o comportamento.

Configuração do roblox-ts

A documentação informa que o Sift inclui definições de tipos para TypeScript e pode ser instalado para roblox-ts com:

npm install @rbxts/sift

Uma importação básica e uma operação com dicionário podem ser semelhantes a esta:

import Sift from "@rbxts/sift"

const updated = Sift.Dictionary.merge(
  { a: 1, c: 2 },
  { b: 3, c: Sift.None }
)

O resultado documentado é um dicionário contendo a: 1 e b: 3. O valor Sift.None remove a entrada existente c durante a combinação.

Instalação manual

A instalação manual consiste em obter uma cópia da Biblioteca do Roblox ou de uma release do GitHub e colocá-la no Studio. O modelo do Sift também pode ser sincronizado com o Rojo. Esse método é acessível para pequenos experimentos, mas as equipes devem registrar a versão da release e a data de instalação para manter as atualizações futuras sob controle.

A maneira mais rápida de entender o Sift é praticar uma atualização imutável por vez. Comece com um dicionário pequeno, examine o valor retornado e confirme que a tabela original continua sendo o valor de referência para a lógica da aplicação.

Uma combinação de dicionários é um exemplo inicial útil:

local Sift = require(path.to.Sift)

local original = {
    Coins = 100,
    Title = "Rookie",
}

local updated = Sift.Dictionary.merge(original, {
    Coins = 125,
    Title = Sift.None,
})

Nesse padrão, o dicionário retornado pode representar o próximo estado. O valor de Coins é substituído, enquanto Title é removido por meio de Sift.None. O caminho exato da importação depende do método de instalação e da estrutura do projeto; portanto, use o caminho gerado pelo seu fluxo de trabalho de dependências.

O Sift é compatível tanto com Luau quanto com roblox-ts, mas a experiência de desenvolvimento ao redor é diferente. Usuários de Luau normalmente trabalham diretamente no Roblox Studio ou em um projeto gerenciado pelo Wally. Usuários de roblox-ts escrevem TypeScript e o compilam em código compatível com o Roblox por meio da ferramenta que já utilizam.

A documentação da biblioteca destaca que o Sift usa tipos nativos do Luau e não executa a verificação de tipos em tempo de execução anteriormente associada à abordagem com a dependência antiga. Isso significa que a correção dos tipos continua sendo uma responsabilidade importante do desenvolvedor.

Escolhendo o melhor ponto de partida

Escolha Luau direto se estiver aprendendo a programar no Roblox ou quiser o caminho mais curto entre o Studio e um exemplo funcional. Escolha roblox-ts se seu projeto já usa TypeScript e npm. Evite mudar de linguagem apenas para usar o Sift; a biblioteca foi projetada para se adaptar a qualquer um dos dois fluxos de trabalho.

Para desenvolvedores Luau, preste atenção à diferença entre orientação estática e comportamento em tempo de execução. Os tipos nativos podem ajudar a descrever os valores esperados, mas dados incorretos ainda podem causar erros em tempo de execução quando as funções recebem entradas inesperadas.

Para desenvolvedores roblox-ts, as definições de tipos podem melhorar o feedback do editor e facilitar a descoberta das APIs. No entanto, o código compilado ainda precisa de testes no nível do projeto, especialmente quando os dados vêm de entradas dos jogadores, dados salvos, rede ou sistemas externos.

Um fluxo de trabalho do Sift adequado para iniciantes depende menos de memorizar todas as funções e mais de manter clara a propriedade dos dados. Decida qual sistema é responsável por um valor, crie um novo resultado para as atualizações e evite misturar padrões mutáveis e imutáveis sem uma razão clara.

Erros comuns

• Editar a tabela original depois de criar um resultado com o Sift: Isso pode dificultar o acompanhamento do histórico do estado.
• Usar uma função de array para dados de dicionário: Selecione a API com base no tipo de coleção, não apenas no resultado desejado.
• Supor que congelar corrige dados inválidos: As funções de congelamento restringem alterações; elas não validam o conteúdo de uma coleção.
• Ignorar estruturas aninhadas: Um congelamento superficial e um congelamento profundo têm efeitos diferentes.
• Atualizar dependências v0.x sem testar: Aumentos na versão menor podem incluir alterações incompatíveis.
• Não documentar o projeto: Registre como o Sift está instalado e qual versão o projeto espera.

Como referência, use a página oficial da documentação do Sift para consultar notas de instalação, orientações sobre a estabilidade do v0.x e os utilitários de coleção disponíveis. Mantenha esse link nas anotações do projeto junto à configuração da dependência.

O Sift é uma opção prática para desenvolvedores que desejam atualizações imutáveis estruturadas em projetos do Roblox. Comece com um tipo de coleção, use o método de instalação que corresponde ao seu fluxo de trabalho e trate as atualizações v0.x como alterações que exigem testes.