Skip to main content

Event Handling and I/O

Console Input & Output#

TAMods allows you to output information via the console. It does not currently support direct console input, but you can open the console with a prompt which will execute Lua (via the /lua command).

console(message: string)

Prints the message to the console. Also aliased to print(message: string)

consoleRGB(message: string, color: Color)

Prints the message to the console in the given colour.

notify(title: string, message: string)

Displays a dropdown notification with the given title and message.

openConsole(prompt: string)

Opens the console, with the prompt pre-filled into the command text entry.

This can be used to prompt users for input by pre-filling the /lua command. The example below would prompt the user to provide a value for MyConfigVariable.

openConsole("/lua MyConfigVariable = ")

Event Handling in TAMods#

The code in your config.lua, custom.lua and any custom scripts is run when TAMods loads the config (on injection, and when the /reloadconfig command is used). Generally you will want your mod to be able to run code at other times during the game. To do this, you need to set up event handlers which are triggered by certain events in the game.

TAMods allows you to write handlers for a number of ingame events. You can also attach handlers to input from the player via keybinds (discussed below).

Writing Event Handlers#

Event handlers are defined by writing a Lua function with the name of the event. The handler function should have a signature appropriate for that event (see below for available event handlers with signatures).

Often you will want to attach multiple event handlers to one event (or use presets/scripts which attach handlers to the same event). Specifying the handler function multiple times will overwrite the handler, and only the last definition will be executed.

Hence, you should always write event handlers following the pattern in the example below to execute any pre-existing event handler before running yours.

-- Variable to hold a reference to any existing handler for SomeEvent
local onSomeEventOld
-- If there's already an onSomeEvent handler, save it into onSomeEventOld
if type(onSomeEvent) == "function" then
onSomeEventOld = onSomeEvent
end
-- Define our new handler
function onSomeEvent(someArg1, someArg2)
-- If we saved a previous handler, execute that handler
if onSomeEventOld then onSomeEventOld(someArg1, someArg2) end
-- Do our own handling
doEventHandlingStuffHere()
end

If event handlers are defined using this structure (substituting SomeEvent and the handling logic as need be), multiple handlers for the same event will execute correctly.

Available Event Handlers#

The below function signatures represent the intended signature of the handler function you write for each event.

onChatMessage#

onChatMessage(team: Team, channel: ChatChannel, sender: string, message: string, isVGS: boolean)

Event which fires when a chat message is received (including from this player). See the Team enum for possible values of the team parameter.

ChatChannel enum#
  • enums.CHAT_CHANNEL_GAME = 2 - the game-wide global chat channel
  • enums.CHAT_CHANNEL_TEAM = 3 - the team chat channel

onGameMessage#

onGameMessage(message: string, persistence: float)

Event which fires when an in-game message appears (e.g. on flag return, kill streak, warm-up timer). persistence represents the length of time in seconds that the message is intended to be shown for.

onKillMessage#

onKillMessage(message: string, playerName: string)

Event which fires when the player kills another player. deathMessage is the text normally in the killbox (i.e. "You killed" or "Kill credit for").

onAddToCombatLog#

onAddToCombatLog(killerTeam: integer, killerName: string, killType: KillType, victimName: string, victimTeam: string)

Event which fires when a player dies. killerTeam and victimTeam will normally be a Team (as per the Team enum) unless the killer or the victim is the current player, in which case it will be <player team> + 2: so 2 if the player is on BE and 3 if the player is on DS.

If the death is due to suicide, then the killerName will be Suicide.

The killType does not distinguish with high granularity between weapons - e.g. the index for a kill from an auto is the same as for a kill from a shotgun.

KillType enum#
  • enums.KILL_TYPE_EXPLOSIVE = 1
  • enums.KILL_TYPE_STICKY = 2
  • enums.KILL_TYPE_SQUISH = 3
  • enums.KILL_TYPE_MELEE = 4
  • enums.KILL_TYPE_FALLING = 5
  • enums.KILL_TYPE_VEHICLE = 6
  • enums.KILL_TYPE_BULLET = 7
  • enums.KILL_TYPE_SNIPER = 8
  • enums.KILL_TYPE_BASE_TURRET = 9
  • enums.KILL_TYPE_HEADSHOT = 10
  • enums.KILL_TYPE_GENERIC = 11
  • enums.KILL_TYPE_SPINFUSOR = 12
  • enums.KILL_TYPE_TURRET = 13
  • enums.KILL_TYPE_CLAIMED = 14

onQueueAccolade#

onQueueAccolade(iconId: integer, accoladeName: string, legacy: "", isBadge: boolean)

Event which fires when the player receives an accolade. The legacy parameter is no longer used by TAMods and will always be passed the empty string. The isBadge parameter will be true if the accolade being received is a badge.

onDamageNumberCreate#

onDamageNumberCreate(existingDamageNumbers: DamageNumberArray, number: integer, location: Vector4, isShield: boolean)

Event called instead of creating a damage number (i.e. handling this event replaces the native handler).

The existingDamageNumbers parameter is a DamageNumberArray of the current existing damage numbers.

onDamageNumberUpdate#

onDamageNumberUpdate(damageNumbers: DamageNumberArray, hud: HUD, deltaTime: float)

Event called once per frame instead of the normal damage number update (i.e. replaces the native handler), to update and draw damage numbers. The hud parameter provides the handler with a reference to the player's HUD. deltaTime is the time in seconds since the last update.

This event is a drawing event, so custom HUD drawing functions may be used.

You will generally want to draw damage numbers in this function using the drawDamageNumber function.

onDrawHealthBar#

onDrawHealthBar(x: float, y: float, isFriendly: boolean, healthPct: float)

Event called to draw IFF indicator health bars instead of the normal function (i.e. replaces the native handler). The x and y parameters define the normal HUD position of the top-left of the healthbar. The healthPct parameter is the proportion of health the player having their health bar drawn has.

This event is a drawing event, so custom HUD drawing functions may be used.

onDrawCustomHud#

onDrawCustomHud(xRes: int, yRes: int)

Event called once per frame to draw the custom HUD. The parameters give the resolution of the game view.

This event is a drawing event, so custom HUD drawing functions may be used.

Further information about custom HUD drawing is available on the Drawing page.

onInputEvent#

onInputEvent(keyPressed: string, eventType: InputEventType, ctrl: boolean, shift: boolean, alt: boolean)

Event to intercept all key/mouse presses for custom input handling. The last three parameters allow for checking whether ctrl, alt and/or shift were held down while the key was pressed.

It is highly recommended that you do not handle this event directly; instead, use the keybinding API described below.

Key Binding#

The key names used for keybinding are as per the Unreal Engine documentation.

InputEventType enum#

This enum under the enums namespace enumerates the possible types of input event.

  • enums.INPUT_EVENT_TYPE_PRESSED - event occurs when the key is pressed down
  • enums.INPUT_EVENT_TYPE_RELEASED - event occurs when the key is released
  • enums.INPUT_EVENT_TYPE_REPEAT - event triggers repeatedly while the key is held down
  • enums.INPUT_EVENT_TYPE_DOUBLECLICK - event triggers when the key is pressed twice in quick succession

Binding Functions#

bindKey(key: string, eventType: InputEventType, func: function): boolean

Binds a key to execute the given function, returning whether the bind was successfully added. Multiple binds to the same key are allowed. The handler function should have the signature:

func(keyPressed: string, eventType: InputEventType, ctrl: boolean, shift: boolean, alt: boolean)

The key pressed, the input event type, and whether ctrl/shift/alt were held down will be passed to your handler as arguments.

unbindKey(key: string, eventType: InputEventType): boolean

Unbinds a key, returning whether the unbinding was successful.

Retrieving Keybinds from TribesInput#

searchTribesInputCommands(action: regex string): list<KeyBind>

Retrieve a list of native Unreal Engine bindings for actions matching the given regex, such as those set via the in-game menus or via tribesinput.ini.

KeyBind class#

The KeyBind class represents a native Unreal Engine keybind.

Properties#
PropertyTypeDescription
namestringThe key pressed
commandstringThe command to be executed
ctrlbooleanWhether the bind requires Control held
shiftbooleanWhether the bind requires Shift held
altbooleanWhether the bind requires Alt held
ignoreCtrlbooleanWhether the bind is ignored if Control is held
ignoreShiftbooleanWhether the bind is ignored if Shift is held
ignoreAltbooleanWhether the bind is ignored if Alt is held