samp-sdk

Das SA-MP (San Andreas Multiplayer) Software Development Kit (SDK) ist eine umfassende Sammlung von C-Dateien und Headers sowie Elementen, die es Entwicklern ermöglichen, Plugins für den SA-MP-Server zu erstellen. Dieses SDK bietet eine Grundlage für die Erweiterung der Funktionalität des SA-MP-Servers durch native Funktionen und ermöglicht es Entwicklern, Funktionen zu implementieren, die über das in Pawn-Skripten Verfügbare hinausgehen.

Sprachen

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

Inhaltsverzeichnis

samp-sdk

Kernkomponenten

AMX-System

Der AMX (Abstract Machine eXecutor) ist die virtuelle Maschine, die Pawn-Skripte in SA-MP ausführt. Das SDK bietet umfangreiche Unterstützung für die Interaktion mit AMX durch verschiedene C- und Header-Dateien:

Core AMX Headers

amx.h

Die Haupt-Header-Datei, die alle AMX-bezogenen Funktionalitäten zusammenfasst. Sie enthält:
- Kern-AMX-Funktionen für Skriptausführung
- Speicherverwaltung
- Native Funktionsregistrierung
- String-Behandlung
- UTF-8-Unterstützung
Wichtige Funktionen sind:
```
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

Definiert die grundlegenden Datentypen, die im AMX-System verwendet werden:

#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

Enthält wesentliche Strukturen für den AMX-Betrieb:

typedef struct tagAMX {
    unsigned char _FAR *base;    // Basisadresse
    unsigned char _FAR *data;    // Datensegment
    AMX_CALLBACK callback;       // Callback-Funktion
    AMX_DEBUG debug;            // Debug-Callback
    cell cip;                   // Code-Instruktionszeiger
    cell frm;                   // Stack-Frame-Basis
    cell hea;                   // Heap-Basis
    cell stk;                   // Stack-Zeiger
    // ... zusätzliche Felder
} AMX;

Plattform-Unterstützung

Das SDK enthält robuste plattformspezifische Behandlung durch verschiedene Header:

amx_platform.h

Bietet Plattformerkennung und -konfiguration:

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

osdefs.h

Behandelt betriebssystemspezifische Definitionen:

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

Plugin-System

plugincommon.h

Definiert die Kern-Plugin-Schnittstelle und Unterstützungsstrukturen:

#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

Die Datei amxplugin.c ist eine wichtige Komponente des SA-MP SDK, die plattformspezifische Implementierungen von AMX-Funktionen bereitstellt. Sie implementiert zwei verschiedene Ansätze basierend auf Plattform und Compiler:

Windows MSVC Implementierung (32-bit)
- Verwendet nackte Funktionen mit Assembly für direkten Funktionstabell-Zugriff
- Bietet optimierte Leistung durch direkte Sprünge zu AMX-Funktionen
- Beispielstruktur:
```
#define NUDE __declspec(naked)
#define AMX_JUMP_HELPER(index) { 
    _asm { mov eax, pAMXFunctions } 
    _asm { jmp dword ptr[eax + index * 4] } 
}
```

Plattformübergreifende Implementierung

Verwendet Funktionszeiger für Plattformunabhängigkeit
Implementiert ein makrobasiertes System für Funktionsdefinitionen
Beispielstruktur:

#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__); \
    }

Hauptmerkmale:

Funktionstabell-Verwaltung
- Verwendet einen statischen Zeiger pAMXFunctions zur Speicherung der AMX-Funktionstabelle
- Bietet Zugriff auf alle Kern-AMX-Funktionen
- Handhabt Funktionsauflösung zur Laufzeit
Plattformspezifische Optimierungen
- Windows 32-bit: Verwendet nackte Funktionen für direkte Assembly-Implementierung
- Andere Plattformen: Verwendet Funktionszeiger-Indirektion
- Spezielle Behandlung für 64-bit-Systeme
Implementierte Funktionskategorien

a. Speicherverwaltungsfunktionen:
- amx_Align16, amx_Align32, amx_Align64
- amx_Allot, amx_Release
b. Ausführungsfunktionen:
- amx_Exec, amx_Callback
- amx_Init, amx_InitJIT
- amx_Cleanup, amx_Clone
c. Symbolmanagement:
- amx_FindPublic, amx_FindPubVar
- amx_FindNative, amx_FindTagId
- amx_GetPublic, amx_GetPubVar
d. String-Behandlung:
- amx_GetString, amx_SetString
- amx_StrLen
- UTF-8-Unterstützungsfunktionen
e. Debug und Information:
- amx_SetDebugHook
- amx_Flags, amx_MemInfo
- amx_NameLength

Bedingte Kompilierung

Behandelt verschiedene Plattformen durch Präprozessor-Direktiven
Spezielle Behandlung für 64-bit-Systeme
Optionale JIT-Unterstützung

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

Fehlerbehandlungsintegration
- Implementiert amx_RaiseError für Fehlerberichterstattung
- Bewahrt Fehlercodes über Funktionsaufrufe hinweg
- Integriert sich mit AMX-Debug-System

AMX Native Funktionen

Das SDK bietet umfassende Unterstützung für die Erstellung und Verwaltung nativer Funktionen:

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;

Wichtige native Funktionsoperationen:

Registrierung durch amx_Register
Parameterzugriff und -validierung
Rückgabewertbehandlung
Fehlerberichterstattung

Technische Details

Speicherverwaltung

Das SDK bietet umfassende Speicherverwaltungsfunktionen:

amx_memory.h

Handhabt Speicherallokation und plattformspezifische Speicheroperationen:

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

amx_alignment.h

Verwaltet Speicherausrichtungsanforderungen:

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

Speicheroperationen

Das SDK enthält mehrere Funktionen für Speichermanipulation:

Speicherallokation
```
int AMXAPI amx_Allot(AMX* amx, int cells, cell* amx_addr, cell** phys_addr);
```
- Allokiert Speicher im AMX-Heap
- Gibt sowohl AMX- als auch physische Adressen zurück
- Handhabt Ausrichtungsanforderungen
Speicherzugriff
```
int AMXAPI amx_GetAddr(AMX* amx, cell amx_addr, cell** phys_addr);
```
- Konvertiert AMX-Adressen in physische Adressen
- Validiert Speicherzugriff
- Handhabt Speichergrenzen
Speicherinformation
```
int AMXAPI amx_MemInfo(AMX* amx, long* codesize, long* datasize, long* stackheap);
```
- Ruft Speicherlayout-Informationen ab
- Berichtet Segmentgrößen
- Nützlich für Debugging und Optimierung

Fehlerbehandlung

Das SDK enthält ein umfassendes Fehlerbehandlungssystem, das in amx_constants.h definiert ist:

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,
};

String-Behandlung

Das SDK bietet robuste String-Behandlungsfähigkeiten durch verschiedene Makros und Funktionen:

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

String-Operationen

String-Länge
```
int AMXAPI amx_StrLen(const cell* cstring, int* length);
```
- Berechnet String-Länge
- Handhabt gepackte und ungepackte Strings
- Gibt Länge in Zeichen zurück
String-Konvertierung
```
int AMXAPI amx_SetString(cell* dest, const char* source, int pack, int use_wchar, size_t size);
```
- Konvertiert C-Strings in AMX-Strings
- Unterstützt gepackte und ungepackte Formate
- Handhabt Unicode-Konvertierung

Unicode-Unterstützung

Das SDK enthält umfassende Unicode-Unterstützung durch UTF-8-Behandlungsfunktionen:

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

Unicode-Operationen

UTF-8-Validierung
```
int AMXAPI amx_UTF8Check(const char* string, int* length);
```
- Validiert UTF-8-kodierte Strings
- Berichtet String-Länge in Zeichen
- Erkennt Kodierungsfehler
Zeichenkonvertierung
```
int AMXAPI amx_UTF8Get(const char* string, const char** endptr, cell* value);
```
- Extrahiert Unicode-Zeichen
- Handhabt Multi-Byte-Sequenzen
- Berichtet Parsing-Fehler

Plattformübergreifende Kompatibilität

Das SDK gewährleistet plattformübergreifende Kompatibilität durch:

Endianness-Behandlung

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

Pfadbehandlung

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

Systemanforderungen

Das SDK unterstützt mehrere Plattformen und Compiler:

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

Compiler-Unterstützung

Microsoft Visual C++
- Pragma-Behandlung
- Warnungsunterdrückung
- Aufrufkonventionen
GCC
- Diagnosesteuerungen
- Attributspezifikationen
- Plattformspezifische Optimierungen
Clang
- Warnungskonfigurationen
- Plattformübergreifende Kompatibilität
- Moderne C++-Funktionen

Best Practices

Bei der Verwendung des SA-MP SDK sollten folgende Best Practices beachtet werden:

Speicherverwaltung
- Immer zugewiesene Ressourcen bereinigen
- Geeignete Speicherausrichtung verwenden
- Speicherfehler angemessen behandeln
- Heap-Nutzung überwachen
- Korrekte Speichergrenzenprüfung implementieren
- Speicherpools für häufige Zuweisungen verwenden
- Ressourcen in umgekehrter Reihenfolge der Zuweisung bereinigen
Fehlerbehandlung
- Rückgabewerte von AMX-Funktionen prüfen
- Angemessene Fehlerbehandlung in nativen Funktionen implementieren
- Bereitgestellte Fehlerkonstanten verwenden
- Fehler angemessen protokollieren
- Fehlerwiederherstellungsmechanismen implementieren
- Aussagekräftige Fehlermeldungen bereitstellen
- Systemspezifische Fehler behandeln
Plattformübergreifende Entwicklung
- Plattformunabhängige Typen verwenden
- Bereitgestellte Makros für plattformspezifischen Code nutzen
- Auf mehreren Plattformen testen
- Endianness-Unterschiede behandeln
- Korrekte Pfadtrenner verwenden
- Dateisystemunterschiede berücksichtigen
- Plattformspezifische Optimierungen implementieren
Leistungsüberlegungen
- Geeignete Zellgrößen verwenden
- Effiziente String-Behandlung implementieren
- Native Funktionsaufrufe optimieren
- Speicherzuweisungen minimieren
- Geeignete Datenstrukturen verwenden
- Caching wo angebracht implementieren
- Kritische Codepfade profilieren

Bei der Arbeit mit amxplugin.c-Funktionalität:

Plattformspezifische Entwicklung
- Plattformunterschiede in Funktionsimplementierungen berücksichtigen
- Auf 32-Bit- und 64-Bit-Systemen testen
- Plattformspezifische Ausrichtungsanforderungen behandeln
- Funktionstabell-Zeiger vor Verwendung validieren
- Angemessene Fehlerprüfung für jede Plattform implementieren
- Leistungsauswirkungen verschiedener Implementierungen berücksichtigen
Funktionstabell-Verwaltung
- Funktionstabell vor Verwendung initialisieren
- Funktionsverfügbarkeit überprüfen
- Fehlende Funktionen angemessen behandeln
- Korrekte Aufräumprozeduren implementieren
- Häufig verwendete Funktionszeiger zwischenspeichern
- Funktionsintegritätsvalidierung durchführen
Fehlerbehandlung
- Korrekte Fehlerprüfung für plattformspezifischen Code implementieren
- Ausrichtungsfehler angemessen behandeln
- Funktionseinträge validieren
- Aussagekräftige Fehlermeldungen bereitstellen
- Wiederherstellungsmechanismen implementieren
- Plattformspezifische Fehler protokollieren

Interne Strukturen

AMX Header Struktur

typedef struct tagAMX_HEADER {
    int32_t size;          // Größe der "Datei"
    uint16_t magic;        // Signatur
    char    file_version;  // Dateiformat-Version
    char    amx_version;   // Erforderliche AMX-Version
    int16_t flags;         // Flags
    int16_t defsize;      // Größe eines Definitionseintrags
    int32_t cod;          // Initialwert von COD - Codeblock
    int32_t dat;          // Initialwert von DAT - Datenblock
    int32_t hea;          // Initialwert von HEA - Heap-Start
    int32_t stp;          // Initialwert von STP - Stack-Top
    int32_t cip;          // Initialwert von CIP - Code-Instruktionszeiger
    int32_t publics;      // Offset zu öffentlichen Funktionen
    int32_t natives;      // Offset zur nativen Funktionstabelle
    int32_t libraries;    // Offset zu Bibliotheken
    int32_t pubvars;      // Offset zu öffentlichen Variablen
    int32_t tags;         // Offset zu Tags
    int32_t nametable;    // Offset zur Namenstabelle
} AMX_HEADER;

Diese Struktur ist entscheidend für das Verständnis des AMX-Dateiformats und wie die virtuelle Maschine Skripte lädt und ausführt.

Erweiterte Funktionen

JIT-Compilation-Unterstützung

Das SDK enthält Unterstützung für Just-In-Time-Kompilierung:

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

Debug-Schnittstelle

Debugging-Unterstützung wird bereitgestellt durch:

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

Public Function Schnittstelle

Das SDK bietet umfassende Unterstützung für die Arbeit mit öffentlichen Funktionen:

Öffentliche Funktionen finden
```
int AMXAPI amx_FindPublic(AMX* amx, const char* funcname, int* index);
```
- Lokalisiert öffentliche Funktionen nach Namen
- Gibt Funktionsindex zurück
- Validiert Funktionsexistenz
Öffentliche Funktionen ausführen
```
int AMXAPI amx_Exec(AMX* amx, cell* retval, int index);
```
- Führt öffentliche Funktionen aus
- Handhabt Rückgabewerte
- Verwaltet Ausführungskontext

Versionsinformationen

Das SDK enthält Versionskonstanten für Kompatibilitätsprüfungen:

#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

Versionskompatibilität

Das SDK behält die Kompatibilität bei durch:

Dateiversions-Prüfung
AMX-Versions-Validierung
JIT-Kompatibilitäts-Verifizierung
Funktionserkennung
Plattformspezifische Versionshandhabung

Lizenz

Diese Software ist unter den Bedingungen der MIT-Lizenz ("Lizenz") lizenziert; Sie dürfen diese Software gemäß den Lizenzbedingungen nutzen. Eine Kopie der Lizenz finden Sie unter: MIT License

Nutzungsbedingungen

1. Gewährte Berechtigungen

Diese Lizenz gewährt jeder Person, die eine Kopie dieser Software und der zugehörigen Dokumentationsdateien erhält, kostenlos folgende Rechte:

Die Software ohne Einschränkungen zu nutzen, zu kopieren, zu modifizieren, zusammenzuführen, zu veröffentlichen, zu verteilen, zu unterlizenzieren und/oder zu verkaufen
Personen, denen die Software zur Verfügung gestellt wird, dies unter den folgenden Bedingungen zu gestatten

2. Verpflichtende Bedingungen

Alle Kopien oder wesentliche Teile der Software müssen enthalten:

Den obigen Urheberrechtshinweis
Diesen Erlaubnishinweis
Den nachstehenden Haftungsausschluss

3. Urheberrecht

Die Software und alle zugehörige Dokumentation sind durch Urheberrechtsgesetze geschützt. Die SA-MP Programming Community behält die ursprünglichen Urheberrechte an der Software.

4. Gewährleistungsausschluss und Haftungsbeschränkung

DIE SOFTWARE WIRD "WIE BESEHEN" ZUR VERFÜGUNG GESTELLT, OHNE JEGLICHE AUSDRÜCKLICHE ODER IMPLIZITE GEWÄHRLEISTUNG, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF DIE GEWÄHRLEISTUNG DER MARKTGÄNGIGKEIT, DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND DER NICHTVERLETZUNG VON RECHTEN DRITTER.

DIE AUTOREN ODER URHEBERRECHTSINHABER SIND IN KEINEM FALL HAFTBAR FÜR ANSPRÜCHE, SCHÄDEN ODER ANDERE VERPFLICHTUNGEN, OB IN EINER VERTRAGS- ODER DELIKTKLAGE, DIE AUS ODER IN VERBINDUNG MIT DER SOFTWARE ODER DER NUTZUNG ODER ANDEREN GESCHÄFTEN MIT DER SOFTWARE ENTSTEHEN.

For detailed information about the MIT License, visit: https://opensource.org/licenses/MIT

Files

README.md

Latest commit

History