- O módulo Sift para Roblox fornece utilitários de dados imutáveis para projetos em Luau e roblox-ts.
- A configuração recomendada usa Wally, npm, a Roblox Creator Store ou uma cópia sincronizada do GitHub.
- O principal benefício são atualizações de estado previsíveis sem modificar a tabela original.
- O suporte a TypeScript já está incluído, com uma API projetada para corresponder à versão em Luau.
- Observação sobre manutenção: o repositório não é mais mantido ativamente, portanto analise os forks com cuidado.
O que é o módulo Sift para Roblox?
O módulo Sift para Roblox é uma biblioteca de dados imutáveis projetada para desenvolvimento em Luau e roblox-ts. Ela é destinada a projetos Roblox que precisam de transformações mais seguras em tabelas e dicionários, especialmente ao gerenciar estado, objetos de configuração, dados de jogadores ou coleções que não devem ser alteradas diretamente.
O Sift é fortemente baseado na biblioteca Llama, mas usa tipos nativos do Luau em vez de depender de verificação de tipos em tempo de execução. Esse design torna o Sift útil em bases de código nas quais as informações de tipo são tratadas durante o desenvolvimento e verificadas pela linguagem ou pela cadeia de ferramentas, sem depender de uma camada de execução separada.
A biblioteca não é um jogo, experiência, personagem ou sistema de progressão do Roblox. Ela é um utilitário de desenvolvimento que passa a fazer parte da árvore de código-fonte ou das dependências de pacotes de um projeto.
| Área | Função do Sift | Uso prático |
|---|---|---|
| Linguagem | Luau e roblox-ts | Compartilhar conceitos de transformação de dados entre os dois fluxos de trabalho |
| Design principal | Manipulação de dados imutáveis | Criar valores atualizados sem alterar a tabela original |
| Integração com Roblox | Wally, Creator Store, versões do GitHub, Rojo | Adicionar a biblioteca ao Studio ou a um projeto sincronizado |
| Suporte a tipos | Tipos nativos do Luau e compatibilidade integrada com TypeScript | Melhorar o feedback do editor e do compilador |
| Status do projeto | Não é mais mantido ativamente | Avaliar forks antes de adotar a biblioteca a longo prazo |
Atualizações imutáveis
Crie uma nova tabela a partir dos dados existentes em vez de alterar diretamente o valor original. Isso pode facilitar o rastreamento das transições de estado.
Luau em primeiro lugar
O Sift usa tipos nativos do Luau e evita exigir uma biblioteca separada de verificação de tipos em tempo de execução para suas próprias operações.
Pronto para TypeScript
A API do roblox-ts foi projetada para corresponder à contraparte em Luau, ajudando as equipes a usar padrões semelhantes entre as linguagens.
Trate o Sift como uma camada de utilitários de dados. Ele não substitui a arquitetura de estado, o modelo de rede, as regras de validação ou a estrutura de pastas do seu projeto.
Um modelo mental útil é considerar que cada operação produz um valor substituto. Seu código pode manter a tabela antiga para comparação, lógica de desfazer, depuração ou verificações de referência enquanto atribui a tabela retornada ao próximo estado.
Essa abordagem é especialmente valiosa em projetos Roblox maiores. A mutação direta pode dificultar a identificação do sistema que alterou uma tabela compartilhada. As operações imutáveis estabelecem limites mais claros: os dados de entrada entram em uma função, um resultado transformado é produzido e o valor original permanece disponível para inspeção.
Opções de instalação do módulo Sift para Roblox
O Sift pode ser adicionado a um projeto Roblox por meio de vários canais de distribuição. A melhor escolha depende de a equipe usar Wally, roblox-ts, Rojo ou um fluxo de trabalho manual no Studio.
| Método de instalação | Mais adequado para | Ação principal | Observações |
|---|---|---|---|
| Wally | Projetos Luau com gerenciamento de pacotes | Adicionar Sift = "csqrl/sift@x.x.x" ao wally.toml e executar wally install | Mantém as dependências definidas na configuração do projeto |
| npm | Projetos roblox-ts | Executar npm install @rbxts/sift | Fornece a interface do pacote para TypeScript |
| Creator Store | Fluxos de trabalho centrados no Studio | Copiar a biblioteca da Roblox Creator Store para o projeto | Útil quando as ferramentas de pacotes não fazem parte do fluxo de trabalho |
| Versões do GitHub | Instalação manual ou controlada do código-fonte | Baixar uma versão e colocá-la no projeto | Verificar o status do repositório antes de selecionar uma versão para uso a longo prazo |
| Sincronização com Rojo | Desenvolvimento baseado em arquivos | Sincronizar o modelo ou código-fonte do Sift com o Studio por meio do Rojo | Funciona bem com repositórios gerenciados fora do Studio |
Escolha o fluxo de trabalho do projeto
Decida se o projeto é principalmente em Luau, roblox-ts, gerenciado pelo Studio ou sincronizado com Rojo. Use Wally em um projeto Luau gerenciado por pacotes e npm em projetos roblox-ts.
Adicione a dependência
Para Wally, coloque a dependência do Sift no wally.toml. Para roblox-ts, instale @rbxts/sift pelo terminal do projeto. Usuários de fluxos manuais podem obter a biblioteca pela Creator Store ou pelas versões do GitHub.
Instale ou sincronize os arquivos
Execute o comando do gerenciador de pacotes quando aplicável. Se estiver usando um arquivo de modelo, coloque-o no Studio ou configure o Rojo para sincronizar a biblioteca com o local esperado.
Verifique a importação
Abra um pequeno módulo de teste e importe um utilitário do Sift. Confirme que o editor, o compilador ou o ambiente do Studio reconhece a dependência antes de integrá-la aos sistemas de produção.
Documente a escolha da versão
Registre a versão selecionada do pacote e o método de instalação na documentação do projeto. Isso facilita a análise de futuras atualizações ou migrações para forks.
Para usuários do Wally, a declaração da dependência deve continuar fazendo parte da configuração do projeto controlada pelo código-fonte. Evite instalar um pacote manualmente e esquecer de adicioná-lo ao manifesto do projeto, pois outro desenvolvedor pode não receber a mesma dependência durante a configuração.
Para usuários do roblox-ts, o nome do pacote é @rbxts/sift. A API do TypeScript foi criada para espelhar a API do Luau, o que facilita a tradução de exemplos entre os dois ambientes.
O repositório do Sift informa que ele não é mais mantido ativamente. Antes de incluir uma nova dependência em um projeto, analise o repositório, o histórico de versões e qualquer fork proposto quanto à compatibilidade e às expectativas de suporte.
A fonte de instalação não altera o propósito central da biblioteca. Wally, npm, Creator Store, GitHub e Rojo são métodos de distribuição; eles não são versões separadas do modelo de dados do Sift.
Padrões de dados imutáveis e operações com dicionários
O Sift é mais útil quando um projeto precisa de transformações consistentes em dicionários ou outros dados estruturados. O hábito central é simples: preservar a entrada, criar um resultado e usar esse resultado como o próximo estado.
Uma operação básica de mesclagem pode combinar vários dicionários enquanto exclui uma chave com Sift.None:
Dictionary.merge({ a: 1, c: 2 }, { b: 3, c: Sift.None })
O dicionário resultante é { a: 1, b: 3 }. O exemplo demonstra duas ideias importantes: valores de um dicionário posterior podem participar do resultado, e Sift.None pode remover uma chave existente durante a mesclagem.
| Padrão | Ideia da entrada | Resultado | Por que ajuda |
|---|---|---|---|
| Preservar o original | O estado existente permanece inalterado | O novo estado é atribuído separadamente | Facilita a depuração e a comparação |
| Mesclar dicionários | Combinar várias fontes de chave e valor | Um dicionário composto | Útil para padrões e substituições |
Remover com Sift.None | Marcar uma chave para exclusão | A chave não aparece no resultado | Mais limpo do que excluir diretamente em um estado compartilhado |
| Transformação tipada | Aplicar estruturas conhecidas de Luau ou TypeScript | Resultado compatível com o editor | Ajuda a detectar dados incompatíveis durante o desenvolvimento |
| Separar responsabilidades | Manter a transformação em uma função utilitária | Os chamadores recebem um novo valor | Reduz alterações ocultas entre os sistemas |
Ao usar utilitários imutáveis, dê nomes claros aos valores intermediários. Um nome como nextConfig, updatedState ou mergedProfile comunica que a variável representa uma substituição, e não uma referência modificada.
Um fluxo prático de atualização de estado se parece com isto:
- Leia a tabela atual.
- Passe-a para uma transformação.
- Armazene a tabela retornada.
- Compare ou publique o novo valor.
- Mantenha o valor antigo disponível quando rollback ou inspeção forem importantes.
Esse padrão funciona bem para camadas de configuração. Comece com os valores padrão, mescle as configurações específicas do ambiente e depois aplique as substituições do jogador ou da sessão. Se um valor precisar ser removido, use o marcador de remoção compatível com a biblioteca em vez de depender de uma mutação não controlada em outra parte da base de código.
Estado
Mantenha a tabela atual como entrada e evite tratá-la como uma área global temporária para alterações arbitrárias.
Transformar
Coloque a lógica de mesclagem ou de dicionários em uma função específica, com entrada e saída claras.
Validar
Use as ferramentas de Luau ou TypeScript para obter feedback sobre tipos e adicione uma biblioteca de validação separada quando forem necessárias verificações em tempo de execução.
Publicar
Atribua ou retorne a nova tabela somente depois que a transformação estiver concluída e compreensível.
Use o Sift nos limites onde os dados são alterados: redutores de estado, montagem de configurações, atualizações de perfis e outras funções que se beneficiam de valores de substituição explícitos.
O Sift não realiza verificação de tipos em tempo de execução por conta própria. Se um jogo precisar validar dados recebidos de clientes, armazenamento persistente ou sistemas externos durante a execução, adicione uma biblioteca de validação apropriada separadamente. Imutabilidade e validação resolvem problemas diferentes.
A documentação do projeto identifica GreenTea e t como exemplos de bibliotecas que podem ser instaladas manualmente para necessidades de verificação de tipos. Selecione uma ferramenta de validação com base nos requisitos reais de execução do projeto, em vez de presumir que o Sift cobre a validação de entradas.
Luau, roblox-ts e manutenção do projeto
O Sift oferece suporte a dois caminhos de desenvolvimento estreitamente relacionados. As equipes de Luau podem usar tipos nativos do Luau e fluxos de trabalho de pacotes projetados para o desenvolvimento Roblox. As equipes de roblox-ts podem usar o pacote npm e uma API compatível com TypeScript.
| Tipo de projeto | Caminho do pacote | Estratégia de tipos | Revisão sugerida |
|---|---|---|---|
| Luau com Wally | csqrl/sift por meio do Wally | Tipos nativos do Luau | Confirmar a resolução do pacote e a estrutura do código-fonte gerado |
| Luau com Rojo | Modelo ou arquivos de código-fonte sincronizados | Tipos nativos do Luau | Verificar se os caminhos do Studio correspondem à estrutura do repositório |
| roblox-ts | @rbxts/sift por meio do npm | Tipagens integradas do TypeScript | Confirmar a saída do compilador e os caminhos de importação |
| Studio manual | Cópia da Creator Store ou do GitHub | Estratégia de tipos definida pelo projeto | Documentar a versão copiada e o processo de atualização |
A API deve permanecer conceitualmente consistente entre Luau e TypeScript. Essa consistência é útil para equipes cujos sistemas são divididos entre código do servidor, código do cliente, ferramentas ou scripts gerados.
No entanto, uma API idêntica não significa que a cadeia de ferramentas ao redor também seja idêntica. Importações, comandos de compilação, saída gerada, arquivos de bloqueio de pacotes e configurações de sincronização ainda pertencem ao fluxo de trabalho específico de cada linguagem.
Antes de adotar o Sift em uma nova base de código de produção, analise estas questões de manutenção:
- O projeto precisa de correções ativas do upstream?
- A versão selecionada é compatível com a cadeia de ferramentas atual de Luau ou roblox-ts?
- A equipe aceitará a responsabilidade por correções de bugs caso seja necessário usar um fork?
- As versões dos pacotes estão fixadas no controle de versão?
- O projeto está preparado para substituir o Sift caso surja um caso extremo sem suporte?
O repositório é distribuído sob a licença MIT, e sua página pública do projeto inclui informações sobre versões, contribuidores e pacotes. Use o repositório do Sift no GitHub como referência principal para detalhes do pacote, análise do código-fonte e status atual de manutenção.
Se você depender de um fork, registre a URL do repositório, o identificador do commit ou da versão e quaisquer alterações na API. Uma breve nota de migração pode evitar incertezas quando o pacote original deixar de ser atualizado.
Revisão do projeto Sift:
- Escolher Wally, npm, Creator Store, GitHub ou Rojo para a instalação
- Fixar e documentar a versão da dependência
- Verificar uma importação de Luau ou roblox-ts em um pequeno teste
- Confirmar se a validação em tempo de execução é necessária separadamente
- Revisar as expectativas de manutenção antes da adoção em produção
Fluxo de trabalho prático para uma nova integração do Sift
Um teste pequeno e isolado é o ponto de partida mais seguro. Não comece substituindo todas as operações de tabela de um projeto grande. Primeiro, selecione um objeto de configuração, redutor de estado ou transformação de perfil e compare o comportamento antigo com o novo.
| Fase | Ação | Sinal de sucesso |
|---|---|---|
| Descoberta | Identificar uma transformação de dicionário repetida | A entrada e a saída esperada estão claramente definidas |
| Instalação | Adicionar o Sift usando o caminho normal de dependências do projeto | O pacote é resolvido sem correções manuais |
| Protótipo | Recriar a transformação com operações imutáveis | A entrada original permanece disponível para comparação |
| Testes | Verificar adições, substituições e remoções | Os resultados correspondem ao contrato de dados pretendido |
| Adoção | Mover transformações relacionadas para utilitários compartilhados | As equipes usam um padrão consistente |
Comece com dados previsíveis. Dicionários de configuração geralmente são mais fáceis de testar do que payloads de rede ou perfis persistentes, pois sua estrutura é conhecida antes da execução.
Em seguida, teste colisões de chaves. Se dois dicionários contiverem a mesma chave, defina qual fonte deve prevalecer e verifique se o resultado segue essa regra. Depois, teste o comportamento de remoção usando o marcador compatível Sift.None quando apropriado.
Por fim, teste o sistema ao redor. Um resultado imutável ainda pode ser atribuído incorretamente, enviado ao consumidor errado ou armazenado sob a chave errada. O Sift torna as transformações mais claras, mas o projeto ainda precisa definir a propriedade e o fluxo dos dados.
Mantenha a primeira integração do Sift limitada. Um utilitário focado, com testes claros, é mais fácil de revisar do que uma reescrita ampla de lógicas de tabela não relacionadas.
Erros comuns incluem tratar o Sift como uma estrutura de validação, instalar os pacotes de Luau e TypeScript sem motivo ou copiar uma dependência para o Studio sem documentar sua origem. Essas escolhas podem causar confusão mesmo quando as operações subjacentes funcionam corretamente.
Para equipes que estão migrando do Llama, compare cuidadosamente cada operação existente. O Sift é fortemente baseado no Llama, mas possui suas próprias decisões de tipos e documentação. Confirme importações, tipos de retorno, testes e comportamento em casos extremos, em vez de presumir que todas as convenções do projeto ao redor serão transferidas automaticamente.
Perguntas frequentes sobre o módulo Sift para Roblox
Q: Para que serve o módulo Sift para Roblox?
O Sift é uma biblioteca de dados imutáveis para Luau e roblox-ts. Ele ajuda os desenvolvedores a criar dicionários e valores estruturados atualizados sem alterar diretamente a tabela original.
Q: Como posso instalar o Sift em um projeto Roblox?
Você pode usar Wally, npm para roblox-ts, a Roblox Creator Store, versões do GitHub ou uma cópia sincronizada pelo Rojo. Escolha o método que corresponde ao fluxo de trabalho do seu projeto e documente a versão selecionada.
Q: O Sift oferece verificação de tipos em tempo de execução?
Não. O Sift usa tipos nativos do Luau e não inclui verificação de tipos em tempo de execução. Se o seu projeto precisar validar dados durante a execução, instale e configure uma biblioteca de validação separada.
Q: O Sift ainda é mantido ativamente em 2026?
O repositório informa que o Sift não é mais mantido ativamente e sugere considerar um fork para contribuições. Analise o repositório oficial e qualquer fork antes de usá-lo em um novo projeto de produção.
Antes de publicar um projeto que dependa do Sift, verifique a compatibilidade do pacote, teste as atualizações imutáveis e decida como a equipe lidará com a manutenção futura.
O melhor uso do Sift é deliberado e focado: instale-o por meio de um fluxo de trabalho documentado, use transformações imutáveis onde elas esclareçam as alterações de estado e mantenha a validação separada da responsabilidade de longo prazo pelas dependências. Essa abordagem permite que as equipes de Luau e roblox-ts se beneficiem de utilitários consistentes para dicionários, mantendo um plano realista de suporte ao projeto.