TTmod Development API
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);
}
TTmod_registerPlayerEnterCallback("my_callback");
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.