TTmod Documentation

1. Configuration

The TTmod/config.cs file allows for customizing a couple of things.

1.1 RCON Interval

The mod checks the database for new RCON commands that were submitted through the Livemap by this interval. The default is 20 seconds. If you frequently use RCON, you might want to decrease the interval so your RCON commands get executed quicker. But be warned that very low intervals (like below 5 seconds) add additional load to the database and might degrade overall performance.

If you don’t use RCON at all or don’t even have a Livemap set up, you might as well configure a very high interval like 99999, so it never checks for new commands.

 1.2 Message Of The Day (MOTD)

The MOTD feature can send a welcome message to new players connecting. This feature is disabled by default. To enable, change false to true and customize the MOTD message. You may use LiF standard color codes to highlight your text.

1.3 GuildGUI Configuration

If you are using a Livemap with Guild Management enabled, it’s highly recommended to enable and configure the GuildGUI. This allows players that have the GuildGUI client mod installed to view and manage their guilds ingame without the necessity to tab out, go to the Livemap and login through Steam. They can skip all these steps and open the guild management directly through the CTRL+G hotkey.

As stated in the comment, find your GuildGUI address on the Livemap Config’s Information tab and copy it into the quotes of the $GuildGUI::Address setting. Then change the $GuildGUI::Enable setting to true.

2. Modding Resources For Developers

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.

2.1 Event Callbacks

2.1.1 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.

2.1.2 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

2.1.3 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");

2.2 Position Triggers

2.2.1 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.

2.2.2 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: Using GeoID is currecntly broken in TTmod 1.3. This wil be fixed in 1.4. A hotfix is available here.
  The trigger system uses X and Y positions only. 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

2.2.3 Removing triggers

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

TTmod_removeTrigger( %trigger );

2.2.4 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" );

2.3 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.