UnifierTSL 0.0.5

UnifierTSL

An experiment-friendly Terraria server launcher built on OTAPI USP, bundling per-instance consoles, early publishing helpers, and plugin scaffolding.

What is UnifierTSL?

UnifierTSL is a plugin framework for Terraria servers that enables:

• Multi-world hosting in a single process
• Hot-reloadable plugin system with dependency management
• Shared event hub for cross-server coordination
• Dedicated console isolation per server instance

Installation

dotnet add package UnifierTSL

Quick Start for Plugin Developers

1. Create Your Plugin

using System;
using System.Collections.Immutable;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Xna.Framework;
using UnifierTSL;
using UnifierTSL.Events.Core;
using UnifierTSL.Events.Handlers;
using UnifierTSL.Logging;
using UnifierTSL.Plugins;

[assembly: CoreModule]

namespace MyPlugin
{
    [PluginMetadata("MyPlugin", "1.0.0", "Author", "My awesome plugin")]
    public sealed class Plugin : BasePlugin, ILoggerHost
    {
        readonly RoleLogger logger;

        public Plugin()
        {
            logger = UnifierApi.CreateLogger(this);
        }

        public string Name => "MyPlugin";
        public string? CurrentLogCategory => null;

        public override Task InitializeAsync(
            IPluginConfigRegistrar registrar,
            ImmutableArray<PluginInitInfo> prior,
            CancellationToken cancellationToken = default)
        {
            // Hook into UnifierApi.EventHub
            UnifierApi.EventHub.Chat.MessageEvent.Register(OnChatMessage, HandlerPriority.Normal);
            logger.Info("MyPlugin initialized!");
            return Task.CompletedTask;
        }

        public override ValueTask DisposeAsync(bool isDisposing)
        {
            if (isDisposing)
            {
                UnifierApi.EventHub.Chat.MessageEvent.UnRegister(OnChatMessage);
            }
            return ValueTask.CompletedTask;
        }

        static void OnChatMessage(ref ReadonlyEventArgs<MessageEvent> args)
        {
            if (!args.Content.Sender.IsClient)
                return;

            if (args.Content.Text.Trim().Equals("!hello", StringComparison.OrdinalIgnoreCase))
            {
                args.Content.Sender.Chat("Hello from MyPlugin!", Color.LightGreen);
                args.Handled = true;
            }
        }
    }
}

2. Key Features for Plugin Authors

Module System

• [CoreModule]: Mark your main plugin assembly
• [RequiresCoreModule("Name")]: Create dependent modules
• [ModuleDependencies]: Declare NuGet or embedded dependencies

Configuration Management

var configHandle = registrar
    .CreateConfigRegistration<MyConfig>("config.json")
    .WithDefault(() => new MyConfig { Enabled = true })
    .TriggerReloadOnExternalChange(true)
    .Complete();

MyConfig config = await configHandle.RequestAsync(cancellationToken);

Logging

// Plugin should implement ILoggerHost
var logger = UnifierApi.CreateLogger(this);
logger.Info("Plugin initialized");
logger.Warning("This is a warning");
logger.Error("An error occurred", exception: ex);

Event Hub Access event providers through UnifierApi.EventHub domains:

• Game: PreUpdate, PostUpdate, GameHardmodeTileUpdate
• Chat: ChatEvent, MessageEvent
• Netplay: ConnectEvent, ReceiveFullClientInfoEvent, LeaveEvent
• Coordinator: SwitchJoinServerEvent, PreServerTransfer, PostServerTransfer
• Server: CreateConsoleService, AddServer, RemoveServer

3. Build and Deploy

Build your plugin as a class library targeting net9.0:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="UnifierTSL" Version="*" />
  </ItemGroup>
</Project>

Drop the compiled DLL into the server's plugins/ directory.

Package Contents

This NuGet package includes:

• Core Runtime: UnifierTSL.dll - Launcher, orchestration services, module loader, event hub, and plugin host
• TrProtocol: Network packet definitions (IL-merged from USP) for type-safe packet handling
• Event System: Zero-allocation, priority-ordered event providers with handler management
• Module System: Collectible assembly loading with hot-reload support and automatic dependency extraction
• Logging Infrastructure: Structured logging with metadata injection and per-server console routing
• Configuration Service: Hot-reloadable config management with file watching and error policies

Documentation

• Plugin Development Guide
• Developer Overview
• Full README

Requirements

• .NET 9.0 or later
• OTAPI USP 1.0.13+
• Supported platforms: Windows, Linux (x64/ARM), macOS

License

GPL-3.0 - See LICENSE for details

Links

• GitHub Repository
• Issue Tracker
• OTAPI USP