Exports Multi Characters

​

Resolva problemas comuns

​

Sobre o sistema

• Abrir o painel de seleção de personagens para qualquer jogador;
• Exibir o passaporte de um jogador para outro jogador;
• Exibir o passaporte de um personagem pelo ID do banco;
• Buscar as informações do passaporte do personagem logado ou de qualquer personagem pelo ID;
• Abrir o painel de renovação de passaporte;
• Iniciar a cutscene de chegada para um jogador;
• Deletar um personagem por ID ou por nome.

​

Funções Exportadas

​

Server-side

• openPanelCharacters -> Abre o painel de seleção de personagens para um jogador
• startCutscenePlayer -> Inicia a cutscene de chegada para um jogador
• showPassport -> Exibe o passaporte do personagem logado para outro jogador
• showPassportFromID -> Exibe o passaporte de qualquer personagem pelo ID
• openPassportRenew -> Abre o painel de renovação de passaporte para um jogador
• getPlayerPassportInfos -> Retorna as informações do passaporte do personagem logado
• getPlayerPassportInfosByID -> Retorna as informações do passaporte de um personagem pelo ID
• deletePerson -> Deleta um personagem por ID ou por nome@sobrenome

​

openPanelCharacters

exports['sqh_multicharacters']:openPanelCharacters(player)

• player (player): jogador que terá o painel de personagens aberto.

• Cria o ped de lobby e muda a dimensão do jogador.
• Busca todos os personagens da conta principal do jogador e os envia para o client.
• Toca a música de lobby e trava os controles do jogador.
• Só abre se o jogador não estiver já no lobby.
• Dispara o evento serverConfig.events.onStartCreationCharacter.

• Sem retorno explícito. O painel é aberto via triggerClientEvent se tiver sucesso.

-- SERVER-SIDE
addCommandHandler('personagens', function(player)
    exports['sqh_multicharacters']:openPanelCharacters(player)
end)

-- SERVER-SIDE (abrir ao logar num sistema próprio)
addEventHandler('onPlayerLogin', root, function(_, account)
    exports['sqh_multicharacters']:openPanelCharacters(source)
end)

​

startCutscenePlayer

exports['sqh_multicharacters']:startCutscenePlayer(player)

• player (player): jogador que irá assistir a cutscene de chegada.

• Só funciona se o jogador estiver com um personagem carregado (playerLoggedInfos).
• Coloca o jogador numa dimensão exclusiva, cria o avião e inicia a sequência de câmera.
• Ao terminar a cutscene, tira a foto do personagem, salva no banco e reposiciona o jogador.
• Dispara serverConfig.events.onFinishCutscene ao fim.

• Sem retorno explícito.

-- SERVER-SIDE
addCommandHandler('cutscene', function(player)
    exports['sqh_multicharacters']:startCutscenePlayer(player)
end)

​

showPassport

exports['sqh_multicharacters']:showPassport(fromPlayer, toPlayer)

• fromPlayer (player): jogador cujo passaporte será exibido (deve ter um personagem logado).
• toPlayer (player): jogador que verá o passaporte na tela.

• Busca os dados do personagem logado de fromPlayer no banco.
• Envia a interface de visualização de passaporte para toPlayer.
• Requer que fromPlayer tenha playerLoggedInfos com personID válido.

• false se fromPlayer ou toPlayer forem inválidos, ou se o personagem não for encontrado.
• Sem retorno explícito em caso de sucesso (abre a interface via triggerClientEvent).

-- SERVER-SIDE
addCommandHandler('verpassaporte', function(player, _, targetName)
    local target = getPlayerFromName(targetName)
    if not target then
        outputChatBox('Jogador não encontrado.', player)
        return
    end
    exports['sqh_multicharacters']:showPassport(target, player)
end)

​

showPassportFromID

exports['sqh_multicharacters']:showPassportFromID(characterID, toPlayer)

• characterID (number): ID do personagem no banco de dados.
• toPlayer (player): jogador que verá o passaporte na tela.

• Busca o personagem pelo ID, independente de ele estar logado ou não.
• Útil para sistemas de administração ou consulta de fichas.

• false se characterID ou toPlayer forem inválidos, ou se o personagem não for encontrado.
• true em caso de sucesso.

-- SERVER-SIDE
addCommandHandler('fichapersonagem', function(player, _, charIDStr)
    local charID = tonumber(charIDStr)
    if not charID then
        outputChatBox('ID inválido.', player)
        return
    end
    local ok = exports['sqh_multicharacters']:showPassportFromID(charID, player)
    outputChatBox(ok and 'Ficha enviada' or 'Personagem não encontrado.', player)
end)

​

openPassportRenew

exports['sqh_multicharacters']:openPassportRenew(player)

• player (player): jogador que terá o painel de renovação aberto.

• Requer que o jogador tenha um personagem logado (playerLoggedInfos).
• Abre a interface de renovação de passaporte, que permite editar nome, sobrenome, gênero, data de nascimento, nacionalidade e naturalidade (conforme config.passport_renews.allowedEditions).
• Cobra o valor definido em config.passport_renews.price do jogador.

• Sem retorno explícito. A interface é aberta via triggerClientEvent em caso de sucesso.

-- SERVER-SIDE (via marker ou NPC)
addEventHandler('onMarkerHit', root, function(hitElement)
    if getElementType(hitElement) == 'player' then
        exports['sqh_multicharacters']:openPassportRenew(hitElement)
    end
end)

​

getPlayerPassportInfos

local infos = exports['sqh_multicharacters']:getPlayerPassportInfos(player)

• player (player): jogador com personagem logado.

• Requer que o jogador tenha um personagem logado.
• Executa uma query coroutine-safe e aguarda o resultado antes de retornar.

• table com os campos do passaporte em sucesso:

{
    emissor       = "HVN",          -- slug do servidor
    number        = 12,             -- player_id do personagem
    city          = "CIDADE...",
    name          = "João",
    surname       = "Silva",
    fullname      = "João Silva",
    gender        = 1,              -- 1 = masculino, 2 = feminino
    birthDate     = "01/01/2000",
    nacionality   = "Brasileiro",
    naturality    = "Brasília",
    expeditionDate  = "04/03/2026",
    expirationDate  = "03/04/2026",
    profilePhoto  = "base64...",    -- nil se não houver foto
    code          = "J O Ã O ..."   -- código do passaporte
}

• false se o personagem não for encontrado ou o jogador não estiver logado.

-- SERVER-SIDE
addCommandHandler('minhaficha', function(player)
    local infos = exports['sqh_multicharacters']:getPlayerPassportInfos(player)
    if infos then
        outputChatBox('Nome: ' .. infos.fullname, player)
        outputChatBox('Nascimento: ' .. infos.birthDate, player)
    else
        outputChatBox('Nenhum personagem logado.', player)
    end
end)

​

getPlayerPassportInfosByID

local infos = exports['sqh_multicharacters']:getPlayerPassportInfosByID(characterID)

• characterID (number): ID do personagem no banco de dados.

• Busca o personagem pelo ID, independente de ele estar logado.
• Útil para sistemas externos que precisam buscar dados de qualquer personagem.
• A busca é feita de forma coroutine-safe (bloqueia até obter resposta).

• table com os mesmos campos de getPlayerPassportInfos em sucesso.
• false se o personagem não for encontrado ou o ID for inválido.

-- SERVER-SIDE
addCommandHandler('fichaporid', function(player, _, charIDStr)
    local charID = tonumber(charIDStr)
    if not charID then return end

    local infos = exports['sqh_multicharacters']:getPlayerPassportInfosByID(charID)
    if infos then
        outputChatBox('Personagem: ' .. infos.fullname .. ' | Nascido em: ' .. infos.birthDate, player)
    else
        outputChatBox('Personagem não encontrado.', player)
    end
end)

​

deletePerson

exports['sqh_multicharacters']:deletePerson(personIDOrAccount)

• personIDOrAccount (number ou string):
  • number: ID do personagem no banco de dados.
  • string: nome e sobrenome no formato "Nome@Sobrenome" (usando o nameSeparator configurado).

• Deleta o personagem da tabela characters e da tabela characters_profile.
• Remove a conta MTA associada ao personagem.
• Caso o personagem esteja logado no momento, o jogador é expulso do servidor.

• true quando a operação é iniciada com sucesso.
• false se personIDOrAccount for nulo ou a licença for inválida.

-- SERVER-SIDE (por ID)
addCommandHandler('deletarporid', function(player, _, idStr)
    local id = tonumber(idStr)
    if not id then return end
    local ok = exports['sqh_multicharacters']:deletePerson(id)
    outputChatBox(ok and 'Deletado.' or 'Falha.', player)
end)

-- SERVER-SIDE (por nome@sobrenome)
addCommandHandler('deletarnome', function(player, _, nameArg)
    -- nameArg esperado: "João@Silva"
    local ok = exports['sqh_multicharacters']:deletePerson(nameArg)
    outputChatBox(ok and 'Personagem deletado.' or 'Falha.', player)
end)

​

Observações

• Todas as exports exigem que o resource já tenha sido liberado pela proteção de licença.
• As funções que operam sobre personagens logados (showPassport, getPlayerPassportInfos, openPassportRenew, startCutscenePlayer) requerem que o jogador tenha passado pela tela de seleção de personagens.
• As funções que recebem characterID funcionam independente do jogador estar online.
• As funções acima seguem o que está exportado no meta.xml do sqh_multicharacters.