MemoryStoreService é um serviço de dados de alta capacidade e baixa latência que fornece armazenamento rápido de dados em memória acessível de todos os servidores em uma sessão ao vivo. Armazenamentos em Memória são adequados para dados frequentes e efêmeros que mudam rapidamente e não precisam ser duráveis, pois são mais rápidos de acessar e desaparecem ao atingir a vida útil máxima. Para dados que precisam persistir entre sessões, use armazenamentos de dados.
Estruturas de dados
Em vez de acessar dados brutos diretamente, os armazenamentos em memória têm três estruturas de dados primitivas compartilhadas entre servidores para processamento rápido: mapa ordenado, fila e mapa hash. Cada estrutura de dados é adequada para certos casos de uso:
- Matchmaking baseado em habilidade - Salve informações do usuário, como nível de habilidade, em uma fila compartilhada entre servidores e use servidores de lobby para executar matchmaking periodicamente.
- Trocas e leilões entre servidores - Permita trocas universais entre diferentes servidores, onde os usuários podem dar lances em itens com preços que mudam em tempo real, com um mapa ordenado de pares chave-valor.
- Classificações globais - Armazene e atualize as classificações dos usuários em uma tabela de classificação compartilhada dentro de um mapa ordenado.
- Inventários compartilhados - Salve itens de inventário e estatísticas em um mapa hash compartilhado, onde os usuários podem utilizar itens de inventário simultaneamente entre si.
- Cache para Dados Persistentes - Sincronize e copie seus dados persistentes em um armazenamento de dados para um mapa hash de armazenamento em memória que pode atuar como um cache e melhorar o desempenho do seu jogo.
Em geral, se você precisa acessar dados com base em uma chave específica, use um mapa hash. Se você precisa que esses dados sejam ordenados, use um mapa ordenado. Se você precisa processar seus dados em uma ordem específica, use uma fila.
Limites e cotas
Para manter a escalabilidade e o desempenho do sistema, os armazenamentos em memória têm cotas de uso de dados para o tamanho da memória, solicitações de API e o tamanho da estrutura de dados.
Os armazenamentos em memória têm uma política de expulsão baseada no tempo de expiração, também conhecido como tempo de vida (TTL). Os itens são expulsos após expirarem, e a cota de memória é liberada para novas entradas. Quando você atinge o limite de memória, solicitações que aumentam o uso de memória falham até que você libere memória ou aumente sua cota. Veja Recuperar da exaustão da cota de memória para opções.
Cota de tamanho de memória
A cota de memória limita a quantidade total de memória que um jogo pode consumir. Não é um valor fixo; em vez disso, muda ao longo do tempo dependendo do número de usuários no jogo de acordo com a fórmula 64 KB + 1,2 KB * [número de usuários]. A cota se aplica no nível do jogo em vez do nível do servidor.
Quando os usuários entram no jogo, a cota de memória adicional está disponível imediatamente. Quando os usuários saem do jogo, a cota não é reduzida imediatamente. Há um período de rastreamento de oito dias antes que a cota seja reavaliada para um valor mais baixo.
Depois que seu jogo atinge a cota de tamanho de memória, qualquer solicitação de API que aumente o tamanho da memória sempre falha. Solicitações que diminuem ou não alteram o tamanho da memória ainda têm sucesso.
Com o painel de observabilidade, você pode visualizar a cota de tamanho de memória do seu jogo em tempo real usando o gráfico de Uso de Memória.
Limites de solicitações de API
Uma cota de unidade de solicitação se aplica a todas as chamadas de API do MemoryStoreService. Essa cota é 1000 + 120 * [número de usuários simultâneos] unidades de solicitação por minuto.
A maioria das chamadas de API consome apenas uma unidade de solicitação, com algumas exceções:
MemoryStoreSortedMap:GetRangeAsync()
Consome unidades com base no número de itens retornados. Por exemplo, se este método retornar 10 itens, a chamada conta como 10 unidades de solicitação. Se retornar uma resposta vazia, conta como uma unidade de solicitação.
Consome unidades com base no número de itens retornados, assim como MemoryStoreSortedMap:GetRangeAsync(), mas consome uma unidade adicional a cada dois segundos enquanto lê. Especifique o tempo máximo de leitura com o parâmetro waitTimeout.
MemoryStoreHashMap:UpdateAsync()
Consome um mínimo de duas unidades.
MemoryStoreHashMap:ListItemsAsync()
Consome [número de partições escaneadas] + [itens retornados] unidades.
A cota de solicitações também se aplica no nível do jogo em vez do nível do servidor. Isso fornece flexibilidade para alocar as solicitações entre servidores, desde que a taxa total de solicitações não exceda a cota. Se você exceder a cota, receberá uma resposta de erro quando o serviço limitar suas solicitações.
Com o recurso de observabilidade disponível, você pode visualizar a cota de unidade de solicitação do seu jogo em tempo real.
Limites de tamanho da estrutura de dados
Para um único mapa ordenado ou fila, os seguintes limites de tamanho e contagem de itens se aplicam:
- Número máximo de itens: 1.000.000
- Tamanho total máximo (incluindo chaves para mapa ordenado): 100 MB
Limites por partição
Além da cota de unidade de solicitação no nível do jogo, os armazenamentos em memória aplicam limites de solicitação a cada partição como uma salvaguarda que protege a estabilidade do serviço para todos os jogos. Esses limites não são uma cota que seu jogo é alocado, e não são um teto rígido sobre a capacidade que seu jogo pode alcançar. Os seguintes valores são estimativas. Eles são configurados no backend do Roblox e podem mudar, então não projete contra eles como números fixos.
Cada solicitação conta para o limite da partição que contém o item, independentemente da estrutura de dados. Você pode atualmente esperar que a limitação comece em aproximadamente 30.000 unidades de solicitação por minuto para uma única partição, então procure ficar bem abaixo dessa taxa. Quanto desse limite uma estrutura de dados consome depende de como seus itens estão distribuídos:
- Mapas ordenados e filas residem cada um em uma única partição, então cada solicitação a uma dessas estruturas de dados conta para o mesmo limite de partição.
- Mapas hash espalham seus itens por muitas partições, então o tráfego distribuído entre muitas chaves de item raramente se aproxima do limite de qualquer uma partição.
Os mapas hash têm um limite adicional em cada chave de item de aproximadamente 5.000 unidades de solicitação de gravação por minuto e 15.000 unidades de solicitação de leitura por minuto. Esse limite por chave se aplica além do limite por partição, então uma chave acessada com frequência pode atingir qualquer um deles. O limite por chave se aplica apenas a operações de chave única: o limite de leitura se aplica a MemoryStoreHashMap:GetAsync(), o limite de gravação se aplica a MemoryStoreHashMap:SetAsync() e MemoryStoreHashMap:RemoveAsync(), e MemoryStoreHashMap:UpdateAsync() conta contra os limites de leitura e gravação. MemoryStoreHashMap:ListItemsAsync() escaneia partições em vez de uma única chave, então apenas o limite por partição se aplica a ele.

Se você não precisa de ordenação ou funcionalidade de primeiro a entrar, primeiro a sair, um mapa hash é geralmente a melhor escolha porque pode distribuir a carga entre partições.
Quando as solicitações excedem um limite de partição ou por chave, o serviço as limita e retorna um código de status PartitionRequestsOverLimit, que você pode monitorar com o painel de observabilidade.
Se você espera que uma estrutura de dados ou uma chave de item receba uma alta taxa de solicitações sustentadas, particione para que a carga se espalhe por mais partições ou chaves. Distribua leituras e gravações uniformemente entre várias chaves de item para permanecer dentro dos limites por chave. Você também pode reduzir a taxa de solicitações armazenando valores em cache no servidor e rechecando-os após um intervalo, agrupando solicitações sempre que possível e aplicando retorno exponencial quando você receber respostas de limitação.
Recuperar da exaustão da cota de memória
Se seu jogo receber erros TotalMemoryOverLimit, verifique o gráfico de Uso de Memória no painel de observabilidade. Para retomar gravações que aumentam o uso de memória, exclua itens desnecessários, aguarde a expiração dos itens ou use uma das seguintes opções.
Limpar armazenamentos em memória com Open Cloud
Se você não precisa mais dos dados armazenados, use o endpoint Open Cloud Flush Memory Store para limpar assíncronamente todas as estruturas de dados de armazenamento em memória em um universo para o escopo selecionado.
Para limpar armazenamentos em memória:
- Crie uma chave de API com permissões para limpar armazenamentos em memória e obter o status da operação de limpeza para o universo alvo.
- Envie uma solicitação POST para https://apis.roblox.com/cloud/v2/universes/{universe_id}/memory-store:flush com a chave de API no cabeçalho x-api-key. Substitua {universe_id} pelo ID do universo do seu jogo. Defina o parâmetro de consulta scope como LIVE para dados de produção ou TEST para dados do Studio. Se você omitir scope, o endpoint usará LIVE.
- Use Get Memory Store Flush Operation para consultar a operação retornada pela solicitação de limpeza até que done seja true, e verifique se há um error. Use o mesmo escopo ao consultar. O path retornado já inclui cloud/v2, então consulte em https://apis.roblox.com/{path} sem adicionar outro prefixo.
Os armazenamentos em memória do Studio e da produção são isolados. Limpar um escopo não limpa o outro. Após limpar dados desnecessários, siga as melhores práticas, como tempos de expiração mais curtos e exclusão explícita, para evitar que o uso de memória atinja a cota novamente.
Aumentar a capacidade com Serviços Estendidos
Se seu jogo precisa reter os dados e usar mais armazenamento do que a cota padrão permite, ative os Serviços Estendidos para armazenamentos em memória. Os Serviços Estendidos permitem que você pague pelo armazenamento e solicitações de armazenamento em memória além das cotas padrão.
Para começar, atenda aos requisitos de elegibilidade, adicione detalhes da conta e um método de pagamento, e então selecione seu jogo no Painel do Criador. Em Serviços Estendidos, ative os armazenamentos em memória e defina orçamentos mensais para os recursos que você precisa. Veja Ativar um serviço e Preços de serviço para detalhes.
Os Serviços Estendidos limitam o serviço se o uso exceder seu orçamento. Monitore o uso e a cobrança, e continue a remover dados desnecessários.
Melhores práticas
Para manter seu padrão de uso de memória ideal e evitar atingir os limites, siga estas melhores práticas:
Remova itens processados. Limpar consistentemente itens lidos usando o método MemoryStoreQueue:RemoveAsync() para filas e MemoryStoreSortedMap:RemoveAsync() para mapas ordenados pode liberar memória e manter a estrutura de dados atualizada.
Defina o tempo de expiração para o menor intervalo de tempo possível ao adicionar dados. Embora o tempo de expiração padrão seja de 45 dias tanto para MemoryStoreQueue:AddAsync() quanto para MemoryStoreSortedMap:SetAsync(), definir o menor tempo possível pode limpar automaticamente dados antigos para evitar que ocupem sua cota de uso de memória.
- Não armazene uma grande quantidade de dados com uma longa expiração, pois isso pode arriscar exceder sua cota de memória e potencialmente causar problemas que podem quebrar todo o seu jogo.
- Sempre exclua explicitamente itens desnecessários ou defina uma expiração curta para os itens.
- Geralmente, você deve usar a exclusão explícita para liberar memória e a expiração de itens como um mecanismo de segurança para evitar que itens não utilizados ocupem memória por um longo período de tempo.
Mantenha apenas valores necessários na memória.
Por exemplo, para um jogo de casa de leilão, você só precisa manter o maior lance. Você pode usar MemoryStoreSortedMap:UpdateAsync() em uma chave para manter o maior lance em vez de manter todos os lances em sua estrutura de dados.
Use retorno exponencial para ajudar a ficar abaixo dos limites de solicitações de API.
Por exemplo, se você receber um DataUpdateConflict, você pode tentar novamente após dois segundos, depois quatro, oito, etc., em vez de enviar constantemente solicitações para MemoryStoreService para obter a resposta correta.
Divida grandes estruturas de dados em várias menores por particionamento.
É frequentemente mais fácil gerenciar dados em estruturas menores do que armazenar tudo em uma grande estrutura de dados. Essa abordagem também pode ajudar a evitar limites de uso e taxa. Por exemplo, se você tiver um mapa ordenado que usa prefixos para suas chaves, considere separar cada prefixo em seu próprio mapa ordenado. Para um jogo especialmente popular, você pode até separar usuários em vários mapas com base nos últimos dígitos de seus IDs de usuário.
Particione chaves acessadas com frequência em mapas hash com várias cópias da chave para distribuir a carga.
Comprimir valores armazenados.
Por exemplo, considere usar o algoritmo LZW para reduzir o tamanho do valor armazenado.
Inscreva-se nos Serviços Estendidos.
Para armazenamento ou uso de solicitações além das cotas padrão, ative os Serviços Estendidos para armazenamentos em memória.
Observabilidade
O Painel de Observabilidade fornece insights e análises para monitorar e solucionar problemas de uso do seu armazenamento em memória. Com gráficos que atualizam em tempo real sobre diferentes aspectos do seu uso de memória e solicitações de API, você pode rastrear o padrão de uso de memória do seu jogo, visualizar as cotas alocadas atuais, monitorar o status da API e identificar problemas potenciais para otimização de desempenho.
A tabela a seguir lista e descreve todos os códigos de status das respostas da API disponíveis nos gráficos de Contagem de Solicitações por Status e Solicitações por API x Status do Painel de Observabilidade. Para mais informações sobre como resolver esses erros, veja Solução de Problemas. Para a cota ou limite específico ao qual um erro se relaciona, veja Limites e Cotizações.
| Código de status | Descrição |
|---|---|
| Success | Sucesso. |
| DataStructureMemoryOverLimit | Excede o limite de tamanho de memória no nível da estrutura de dados (100 MB). |
| DataUpdateConflict | Conflito devido a atualização concorrente. |
| AccessDenied | Não autorizado a acessar os dados do jogo. Esta solicitação não consome unidades de solicitação ou usa cota. |
| InternalError | Erro interno. |
| InvalidRequest | A solicitação não possui as informações necessárias ou possui informações malformadas. |
| DataStructureItemsOverLimit | Excede o limite de contagem de itens no nível da estrutura de dados (1M). |
| NoItemFound | Nenhum item encontrado em MemoryStoreQueue:ReadAsync() ou MemoryStoreSortedMap:UpdateAsync(). ReadAsync() consulta a cada 2 segundos e retorna este código de status até encontrar itens na fila. |
| DataStructureRequestsOverLimit | Excede o limite de unidade de solicitação no nível da estrutura de dados (100.000 unidades de solicitação por minuto). |
| PartitionRequestsOverLimit | Excede um limite de unidade de solicitação por partição ou por chave. |
| TotalRequestsOverLimit | Excede o limite de unidade de solicitação no nível do universo. |
| TotalMemoryOverLimit | Excede a cota de memória no nível do universo. |
| ItemValueSizeTooLarge | O tamanho do valor excede o limite (32 KB). |
A tabela a seguir lista códigos de estado do lado do cliente, que atualmente não estão disponíveis no Painel de Observabilidade.
| Código de status | Descrição |
|---|---|
| InternalError | Erro Interno. |
| UnpublishedPlace | Você deve publicar este lugar para usar o MemoryStoreService. |
| InvalidClientAccess | MemoryStoreService deve ser chamado do servidor. |
| InvalidExpirationTime | O campo 'expiration' deve estar entre 0 e 3.888.000. |
| InvalidRequest | Incapaz de converter valor para json. |
| InvalidRequest | Incapaz de converter sortKey para um número ou string válido. |
| TransformCallbackFailed | Falha ao invocar a função de callback de transformação. |
| RequestThrottled | Solicitações recentes de MemoryStores atingiram um ou mais limites. |
| UpdateConflict | Excedeu o número máximo de tentativas. |
Solução de Problemas
A tabela a seguir lista e descreve a solução recomendada para cada código de status de resposta:
| Erro | Opções de solução de problemas |
|---|---|
| DataStructureRequestsOverLimit / PartitionRequestsOverLimit |
|
| TotalRequestsOverLimit | |
| DataStructureItemsOverLimit |
|
| DataStructureMemoryOverLimit | |
| TotalMemoryOverLimit |
|
| DataUpdateConflict |
Exemplo de Abortando Solicitação |
| Erro Interno |
|
| InvalidRequest |
|
| ItemValueSizeTooLarge |
|
Testar e depurar no Studio
Os dados em MemoryStoreService são isolados entre o Studio e a produção, então alterar os dados no Studio não afeta o comportamento da produção. Isso significa que suas chamadas de API do Studio não acessam dados de produção, permitindo que você teste com segurança os armazenamentos em memória e novos recursos antes de ir para a produção.
Os testes no Studio têm os mesmos limites e cotas que a produção. Para cotas calculadas com base no número de usuários, a cota resultante pode ser muito pequena, uma vez que você é o único usuário para testes no Studio. Ao testar a partir do Studio, você também pode notar latência ligeiramente maior e taxas de erro elevadas em comparação com o uso na produção devido a algumas verificações adicionais que são realizadas para verificar acesso e permissões.
Para informações sobre como depurar um armazenamento em memória em jogos ao vivo ou ao testar no estúdio, use o Console do Desenvolvedor.