Início › Documentação › Hooks · origen_ilegalv2

Hooks · origen_ilegalv2

O runner expõe um conjunto de hooks que te permitem injetar lógica própria no ciclo de vida do laboratório sem modificar os ficheiros do núcleo. Todos os hooks são opcionais: passa-os como terceiro argumento de LabProcessRunner.Register() no cliente, ou usa as funções independentes do servidor descritas mais abaixo.

Hooks do cliente

Os hooks passam-se como uma tabela ao registar o laboratório:

LabProcessRunner.Register('heroin', Config.LabHeroin, {
    onEnter         = function(labType) ... end,
    onExit          = function(labType) ... end,
    onReset         = function() ... end,
    onStageComplete = function(stageId, result) ... end,
})

onEnter(labType)

É chamado imediatamente depois de o runner criar todos os pontos de interação, sempre que um jogador entra num laboratório deste tipo.

Casos de uso:

• Carregar props / IPL personalizados específicos do laboratório
• Consultar o servidor sobre um estado prévio (p. ex. que plantas já tinham sido colhidas)
• Iniciar uma thread própria que corra enquanto o jogador está dentro

onEnter = function(labType)
    -- Ask the server which plants are already taken
    local takenPlants = lib.callback.await('origen_gang:labs:weed:getTakenPlants', false)
    for _, idx in ipairs(takenPlants or {}) do
        RemovePlantProp(idx)  -- your custom function
    end
end,

onExit(labType)

É chamado depois de o runner remover todos os pontos de interação e reiniciar o estado de produção, sempre que um jogador sai de um laboratório deste tipo.

Casos de uso:

• Eliminar os props personalizados gerados em onEnter
• Cancelar threads próprias
• Limpar o estado do cliente

onExit = function(labType)
    DeleteCustomProps()
    StopMyThread()
end,

onReset()

O runner chama-o sempre que o ciclo de produção é reiniciado à força: ao sair, ao descarregar o jogador (origen:Client:OnPlayerUnload) e ao parar o recurso.

Casos de uso:

• Desanexar props presos ao ped durante uma fase (p. ex. o prop do tabuleiro do laboratório de meta, preso à mão durante grab_tray)
• Limpar qualquer sobreposição do HUD ligada a um ciclo de produção

onReset = function()
    if trayPropEntity and DoesEntityExist(trayPropEntity) then
        DetachEntity(trayPropEntity, true, true)
        DeleteEntity(trayPropEntity)
        trayPropEntity = nil
    end
end,

onStageComplete(stageId, result)

É chamado depois de o runner terminar de processar uma fase (barra de progresso concluída, callback do servidor com sucesso, items entregues). Executa-se em todas as fases, incluindo a última.

Campos de result (o que o servidor devolveu):

Casos de uso:

• Prender / soltar props em sincronia com as transições de fase
• Disparar um som ou um efeito de partículas personalizado ao concluir uma fase
• Mostrar um elemento de HUD personalizado consoante as fases restantes

onStageComplete = function(stageId, result)
    if stageId == 'grab_tray' then
        -- Attach the tray prop to the player's hand
        AttachTrayToHand()
    elseif stageId == 'smash' then
        -- Detach and delete the tray
        DetachTrayFromHand()
    end
end,

Eventos do ciclo de vida (cliente)

O runner escuta automaticamente estes eventos ao nível do recurso para cada laboratório registado. Também os podes escutar a partir dos teus próprios ficheiros de laboratório para acrescentar lógica personalizada:

-- Example: custom logic on any weed lab entry
AddEventHandler('origen:Lab:OnEnter', function(labType)
    if labType ~= 'weed' then return end
    print('Player entered a weed lab!')
end)

Ciclo de vida no servidor

O servidor não tem um parâmetro de tabela de hooks; em vez disso expõe funções e exports que podes chamar a partir de outros scripts:

LabProcessRunner.ResetPlayerState(labType, source)

Reinicia à força o estado de produção de um único jogador para um tipo de laboratório concreto. Usa-o quando um script interrompe a produção a partir de fora (p. ex. a expulsão por uma rusga).

-- From another resource via export
exports['origen_ilegalv2']:MethLabResetPlayerState(source)
 
-- From inside origen_ilegalv2
LabProcessRunner.ResetPlayerState('meth', source)

LabProcessRunner.ResetAllForSource(source)

Limpa o estado de produção de um jogador em todos os tipos de laboratório registados. É chamado automaticamente ao sair e em playerDropped; usa-o se expulsares um jogador por código.

LabProcessRunner.ResetAllForSource(source)

LabProcessRunner.GetPlayerState(labType, source) → table | nil

Devolve o estado de produção atual em memória de um jogador para um tipo de laboratório concreto:

local state = LabProcessRunner.GetPlayerState('meth', source)
-- state = { stage, lab_id, timers, modifiers, last_done }
-- nil if not in production

exports('GetPlayerLabState', ...) → table | nil

Devolve em que laboratório está atualmente um jogador (definido pelos callbacks de entrada/saída em server/labs.lua):

local labState = exports['origen_ilegalv2']:GetPlayerLabState(source)
-- { lab_id, lab_type, bucket, world_exit }
-- nil if the player is not inside any lab

É o que todos os ficheiros de servidor dos laboratórios usam para validar que «o jogador está mesmo no laboratório certo».

Exports de reinício por laboratório

Cada laboratório integrado regista o seu próprio export de reinício com nome, por compatibilidade externa:

Os laboratórios personalizados que adicionares devem seguir o mesmo padrão:

exports('HeroinLabResetPlayerState', function(source)
    LabProcessRunner.ResetPlayerState('heroin', source)
end)

Exemplo completo de hooks — prop do tabuleiro de meta

O laboratório de meta usa onStageComplete e onReset para prender um prop físico de tabuleiro à mão do jogador entre as fases grab_tray e smash:

local trayProp = nil
 
local function attachTray(ped)
    local hash = GetHashKey('bkr_prop_meth_tray_02a')
    RequestModel(hash)
    while not HasModelLoaded(hash) do Wait(50) end
    trayProp = CreateObject(hash, 0, 0, 0, true, true, true)
    AttachEntityToEntity(trayProp, ped, GetPedBoneIndex(ped, 28422),
        0.01, -0.2, -0.2, 20.0, 0.0, 0.0, true, true, false, true, 1, true)
    SetModelAsNoLongerNeeded(hash)
end
 
local function detachTray()
    if trayProp and DoesEntityExist(trayProp) then
        DetachEntity(trayProp, true, true)
        DeleteEntity(trayProp)
        trayProp = nil
    end
end
 
LabProcessRunner.Register('meth', Config.LabMeth, {
    onStageComplete = function(stageId, result)
        if stageId == 'grab_tray' then
            attachTray(PlayerPedId())
        elseif stageId == 'smash' then
            detachTray()
        end
    end,
    onReset = function()
        detachTray()
    end,
})