Skip to content

plugins-dev.md

Latest commit

 

History

History
145 lines (103 loc) · 3.74 KB

plugins-dev.md

File metadata and controls

145 lines (103 loc) · 3.74 KB
Raw
name gtamodx-plugins-dev
description GTAMODX 插件（ASI / plugin-sdk）子 skill — Call、Events、Patch、Pattern、Command、Extender、实体 C++。写 .asi、plugin:: 时加载。

Plugins Dev — GTAMODX

Docs Root: https://gtadev.miomoe.cn/docs/plugins

Loaded from parent SKILL.md. Hard constraints for plugin-sdk ASI work.

Upstream: DK22Pac/plugin-sdk. Site = 高频精选; long-tail headers = local SDK.

Baseline

#include "plugin.h"
Macro Meaning
GTA3 / GTAVC / GTASA build target
BY_GAME(iii, vc, sa) pick per game

Priority (from plugin-base):

existing C++ wrapper → Command → Call → patch last

PluginBase / Call

Doc: plugins/plugin-base.mdx · namespace plugin

Scene Use
compile-time addr, cdecl Call / CallAndReturn
thiscall CallMethod / CallMethodAndReturn
runtime addr (Pattern / relocate) CallDyn*
absolute addr, no base add *DynGlobal
vtable slot CallVirtualMethod* 
plugin::Call<0x53BEE0>();
int value = plugin::CallAndReturn<int, 0x53BEE0>();

MUST NOT Call game logic from static ctor / DllMain / before pools / after device Lost (render path).

Events

Doc: plugins/events.mdx · plugin::Events

  • Register with += in static global object ctor; instance must exist.
  • Touch game objects only inside callbacks.
Phase OK Avoid
static ctor +=, own ini FindPlayerPed, spawn
initRwEvent textures, Pattern, config assume player exists
initPoolsEvent Extender pool alloc iterate missing entities
processScriptsEvent logic, Command, keys heavy IO
drawing / drawHud 2D draw create/delete entities
*DtorEvent free side data use pointer after 
class MyPlugin {
public:
    MyPlugin() {
        plugin::Events::processScriptsEvent += OnProcessScripts;
        plugin::Events::drawingEvent += OnDraw;
    }
private:
    static void OnProcessScripts() {}
    static void OnDraw() {}
};
MyPlugin g_my_plugin;

Patch / Pattern

  • Patch (plugins/patch.mdx): plugin::patch::Nop / r/w / jumps; reversible mods MUST backup.
  • Pattern (plugins/pattern.mdx): locate then CallDyn or patch.

Command (C++ → SCM)

Doc: plugins/commands.mdx

  • Call from processScriptsEvent (or equally safe script tick).
  • plugin::Command<plugin::Commands::NAME>(...).
  • Return = script condition result, not vague “success”.
  • NOT CLEO Lua/Redux — script opcodes → cleo-dev.md.

Extender / extensions / utils / entities

Topic Path
Ped/Vehicle/Object data plugins/extender.mdx
paths / screen / Config / KeyCheck plugins/extensions/**
sprites / audio / shaders plugins/utils/**
SA game classes plugins/entities/**
recipes plugins/index.mdx, plugins/recipes.mdx

Entity pages: module note → <Api> (desc + signature + call). Page signatures win.

Minimal ASI

#include "plugin.h"

class Minimal {
public:
    Minimal() {
        plugin::Events::initRwEvent += [] {};
        plugin::Events::processScriptsEvent += [] {};
        plugin::Events::drawingEvent += [] {};
    }
} g_minimal;

MUST NOT

  • FindPlayer* / spawn / render from DllMain or static ctor.
  • Treat CLEO writeMemory / Car.Create as C++ APIs.
  • Assume full game_sa headers or full ScriptCommands enum are on-site.

Output Rules

  1. State selection reason (why Call vs Patch, etc.).
  2. Examples include needed #include and event hook point.
  3. Addresses/RVA are version-sensitive; prefer docs; Pattern when available.