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.
- Deutsch: README
- English: README
- Español: README
- Français: README
- Italiano: README
- Polski: README
- Русский: README
- Svenska: README
- Türkçe: README
- 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.
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
.
Após o download, o plugin deve ser colocado na pasta correta para que seu servidor o carregue:
- Copie o arquivo do plugin: Mova o arquivo baixado (
spc-integration.dll
ouspc-integration.so
) para a pastaplugins
localizada no diretório principal do seu servidor de jogo. - 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 complugins
e adicionespc-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çãopawn
, você encontrará uma lista chamadalegacy_plugins
. Adicione"spc-integration"
a esta lista:{ "pawn": { "legacy_plugins": [ "spc-integration" ] } }
- Para servidores SA-MP: Abra o arquivo
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
ereserved.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.
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
.
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.
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://
ouhttps://
). 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çãoteam
), 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 comnull
também o fará ser ignorado, mas"not-defined"
é mais claro e evita validações desnecessárias para URLs não existentes.
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 chaveconnection
para oconfig.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.
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.
A API serve como uma interface segura para o arquivo de dados integration_list.json
. Quando uma requisição é recebida, o sistema:
- 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.
- 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.
- 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.
A API possui dois endpoints principais, ambos utilizando o método GET
.
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 chaveIP: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." } } } }
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." } } }
A seguir, exemplos práticos de como consumir a API em diferentes linguagens.
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);
});
Ú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.
As instruções a seguir são destinadas a desenvolvedores que desejam compilar o plugin a partir do código-fonte.
A compilação em ambiente Windows utiliza o Visual Studio 2022.
- Visual Studio 2022 com a carga de trabalho "Desktop development with C++" instalada.
- Abra a Solução: Navegue até
spc-integration/src/
e abra o arquivospc-integration.sln
. - Selecione a Configuração: Na barra de ferramentas, defina a configuração de compilação para
Release
e a plataforma paraWin32
. - Compile: Use o menu
Compilation > Build Solution
ou o atalhoCtrl + Shift + B
. - Localize o Artefato: O arquivo compilado,
spc-integration.dll
, estará disponível no diretóriospc-integration/src/compiled/
.
A compilação em Linux utiliza Docker para criar um ambiente de build consistente e isolado.
- Uma instalação funcional do Docker.
-
Acesse o Diretório Docker: Em um terminal, navegue até a pasta
spc-integration/src/docker/
.cd spc-integration/src/docker
-
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
eOpenSSL
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óriospc-integration/src/compiled-linux/
em sua máquina.
- Construir uma imagem Docker customizada com
-
Localize o Artefato: O arquivo
spc-integration.so
estará disponível emspc-integration/src/compiled-linux/
.
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.
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.
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 arquivoconfig.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.
- Finalidade: Define o domínio (ex:
Get_Obfuscated_Backend_Path()
:- Finalidade: Define o caminho do endpoint principal no backend (ex:
/php/spc-integration.php
) que lida com as açõescreate
,update
,delete
, etc. - Sincronização: Deve corresponder ao caminho exato do seu script no servidor web.
- Finalidade: Define o caminho do endpoint principal no backend (ex:
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.
- Finalidade: Define o caminho para um endpoint secundário usado para verificações de ambiente (
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
noconfig.php
do backend, pois elas servem a propósitos independentes em seus respectivos ambientes. Elas podem ser diferentes.
- Finalidade: Define a chave usada localmente pelo plugin para criptografar o conteúdo do arquivo
Se você está compilando o plugin e/ou configurando o backend para um ambiente próprio:
- Edite o
secret_manager.hpp
: Substitua os valores de exemplo dentro das chamadasDRALYXOR_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; }
- 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.
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
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
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
- 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
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.
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