Combat Events - Target-Scoped Event Handlers for Lua

[Heisa]

Combat Events

Target-scoped event handlers for Lua scripts

A shared helper module that ships with GoS: SWTOR Core.

 

Overview

combat_events is a shared Lua helper built on the public gos.events.combat stream. It owns one combat cursor for the importing script and delivers ordered events to target-scoped handlers. It adds no native surface, and fields the stream did not report stay absent - nothing is estimated or guessed.

• One cursor - the module reads one bounded batch (up to 64 events) per tick and keeps its own cursor, so your script never manages one. A backlog drains across later ticks through that cursor.
• Target scopes - register handlers for the local player, the current target, or resolved friendly allies.
• Kind or action - a handler name matches either event.kind or event.action.
• Ordered and contained - events are delivered in stream order, and a failing handler is logged without stopping the others.
• Drop reporting - overwritten stream records are reported through the script log with a running total.
• Idle when unused - polling starts with the first handler registered for that script.
• No history replay - the first cursorless poll subscribes at the stream's current head. Events produced before the first registered handler starts polling are not replayed.

One stream reader, three destination scopes: you, your current target, and your allies.

Usage

local Combat = require("combat_events")

-- Events targeting the local player.
Combat.on_player("damage", function(event)
  gos.log.info("Player damage", event.effective_amount or 0)
end)

-- Damage whose destination is the current target.
Combat.on_current_target("damage", function(event)
  gos.log.debug("Target damage", event.effective_amount or 0)
end)

-- Healing on a resolved friendly ally.
Combat.on_ally("heal", function(event)
  gos.log.success("Ally healed", event.amount or 0)
end)

Event scopes

• Combat.on_player - events whose destination is the local player. It is not every event sourced by that player: for outgoing damage or historical identities, read gos.events.combat directly and compare source_handle.
• Combat.on_current_target - events whose destination matches the target selected when that batch is polled. It does not mean the selected target sourced the event.
• Combat.on_ally - events whose destination resolves to a friendly unit other than the local player.
• A friendly current target can match both on_current_target and on_ally. Registering the same callback under both scopes therefore allows two deliveries by design.

Register handlers at load time. The module owns its polling callback.

Event fields

• Identity - kind, action, result, source/target/ability/effect handles, each event's actor_epoch, and optional source_name / target_name snapshots when Core captured a matching handle and name.
• Values - name, amount, effective_amount, damage_type, critical, and a monotonic millisecond timestamp.
• Fields other than kind are optional and appear only when the client reported them. name is never emitted for effect-kind events; use the documented effect queries instead.
• The native batch also carries actor_epoch and actor_revision metadata alongside cursor, dropped, more, and events. The helper uses the event rows and does not expose the batch object to handlers.

Requirements

• GoS: SWTOR Core (v1.0.0 or newer) with scripting enabled.
• Star Wars: The Old Republic, retail client.

Installation

• combat_events.lua ships with Core in the shared modules folder, next to the other common helpers.
• Load it in your script with local Combat = require("combat_events"). Modules resolve only from the approved script roots and are cached per script.

Notes

• The module is a Lua convenience over the public API, not an extra native interface.
• Every handler runs inside a guarded call: a failure is written to the script log and the remaining handlers still receive the event.
• Part of GoS: SWTOR Core - see the full feature overview: Detailed Explanation of All Features.

 

Built on GoS: SWTOR Core.

Edited Tuesday at 10:54 PM by Heisa