API Documentation: Overview

TDSM API Documentation and Usage

This page will help you understand how to use the API provided by TDSM.

There are two types of plugins that you can program for TDSM, one being the native C# plugin and the other being LUA which is implemented using NLua.

Please note that the LUA plugin implementation very experimental, and may very well change in the future. I'd say nothing too dramatic, maybe from using the export = [plugin].create to fixed functions.

The essentials common between the two types are the Plugin Details which are required for loading your plugin. These details must be set before you can hook into server events or add new commands to the console or player. The details are for defining your plugins name, the supported TDSM build and who it's created by. Here's the exact list you need to populate in your constructor:

• Name - String value
• Version - String value
• TDSMBuild - Integral value
• Author - String value
• Description - String value

C# Example

pubic YourPlugin()
{
    this.TDSMBuild = 1;
    this.Version = "1";
    this.Author = "TDSM";
    this.Name = "Simple name";
    this.Description = "This plugin does these awesome things!";
}

LUA Example

function YourPlugin.create()
    local plg = {}
    setmetatable(plg, YourPlugin)
	
    --Set the details (TDSM requires this)
    plg.TDSMBuild = 1
    plg.Version = "1"
    plg.Author = "TDSM"
    plg.Name = "Simple name"
    plg.Description = "This plugin does these awesome things!"

    return plg
end

export = YourPlugin.create() --Ensure this exists, as TDSM needs this to find your plugin

Hooks

Hooks allow you to hook into server events such as player chat, server state changes or even when the patcher is applying changes. See the bottom of this overview for a full list of the rest of the api

Implementing a hook

Implementing a hook requires you to specify a function which takes two reference arguments; the first of HookContext and the second of the specific event argument.

For a demonstration here shows the event where the user has just joined the server

C# Example

[Hook(HookOrder.NORMAL)]
void MyFunctionNameThatDoesntMatter(ref HookContext ctx, ref HookArgs.PlayerEnteredGame args)
{
    //Your implementation here
}

LUA Example

function YourPlugin:Initialized()
    --Register hooks
    export.Hooks = {}
    export.Hooks.PlayerEnteredGame = --This must be the event as per TDSMs API.
    {
        Call = export.MyFunctionNameThatDoesntMatter,
        Priority = HookOrder.NORMAL --Normal is default and is here for demonstration purposes.
    }
end

function YourPlugin:MyFunctionNameThatDoesntMatter(ctx, args)
    --Your implementation here
    return ctx
end

As you can see the [Hook( ... )] attribute in C# is used to register the event, whereas in LUA you must manually register it inside the plugin's Initialized function.

Registering commands

Adding commands is simple in both syntaxs, and is as simple as calling AddCommand in the Initialized function of your plugin. The only difference is that in order to register a callback a C# pulgin must call [.Calls] and a LUA plugin must call [.LuaCall].

C# Example

protected override void Initialized(object state)
{
    AddCommand("commandname")
        .WithAccessLevel(AccessLevel.PLAYER)
        .WithDescription("My command description")
        .WithHelpText("Usage:    commandname <name>")
        .WithHelpText("          commandname <something else> <maybe more>")
        .WithPermissionNode("tdsm.commandname")
        .Calls(MyCustomCommandCallback);
}

public static void MyCustomCommandCallback(ISender sender, ArgumentList args)
{
    //Your implementation
}

LUA Example

function YourPlugin:Initialized()
    AddCommand("commandname")
        :WithAccessLevel(AccessLevel.PLAYER)
        :WithDescription("My command description")
        :WithHelpText("Usage:    commandname <name>")
        :WithHelpText("          commandname <something else> <maybe more>")
        :WithPermissionNode("tdsm.commandname")
        :LuaCall(export.MyCustomCommandCallback)
end

function YourPlugin:MyCustomCommandCallback(sender, args)
    --Your implementation
end

A LUA command args parameter is limited to only of the type [ArgumentList], whereas a C# command may well be ArgumentList or simply a string of the whole line (without the command prefix of course). This is useful where you command only ever expects one argument. Here's what I mean:

C# Example

public static void MyCustomCommandCallback(ISender sender, string args)
{
    //Your implementation
}

Full list of server hooks (WIP)

• [ConfigurationLine](javascript::alert("Sorry - this is being implemented"))
• [StartDefaultServer](javascript::alert("Sorry - this is being implemented"))
• [StatusTextChanged](javascript::alert("Sorry - this is being implemented"))
• [UpdateServer](javascript::alert("Sorry - this is being implemented"))
• [NewConnection](javascript::alert("Sorry - this is being implemented"))
• [ServerStateChange](javascript::alert("Sorry - this is being implemented"))
• [PluginLoadRequest](javascript::alert("Sorry - this is being implemented"))
• [SendNetData](javascript::alert("Sorry - this is being implemented"))
• [ConnectionRequestReceived](javascript::alert("Sorry - this is being implemented"))
• [DisconnectReceived](javascript::alert("Sorry - this is being implemented"))
• [ServerPassReceived](javascript::alert("Sorry - this is being implemented"))
• [PlayerPassReceived](javascript::alert("Sorry - this is being implemented"))
• [PlayerDataReceived](javascript::alert("Sorry - this is being implemented"))
• [StateUpdateReceived](javascript::alert("Sorry - this is being implemented"))
• [InventoryItemReceived](javascript::alert("Sorry - this is being implemented"))
• [ObituaryReceived](javascript::alert("Sorry - this is being implemented"))
• [PlayerWorldAlteration](javascript::alert("Sorry - this is being implemented"))
• [ProjectileReceived](javascript::alert("Sorry - this is being implemented"))
• [ChestOpenReceived](javascript::alert("Sorry - this is being implemented"))
• [PvpSettingReceived](javascript::alert("Sorry - this is being implemented"))
• [PartySettingReceived](javascript::alert("Sorry - this is being implemented"))
• [PlayerEnteringGame](javascript::alert("Sorry - this is being implemented"))
• [PlayerEnteredGame](javascript::alert("Sorry - this is being implemented"))
• [PlayerLeftGame](javascript::alert("Sorry - this is being implemented"))
• SignTextSet
• SignTextGet
• [PluginsLoaded](javascript::alert("Sorry - this is being implemented"))
• [PlayerTriggeredEvent](javascript::alert("Sorry - this is being implemented"))
• [PlayerChat](javascript::alert("Sorry - this is being implemented"))
• [Command](javascript::alert("Sorry - this is being implemented"))
• [WorldRequestMessage](javascript::alert("Sorry - this is being implemented"))
• [ProgramStart](javascript::alert("Sorry - this is being implemented"))
• [StartCommandProcessing](javascript::alert("Sorry - this is being implemented"))

Additional references for plugin developers (WIP)

Examples

• [C# Bare bones plugin](javascript::alert("Sorry - this is being implemented"))
• LUA plugin examples

Classes

• [ArgumentList](javascript::alert("Sorry - this is being implemented"))
• [DataRegister](javascript::alert("Sorry - this is being implemented"))
• [HookContext](javascript::alert("Sorry - this is being implemented"))
• [HookOrder](javascript::alert("Sorry - this is being implemented"))
• Tools