Skip to content

SPC Integration is a plugin for SA-MP (San Andreas Multiplayer). It sends server information to SPC's storage, which holds data about servers, where it is used in SPC's applications.

License

Notifications You must be signed in to change notification settings

spc-samp/spc-integration

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SPC Integration

Licença Visual Studio 2022 CMake Ubuntu GCC Windows Linux

SPC Integration é um plugin desenvolvido para as plataformas SA-MP (San Andreas Multiplayer) e open.mp (Open Multiplayer), com o objetivo de coletar informações dos servidores. Esses dados são disponibilizados pelo desenvolvedor do respectivo servidor por meio de um arquivo de configuração do plugin. As informações coletadas são então enviadas ao sistema de armazenamento de dados da SPC (SA-MP Programming Community), onde são devidamente registradas e armazenadas. Posteriormente, esses dados são utilizados em diversas aplicações desenvolvidas e mantidas pela SPC.

Idiomas

Índice

Como Utilizar o SPC Integration

O processo descrito abaixo detalha todos os passos necessários para a integração do seu servidor com as aplicações da SPC. Siga as orientações para garantir que a comunicação seja estabelecida de forma correta e segura.

1. Download do Plugin

Para começar, você precisa obter a versão mais recente do plugin compilada para o sistema operacional do seu servidor. Acesse a seção de releases no nosso repositório oficial no GitHub.

  • Para servidores Windows: Baixe o arquivo spc-integration.dll.
  • Para servidores Linux: Baixe o arquivo spc-integration.so.

2. Instalação do Plugin

Após o download, o plugin deve ser colocado na pasta correta para que seu servidor o carregue:

  1. Copie o arquivo do plugin: Mova o arquivo baixado (spc-integration.dll ou spc-integration.so) para a pasta plugins localizada no diretório principal do seu servidor de jogo.
  2. Habilite o carregamento:
    • Para servidores SA-MP: Abra o arquivo server.cfg do seu servidor com um editor de texto. Encontre a linha que começa com plugins e adicione spc-integration a ela. Se não houver, adicione a linha completa:
      plugins spc-integration
      
    • Para servidores open.mp: Abra o arquivo config.json do seu servidor. Dentro da seção pawn, você encontrará uma lista chamada legacy_plugins. Adicione "spc-integration" a esta lista:
      {
          "pawn": {
              "legacy_plugins": [
                  "spc-integration"
              ]
          }
      }

3. Estrutura de Diretórios

O SPC Integration organiza seus arquivos de configuração e logs na pasta spc-integration, localizada na raiz do diretório do servidor.

  • Arquivos principais:
    • config.json: Arquivo de configuração principal.
    • logs.log: Registro de atividades do plugin.
    • Outros arquivos gerados automaticamente, como hash.hash e reserved.recovery.

Note

A pasta spc-integration e o arquivo config.json são fornecidos jutamente com o plugin em releases ou criados automaticamente pelo plugin na primeira execução. Não é necessário criá-los manualmente.

4. Configuração através do config.json

O arquivo config.json é a sua ferramenta principal para controlar o SPC Integration. Este arquivo é formatado em JSON e é dividido em duas seções principais: connection e public_information.

Seção connection: Identidade e Comportamento

Esta seção define os dados técnicos do seu servidor e como o plugin deve se comportar em relação à rede e ao ambiente da SPC.

Parâmetro Tipo Explicação e Uso
ip string O IP público ou hostname do seu servidor. O sistema da SPC utilizará este endereço para verificar a acessibilidade do seu servidor na internet.
Importante: Em modo de produção ("production_environment": true), este valor NÃO PODE SER UM IP LOCAL (127.0.0.1 ou localhost). O plugin irá se desativar se detectar um IP local em produção.
port int A porta de jogo do seu servidor SA-MP/open.mp. Deve ser um número inteiro entre 1 e 65535. O SPC Integration a utiliza para identificar unicamente seu servidor e para a checagem de acessibilidade da SPC.
production_environment bool Define o modo de operação do plugin.
• Se true (padrão e recomendado), o plugin operará em modo de produção, ativando todas as verificações de segurança e se registrará na plataforma SPC.
• Se false, o plugin se desativará automaticamente ao iniciar, pois sua finalidade é servir a servidores em ambientes de produção da SPC.

Note

Após a inicialização bem-sucedida, a chave "connection" é removida do config.json por motivos de segurança e armazenada em cache. Ao desligar o servidor, ela é restaurada ao arquivo.

Seção public_information: Informações Públicas do Servidor

Aqui você especifica todas as informações que serão exibidas publicamente sobre o seu servidor nas aplicações da SPC. Preencher estes campos de forma completa e precisa é essencial para que seu servidor se destaque.

Parâmetro Tipo Obrigatório Explicação e Uso
logo string Sim A URL completa de uma imagem que representará o logo do seu servidor. Esta URL deve apontar para uma imagem válida e publicamente acessível (formatos suportados incluem JPEG, PNG, GIF, BMP, WebP).
banner string Sim A URL completa de uma imagem que servirá como banner para o seu servidor. Semelhante ao logo, a URL deve ser válida, acessível e apontar para um formato de imagem suportado.
website string Sim A URL completa do website oficial ou fórum do seu servidor.
discord string Não A URL de convite para o seu servidor Discord. Se o seu servidor não possui um Discord ou você não deseja exibi-lo, defina o valor como "not-defined".
youtube string Não A URL do canal do seu servidor no YouTube. Use "not-defined" se não for aplicável.
instagram string Não A URL do perfil do seu servidor no Instagram. Use "not-defined" se não for aplicável.
facebook string Não A URL da página oficial do seu servidor no Facebook. Use "not-defined" se não for aplicável.
tiktok string Não A URL do perfil do seu servidor no TikTok. Use "not-defined" se não for aplicável.
team array Não Uma lista (array) de membros da sua equipe. Cada membro é um objeto JSON que pode conter name (nome do membro), function (cargo ou função) e profile_image (URL da imagem de perfil). Se não quiser usar, defina como uma array vazia ([]).
description string Sim Uma breve descrição textual do seu servidor. Este texto aparecerá junto com as informações do seu servidor. Tente ser conciso e cativante.

Caution

Validação de URLs e Conteúdo: O plugin realiza validações rigorosas em todas as URLs fornecidas.

  • Elas devem ser publicamente acessíveis (via http:// ou https://). O plugin tentará se conectar à URL para confirmar sua acessibilidade. URLs bloqueadas por firewall ou que retornam erros (4xx, 5xx) causarão falha.
  • Para campos de imagem (logo, banner, profile_image na seção team), o plugin verificará se o link realmente aponta para um arquivo de imagem (JPEG, PNG, GIF, BMP, WebP).
  • Qualquer URL inválida, inacessível, ou que não corresponda ao tipo de conteúdo esperado resultará em um erro fatal e impedirá o carregamento do plugin.
  • Para os campos marcados como obrigatórios, você deve substituir os valores de exemplo por suas próprias informações. O plugin irá falhar ao carregar se detectar que os valores padrão não foram alterados.
  • Para campos opcionais de redes sociais, é altamente recomendado usar a string "not-defined" se você não tiver a URL ou não quiser exibi-la. Deixar o campo vazio ("") ou com null também o fará ser ignorado, mas "not-defined" é mais claro e evita validações desnecessárias para URLs não existentes.

5. Arquivos Gerados Pelo Plugin (hash.hash e reserved.recovery)

Além do logs.log, o plugin criará e gerenciará outros arquivos importantes dentro da pasta spc-integration/:

  • hash.hash: Este arquivo armazena a identidade secreta e única do seu servidor (um "Server Hash" criptografado). Ele é usado para autenticar todas as comunicações subsequentes com o backend da SPC, garantindo que apenas o seu plugin possa atualizar ou remover os dados do seu servidor.
  • reserved.recovery: Este é um arquivo de "recuperação" temporário. Se o seu servidor travar inesperadamente ou o servidor ser desligado de forma abrupta, este arquivo contém informações para que, na próxima inicialização, o plugin possa limpar o registro "órfão" da sessão anterior na lista de dados da SPC e recuperando a chave connection para o config.json.

Caution

NUNCA modifique ou exclua manualmente os arquivos hash.hash e reserved.recovery enquanto o servidor estiver rodando, ou mesmo se ele desligou e você o está reiniciando.

  • hash.hash: Manipular este arquivo irá corromper a identidade do seu servidor com a SPC, tornando impossível para o plugin atualizá-lo ou removê-lo. Isso pode exigir intervenção manual para limpar dados órfãos.
  • reserved.recovery: Interromper o processo de recuperação (excluindo o arquivo enquanto o plugin o está processando) pode deixar registros órfãos na plataforma da SPC.

O plugin gerencia esses arquivos automaticamente para sua segurança e a integridade dos dados da SPC. Deixe-os como estão.

SPC Integration API

Para complementar a coleta de dados, a SPC (SA-MP Programming Community) fornece uma API pública, de leitura (read-only), projetada para que desenvolvedores possam acessar e integrar a lista de servidores em suas próprias aplicações, como websites, bots para Discord, painéis de monitoramento, ou qualquer outro projeto.

Esta API foi desenvolvida com foco em alto desempenho e simplicidade de uso, garantindo que você sempre tenha acesso a dados frescos sem sobrecarregar o sistema.

Como a API Funciona

A API serve como uma interface segura para o arquivo de dados integration_list.json. Quando uma requisição é recebida, o sistema:

  1. Verifica um cache interno de alta velocidade: Para evitar leituras repetitivas do disco, a API mantém os dados processados em memória. Se o arquivo de dados não foi modificado desde a última leitura, a resposta é servida instantaneamente a partir deste cache.
  2. Garante dados frescos: Se o arquivo foi modificado (por exemplo, um servidor foi adicionado ou atualizado), a API lê o arquivo novamente, atualiza o cache e serve os novos dados.
  3. Filtra dados privados: A API remove automaticamente todas as informações privadas antes de enviar a resposta, garantindo que apenas os dados da seção public sejam expostos.

Graças a esta otimização, você pode requisitar a API com frequência (por exemplo, a cada minuto para atualizar o status do seu site) sem se preocupar em causar sobrecarga. A API é projetada para isso.

Endpoints da API

A API possui dois endpoints principais, ambos utilizando o método GET.

1. Obter a Lista Completa de Servidores

Este endpoint retorna todos os servidores que estão atualmente registrados e ativos na lista de dados da SPC.

  • URL: https://example.com/interface/spc-integration-api.php
  • Método: GET
  • Resposta em Caso de Sucesso (200 OK): Um objeto JSON contendo todos os servidores, onde cada servidor é uma chave IP:Porta com suas respectivas informações públicas.
  • Exemplo de Resposta:
    {
        "success": true,
        "data": {
            "192.0.2.100:7777": {
                "public": {
                    "logo": "https://example.com/logo.png",
                    "banner": "https://example.com/banner.png",
                    "website": "https://myserver.com",
                    // Outros parâmetros (omitidos).
                    "description": "Descrição do meu incrível servidor."
                }
            },
            "203.0.113.50:8888": {
                "public": {
                    "logo": "https://example.com/logo.png",
                    "banner": "https://example.com/banner.png",
                    "website": "https://myserver.com",
                    // Outros parâmetros (omitidos).
                    "description": "Servidor fantástico."
                }
            }
        }
    }

2. Obter Dados de um Servidor Específico

Este endpoint permite que você consulte os dados de um único servidor, utilizando seu IP e porta como parâmetros.

  • URL: https://example.com/interface/spc-integration-api.php?ip=IP_DO_SERVIDOR&port=PORTA_DO_SERVIDOR
  • Método: GET
  • Parâmetros:
    • ip (string, obrigatório): O endereço IP ou domínio do servidor.
    • port (int, obrigatório): A porta do servidor.
  • Resposta em Caso de Sucesso (200 OK): Um objeto JSON contendo os dados do servidor solicitado.
  • Resposta em Caso de Falha (404 Not Found): Se o servidor solicitado não for encontrado na lista.
  • Exemplo de Requisição: https://example.com/interface/spc-integration-api.php?ip=192.0.2.100&port=7777
  • Exemplo de Resposta:
    {
        "success": true,
        "data": {
            "public": {
                "logo": "https://example.com/logo.png",
                "banner": "https://example.com/banner.png",
                "website": "https://myserver.com",
                "discord": "https://discord.gg/invite",
                // Outros parâmetros (omitidos).
                "team": [
                    {
                        "name": "Nome do Membro",
                        "function": "Cargo",
                        "profile_image": "https://example.com/photo.jpg"
                    }
                ],
                "description": "Descrição do meu incrível servidor."
            }
        }
    }

Exemplos de Uso

A seguir, exemplos práticos de como consumir a API em diferentes linguagens.

JavaScript (utilizando fetch no navegador)

Ideal para exibir a lista de servidores em seu website.

// URL da API
const API_URL = 'https://example.com/interface/spc-integration-api.php';

fetch(API_URL)
    // Converte a resposta para JSON
    .then(response => {
        if (!response.ok)
            throw new Error(`Erro na API: ${response.statusText}`);

        return response.json();
    })
    // Processa os dados recebidos
    .then(api_data => {
        if (api_data.success) {
            // O 'api_data.data' contém o objeto com todos os servidores
            const servers = api_data.data;
            console.log('Servidores encontrados:', servers);

            // Exemplo de como iterar e exibir os dados no console
            for (const serverKey in servers) {
                const serverInfo = servers[serverKey].public;
                console.log(`Website do servidor ${serverKey}:`, serverInfo.website);
            }
        }
        else
            console.error('A API retornou um erro:', api_data.error.message);
    })
    .catch(error => {
        // Captura erros de rede ou falhas na requisição
        console.error('Falha ao buscar dados da API:', error);
    });

PHP (utilizando file_get_contents no backend)

Útil para processar os dados do lado do servidor antes de exibi-los.

<?php
// URL da API
$API_URL = 'https://example.com/interface/spc-integration-api.php';

// Executa a requisição e obtém o conteúdo. O '@' suprime warnings em caso de falha.
$response_json = @file_get_contents($API_URL);

if ($response_json === false)
    die('Erro: Não foi possível conectar à API do SPC Integration.');

// Decodifica a resposta JSON para um array associativo
$response_data = json_decode($response_json, true);

if (!$response_data || !isset($response_data['success']))
    die('Erro: A resposta da API é inválida ou mal formatada.');

if ($response_data['success']) {
    $servers = $response_data['data'];
    echo "<h1>Lista de Servidores da SPC</h1>";
    echo "<ul>";

    foreach ($servers as $server_key => $server_data) {
        $public_info = $server_data['public'];
        echo "<li>";
        echo "<strong>{$server_key}</strong> - ";
        echo "<a href='" . htmlspecialchars($public_info['website']) . "' target='_blank'>Visitar Website</a>";
        echo "</li>";
    }

    echo "</ul>";
}
else {
    $error_message = $response_data['error']['message'] ?? 'Erro desconhecido.';
    echo "A API retornou um erro: " . htmlspecialchars($error_message);
}
?>

Important

Disponibilidade da API

Por favor, note que, no momento, os endpoints públicos da SPC Integration API ainda não estão ativos e acessíveis através de um endereço público.

As URLs fornecidas nesta documentação (https://example.com/...) são ilustrativas e servem como exemplos para o futuro. Um anúncio oficial será feito pela equipe SPC assim que a API estiver totalmente operacional e disponível para uso público.

Compilação

As instruções a seguir são destinadas a desenvolvedores que desejam compilar o plugin a partir do código-fonte.

Compilação para Windows

A compilação em ambiente Windows utiliza o Visual Studio 2022.

Requisitos

  • Visual Studio 2022 com a carga de trabalho "Desktop development with C++" instalada.

Passos para Compilação

  1. Abra a Solução: Navegue até spc-integration/src/ e abra o arquivo spc-integration.sln.
  2. Selecione a Configuração: Na barra de ferramentas, defina a configuração de compilação para Release e a plataforma para Win32.
  3. Compile: Use o menu Compilation > Build Solution ou o atalho Ctrl + Shift + B.
  4. Localize o Artefato: O arquivo compilado, spc-integration.dll, estará disponível no diretório spc-integration/src/compiled/.

Compilação para Linux

A compilação em Linux utiliza Docker para criar um ambiente de build consistente e isolado.

Requisitos

  • Uma instalação funcional do Docker.

Passos para Compilação

  1. Acesse o Diretório Docker: Em um terminal, navegue até a pasta spc-integration/src/docker/.

    cd spc-integration/src/docker
  2. Execute o Script de Build: O script build.sh automatiza todo o processo.

    ./build.sh

    O script irá:

    • Construir uma imagem Docker customizada com Ubuntu 18.04, GCC 9 e OpenSSL estaticament compilado.
    • Iniciar um contêiner a partir desta imagem.
    • Compilar o código-fonte dentro do contêiner.
    • Copiar o binário final (spc-integration.so) para o diretório spc-integration/src/compiled-linux/ em sua máquina.
  3. Localize o Artefato: O arquivo spc-integration.so estará disponível em spc-integration/src/compiled-linux/.

Informações Importantes

As informações a seguir são essenciais para quem deseja compilar, testar, contribuir com o código-fonte ou implementar a infraestrutura backend do SPC Integration.

Gerenciamento de Segredos e Sincronização de Chaves

A segurança do sistema é garantida pelo gerenciamento cuidadoso de chaves sensíveis, tanto no plugin (cliente) quanto no script de backend (servidor). Os valores definidos no arquivo src/secret_manager.hpp do plugin são ofuscados em tempo de compilação usando a biblioteca Dralyxor.

É crucial entender a finalidade de cada chave e quais delas precisam estar sincronizadas entre o cliente e o servidor. Os valores no código-fonte público são placeholders (valores de exemplo) e não são funcionais.

Detalhamento das Chaves (src/secret_manager.hpp)

  • Get_Obfuscated_API_KEY():
    • Finalidade: Define a chave de API (Bearer Token) usada para autorizar as requisições do plugin no backend. O backend irá validar esta chave em cada chamada.
    • Sincronização: OBRIGATÓRIA. O valor desta chave no plugin deve ser exatamente o mesmo que o valor da constante API_KEY no arquivo config.php do backend.
  • Get_Obfuscated_Backend_Host():
    • Finalidade: Define o domínio (ex: api.exemplo.com) do servidor de backend para onde o plugin enviará as requisições.
    • Sincronização: Não é uma chave secreta, mas aponta para a infraestrutura do seu backend. Deve corresponder ao host onde seu script PHP está sendo executado.
  • Get_Obfuscated_Backend_Path():
    • Finalidade: Define o caminho do endpoint principal no backend (ex: /php/spc-integration.php) que lida com as ações create, update, delete, etc.
    • Sincronização: Deve corresponder ao caminho exato do seu script no servidor web.
  • Get_Obfuscated_Backend_API_Path():
    • Finalidade: Define o caminho para um endpoint secundário usado para verificações de ambiente (environment check), confirmando se um IP:Porta está acessível publicamente.
    • Sincronização: Deve corresponder ao caminho exato do script de verificação no seu servidor web.
  • Get_Obfuscated_Hash_KEY():
    • Finalidade: Define a chave usada localmente pelo plugin para criptografar o conteúdo do arquivo hash.hash. Este arquivo armazena a identidade única do servidor.
    • Sincronização: NÃO é obrigatório que esta chave seja a mesma que a HASH_XOR_KEY no config.php do backend, pois elas servem a propósitos independentes em seus respectivos ambientes. Elas podem ser diferentes.

Compilando para Uso Próprio ou Testes

Se você está compilando o plugin e/ou configurando o backend para um ambiente próprio:

  1. Edite o secret_manager.hpp: Substitua os valores de exemplo dentro das chamadas DRALYXOR_KEY para corresponderem à sua infraestrutura e segredos.
    // Exemplo de configuração no plugin
    inline auto& Get_Obfuscated_API_KEY() {
        static auto& api_key_obfuscated = DRALYXOR_KEY("MINHA-API-KEY-SUPER-SECRETA", "UMA_CHAVE_PARA_OFUSCAR");
        
        return api_key_obfuscated;
    }
    
    inline auto& Get_Obfuscated_Backend_Host() {
        static auto& host_obfuscated = DRALYXOR_KEY("meu-backend.com", "OUTRA_CHAVE_DE_OFUSCACAO");
        
        return host_obfuscated;
    }
  2. Edite o config.php do Backend: Configure as constantes no seu script PHP para que correspondam, onde necessário.
    // Exemplo de configuração no backend
    final class Config {
        // ...
        // Este valor DEVE ser o mesmo que em Get_Obfuscated_API_KEY()
        public const API_KEY = 'MINHA-API-KEY-SUPER-SECRETA';
    
        // Este valor pode ser diferente do Get_Obfuscated_Hash_KEY() do plugin
        public const HASH_XOR_KEY = 'CHAVE_OFUSCAR_HASH_RECEBIDO_DO_PLUGIN';
        // ...
    }

Important

Apenas compilações oficiais, liberadas pela equipe da SPC, contêm as chaves e endpoints corretos para se conectar à plataforma oficial. Compilar o código-fonte público diretamente do GitHub não permitirá a integração com o sistema da SPC, pois os segredos no repositório são meramente ilustrativos.

Licença

Copyright © SA-MP Programming Community

Este software é licenciado sob os termos da Licença Apache, Versão 2.0 ("Licença"); você não pode utilizar este software exceto em conformidade com a Licença. Uma cópia da Licença pode ser obtida em: Apache License 2.0

Termos e Condições de Uso

1. Permissões Concedidas

A presente licença concede, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e arquivos de documentação associados, os seguintes direitos:

  • Utilizar, copiar, modificar e distribuir o software em qualquer meio ou formato, para qualquer finalidade, comercial ou não-comercial
  • Mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do software
  • Permitir que pessoas para as quais o software é fornecido façam o mesmo

2. Condições Obrigatórias

Todas as distribuições do software ou trabalhos derivados devem:

  • Incluir uma cópia completa desta licença
  • Indicar claramente quaisquer modificações realizadas no código-fonte original
  • Preservar todos os avisos de direitos autorais, patentes, marcas registradas e atribuições
  • Fornecer documentação adequada das alterações implementadas
  • Manter o aviso de licença e garantia em todas as cópias

3. Restrições e Limitações

  • Esta licença não concede permissão para uso de marcas registradas, logotipos ou nomes comerciais da SA-MP Programming Community
  • As contribuições para o código-fonte devem ser licenciadas sob os mesmos termos desta licença
  • O uso de nomes dos contribuidores para endossar ou promover produtos derivados deste software requer permissão prévia específica

4. Propriedade Intelectual

O software e toda a documentação associada são protegidos por leis de direitos autorais e tratados internacionais. A SA-MP Programming Community retém todos os direitos, títulos e interesses não expressamente concedidos por esta licença.

5. Isenção de Garantias e Limitação de Responsabilidade

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIAS DE QUALQUER NATUREZA, EXPRESSAS OU IMPLÍCITAS, INCLUINDO, MAS NÃO SE LIMITANDO A, GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM PROPÓSITO ESPECÍFICO E NÃO VIOLAÇÃO.

EM NENHUMA CIRCUNSTÂNCIA OS AUTORES OU TITULARES DOS DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUAISQUER REIVINDICAÇÕES, DANOS OU OUTRAS RESPONSABILIDADES, SEJA EM AÇÃO DE CONTRATO, DELITO OU DE OUTRA FORMA, DECORRENTES DE, OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.


Para informações detalhadas sobre a Licença Apache 2.0, consulte: http://www.apache.org/licenses/LICENSE-2.0

About

SPC Integration is a plugin for SA-MP (San Andreas Multiplayer). It sends server information to SPC's storage, which holds data about servers, where it is used in SPC's applications.

Topics

Resources

License

Stars

Watchers

Forks