Habilidade Offline Roblox

O que Habilidade Offline Roblox faz?

Propósito

Use esta habilidade para construir e revisar sistemas confiáveis de dados de jogadores e progressão calculada para períodos de ausência do jogo. Ela cobre arquitetura, implementação, testes, operações e recuperação. É uma orientação para um agente de IA, não uma estrutura de persistência implantável.

Condições de ativação

Use esta habilidade quando uma tarefa envolver:

• Salvar, carregar, redefinir, migrar, restaurar ou inspecionar dados de jogadores.
• DataStoreService, DataStores padrão, OrderedDataStores, MemoryStoreService, Open Cloud DataStores ou Gerenciador de Data Stores do Creator Hub.
• Perfis de jogadores, moedas, inventário, mascotes, atualizações, terrenos, colheitas, máquinas, geradores, placares de líderes e configurações persistentes.
• Propriedade de sessão, bloqueio de sessão, salvamento automático, novas tentativas, orçamentos de solicitação, limitação de taxa, PlayerRemoving ou BindToClose.
• Ganhos offline, renda inativa, temporizadores de cultivo, produção, tempos de espera ou progresso após reconexão.
• Perda de dados, gravações desatualizadas, recompensas duplicadas, registros corrompidos, recibos de compra ou migrações de esquema.

Não use esta habilidade para tarefas não relacionadas de interface, mapa, animação, combate ou jogabilidade geral, a menos que elas envolvam dados persistentes de jogadores.

Fatos principais

1. DataStoreService fornece armazenamento persistente em nuvem da Roblox. Ele é acessado por código do servidor e requer conectividade com os serviços da Roblox.
2. O Gerenciador de Data Stores do Creator Hub é um painel para visualizar e gerenciar dados. Não é um serviço Luau ou uma API de banco de dados em tempo de execução.
3. MemoryStoreService fornece dados temporários entre servidores. As entradas expiram e não é um armazenamento permanente de perfis de jogadores.
4. OrderedDataStore é para valores numéricos ordenados, comumente pontuações persistentes em placares de líderes. Não é um perfil completo de jogador.
5. A memória do servidor é a cópia de trabalho volátil do servidor ativo. Ela pode ser perdida se o processo for encerrado antes de um salvamento bem-sucedido.
6. Progressão offline normalmente significa atualização limitada calculada pelo servidor após o retorno de um jogador. Não significa um mundo particular continuando a simular sem um servidor ativo.
7. Um cliente totalmente desconectado não pode gravar em DataStores da nuvem Roblox. Não prometa que uma experiência Roblox publicada normal pode continuar jogando e salvando na nuvem sem conectividade.
8. Chamadas ao DataStoreService pertencem a Scripts do servidor ou ModuleScripts requeridos por Scripts do servidor. Nunca salve dados canônicos de um LocalScript.
9. UpdateAsync é uma operação de ler-modificar-gravar. Por si só, não implementa bloqueio de sessão.
10. Uma solicitação bem-sucedida não prova que o perfil retornado é estruturalmente válido ou compatível com o esquema atual.
11. Uma falha de carregamento não é equivalente a uma chave ausente ou a um novo jogador.
12. Nunca afirme que o código foi testado no Roblox Studio, a menos que a experiência alvo tenha sido realmente executada no Studio.

Fluxo de trabalho obrigatório

1. Inspecionar antes de editar

Inspecione a experiência real, arquivos, scripts, ModuleScripts, remotos, pacotes e integrações disponíveis do Studio.

Identifique:

• Cada nome de DataStore, escopo, construtor de chave, prefixo de chave e adaptador de armazenamento.
• Todas as chamadas GetAsync, SetAsync, UpdateAsync, IncrementAsync, versão e listagem.
• PlayerAdded, PlayerRemoving, BindToClose, tarefas de salvamento automático, manipuladores de recibos de compra e cada gravador para cada chave de perfil.
• O esquema atual, modelo padrão, versão de migração e o ponto exato em que um perfil se torna gravável.
• Se o projeto usa DataStoreService nativo, uma biblioteca de perfil de terceiros ou um wrapper personalizado.
• Como a propriedade do perfil, novas tentativas, ordenação de mesma chave e desligamento são atualmente tratados.
• O que o usuário significa por offline: atualização de tempo de ausência, interrupção temporária de serviço, teste simulado ou jogo totalmente desconectado.

Não infira a arquitetura a partir de uma captura de tela, um nome de repositório ou alguns fragmentos de código isolados. Preserve um sistema funcional, a menos que haja evidências mostrando um motivo concreto para alterá-lo.

2. Verificar o comportamento da Roblox

Use references/official-roblox-sources.md como índice de fontes. Reconsulte a documentação atual do Creator Hub da Roblox para assinaturas de API, cotas, comportamento do serviço, configuração e descontinuações antes de codificar.

Use a documentação da Roblox para garantias do mecanismo. Para pacotes de terceiros, inspecione a versão exata instalada no projeto alvo e verifique a API desse pacote. Não invente métodos de bibliotecas a partir da memória ou de exemplos antigos.

3. Escolher armazenamento por requisito

Requisito	Ponto de partida correto
Progresso durável do jogador	DataStore padrão via DataStoreService ou uma camada de perfil mantida
Classificação numérica persistente	OrderedDataStore
Estado temporário compartilhado entre servidores	MemoryStoreService
Perfil ativo do servidor atual	Memória do servidor
Inspecionar ou recuperar entradas armazenadas	Gerenciador de Data Stores do Creator Hub e APIs de versão
Administração externa	Open Cloud através de um backend confiável
Progresso para períodos de ausência	Perfil persistente mais cálculo de atualização no servidor
Jogo independente totalmente desconectado	Não fornecido por DataStores normais da nuvem Roblox

Prefira uma chave de perfil estável baseada em UserId quando o perfil couber e seus campos precisarem de atualizações coerentes. Divida apenas por um motivo real de tamanho, taxa de transferência ou padrão de acesso. Não crie um DataStore por jogador.

4. Carregar e possuir perfis com segurança

Um perfil se torna gravável somente após carregamento bem-sucedido e propriedade exclusiva sob a arquitetura selecionada.

1. Comece o carregamento quando o servidor receber PlayerAdded.
2. Adquira o bloqueio de perfil/sessão usando a camada de persistência existente.
3. Diferencie um resultado válido de chave ausente de falha de rede, limitação de taxa, conflito de sessão, dados malformados e esquema não suportado.
4. Valide a carga útil e aplique migrações ordenadas e determinísticas.
5. Publique o perfil como pronto somente depois que todas as etapas necessárias forem bem-sucedidas.
6. Permita que a jogabilidade do servidor modifique a cópia de trabalho de propriedade do servidor através de métodos controlados.
7. Pare as mutações imediatamente se a biblioteca de perfil relatar que a propriedade terminou.

Nunca crie um perfil padrão gravável após uma falha de carregamento transitória. Isso pode sobrescrever os dados reais de um jogador que retorna.

5. Salvar com ordenação e novas tentativas limitadas

• Trate chamadas de rede com pcall ou a camada de erro estabelecida do projeto.
• Repita apenas erros transitórios, usando back-off exponencial limitado e jitter aleatório.
• Não repita argumentos inválidos ou falhas permanentes para sempre.
• Serialize gravações por chave. Uma nova tentativa atrasada antiga não deve sobrescrever um salvamento bem-sucedido mais recente.
• Projete operações repetíveis para serem idempotentes, porque uma resposta de falha pode deixar o resultado da gravação incerto.
• Use UpdateAsync quando o novo valor depender do estado atual armazenado ou quando gravações concorrentes forem possíveis.
• SetAsync é válido para substituição intencional de valor inteiro quando a propriedade exclusiva e a semântica de substituição estão estabelecidas. Não o chame universalmente proibido.
• Mantenha as funções de transformação do UpdateAsync determinísticas, sem suspensão e livres de efeitos colaterais externos. Nunca execute esperas, chamadas HTTP, chamadas remotas, concessões de recibos, análises ou criação de Instâncias dentro do callback.
• Um retorno nil de uma transformação UpdateAsync cancela a gravação.
• Observe os orçamentos de solicitação atuais e o comportamento de limitação. UpdateAsync consome orçamento de leitura e gravação.
• Distribua os salvamentos automáticos. Não salve a cada quadro ou para cada evento de jogabilidade mínimo.

6. Implementar progressão offline corretamente

Leia references/offline-progression.md e examples/offline-progress.luau antes de construir um sistema de recompensa offline.

O servidor deve:

1. Carregar e validar o perfil.
2. Confirmar a propriedade exclusiva da sessão.
3. Ler os timestamps salvos e as entradas de produção de propriedade do servidor.
4. Obter a hora epoch atual do servidor.
5. Calcular o tempo decorrido não negativo e limitá-lo a um máximo configurado.
6. Derivar as taxas de produção a partir da propriedade validada e definições do servidor.
7. Aplicar eficiência offline configurada, elegibilidade e limites de recompensa.
8. Atualizar a recompensa e seu timestamp de simulação correspondente juntos na cópia de trabalho do perfil.
9. Persistir através da camada de perfil ativa.
10. Replicar dados de apresentação para o cliente.

Use os.time() ou outro timestamp epoch do servidor documentado para cálculos entre sessões. Nunca use os.clock() como timestamp epoch. Nunca confie em relógio do cliente, duração decorrida, taxa de produção, estágio de colheita, lista de ativos ou timestamp da última reivindicação.

Não recompense o mesmo intervalo duas vezes. Não conte a produção online em dobro. Não execute um loop ilimitado uma vez por segundo offline. Lide com timestamps ausentes, malformados, zero, negativos e futuros deliberadamente.

7. Proteger dados de desenvolvimento e produção

• Use uma experiência de desenvolvimento ou teste publicada separada para testes de integração com DataStore ativo.
• Habilite o Acesso do Studio a Serviços de API apenas nessa experiência de teste isolada.
• A Roblox adverte que o Studio pode acessar os mesmos DataStores que a aplicação ativa. Nunca habilite essa configuração na produção para testes de rotina.
• Use mocks ou um adaptador em memória para testes lógicos determinísticos. Um mock não é um salvamento real de jogador e não é armazenamento durável.
• Use contas descartáveis e chaves de teste.
• Não exclua, reverta, renomeie ou sobrescreva dados de produção sem autorização explícita do operador, identificação exata do alvo e um plano de recuperação.
• Mantenha as credenciais do Open Cloud em um backend confiável. Nunca as exponha em um LocalScript, cliente, repositório público ou contexto de prompt.

8. Verificar e relatar honestamente

Use references/test-matrix.md. Cubra perfis de primeira vez e retorno, falhas de carregamento, conflitos, proprietários desatualizados, ordenação de gravações, novas tentativas, salvamento automático, desligamento, recuperação de falha, cargas malformadas, migrações, limites offline, reivindicações repetidas e recibos duplicados.

Relate o nível de validação com precisão:

• Revisão estática
• Testes unitários puros
• Testes de integração simulados/em memória
• Testes de DataStore publicados em estágio
• Testes de tempo de execução no Roblox Studio
• Testes de conflito multisservidor/sessão

Essas são verificações diferentes. Se o Studio ou o estágio não estavam disponíveis, declare que a validação em tempo de execução permanece pendente.

Proibições não negociáveis

• Nunca salve dados canônicos de jogador a partir de um LocalScript.
• Nunca confie em UserIds, saldos, preços, inventário, propriedade, taxas de recompensa, timestamps, tempo decorrido ou resultados de compra fornecidos pelo cliente.
• Nunca trate um erro de carregamento transitório como um novo jogador.
• Nunca use MemoryStoreService ou RAM do servidor como armazenamento permanente de perfil.
• Nunca use DataStore2 para uma nova experiência. A Roblox atualmente o identifica como uma biblioteca legada.
• Nunca suspenda ou execute efeitos colaterais em callbacks do UpdateAsync.
• Nunca permita que gravações e novas tentativas da mesma chave concorram.
• Nunca roube à força uma sessão ativa como uma nova tentativa normal.
• Nunca grave valores brutos sobre uma chave gerenciada por uma biblioteca de perfil.
• Nunca afirme que UpdateAsync sozinho implementa um bloqueio de sessão.
• Nunca execute loops de simulação offline ilimitados.
• Nunca exponha segredos do Open Cloud.
• Nunca modifique dados de produção de forma destrutiva sem autorização explícita e um plano de recuperação.
• Nunca afirme que testes no Studio foram realizados se não aconteceram.

Mapa de referência

Carregue apenas os documentos necessários para a tarefa atual:

• references/architecture-and-services.md: papéis dos serviços, Gerenciador de Data Stores, Open Cloud e seleção de armazenamento.
• references/player-data-lifecycle.md: ciclo de vida do perfil, cópias de trabalho em memória, prontidão, saída e desligamento.
• references/session-locking-and-failures.md: propriedade de sessão, UpdateAsync, ordenação de gravação, novas tentativas, limitação e resultados desconhecidos.
• references/offline-progression.md: recompensas inativas, temporizadores de colheita, geradores, cálculo de timestamp, limites e limitações de desconexão.
• references/studio-testing.md: acesso à API, estágio, mocks e isolamento de teste seguro.
• references/schema-migrations-and-recovery.md: serialização, versões de esquema, migrações, histórico de versões e recuperação.
• references/security-and-purchases.md: remotos, autoridade do servidor, recibos, segredos do Open Cloud e privacidade de dados.
• references/performance-and-limits.md: limites documentados, orçamentos, taxa de transferência e ajuste operacional.
• references/library-selection.md: DataStoreService nativo, código de referência oficial e avaliação de pacotes de terceiros.
• references/game-patterns.md: perfis, placares de líderes, terrenos, sistemas inativos, trocas e compras.
• references/test-matrix.md: cenários de verificação.
• references/official-roblox-sources.md: links de fontes do Creator Hub da Roblox apenas.
• examples/profile-template.luau: formato ilustrativo de perfil.
• examples/offline-progress.luau: cálculo puro e limitado de recompensa offline.

Resposta de implementação obrigatória

Para tarefas de implementação e depuração:

1. Resuma a arquitetura existente encontrada no projeto real.
2. Explique o fluxo de dados pretendido e a menor alteração segura.
3. Liste os arquivos exatos a serem criados ou modificados.
4. Entregue código completo e consciente do contexto, não fragmentos desconectados.
5. Explique as etapas de configuração, estágio e qualquer migração de esquema.
6. Relate os testes reais e as verificações de tempo de execução restantes.
7. Declare limites e riscos materiais sem inventar garantias.

Respeite o idioma e estilo solicitados pelo usuário. Preserve sistemas funcionais. Não adicione recursos não relacionados ou substitua uma biblioteca de persistência existente por razões estilísticas.