Integrações

cxg-tattoos pode se conectar a diferentes frameworks para cobrar compras e verificar permissões administrativas. A integração de aparência reaplica as tatuagens salvas quando o personagem carrega ou troca de skin. Cada parte é configurada separadamente.

Consulte também Introdução, Instalação, Configuração, Catálogo e Interface.

Frameworks disponíveis

Com auto, o recurso detecta Qbox, QBCore ou ESX se estiverem iniciados; se nenhum for encontrado, usa standalone. Você pode definir o framework quando o servidor tiver vários ativos ou usar um nome de recurso diferente:

Config.Purchases.framework = 'qbx' -- auto | qbx | qbcore | esx | standalone
Config.Purchases.resources.qbx = 'qbx_core'
Config.Purchases.accounts = { 'cash', 'bank' }
Config.Purchases.esxAccountMap.cash = 'money'
Config.Purchases.esxAccountMap.bank = 'bank'
Config.Purchases.allowFreePurchases = false

As contas são verificadas na ordem indicada. A cobrança é feita em uma única conta; se o saldo não for suficiente, a seguinte será tentada. No ESX, esxAccountMap traduz cash para o nome de conta money.

Config.Purchases.reason e refundReason identificam o motivo das transações nos providers compatíveis. Os valores iniciais são tattoo-purchase e tattoo-purchase-refund. allowFreePurchases permite dispensar a cobrança no adaptador standalone; isso não torna gratuitas as compras em outros frameworks.

Pagamentos sem framework

No modo standalone, conecte tryCharge e refund ao recurso de economia do servidor. Os dois callbacks são necessários para aceitar compras: o reembolso devolve a cobrança se o salvamento da tatuagem falhar.

Config.Purchases.framework = 'standalone'
Config.Purchases.standalone.tryCharge = function(source, totalAmount, context)
    -- Sustituye esta llamada por la API de economía de tu servidor.
    local charged, receipt = MyEconomy.charge(source, totalAmount, context)
    if charged then
        return true, receipt
    end
    return false, 'No tienes saldo suficiente.'
end

Config.Purchases.standalone.refund = function(source, totalAmount, context, receiptData)
    -- Usa receiptData para devolver el mismo cobro aprobado.
    return MyEconomy.refund(source, totalAmount, receiptData) == true
end

MyEconomy representa a API do seu servidor; substitua-a pelo nome e pelas chamadas reais. Para permitir compras sem custo intencionalmente, defina allowFreePurchases = true.

Os adaptadores de pagamento expõem isAvailable(settings), charge(source, amount, context, settings) e refund(source, amount, context, settings). Um pagamento aprovado deve manter o recibo em context.paymentReceipt; cxg-tattoos o usa para enviar qualquer reembolso ao mesmo sistema. Para uma economia própria, os callbacks standalone tryCharge e refund são a forma direta de configuração.

Permissões administrativas

As permissões são verificadas no servidor para abrir e operar o painel administrativo. Ocultar ou alterar a interface do cliente não concede acesso.

A configuração inicial usa o framework detectado e ACE como fallback:

Config.Permissions = {
    framework = 'auto', -- auto | qbx | qbcore | esx | standalone
    mode = 'hybrid',    -- framework | ace | hybrid | custom
    acePrefix = 'cxg-tattoos.',
    resources = {
        qbx = 'qbx_core',
        qbcore = 'qb-core',
        esx = 'es_extended',
    },
    bindings = {
        admin = {
            ace = { 'cxg-tattoos.admin', 'group.admin', 'admin' },
            qbx = { 'god', 'admin', 'group.admin' },
            qbcore = { 'god', 'admin', 'group.admin' },
            esx = { 'superadmin', 'admin' },
        },
    },
}

O modo framework consulta os cargos do framework. ace usa as entradas ACE do binding. hybrid aceita qualquer um dos dois caminhos. Em standalone, a autorização do framework não está disponível; configure ACE ou uma verificação própria.

Por exemplo, para permitir membros do principal ACE group.admin:

add_ace group.admin cxg-tattoos.admin allow

Para delegar uma decisão ao seu próprio sistema, use mode = 'custom'. O callback recebe o ID do jogador, a permissão, o contexto da operação e o binding configurado; somente o booleano true autoriza:

Config.Permissions.mode = 'custom'
Config.Permissions.custom = {
    hasPermission = function(source, permission, context, binding)
        return exports.my_permissions:hasPermission(source, permission) == true
    end,
}

Adapte my_permissions à API instalada no servidor. Se o callback não existir, falhar ou retornar outro valor, o acesso será negado.

O comando que abre o painel também é configurável. permission deve corresponder a uma chave de Config.Permissions.bindings:

Config.AdminCommand.enabled = true
Config.AdminCommand.name = 'tattooadmin'
Config.AdminCommand.permission = 'admin'

Com esses valores, a permissão admin protege o comando /tattooadmin e as ações administrativas. Defina enabled = false para desativar o comando; a permissão continua sendo verificada nos outros caminhos administrativos.

Arquivos de integração editáveis

Os bridges editáveis agrupam conexões com sistemas externos. Para uma permissão ou pagamento personalizado, prefira configurar os callbacks explicados acima. Ao adaptar um bridge existente, preserve seu contrato:

O callback de permissão também recebe context como quinto argumento quando chamado pelo bridge. O registro contém os providers incluídos (qbx, qbcore, esx, standalone); opções personalizadas não exigem adicionar outro provider.

Em um adaptador de pagamentos, preserve o registro do recibo com TattooPaymentBridge.setReceipt(context, provider, account, amount, identifier, data). O reembolso deve verificar o mesmo provider e valor com getReceipt(context, provider, amount) e marcar o recibo como reembolsado após a confirmação. Adapte o arquivo do provider que você já usa; para uma integração própria sem alterar adaptadores, use os callbacks standalone.

Aparência e carregamento do personagem

O recurso escuta eventos comuns de illenium-appearance, fivem-appearance, QBCore, ESX e spawnmanager; em seguida, recupera e reaplica as tatuagens salvas. No Qbox, a configuração de prévia multicharacter usa playerskins.skin para exibir as tatuagens salvas na seleção de personagem.

Se o sistema de aparência usar outro evento, solicite a aplicação depois que o carregamento da skin terminar:

TriggerServerEvent('cxg-tattoos:fetchMyTattoos')

O evento retorna ao cliente as tatuagens do personagem atual. Não envie a lista a partir de uma fonte escolhida pelo jogador: a propriedade é resolvida e validada no servidor.

A prévia multicharacter do Qbox é ajustada com estes campos:

Config.QbxMulticharacterPreview.enabled = true
Config.QbxMulticharacterPreview.resource = 'qbx_core'
Config.QbxMulticharacterPreview.playerskinsTable = 'playerskins'
Config.QbxMulticharacterPreview.playersTable = 'players'
Config.QbxMulticharacterPreview.syncExistingOnStart = true

enabled ativa a integração; resource indica o nome instalado do Qbox. playerskinsTable e playersTable identificam as tabelas de aparência e personagens usadas pela instalação. syncExistingOnStart sincroniza tatuagens salvas ao iniciar cxg-tattoos, para que também apareçam na seleção multicharacter. Se o servidor renomeou as tabelas, atualize esses dois campos. Não é necessário modificar qbx_core.