Skip to content

Latest commit

 

History

History
667 lines (537 loc) · 23.1 KB

README.md

File metadata and controls

667 lines (537 loc) · 23.1 KB

samp-sdk

License Language SDK Platform Windows Platform Linux Platform FreeBSD AMX Native Support Memory Safe

El SA-MP (San Andreas Multiplayer) Software Development Kit (SDK) es una colección integral de archivos C y headers que permiten a los desarrolladores crear plugins para el servidor SA-MP. Este SDK proporciona una base para extender la funcionalidad del servidor SA-MP a través de funciones nativas, permitiendo a los desarrolladores implementar características más allá de lo disponible en el script Pawn.

Idiomas

Índice

Componentes Principales

Sistema AMX

El AMX (Abstract Machine eXecutor) es la máquina virtual que ejecuta scripts Pawn en SA-MP. El SDK proporciona soporte extenso para interactuar con AMX a través de varios archivos C y headers:

Headers AMX Principales

  1. amx.h

    El archivo header principal que consolida toda la funcionalidad relacionada con AMX. Incluye:

    • Funciones principales de AMX para ejecución de scripts
    • Gestión de memoria
    • Registro de funciones nativas
    • Manejo de strings
    • Soporte UTF-8

    Funciones principales incluyen:

    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);

  2. amx_cell.h

    Define los tipos de datos fundamentales utilizados en el 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

  3. amx_structures.h

    Contiene estructuras esenciales para la operación de AMX:

    typedef struct tagAMX {
    unsigned char _FAR *base;    // Dirección base
    unsigned char _FAR *data;    // Segmento de datos
    AMX_CALLBACK callback;       // Función de callback
    AMX_DEBUG debug;            // Callback de depuración
    cell cip;                   // Puntero de instrucción de código
    cell frm;                   // Base del marco de pila
    cell hea;                   // Base del heap
    cell stk;                   // Puntero de pila
    // ... campos adicionales
} AMX;

Soporte de Plataformas

El SDK incluye manejo robusto específico de plataforma a través de varios headers:

  1. amx_platform.h

    Proporciona detección y configuración de plataforma:

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

  2. osdefs.h

    Maneja definiciones específicas del sistema operativo:

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

Sistema de Plugins

plugincommon.h

Define la interfaz principal del plugin y las estructuras de soporte:

#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

El archivo amxplugin.c es un componente crucial del SA-MP SDK que proporciona implementaciones específicas de plataforma para funciones AMX. Implementa dos enfoques diferentes según la plataforma y el compilador:

  1. Implementación Windows MSVC (32-bit)

    • Usa funciones naked con ensamblador para acceso directo a la tabla de funciones
    • Proporciona rendimiento optimizado a través de saltos directos a funciones AMX
    • Estructura de ejemplo:
    #define NUDE __declspec(naked)
#define AMX_JUMP_HELPER(index) { 
    _asm { mov eax, pAMXFunctions } 
    _asm { jmp dword ptr[eax + index * 4] } 
}

  2. Implementación Multiplataforma

    • Usa punteros a funciones para independencia de plataforma
    • Implementa un sistema basado en macros para definiciones de funciones
    • Estructura de ejemplo:
    #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 Principales:

  1. Gestión de Tabla de Funciones

    • Usa un puntero estático pAMXFunctions para almacenar la tabla de funciones AMX
    • Proporciona acceso a todas las funciones principales de AMX
    • Maneja la resolución de funciones en tiempo de ejecución

  2. Optimizaciones Específicas de Plataforma

    • Windows 32-bit: Usa funciones naked para implementación directa en ensamblador
    • Otras plataformas: Usa indirección de punteros a funciones
    • Manejo especial para sistemas de 64 bits

  3. Categorías de Funciones Implementadas

    a. Funciones de Gestión de Memoria:

    • amx_Align16, amx_Align32, amx_Align64
    • amx_Allot, amx_Release

    b. Funciones de Ejecución:

    • amx_Exec, amx_Callback
    • amx_Init, amx_InitJIT
    • amx_Cleanup, amx_Clone

    c. Gestión de Símbolos:

    • amx_FindPublic, amx_FindPubVar
    • amx_FindNative, amx_FindTagId
    • amx_GetPublic, amx_GetPubVar

    d. Manejo de Strings:

    • amx_GetString, amx_SetString
    • amx_StrLen
    • Funciones de soporte UTF-8

    e. Depuración e Información:

    • amx_SetDebugHook
    • amx_Flags, amx_MemInfo
    • amx_NameLength

  4. Compilación Condicional

    • Maneja diferentes plataformas a través de directivas de preprocesador
    • Manejo especial para sistemas de 64 bits
    • Soporte 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

  5. Integración de Manejo de Errores

    • Implementa amx_RaiseError para reportar errores
    • Preserva códigos de error a través de llamadas a funciones
    • Se integra con el sistema de depuración AMX

Funciones Nativas AMX

El SDK proporciona soporte integral para crear y gestionar funciones 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;

Operaciones principales de funciones nativas:

  • Registro a través de amx_Register
  • Acceso y validación de parámetros
  • Manejo de valores de retorno
  • Reporte de errores

Detalles Técnicos

Gestión de Memoria

El SDK proporciona instalaciones completas de gestión de memoria:

  1. amx_memory.h

    Maneja la asignación de memoria y operaciones de memoria específicas de plataforma:

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

  2. amx_alignment.h

    Gestiona requisitos de alineación de memoria:

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

Operaciones de Memoria

El SDK incluye varias funciones para manipulación de memoria:

  1. Asignación de Memoria

    int AMXAPI amx_Allot(AMX* amx, int cells, cell* amx_addr, cell** phys_addr);
    • Asigna memoria en el heap AMX
    • Devuelve direcciones AMX y físicas
    • Maneja requisitos de alineación

  2. Acceso a Memoria

    int AMXAPI amx_GetAddr(AMX* amx, cell amx_addr, cell** phys_addr);
    • Convierte direcciones AMX a direcciones físicas
    • Valida acceso a memoria
    • Maneja límites de memoria

  3. Información de Memoria

    int AMXAPI amx_MemInfo(AMX* amx, long* codesize, long* datasize, long* stackheap);
    • Recupera información del diseño de memoria
    • Reporta tamaños de segmentos
    • Útil para depuración y optimización

Manejo de Errores

El SDK incluye un sistema integral de manejo de errores definido en 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,
};

Manejo de Strings

El SDK proporciona capacidades robustas de manejo de strings a través de varios macros y funciones:

#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)

Operaciones de Strings

  1. Longitud de String

    int AMXAPI amx_StrLen(const cell* cstring, int* length);
    • Calcula la longitud del string
    • Maneja strings empaquetados y no empaquetados
    • Devuelve la longitud en caracteres

  2. Conversión de Strings

    int AMXAPI amx_SetString(cell* dest, const char* source, int pack, int use_wchar, size_t size);
    • Convierte strings C a strings AMX
    • Soporta formatos empaquetados y no empaquetados
    • Maneja conversión Unicode

Soporte Unicode

El SDK incluye soporte integral para Unicode a través de funciones de manejo 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);

Operaciones Unicode

  1. Validación UTF-8

    int AMXAPI amx_UTF8Check(const char* string, int* length);
    • Valida strings codificados en UTF-8
    • Reporta longitud del string en caracteres
    • Detecta errores de codificación

  2. Conversión de Caracteres

    int AMXAPI amx_UTF8Get(const char* string, const char** endptr, cell* value);
    • Extrae caracteres Unicode
    • Maneja secuencias multi-byte
    • Reporta errores de análisis

Compatibilidad Multiplataforma

El SDK asegura compatibilidad multiplataforma a través de:

  1. Manejo de Endianness

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

  2. Manejo de Rutas

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

Requisitos del Sistema

El SDK soporta múltiples plataformas y compiladores:

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

Soporte de Compiladores

  1. Microsoft Visual C++

    • Manejo de pragmas
    • Supresión de advertencias
    • Convenciones de llamada

  2. GCC

    • Controles de diagnóstico
    • Especificaciones de atributos
    • Optimizaciones específicas de plataforma

  3. Clang

    • Configuraciones de advertencias
    • Compatibilidad multiplataforma
    • Características modernas de C++

Mejores Prácticas

Al usar el SA-MP SDK, considere las siguientes mejores prácticas:

  1. Gestión de Memoria

    • Siempre limpie los recursos asignados
    • Use alineación de memoria apropiada
    • Maneje errores de memoria con elegancia
    • Monitoree el uso del heap
    • Implemente verificación apropiada de límites de memoria
    • Use pools de memoria para asignaciones frecuentes
    • Limpie recursos en orden inverso a la asignación

  2. Manejo de Errores

    • Verifique valores de retorno de funciones AMX
    • Implemente manejo apropiado de errores en funciones nativas
    • Use las constantes de error proporcionadas
    • Registre errores apropiadamente
    • Implemente mecanismos de recuperación de errores
    • Proporcione mensajes de error significativos
    • Maneje errores específicos del sistema

  3. Desarrollo Multiplataforma

    • Use tipos independientes de plataforma
    • Utilice macros proporcionados para código específico de plataforma
    • Pruebe en múltiples plataformas
    • Maneje diferencias de endianness
    • Use separadores de ruta apropiados
    • Considere diferencias del sistema de archivos
    • Implemente optimizaciones específicas de plataforma

  4. Consideraciones de Rendimiento

    • Use tamaños de cell apropiados
    • Implemente manejo eficiente de strings
    • Optimice llamadas a funciones nativas
    • Minimice asignaciones de memoria
    • Use estructuras de datos apropiadas
    • Implemente caché donde sea apropiado
    • Perfile rutas críticas de código

Cuando trabaje con la funcionalidad de amxplugin.c:

  1. Desarrollo Específico de Plataforma

    • Considere diferencias de plataforma en implementaciones de funciones
    • Pruebe en sistemas de 32 bits y 64 bits
    • Maneje requisitos de alineación específicos de plataforma
    • Valide el puntero de tabla de funciones antes de usar
    • Implemente verificación de errores apropiada para cada plataforma
    • Considere implicaciones de rendimiento de diferentes implementaciones

  2. Gestión de Tabla de Funciones

    • Inicialice la tabla de funciones antes de usar
    • Verifique disponibilidad de funciones
    • Maneje funciones faltantes con elegancia
    • Implemente procedimientos apropiados de limpieza
    • Cache punteros de funciones frecuentemente usados
    • Valide integridad de la tabla de funciones

  3. Manejo de Errores

    • Implemente verificación apropiada de errores para código específico de plataforma
    • Maneje errores de alineación apropiadamente
    • Valide entradas de tabla de funciones
    • Proporcione mensajes de error significativos
    • Implemente mecanismos de recuperación
    • Registre errores específicos de plataforma

Estructuras Internas

Estructura del Header AMX

typedef struct tagAMX_HEADER {
    int32_t size;          // Tamaño del "archivo"
    uint16_t magic;        // Firma
    char    file_version;  // Versión del formato de archivo
    char    amx_version;   // Versión AMX requerida
    int16_t flags;         // Banderas
    int16_t defsize;      // Tamaño de un registro de definición
    int32_t cod;          // Valor inicial de COD - bloque de código
    int32_t dat;          // Valor inicial de DAT - bloque de datos
    int32_t hea;          // Valor inicial de HEA - inicio del heap
    int32_t stp;          // Valor inicial de STP - tope de pila
    int32_t cip;          // Valor inicial de CIP - puntero de instrucción de código
    int32_t publics;      // Desplazamiento a funciones públicas
    int32_t natives;      // Desplazamiento a tabla de funciones nativas
    int32_t libraries;    // Desplazamiento a bibliotecas
    int32_t pubvars;      // Desplazamiento a variables públicas
    int32_t tags;         // Desplazamiento a tags
    int32_t nametable;    // Desplazamiento a tabla de nombres
} AMX_HEADER;

Esta estructura es crucial para entender el formato de archivo AMX y cómo la máquina virtual carga y ejecuta scripts.

Características Avanzadas

Soporte de Compilación JIT

El SDK incluye soporte para compilación Just-In-Time:

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

Interfaz de Depuración

El soporte de depuración se proporciona a través de:

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

Interfaz de Funciones Públicas

El SDK proporciona soporte integral para trabajar con funciones públicas:

  1. Búsqueda de Funciones Públicas

    int AMXAPI amx_FindPublic(AMX* amx, const char* funcname, int* index);
    • Localiza funciones públicas por nombre
    • Devuelve índice de función
    • Valida existencia de función

  2. Ejecución de Funciones Públicas

    int AMXAPI amx_Exec(AMX* amx, cell* retval, int index);
    • Ejecuta funciones públicas
    • Maneja valores de retorno
    • Gestiona contexto de ejecución

Información de Versión

El SDK incluye constantes de versión para verificación de compatibilidad:

#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

Compatibilidad de Versiones

El SDK mantiene compatibilidad a través de:

  1. Verificación de versión de archivo
  2. Validación de versión AMX
  3. Verificación de compatibilidad JIT
  4. Detección de características
  5. Manejo de versión específico de plataforma

Licencia

Copyright © SA-MP Programming Community

Este software está licenciado bajo los términos de la Licencia MIT ("Licencia"); puede utilizar este software de acuerdo con las condiciones de la Licencia. Puede obtener una copia de la Licencia en: MIT License

Términos y Condiciones de Uso

1. Permisos Otorgados

La presente licencia otorga, gratuitamente, a cualquier persona que obtenga una copia de este software y archivos de documentación asociados, los siguientes derechos:

  • Usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del software sin restricciones
  • Permitir que las personas a las que se les proporciona el software hagan lo mismo, sujeto a las siguientes condiciones

2. Condiciones Obligatorias

Todas las copias o partes sustanciales del software deben incluir:

  • El aviso de derechos de autor anterior
  • Este aviso de permiso
  • El aviso de exención de responsabilidad a continuación

3. Derechos de Autor

El software y toda la documentación asociada están protegidos por leyes de derechos de autor. La SA-MP Programming Community mantiene la titularidad de los derechos de autor originales del software.

4. Exención de Garantías y Limitación de Responsabilidad

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN.

EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMACIÓN, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, FUERA DE O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.

Para información detallada sobre la Licencia MIT, consulte: https://opensource.org/licenses/MIT