TTmod Development API

You are here:
← All Topics

Updated 2020-03-05 for TTmod v1.5

This section is for mod developers and people who write their own server-side scripts. I will need to assume at least basic Torque3D scripting knowledge to describe the functions below.

Event Callbacks

About Event Callbacks

You can register own callback functions that will be triggered when certain events happen. For example, when a new player enters the world or when somebody goes into GM mode. To register such callback function, you will have to define your function first and then pass the function name to the respective TTmod function.

It is worth mentioning that you can register as many callback functions as you like. They do stack and they will be executed in the order they were added. Just make sure you load all mods that depend on this after TTmod.

Available Callbacks

Event: Player enters the server
Function: TTmod_registerPlayerEnterCallback()
Arguments passed back: Client Object (GameConnection) of the player

Event: Player leaves the server
Function: TTmod_registerPlayerLeaveCallback()
Arguments passed back: Character ID of the player who left the server

Event: Player enters GM mode
Function: TTmod_registerGmEnableCallback()
Arguments passed back: Client Object (GameConnection) of the player

Event: Player exits GM mode
Function: TTmod_registerGmDisableCallback()
Arguments passed back: Client Object (GameConnection) of the player

Event: Judgement Hour starts
Function: TTmod_registerJhBeginCallback()
Arguments passed back: none

Event: Judgement Hour ends
Function: TTmod_registerJhEndCallback()
Arguments passed back: none

Callback Usage Example

Let’s look at a very basic example:

function my_callback(%client) {
    centerprintall("Character ID " @ %client.player.getCharacterId() @ " has entered the world!", 8);

Once a new player enters the world, a centerprint message with the Character ID is displayed on everyones screen for 8 seconds. Fun.

Now you could utilize this to do something actually useful.
This is a commented copy of the MOTD script:

// Define callback function
function TTmod_SendMOTD( %client ) {
    // Write to server console (optional)
    echo( "TTmod | Sending MOTD to character " @ %client.player.getCharacterId() );
    // Send MOTD to clients system chat
    %client.cmSendClientMessage(2475, $TTmod::MOTD);
    // Send MOTD to clients local chat
    cmChatSendLocalMessageToClient(%client, "Server", %client.player.position, " " @ $TTmod::MOTD);

// Register our callback if MOTD is enabled in config
if( $TTmod::EnableMOTD ) TTmod_registerPlayerEnterCallback("TTmod_SendMOTD");

Position Triggers

About Position Triggers

With TTmod you can create tigger locations in the game world that execute a certain function when a player enters or leaves the trigger area.

Creating Triggers

The syntax to add a new trigger is this:

TTmod_addTrigger( %position, %radius, %enter, %leave, %data );
  • %position
    “X Y Z” position or GeoID of the trigger center.
    Notice: The z-axis is ignored.
  • %radius
    Radius of the trigger area. Note that 4 units equals one tile in game. So for a radius of 3 tiles, pass a radius of 12.
  • %enter
    The function name to be executed when a player enters the trigger area.
  • %leave 
    The function name to be executed when a player leaves the trigger area.
  • %data
    Optional – can be any string or number or object reference that you would like to assign to trigger object

The function returns the trigger object.

Removing triggers

An existing trigger can be removed with this function. The trigger object must be passed into it.

TTmod_removeTrigger( %trigger );

Trigger Usage Example

Let’s say we have placed a cog at GeoID 123456789 and we want to display a message to everyone boarding the ship.

// First we define the function to run when the player enters the trigger
function greetSailor( %trigger, %player ) {
    // Display a greeting message for 10 seconds
    centerprint( %player.getControllingClient(), "Welcome aboard, sailor!", 20 );
// Now define the function to run when the player leaves the trigger
function clearGreeting( %trigger, %player ) {
    // Make sure to clear all centerprint messages
    clearcenterprint( %player.getControllingClient() );
// Then add the trigger to TTmod
TTmod_addTrigger( "123456789", 12, "greetSailor", "clearGreeting" );

Respawning Players

Through this function you can respawn a player. This is useful if you want to update the player’s stats or inventory through the database only. The trading post mod uses this method to trade with regional items, as they can’t be distributed through server functions.

TTmod.respawnPlayer( %playerObject );

The player object must be passed into the function. It has no return value.

Find Objects By Model File Name

This function finds objects, such as buildings, by their DTS model file name.

%result = TTmod.findShapes( %name, %group );

It returns a SimSet with all child objects of %group whose DTS shape filename contains %name

Example Usage:

%result = TTmod.findShapes( "trade_post", RootGroup );
foreach( %obj in %result ) {
  info( "Trading Post found at position" SPC %obj.position );

Character Security Tokens

Once a new clients connects to the server, TTmod generates a random 64-character token and stores it in the database. You can find it in the ‘nyu_ttmod_tokens’ database table. A new property “TTmodSecurityToken” is added to the client object to ensure scripting access to it.

These security tokens can be used to safely authenticate players in a web application that is accessed through the in-game browser. This is what we’re doing with the GuildGUI. In a nutshell, once a new player connects to the server, the token and Livemap URL are sent to the client. The player presses a hotkey to open the in-game browser, which points to the Livemap URL with the token attached. This token is read by the Livemap and compared with the database table to authenticate the player and assign their character and privileges.

So if you would like to develop web applications that are accessed through the ingame browser via client-mod, this might be a helping hand.