samp-sdk

O SA-MP (San Andreas Multiplayer) Software Development Kit (SDK) é uma coleção abrangente de arquivos C, headers e itens que permitem aos desenvolvedores criar plugins para o servidor SA-MP. Este SDK fornece uma base para estender a funcionalidade do servidor SA-MP através de funções nativas, permitindo que os desenvolvedores implementem recursos além do que está disponível no script Pawn.

Idiomas

Deutsch: README
English: README
Español: README
Français: README
Italiano: README
Polski: README
Русский: README
Svenska: README
Türkçe: README

Índice

samp-sdk

Componentes Principais

Sistema AMX

O AMX (Abstract Machine eXecutor) é a máquina virtual que executa scripts Pawn no SA-MP. O SDK fornece suporte extensivo para interação com AMX através de vários arquivos C e headers:

Headers AMX Principais

amx.h

O header principal que consolida todas as funcionalidades relacionadas ao AMX. Inclui:
- Funções principais do AMX para execução de script
- Gerenciamento de memória
- Registro de funções nativas
- Manipulação de strings
- Suporte a UTF-8
Funções principais incluem:
```
int AMXAPI amx_Init(AMX* amx, void* program);
int AMXAPI amx_Exec(AMX* amx, cell* retval, int index);
int AMXAPI amx_Register(AMX* amx, const AMX_NATIVE_INFO* nativelist, int number);
```

amx_cell.h

Define os tipos de dados fundamentais usados no sistema AMX:

#if PAWN_CELL_SIZE==32
    typedef uint32_t  ucell;
    typedef int32_t   cell;
#elif PAWN_CELL_SIZE==64
    typedef uint64_t  ucell;
    typedef int64_t   cell;
#endif

amx_structures.h

Contém estruturas essenciais para operação do AMX:

typedef struct tagAMX {
    unsigned char _FAR *base;    // Endereço base
    unsigned char _FAR *data;    // Segmento de dados
    AMX_CALLBACK callback;       // Função de callback
    AMX_DEBUG debug;            // Callback de debug
    cell cip;                   // Ponteiro de instrução de código
    cell frm;                   // Base do frame da pilha
    cell hea;                   // Base do heap
    cell stk;                   // Ponteiro da pilha
    // ... campos adicionais
} AMX;

Suporte a Plataformas

O SDK inclui tratamento robusto específico para plataformas através de vários headers:

amx_platform.h

Fornece detecção e configuração de plataforma:

#if (defined __linux || defined __linux__) && !defined __LINUX__
    #define __LINUX__
#endif
#if defined FREEBSD && !defined __FreeBSD__
    #define __FreeBSD__
#endif

osdefs.h

Lida com definições específicas do sistema operacional:

#if defined(__WATCOMC__)
    #if defined(__WINDOWS__) || defined(__NT__)
        #define _Windows 1
    #endif
    #ifdef __386__
        #define __32BIT__ 1
    #endif
#endif

Sistema de Plugin

plugincommon.h

Define a interface principal do plugin e estruturas de suporte:

#define SAMP_PLUGIN_VERSION 0x0200

enum SUPPORTS_FLAGS {
    SUPPORTS_VERSION = SAMP_PLUGIN_VERSION,
    SUPPORTS_VERSION_MASK = 0xffff,
    SUPPORTS_AMX_NATIVES = 0x10000
};

enum PLUGIN_DATA_TYPE {
    PLUGIN_DATA_LOGPRINTF = 0x00,
    PLUGIN_DATA_AMX_EXPORTS = 0x10,
    PLUGIN_DATA_CALLPUBLIC_FS = 0x11,
    PLUGIN_DATA_CALLPUBLIC_GM = 0x12
};

amxplugin.c

O arquivo amxplugin.c é um componente crucial do SA-MP SDK que fornece implementações específicas de plataforma para funções AMX. Implementa duas abordagens diferentes baseadas na plataforma e compilador:

Implementação Windows MSVC (32-bit)
- Usa funções naked com assembly para acesso direto à tabela de funções
- Fornece desempenho otimizado através de jumps diretos para funções AMX
- Exemplo de estrutura:
```
#define NUDE __declspec(naked)
#define AMX_JUMP_HELPER(index) { 
    _asm { mov eax, pAMXFunctions } 
    _asm { jmp dword ptr[eax + index * 4] } 
}
```

Implementação Multiplataforma

Usa ponteiros de função para independência de plataforma
Implementa um sistema baseado em macros para definições de funções
Exemplo de estrutura:

#define DEFINE_AMX_FN_TYPE(name, ret_type, ...) \
    typedef ret_type AMXAPI (*name##_t)(__VA_ARGS__); \
    ret_type AMXAPI name(__VA_ARGS__) { \
        name##_t fn = ((name##_t*)pAMXFunctions)[PLUGIN_AMX_EXPORT_##name]; \
        return fn(__VA_ARGS__); \
    }

Características Principais:

Gerenciamento de Tabela de Funções
- Usa um ponteiro estático pAMXFunctions para armazenar a tabela de funções AMX
- Fornece acesso a todas as funções principais do AMX
- Lida com resolução de função em tempo de execução
Otimizações Específicas de Plataforma
- Windows 32-bit: Usa funções naked para implementação direta em assembly
- Outras plataformas: Usa indireção de ponteiro de função
- Tratamento especial para sistemas 64-bit
Categorias de Funções Implementadas

a. Funções de Gerenciamento de Memória:
- amx_Align16, amx_Align32, amx_Align64
- amx_Allot, amx_Release
b. Funções de Execução:
- amx_Exec, amx_Callback
- amx_Init, amx_InitJIT
- amx_Cleanup, amx_Clone
c. Gerenciamento de Símbolos:
- amx_FindPublic, amx_FindPubVar
- amx_FindNative, amx_FindTagId
- amx_GetPublic, amx_GetPubVar
d. Manipulação de Strings:
- amx_GetString, amx_SetString
- amx_StrLen
- Funções de suporte UTF-8
e. Debug e Informações:
- amx_SetDebugHook
- amx_Flags, amx_MemInfo
- amx_NameLength

Compilação Condicional

Lida com diferentes plataformas através de diretivas de pré-processador
Tratamento especial para sistemas 64-bit
Suporte JIT opcional

#if defined _I64_MAX || defined HAVE_I64
    DEFINE_AMX_NAKED_FN(uint64_t* AMXAPI amx_Align64(uint64_t* v), 
        PLUGIN_AMX_EXPORT_Align64)
#endif

Integração de Tratamento de Erros
- Implementa amx_RaiseError para relatório de erros
- Preserva códigos de erro através de chamadas de função
- Integra com sistema de debug AMX

Funções Nativas AMX

O SDK fornece suporte abrangente para criar e gerenciar funções nativas:

typedef cell (AMX_NATIVE_CALL *AMX_NATIVE)(struct tagAMX *amx, const cell *params);

typedef struct tagAMX_NATIVE_INFO {
    const char _FAR *name;
    AMX_NATIVE func;
} AMX_NATIVE_INFO;

Operações principais de funções nativas:

Registro através de amx_Register
Acesso e validação de parâmetros
Manipulação de valor de retorno
Relatório de erros

Detalhes Técnicos

Gerenciamento de Memória

O SDK fornece facilidades abrangentes de gerenciamento de memória:

amx_memory.h

Lida com alocação de memória e operações específicas de plataforma:

#if defined HAVE_ALLOCA_H
    #include <alloca.h>
#elif defined __BORLANDC__
    #include <malloc.h>
#endif

amx_alignment.h

Gerencia requisitos de alinhamento de memória:

#if (defined SN_TARGET_PS2 || defined __GNUC__) && !defined AMX_NO_ALIGN
    #define AMX_NO_ALIGN
#endif

Operações de Memória

O SDK inclui várias funções para manipulação de memória:

Alocação de Memória
```
int AMXAPI amx_Allot(AMX* amx, int cells, cell* amx_addr, cell** phys_addr);
```
- Aloca memória no heap AMX
- Retorna endereços AMX e físicos
- Lida com requisitos de alinhamento
Acesso à Memória
```
int AMXAPI amx_GetAddr(AMX* amx, cell amx_addr, cell** phys_addr);
```
- Converte endereços AMX para endereços físicos
- Valida acesso à memória
- Lida com limites de memória
Informações de Memória
```
int AMXAPI amx_MemInfo(AMX* amx, long* codesize, long* datasize, long* stackheap);
```
- Recupera informações de layout de memória
- Reporta tamanhos de segmento
- Útil para depuração e otimização

Tratamento de Erros

O SDK inclui um sistema abrangente de tratamento de erros definido em amx_constants.h:

enum {
    AMX_ERR_NONE,
    AMX_ERR_EXIT,
    AMX_ERR_ASSERT,
    AMX_ERR_STACKERR,
    AMX_ERR_BOUNDS,
    AMX_ERR_MEMACCESS,
    AMX_ERR_INVINSTR,
    AMX_ERR_STACKLOW,
    AMX_ERR_HEAPLOW,
    AMX_ERR_CALLBACK,
    AMX_ERR_NATIVE,
    AMX_ERR_DIVIDE,
    AMX_ERR_SLEEP,
    AMX_ERR_INVSTATE,
    
    AMX_ERR_MEMORY = 16,
    AMX_ERR_FORMAT,
    AMX_ERR_VERSION,
    AMX_ERR_NOTFOUND,
    AMX_ERR_INDEX,
    AMX_ERR_DEBUG,
    AMX_ERR_INIT,
    AMX_ERR_USERDATA,
    AMX_ERR_INIT_JIT,
    AMX_ERR_PARAMS,
    AMX_ERR_DOMAIN,
    AMX_ERR_GENERAL,
};

Manipulação de Strings

O SDK fornece capacidades robustas de manipulação de strings através de vários macros e funções:

#define amx_StrParam(amx,param,result) \
    do { \
        int result##_length_; \
        amx_StrLen(amx_Address(amx,param),&result##_length_); \
        if (result##_length_>0 && \
            ((result)=(type)alloca((result##_length_+1)*sizeof(*(result))))!=NULL) \
        amx_GetString((char*)(result),amx_Address(amx,param), \
                            sizeof(*(result))>1,result##_length_+1); \
        else (result)=NULL; \
    } while(0)

Operações com Strings

Comprimento de String
```
int AMXAPI amx_StrLen(const cell* cstring, int* length);
```
- Calcula comprimento da string
- Lida com strings empacotadas e não empacotadas
- Retorna comprimento em caracteres
Conversão de String
```
int AMXAPI amx_SetString(cell* dest, const char* source, int pack, int use_wchar, size_t size);
```
- Converte strings C para strings AMX
- Suporta formatos empacotados e não empacotados
- Lida com conversão Unicode

Suporte a Unicode

O SDK inclui suporte abrangente a Unicode através de funções de manipulação UTF-8:

int AMXAPI amx_UTF8Check(const char* string, int* length);
int AMXAPI amx_UTF8Get(const char* string, const char** endptr, cell* value);
int AMXAPI amx_UTF8Len(const cell* cstr, int* length);
int AMXAPI amx_UTF8Put(char* string, char** endptr, int maxchars, cell value);

Operações Unicode

Validação UTF-8
```
int AMXAPI amx_UTF8Check(const char* string, int* length);
```
- Valida strings codificadas em UTF-8
- Reporta comprimento da string em caracteres
- Detecta erros de codificação
Conversão de Caracteres
```
int AMXAPI amx_UTF8Get(const char* string, const char** endptr, cell* value);
```
- Extrai caracteres Unicode
- Lida com sequências multi-byte
- Reporta erros de análise

Compatibilidade Multiplataforma

O SDK garante compatibilidade multiplataforma através de:

Tratamento de Endianness

#ifndef BYTE_ORDER
    #if defined(UCLINUX)
        #define BYTE_ORDER BIG_ENDIAN
    #else
        #define BYTE_ORDER LITTLE_ENDIAN
    #endif
#endif

Tratamento de Caminhos

#if defined(__MSDOS__) || defined(__WIN32__) || defined(_Windows)
    #define DIRSEP_CHAR '\\'
#elif defined(macintosh)
    #define DIRSEP_CHAR ':'
#else
    #define DIRSEP_CHAR '/'
#endif

Requisitos do Sistema

O SDK suporta múltiplas plataformas e compiladores:

Windows (MSVC, MinGW)
Linux (GCC)
FreeBSD
OpenBSD
macOS

Suporte a Compiladores

Microsoft Visual C++
- Tratamento de pragmas
- Supressão de avisos
- Convenções de chamada
GCC
- Controles de diagnóstico
- Especificações de atributos
- Otimizações específicas de plataforma
Clang
- Configurações de aviso
- Compatibilidade multiplataforma
- Recursos modernos de C++

Melhores Práticas

Ao usar o SA-MP SDK, considere as seguintes melhores práticas:

Gerenciamento de Memória
- Sempre limpe recursos alocados
- Use alinhamento de memória apropriado
- Trate erros de memória graciosamente
- Monitore uso do heap
- Implemente verificação adequada de limites de memória
- Use pools de memória para alocações frequentes
- Limpe recursos na ordem inversa da alocação
Tratamento de Erros
- Verifique valores de retorno das funções AMX
- Implemente tratamento adequado de erros em funções nativas
- Use as constantes de erro fornecidas
- Registre erros apropriadamente
- Implemente mecanismos de recuperação de erros
- Forneça mensagens de erro significativas
- Trate erros específicos do sistema
Desenvolvimento Multiplataforma
- Use tipos independentes de plataforma
- Utilize macros fornecidos para código específico de plataforma
- Teste em múltiplas plataformas
- Lide com diferenças de endianness
- Use separadores de caminho apropriados
- Considere diferenças do sistema de arquivos
- Implemente otimizações específicas de plataforma
Considerações de Performance
- Use tamanhos de cell apropriados
- Implemente manipulação eficiente de strings
- Otimize chamadas de funções nativas
- Minimize alocações de memória
- Use estruturas de dados apropriadas
- Implemente cache quando apropriado
- Profile caminhos críticos de código

Ao trabalhar com funcionalidade amxplugin.c:

Desenvolvimento Específico de Plataforma
- Considere diferenças de plataforma nas implementações de função
- Teste em sistemas 32-bit e 64-bit
- Lide com requisitos de alinhamento específicos de plataforma
- Valide ponteiro da tabela de funções antes do uso
- Implemente verificação de erro apropriada para cada plataforma
- Considere implicações de performance de diferentes implementações
Gerenciamento de Tabela de Funções
- Inicialize tabela de funções antes do uso
- Verifique disponibilidade de função
- Lide graciosamente com funções ausentes
- Implemente procedimentos adequados de limpeza
- Cache ponteiros de função frequentemente usados
- Valide integridade da tabela de funções
Tratamento de Erros
- Implemente verificação de erro adequada para código específico de plataforma
- Trate erros de alinhamento apropriadamente
- Valide entradas da tabela de funções
- Forneça mensagens de erro significativas
- Implemente mecanismos de recuperação
- Registre erros específicos de plataforma

Estruturas Internas

Estrutura do Header AMX

typedef struct tagAMX_HEADER {
    int32_t size;          // Tamanho do "arquivo"
    uint16_t magic;        // Assinatura
    char    file_version;  // Versão do formato do arquivo
    char    amx_version;   // Versão AMX requerida
    int16_t flags;         // Flags
    int16_t defsize;      // Tamanho de um registro de definição
    int32_t cod;          // Valor inicial de COD - bloco de código
    int32_t dat;          // Valor inicial de DAT - bloco de dados
    int32_t hea;          // Valor inicial de HEA - início do heap
    int32_t stp;          // Valor inicial de STP - topo da pilha
    int32_t cip;          // Valor inicial de CIP - ponteiro de instrução de código
    int32_t publics;      // Offset para funções públicas
    int32_t natives;      // Offset para tabela de funções nativas
    int32_t libraries;    // Offset para bibliotecas
    int32_t pubvars;      // Offset para variáveis públicas
    int32_t tags;         // Offset para tags
    int32_t nametable;    // Offset para tabela de nomes
} AMX_HEADER;

Esta estrutura é crucial para entender o formato de arquivo AMX e como a máquina virtual carrega e executa scripts.

Recursos Avançados

Suporte à Compilação JIT

O SDK inclui suporte para compilação Just-In-Time:

int AMXAPI amx_InitJIT(AMX* amx, void* reloc_table, void* native_code);

Interface de Depuração

Suporte à depuração é fornecido através de:

typedef int (AMXAPI *AMX_DEBUG)(struct tagAMX *amx);
int AMXAPI amx_SetDebugHook(AMX* amx, AMX_DEBUG debug);

Interface de Função Pública

O SDK fornece suporte abrangente para trabalhar com funções públicas:

Encontrando Funções Públicas
```
int AMXAPI amx_FindPublic(AMX* amx, const char* funcname, int* index);
```
- Localiza funções públicas por nome
- Retorna índice da função
- Valida existência da função
Executando Funções Públicas
```
int AMXAPI amx_Exec(AMX* amx, cell* retval, int index);
```
- Executa funções públicas
- Lida com valores de retorno
- Gerencia contexto de execução

Informações de Versão

O SDK inclui constantes de versão para verificação de compatibilidade:

#define CUR_FILE_VERSION  9
#define MIN_FILE_VERSION  6
#define MIN_AMX_VERSION   10
#define MAX_FILE_VER_JIT  8
#define MIN_AMX_VER_JIT   8

Compatibilidade de Versão

O SDK mantém compatibilidade através de:

Verificação de versão do arquivo
Validação de versão AMX
Verificação de compatibilidade JIT
Detecção de recursos
Tratamento de versão específico de plataforma

Licença

Este software é licenciado sob os termos da Licença MIT ("Licença"); você pode utilizar este software de acordo com as condições da Licença. Uma cópia da Licença pode ser obtida em: MIT License

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, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do software sem restrições
Permitir que pessoas para as quais o software é fornecido façam o mesmo, desde que sujeitas às condições a seguir

2. Condições Obrigatórias

Todas as cópias ou partes substanciais do software devem incluir:

O aviso de direitos autorais acima
Este aviso de permissão
O aviso de isenção de responsabilidade abaixo

3. Direitos Autorais

O software e toda a documentação associada são protegidos por leis de direitos autorais. A SA-MP Programming Community mantém a titularidade dos direitos autorais originais do software.

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

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM DETERMINADO FIM E NÃO VIOLAÇÃO.

EM NENHUMA CIRCUNSTÂNCIA OS AUTORES OU TITULARES DOS DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER REIVINDICAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, DELITO OU DE OUTRA FORMA, DECORRENTE DE, FORA 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 MIT, consulte: https://opensource.org/licenses/MIT

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
sdk		sdk
translations		translations
LICENSE		LICENSE
README.md		README.md

License

spc-samp/samp-sdk

Folders and files

Latest commit

History

Repository files navigation