API Documentation: Overview

TDSM API Documentation and Usage

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

There are three types of plugins that you can program for TDSM; the native C# plugin, LUA which is implemented using NLua, and VB.Net.

Please note that the LUA plugin implementation is 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

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

VB.Net Example

Public Sub New()
    MyBase.TDSMBuild = 1
    MyBase.Version = "1"
    MyBase.Author = "TDSM"
    MyBase.Name = "Simple name"
    MyBase.Description = "This plugin does these awesome things!"
End Sub

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
}

VB.Net Example

<Hook(HookOrder.NORMAL)> _
Sub MyFunctionNameThatDoesntMatter(ByRef ctx As HookContext, ByRef args As HookArgs.PlayerEnteredGame)
    'Your implementation here
End Sub

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.

Note: LUA event callbacks also must return the HookContext object when it is modified; however if you don't touch it then it doesn't matter. For example, when you set the HookResult to something other than DEFAULT.

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
}

VB.Net Example

Protected Overrides Sub Initialized(state as Object)
    AddCommand("commandname") _
        .WithAccessLevel(AccessLevel.PLAYER) _
        .WithDescription("My command description") _
        .WithHelpText("Usage:    commandname <name>") _
        .WithHelpText("          commandname <something else> <maybe more>") _
        .WithPermissionNode("tdsm.commandname") _
        .Calls(MyCustomCommandCallback)
End Sub

Public Shared Sub MyCustomCommandCallback(sender As ISender, args As ArgumentList)
    'Your implementation
End Sub

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
}

Namespaces

• tdsm.api
• tdsm.api.Plugin

Classes

• Tools
• HookPoints
• ArgumentList
• DataRegister
• HookContext
• HookOrder

Additional references for plugin developers (WIP)

Examples

• C# Bare bones plugin
• LUA plugin examples
• VB.NET Bare bones plugin