Routing buckets em FiveM: SetPlayerRoutingBucket, instâncias e voz

O sintoma: dois grupos de jogadores compartilham a mesma localização e você quer que fiquem separados, ou jogadores em um minigame veem um mundo cheio de carros e pedestres de outras pessoas.

Routing buckets são a versão de FiveM de dimensões ou instâncias. Entidades e jogadores em buckets diferentes não se veem. Eles são a ferramenta por trás de apartamentos, minigames e telas de seleção de personagem, e são gerenciados no servidor. Este artigo cobre cada native e os erros a evitar.

#O que é um routing bucket

Um bucket é um número. Cada jogador e cada entidade pertence a exatamente um bucket, e o padrão é 0. Duas coisas em buckets diferentes são invisíveis uma para a outra: jogadores não veem os jogadores do outro bucket, veículos ou props, e eles não interagem. Eles ainda compartilham o mesmo mapa, então as coordenadas permanecem as mesmas.

Isso funciona apenas em um servidor com OneSync, que os servidores atuais usam. Veja enabling OneSync se você não tem certeza.

#Os natives principais

Todos esses rodam no servidor:

-- put a player in a bucket, and read it back
SetPlayerRoutingBucket(source, 50)
local bucket = GetPlayerRoutingBucket(source)

-- put an entity (vehicle, ped, object) in a bucket
SetEntityRoutingBucket(vehicle, 50)
local entityBucket = GetEntityRoutingBucket(vehicle)

-- back to the default world
SetPlayerRoutingBucket(source, 0)

SetPlayerRoutingBucket pega o id do servidor do jogador e um número de bucket. SetEntityRoutingBucket pega o handle da entidade. Entidades que você cria no servidor após o jogador se mover começam no bucket 0 a menos que você as mova, então defina o bucket logo após criá-las:

local veh = CreateVehicle(`sultan`, 0.0, 0.0, 70.0, 0.0, true, true)
SetEntityRoutingBucket(veh, 50)

Escolha números de bucket com propósito. Um hábito comum é reservar ranges, por exemplo uma range para casas, uma para minigames, para que dois recursos nunca reutilizem um número por acidente.

Atenção: esses natives são apenas do servidor. Chamá-los de um script do cliente não faz nada útil. Envie um evento para o servidor e deixe o servidor mover o jogador, após verificar a solicitação.

#População e lockdown

Cada bucket pode ter suas próprias regras:

-- no ambient pedestrians or traffic in bucket 50
SetRoutingBucketPopulationEnabled(50, false)

-- who may create entities in bucket 50
SetRoutingBucketEntityLockdownMode(50, 'strict')

• SetRoutingBucketPopulationEnabled(bucket, false) desativa NPCs ambiente e tráfego naquele bucket. É útil para instâncias, porque um interior vazio ou um minigame não precisa de carros passando por ele. Bucket 0 mantém sua população normal.
• SetRoutingBucketEntityLockdownMode(bucket, mode) controla criação de entidades. Os modos são 'strict', 'relaxed' e 'inactive', e 'inactive' é o comportamento normal, com 'strict' sendo o mais apertado. Verifique a documentação do native para a diferença exata antes de confiar em um.

Definir as regras de um novo bucket uma vez, quando é usado pela primeira vez, é suficiente. Elas ficam pela vida do servidor.

#Casos de uso

• Apartamentos e casas: um bucket por propriedade, para que interiores idênticos não se sobreponham. O padrão completo está em housing and instances.
• Minigames e eventos: coloque os participantes em um bucket privado com população desligada, para que nada de fora interfira.
• Seleção de personagem e criação: coloque o jogador em um bucket privado enquanto escolhe um personagem, para que não seja visto em pé no mundo, e mova para 0 quando eles spawnarem.
• Tutoriais e espaços de admin: um bucket silencioso para explicar coisas sem o resto do servidor.
• Testes: tente um script longe dos jogadores.

#Voz em buckets

Como jogadores em buckets diferentes não estão perto um do outro do ponto de vista do jogo, a voz de proximidade geralmente segue a mesma separação. Recursos de voz como pma-voice são construídos em torno de OneSync e funcionam por bucket, então jogadores em uma casa não ouvem a rua. Se você quer que pessoas em buckets diferentes falem, use o próprio canal ou recursos de chamada do recurso de voz em vez de lutar contra os buckets. Se a voz está silenciosa após você mover jogadores, veja pma-voice not working. Teste com dois jogadores reais, não apenas com um.

#Um ajudante de instância reutilizável

Mantenha a lógica do bucket em um lugar, para que cada caminho de saída a resete:

local instances = {}   -- [source] = bucket

function EnterInstance(src, bucket)
    instances[src] = bucket
    SetPlayerRoutingBucket(src, bucket)
end

function LeaveInstance(src)
    instances[src] = nil
    SetPlayerRoutingBucket(src, 0)
end

AddEventHandler('playerDropped', function()
    instances[source] = nil
end)

Chame LeaveInstance ao sair, na morte, e quando seu recurso para:

AddEventHandler('onResourceStop', function(resource)
    if resource ~= GetCurrentResourceName() then return end
    for src in pairs(instances) do
        SetPlayerRoutingBucket(src, 0)
    end
end)

Sem esse último manipulador, um reinício de script deixa jogadores sozinhos em um bucket vazio.

#Problemas comuns

• Um jogador está preso sozinho: ele nunca foi movido de volta para 0. Resete em cada caminho de saída e ao parar o recurso.
• Um veículo está faltando para o passageiro: o jogador e o veículo terminaram em buckets diferentes. Mova ambos.
• Entidades criadas aparecem no mundo errado: novas entidades lado do servidor começam no bucket 0.
• Diferentes recursos reutilizam o mesmo número e jogadores caem na instância um do outro: reserve ranges.
• Chamar os natives no cliente: eles pertencem ao servidor.

#Lista de verificação