carl.tngl.sh / OMaNGOS
Oxidized Massive Network Game Object Server
rust wow-emulation wow mangos
Star
Fork 0
Watch
OMaNGOS docs plugin-api.md
24 kB
Markdown
at main

Plugin API reference — mangos:scripting@0.1.0 #

The contract a WASM plugin imports/exports. Types are shown in their WIT spelling. The generated WIT package is wit/plugin.wit.

interface game-types #

  • record position — { map: u32, x: f32, y: f32, z: f32, o: f32 }
  • record gossip-item — { icon: u8, text: string, sender: u32, action: u32 }
  • record creature-event-key — { entry: u32, kind: creature-event-kind }
    • Registers a plugin's creature event handler for one creature entry.
  • record game-object-event-key — { entry: u32, kind: game-object-event-kind }
    • Registers a plugin's gameobject event handler for one gameobject entry.
  • record item-event-key — { entry: u32, kind: item-event-kind }
    • Registers a plugin's item event handler for one item entry.
  • record spell-event-key — { spell: u32, kind: spell-event-kind }
    • Registers a plugin's spell event handler for one spell id.
  • enum player-event-kind — on-login | on-logout | on-learn-spell | on-level-change | on-text-emote | on-update-zone | on-kill-creature | on-kill-player | on-killed-by-creature | on-enter-combat | on-leave-combat | on-resurrect | on-repop | on-save | on-loot-item | on-loot-money | on-equip | on-quest-abandon | on-quest-status-changed | on-duel-request | on-duel-start | on-duel-end | on-discover-area | on-whisper | on-group-chat | on-guild-chat | on-channel-chat | on-first-login | on-can-use-item | on-reputation-change | on-skill-change | on-talents-change | on-talents-reset | on-money-change | on-chat | on-send-mail | on-trade-init | on-trade-accept | on-spell-cast | on-give-xp | on-environmental-death | on-map-player-enter | on-map-player-leave | on-modify-money | on-modify-skill-gain | on-modify-reputation | on-modify-honor | on-death | on-can-trade | on-can-send-mail | on-can-take-mail-item | on-can-auction | on-can-resurrect | on-addon-message
    • Broadcast player events. Commands are NOT here — they are keyed by verb, see the registration variant.
  • enum stale — gone
    • An item handle referenced an object that no longer exists.
  • enum quest-status-change — accepted | completed | rewarded
    • How a quest's status changed, for the on-quest-status-changed player event: taken into the log, objectives met, or turned in for a reward.
  • enum duel-end-type — won | fled | interrupted
    • How a duel ended, for the on-duel-end player event: a knockout/forfeit win, a flee out of bounds, or an interruption before a winner was decided.
  • enum chat-kind — say | yell | emote
    • The kind of spoken chat line, for the on-chat player event.
  • enum xp-source — kill | quest | exploration
    • Where an experience award came from, for on-give-xp. A hunter pet's share derives from the (already modified) kill award and raises no separate event, so there is no pet case.
  • enum money-source — loot-coin | quest-reward
    • Which reward paid the copper, for on-modify-money. Only reward paths are routed here: a charge (a vendor purchase, a repair, a quest's required money) and a transfer the player already owned (taking money out of a mail, a completed trade) are not rewards and never fire the hook.
  • enum skill-source — crafting | gathering | weapon | defense
    • Which skill-up rolled, for on-modify-skill-gain: a crafted recipe, a gathered node (mining/herbalism/skinning/lockpicking), a weapon swing, or a blow taken on defense.
  • enum reputation-source — kill | quest | spell | battleground | script
    • Which path earned the standing, for on-modify-reputation. Absolute sets (a GM's .modify rep, a plugin's own set-reputations, the bot factory) are not gains and never fire the hook — otherwise a plugin's multiplier would overshoot a value the operator asked for exactly.
  • enum honor-source — pvp-kill | dishonorable-kill | objective
    • Which path earned the contribution points, for on-modify-honor. Note that the server's Rate.Honor is applied to kill awards only, so an objective amount arrives unscaled by config.
  • enum death-cause — creature | player | environment | unknown
    • What killed the player, for on-death.
  • enum trade-stage — initiate | accept
    • Which point of a trade is being gated, for on-can-trade: opening the window, or the Accept click that would complete it.
  • enum auction-action — open | sell | bid | cancel | browse | list-owner | list-bidder
    • Which auction-house interaction is being gated, for on-can-auction.
  • enum resurrect-method — reclaim-corpse | spirit-healer | accepted-offer | self-res | battleground | dungeon-entrance | gm-revive
    • How the player would return to life, for on-can-resurrect. Releasing the spirit to a graveyard is NOT a resurrect and is never gated — a refused player still becomes a ghost.
  • enum addon-channel — whisper | party | raid | guild
    • The chat channel an addon frame rode in on. 1.12 has no WHISPER addon channel client-side, so a client sending to the server whispers a sentinel name instead; server-to-client frames are party-typed, which is what the 1.12 client reliably routes to CHAT_MSG_ADDON.
  • enum creature-event-kind — on-death | on-enter-combat | on-leave-combat | on-spawn | on-target-died | on-reset | on-reach-home | on-just-summoned | on-summoned-despawn | on-summoned-died | on-reach-wp | on-receive-emote | on-quest-accept | on-quest-reward | on-damage-taken | on-corpse-removed | on-spell-hit-target | on-hit-by-spell | on-dummy-effect | on-summoned | on-dialog-status | on-remove | on-ai-update
    • A keyed creature event a plugin registers for, per creature entry (mirrors the keyed gossip routes).
  • enum game-object-event-kind — on-use | on-spawn | on-quest-accept | on-dialog-status
    • A keyed gameobject event a plugin registers for, per gameobject entry.
  • enum item-event-kind — on-use | on-expire | on-remove | on-equip | on-unequip
    • A keyed item event a plugin registers for, per item entry.
  • enum spell-event-kind — on-cast | on-hit | on-aura-application | on-periodic-tick | on-proc | on-effect-hit-target
    • A keyed spell event a plugin registers for, per spell id (Eluna RegisterSpellEvent). Only the notification (fire-and-forget) hooks are exposed; the calc/check hooks that return a value into the spell math are not representable on this broadcast seam.
  • enum server-event-kind — on-world-update | on-map-create | on-map-destroy | on-character-create | on-character-delete | on-config-load | on-world-startup | on-world-shutdown | on-auction-add | on-auction-remove | on-auction-successful | on-auction-expire | on-bg-start | on-bg-end | on-weather-change | on-game-event-start | on-game-event-stop | on-area-trigger | on-guild-create | on-guild-add-member | on-guild-remove-member | on-guild-disband | on-group-create | on-group-member-add | on-group-member-remove | on-group-disband
    • A broadcast server event a plugin registers for (no subject entity), e.g. the per-tick world update, a map task starting up / shutting down, or a character being created / deleted at the character-select screen. Map-scoped kinds fire from the owning map task; world-scoped kinds (character create/delete) fire from the dedicated world plugin host — a plugin's state is isolated between the two, as it already is between maps.
  • variant registration — player-event(player-event-kind) | command(string) | any-command | creature-gossip(u32) | player-gossip(u32) | creature-event(creature-event-key) | game-object-event(game-object-event-key) | item-event(item-event-key) | spell-event(spell-event-key) | server-event(server-event-kind)
    • Parameterized registration. Gossip and commands are keyed (exclusive-ownership) routes; player-events are broadcast routes.
  • variant gossip-source — creature(u64) | self-menu

resource item #

Owned handle backed by item GUID. Item handles can be invalidated mid-callback, so every method is fallible.

method signature since
entry () -> result<u32, stale> 0.1.0
count () -> result<u32, stale> 0.1.0
item-level () -> result<u32, stale> 0.1.0
sub-class () -> result<u32, stale> 0.1.0
set-permanent-enchant (enchant-id: u32) -> result<_, stale> 0.1.0

resource player (extends unit) #

Host-defined resource. All methods execute host-side against real world state (the shuttled MapState). Player methods are infallible: the player is owned by the dispatching map thread for the callback.

method signature since
guid () -> u64 0.1.0
get-location () -> position 0.1.0
get-level () -> u32 0.1.0
get-class () -> u8 0.1.0
get-faction () -> u32 0.1.0
get-team () -> u8 0.1.0
get-race () -> u8 0.1.0
get-name () -> string 0.1.0
get-zone-name () -> string 0.1.0
get-xp () -> u32 0.1.0
get-selection () -> u64 0.1.0
get-gm-level () -> u8 0.1.0
set-level (level: u32) 0.1.0
set-coinage (copper: u64) 0.1.0
send-broadcast-message (msg: string) 0.1.0
send-addon-message (prefix: string, body: string, channel: addon-channel) 0.1.0
kick (reason: string) 0.1.0
teleport (pos: position) 0.1.0
get-equipped-item (slot: u8) -> option<item> 0.1.0
get-item-by-entry (entry: u32) -> option<item> 0.1.0
add-item (entry: u32, count: u32) -> option<item> 0.1.0
equip-item (it: borrow<item>, slot: u8) -> bool 0.1.0
remove-item (it: borrow<item>, count: u32) 0.1.0
learn-spells (spells: list<u32>) 0.1.0
finish-quests (quests: list<u32>) 0.1.0
set-reputations (reps: list<tuple<u32, s32>>) 0.1.0
set-skill (skill: u16, current: u16, max: u16) 0.1.0
advance-skills-to-max () 0.1.0
send-gossip-menu (text-id: u32, source: gossip-source, menu-id: u32, items: list<gossip-item>) 0.1.0
close-gossip () 0.1.0
add-aura (spell: u32) 0.1.0
remove-aura (spell: u32) 0.1.0
cast-spell (target: u64, spell: u32) 0.1.0

interface lifecycle #

  • record creature-template — { name: string, subname: option, min-level: u32, max-level: u32, display-id: u32, faction: u32, npc-flags: u32, unit-flags: u32, scale: f32, equipment-template-id: option, overrides: list<tuple<string, sql-value>> }
    • Typed core fields + host baseline defaults + a validated overrides escape hatch (the real creature_template is ~90 per-core columns).
  • enum install-error — conflict | denied | database | invalid
  • enum id-kind — creature-entry | gossip-menu | game-object-entry
    • Kinds of host-allocated identifiers a plugin can own.
  • variant sql-value — null | int(s64) | uint(u64) | float(f64) | text(string) | blob(list)
    • Typed SQL parameters — the host binds these; plugins never string-format into queries.
  • variant setting-value — flag(bool) | number(s64) | decimal(f64) | text(string) | list(list)
    • An operator-editable plugin setting's value. Declared with a default during on-install, then read at runtime — a plugin's behaviour is tunable without rebuilding its component. The variant carries the type so the host can reject an operator's plugins config set at the point they type it, instead of leaving the plugin to cope with nonsense.

resource installer #

Only valid during on-install / on-uninstall (passed as borrow). Conceptually the db/world handle: every method executes host-side and everything it creates lands in the ownership ledger under this plugin, in the plugins schema.

method signature since
allocate-id (kind: id-kind, logical-name: string) -> result<u32, install-error> 0.1.0
define-creature-template (logical-name: string, tpl: creature-template) -> result<u32, install-error> 0.1.0
spawn-creature (logical-name: string, entry: u32, pos: position) -> result<u64, install-error> 0.1.0
create-table (logical-name: string, ddl: string) -> result<string, install-error> 0.1.0
declare-setting (key: string, default-value: setting-value, doc: string) -> result<_, install-error> 0.1.0
execute-sql (query: string, params: list<sql-value>) -> result<u64, install-error> 0.1.0
query-sql (query: string, params: list<sql-value>) -> result<list<list<sql-value>>, install-error> 0.1.0

interface host #

  • enum log-level — trace | debug | info | warn | error
    • Severity for log, mapped onto the host's tracing levels.
function signature since scope
register (reg: registration) 0.1.0 map
get-core-expansion () -> u32 0.1.0 map
log (level: log-level, msg: string) 0.1.0 map
player-by-guid (guid: u64) -> option<player> 0.1.0 map
server-announce (text: string) 0.1.0 map
kv-get (key: string) -> option<list<u8>> 0.1.0 map
kv-set (key: string, value: list<u8>) 0.1.0 map
kv-delete (key: string) 0.1.0 map
setting (key: string) -> option<setting-value> 0.1.0 map
lookup-id (kind: id-kind, logical-name: string) -> option<u32> 0.1.0 map

interface events #

  • record plugin-metadata — { name: string, version: string, description: string }
    • A plugin's static identity, stamped into the component by the SDK. The host reads it from a component on disk — without installing or registering it — to list the plugins available in the plugins directory with their version and description.
function signature since scope
init () 0.1.0 map
metadata () -> plugin-metadata 0.1.0 world
on-install (ctx: borrow<installer>, from-version: option<string>) -> result<_, string> 0.1.0 world
on-uninstall (ctx: borrow<installer>) -> result<_, string> 0.1.0 world
on-player-login (p: borrow<player>) -> bool 0.1.0 map
on-logout (p: borrow<player>) 0.1.0 map
on-level-change (p: borrow<player>, old-level: u32) 0.1.0 map
on-text-emote (p: borrow<player>, text-emote: u32, emote: u32, target: u64) 0.1.0 map
on-update-zone (p: borrow<player>, new-zone: u32) 0.1.0 map
on-kill-creature (p: borrow<player>, creature-entry: u32, creature-guid: u64) 0.1.0 map
on-kill-player (p: borrow<player>, killed-guid: u64) 0.1.0 map
on-killed-by-creature (p: borrow<player>, creature-entry: u32, creature-guid: u64) 0.1.0 map
on-enter-combat (p: borrow<player>, enemy-guid: u64) 0.1.0 map
on-leave-combat (p: borrow<player>) 0.1.0 map
on-resurrect (p: borrow<player>) 0.1.0 map
on-map-player-enter (p: borrow<player>) 0.1.0 map
on-map-player-leave (p: borrow<player>) 0.1.0 map
on-repop (p: borrow<player>) 0.1.0 map
on-save (p: borrow<player>) 0.1.0 map
on-loot-item (p: borrow<player>, item: u32, count: u32) 0.1.0 map
on-loot-money (p: borrow<player>, amount: u32) 0.1.0 map
on-equip (p: borrow<player>, item: u32, bag: u32, slot: u32) 0.1.0 map
on-quest-abandon (p: borrow<player>, quest: u32) 0.1.0 map
on-quest-status-changed (p: borrow<player>, quest: u32, change: quest-status-change) 0.1.0 map
on-duel-request (p: borrow<player>, challenger: u64) 0.1.0 map
on-duel-start (p: borrow<player>, opponent: u64) 0.1.0 map
on-duel-end (p: borrow<player>, opponent: u64, kind: duel-end-type) 0.1.0 map
on-discover-area (p: borrow<player>, area: u32) 0.1.0 map
on-whisper (p: borrow<player>, receiver: string, message: string) -> bool 0.1.0 map
on-group-chat (p: borrow<player>, raid: bool, message: string) -> bool 0.1.0 map
on-guild-chat (p: borrow<player>, officer: bool, message: string) -> bool 0.1.0 map
on-channel-chat (p: borrow<player>, channel: string, message: string) -> bool 0.1.0 map
on-first-login (p: borrow<player>) 0.1.0 map
on-can-use-item (p: borrow<player>, item: u32) -> bool 0.1.0 map
on-reputation-change (p: borrow<player>, faction: u32, standing: s32) 0.1.0 map
on-skill-change (p: borrow<player>, skill: u32, value: u32) 0.1.0 map
on-talents-change (p: borrow<player>, spell: u32, rank: u32) 0.1.0 map
on-talents-reset (p: borrow<player>, cost: u32) 0.1.0 map
on-money-change (p: borrow<player>, amount: u32) 0.1.0 map
on-chat (p: borrow<player>, kind: chat-kind, message: string) -> bool 0.1.0 map
on-send-mail (p: borrow<player>, receiver: string, money: u32) 0.1.0 map
on-trade-init (p: borrow<player>, partner: u64) 0.1.0 map
on-trade-accept (p: borrow<player>, partner: u64) 0.1.0 map
on-creature-death (guid: u64, killer: u64) 0.1.0 map
on-creature-enter-combat (guid: u64, target: u64) 0.1.0 map
on-creature-leave-combat (guid: u64) 0.1.0 map
on-creature-spawn (guid: u64) 0.1.0 map
on-creature-target-died (guid: u64, victim: u64) 0.1.0 map
on-creature-reset (guid: u64) 0.1.0 map
on-creature-reach-home (guid: u64) 0.1.0 map
on-creature-just-summoned (summon: u64, summon-entry: u32) 0.1.0 map
on-creature-summoned-despawn (summon: u64, summon-entry: u32) 0.1.0 map
on-creature-summoned-died (summon: u64, summon-entry: u32) 0.1.0 map
on-creature-reach-wp (guid: u64, point: u32) 0.1.0 map
on-creature-receive-emote (guid: u64, player: u64, text-emote: u32) 0.1.0 map
on-creature-quest-accept (guid: u64, player: u64, quest: u32) 0.1.0 map
on-creature-quest-reward (guid: u64, player: u64, quest: u32) 0.1.0 map
on-creature-damage-taken (guid: u64, attacker: u64, damage: u32) 0.1.0 map
on-creature-corpse-removed (guid: u64) 0.1.0 map
on-creature-spell-hit-target (guid: u64, target: u64, spell: u32) 0.1.0 map
on-creature-hit-by-spell (guid: u64, caster: u64, spell: u32) 0.1.0 map
on-creature-dummy-effect (guid: u64, caster: u64, spell: u32, effect-index: u32) 0.1.0 map
on-creature-summoned (guid: u64, summoner: u64) 0.1.0 map
on-creature-dialog-status (guid: u64, player: u64, status: u8) 0.1.0 map
on-creature-remove (guid: u64) 0.1.0 map
on-creature-ai-update (guid: u64, diff: u32) 0.1.0 map
on-gameobject-use (guid: u64, user: u64) 0.1.0 map
on-gameobject-spawn (guid: u64) 0.1.0 map
on-gameobject-quest-accept (guid: u64, player: u64, quest: u32) 0.1.0 map
on-gameobject-dialog-status (guid: u64, player: u64, status: u8) 0.1.0 map
on-item-use (item: u64, user: u64) 0.1.0 map
on-item-equip (item: u64, player: u64, slot: u32) 0.1.0 map
on-item-unequip (item: u64, player: u64, slot: u32) 0.1.0 map
on-item-expire (item: u64, owner: u64) 0.1.0 map
on-item-remove (item: u64, owner: u64) 0.1.0 map
on-cast-spell (caster: u64, spell: u32) 0.1.0 map
on-hit-spell (caster: u64, target: u64, spell: u32) 0.1.0 map
on-aura-application-spell (caster: u64, target: u64, spell: u32) 0.1.0 map
on-periodic-tick-spell (holder: u64, caster: u64, spell: u32) 0.1.0 map
on-proc-spell (proccer: u64, target: u64, spell: u32) 0.1.0 map
on-effect-hit-target-spell (caster: u64, target: u64, spell: u32, effect-index: u32) 0.1.0 map
on-spell-cast (p: borrow<player>, spell: u32) 0.1.0 map
on-give-xp (p: borrow<player>, amount: u32, source: xp-source) -> u32 0.1.0 map
on-modify-money (p: borrow<player>, amount: u32, source: money-source) -> u32 0.1.0 map
on-modify-skill-gain (p: borrow<player>, skill: u32, gain: u32, source: skill-source) -> u32 0.1.0 map
on-modify-reputation (p: borrow<player>, faction: u32, delta: s32, source: reputation-source) -> s32 0.1.0 map
on-modify-honor (p: borrow<player>, honor: f32, source: honor-source) -> f32 0.1.0 map
on-death (p: borrow<player>, killer: u64, killer-name: string, cause: death-cause) 0.1.0 map
on-can-trade (p: borrow<player>, partner: u64, stage: trade-stage) -> bool 0.1.0 map
on-can-send-mail (p: borrow<player>, receiver: string, receiver-guid: u64, money: u32, item: u32) -> bool 0.1.0 map
on-can-take-mail-item (p: borrow<player>, sender-guid: u64, item: u32) -> bool 0.1.0 map
on-can-auction (p: borrow<player>, action: auction-action) -> bool 0.1.0 map
on-can-resurrect (p: borrow<player>, method: resurrect-method) -> bool 0.1.0 map
on-addon-message (p: borrow<player>, prefix: string, body: string, channel: addon-channel) -> bool 0.1.0 map
on-environmental-death (p: borrow<player>) 0.1.0 map
on-world-update (diff: u32) 0.1.0 map
on-map-create (map: u32, instance: u32) 0.1.0 map
on-map-destroy (map: u32, instance: u32) 0.1.0 map
on-bg-start (map: u32, instance: u32) 0.1.0 map
on-bg-end (map: u32, instance: u32, winner: u8) 0.1.0 map
on-guild-create (guild: u32, leader: u64, name: string) 0.1.0 world
on-guild-add-member (guild: u32, player: u64) 0.1.0 world
on-guild-remove-member (guild: u32, player: u64) 0.1.0 world
on-guild-disband (guild: u32) 0.1.0 world
on-group-create (group: u32, leader: u64) 0.1.0 world
on-group-member-add (group: u32, player: u64) 0.1.0 world
on-group-member-remove (group: u32, player: u64) 0.1.0 world
on-group-disband (group: u32) 0.1.0 world
on-weather-change (zone: u32, weather-type: u32, grade: f32) 0.1.0 map
on-game-event-start (event: u32) 0.1.0 map
on-game-event-stop (event: u32) 0.1.0 map
on-area-trigger (player: u64, trigger: u32) 0.1.0 map
on-character-create (guid: u64, account: u32, name: string, race: u8, class: u8, gender: u8) 0.1.0 world
on-character-delete (guid: u64, account: u32) 0.1.0 world
on-config-load (reload: bool) 0.1.0 world
on-world-startup () 0.1.0 world
on-world-shutdown () 0.1.0 world
on-auction-add (auction: u32, owner: u64, item: u32, start-bid: u32, buyout: u32) 0.1.0 world
on-auction-remove (auction: u32, owner: u64, item: u32) 0.1.0 world
on-auction-successful (auction: u32, owner: u64, bidder: u64, item: u32, price: u32) 0.1.0 world
on-auction-expire (auction: u32, owner: u64, item: u32) 0.1.0 world
on-command (p: borrow<player>, verb: string, args: string) -> bool 0.1.0 map
on-learn-spell (p: borrow<player>, spell: u32) -> bool 0.1.0 map
on-gossip-hello (p: borrow<player>, source: gossip-source) 0.1.0 map
on-gossip-select (p: borrow<player>, source: gossip-source, sender: u32, action: u32, code: option<string>) 0.1.0 map

world plugin #

  • imports: game-types, lifecycle, host
  • exports: events