O restante da documentação descreve a integração de forma genérica: quem assina, quem transporta, quem entrega. Esta seção mostra tudo isso funcionando de verdade num servidor de jogo real. O case OpenTibia é a implementação de referência da Lootfy — não um exemplo hipotético, mas código que anuncia itens, cria transações, cobra Pix e entrega o item dentro de um servidor OpenTibia (família TFS 0.3) rodando um client 8.54.
Se você mantém um servidor OpenTibia e quer integrar, esta é a sua trilha mais curta: aqui está o que já foi escrito, testado ponta a ponta e validado com pagamento real. Se você usa outra engine, leia como referência de forma — o desenho vale para qualquer servidor; o que muda são os detalhes de como o seu engine assina e entrega.
A bancada OpenTibia produz dois entregáveis, e apenas dois. Eles são o que um parceiro real pega e adapta; o resto da lógica não mora aqui.
1. Módulo de client de referência
O game_lootfy — um módulo Lua do client OTClient que enxerta as janelas de venda e compra do market do jogo, adicionando o checkbox “Anunciar na Lootfy”, o botão “Comprar na Lootfy” e o fluxo de vínculo. Instala soltando uma pasta em modules/, sem recompilar o client.
2. Patch de entrega na engine
O primitivo doLootfyDeliver — quatro arquivos-fonte C++ aplicados na árvore do TFS 0.3 que dão à engine a capacidade de entregar um item de market ao comprador, online ou offline, sem mover dinheiro do jogo. Exige recompilar a engine.
O primeiro roda na máquina do jogador; o segundo, no servidor. Juntos, eles cobrem as duas pontas que o OpenTibia não tinha: uma UI para o jogador anunciar/comprar e um primitivo de entrega durável.
Este é o ponto que mais confunde quem lê o código pela primeira vez, então vale fixá-lo antes de qualquer coisa: a lógica que recebe o pedido do jogo, checa elegibilidade, assina o envelope e chama a Lootfy NÃO está na bancada. Ela é do Agent e do Lua de servidor que o acompanha.
O caminho completo, em uma frase: o jogador clica no jogo → o client manda um opcode ao servidor → o servidor enfileira num spool → o Agent assina e chama a Lootfy → a plataforma responde. A engine C++ só entra no fim, quando o pagamento confirma e a Lootfy manda entregar. A próxima página desenha esse caminho inteiro.
A família TFS só tem md5 e sha1 em Lua — não tem RSA nem cliente HTTP com header customizado. A plataforma exige assinatura JWS RS256 em toda chamada de contrato. Logo, o servidor OpenTibia não consegue assinar sozinho: ele delega ao Agent, um sidecar Node que roda na mesma host e existe justamente para ser “a caneta”. O Agent assina e transporta; nunca decide regra de negócio nem toca o banco do parceiro.
Há um segundo motivo, específico do OpenTibia antigo: o client 8.54 não consegue setar header HTTP customizado. Como a assinatura viaja no header X-Lootfy-Signature, o client jamais poderia carregar o envelope assinado sozinho. Por isso o desenho usa o “ramo B” do contrato: o servidor assina e envia, e o client só pede e mostra o resultado. A página de arquitetura detalha esse ramo.
Vale ser explícito sobre os limites, para você não esperar o que não está lá:
