Skip to content

API Integration

shmitzas edited this page Nov 10, 2026 · 1 revision

API Integration

How to show panels from another plugin, and how to style its menus for CustomHUD. Every member and directive is on API Reference.


1. Reference the contract

Only the Panels API needs a reference; directives need none. CustomHUD.Contract.dll is in the CustomHUD release, under resources/exports/, and names only .NET types.

<Reference Include="CustomHUD.Contract">
  <HintPath>path\to\CustomHUD.Contract.dll</HintPath>
  <Private>false</Private>
</Reference>

Private must be false. SwiftlyS2 loads the copy in CustomHUD's resources/exports/, and a second copy beside your plugin gives the interface a second identity: it stops matching, with no build error.


2. Get the interface

Shared interfaces do not exist yet in Load. Get it in UseSharedInterface, which SwiftlyS2 runs again whenever any plugin loads or unloads, and assign on every path, so a reference to an unloaded CustomHUD never lingers.

private ICustomHudPanels? _panels;

public override void UseSharedInterface(IInterfaceManager im)
{
    _panels = im.TryGetSharedInterface<ICustomHudPanels>(ICustomHudPanels.InterfaceKey, out var panels)
        ? panels
        : null;
}

When CustomHUD is optional

On a server without CustomHUD the contract DLL is missing, and the runtime throws as soon as it prepares a method that names a contract type. The exception lands in the calling method, where a try inside the failing method cannot catch it, and one escaping the handshake brings down the SwiftlyS2 host.

  1. Name contract types in one file only, and mark every member there that touches one [MethodImpl(MethodImplOptions.NoInlining)].
  2. Keep the instance in an object? field, and give the rest of the plugin a bool to check.
  3. Put the try/catch around the calls into that file.
// HudPanels.cs: the only file naming CustomHUD.Contract types.
internal sealed class HudPanels
{
    private object? _panels;

    public bool IsAvailable => _panels is not null;

    [MethodImpl(MethodImplOptions.NoInlining)]
    public void Bind(IInterfaceManager im)
    {
        _panels = im.TryGetSharedInterface<ICustomHudPanels>(ICustomHudPanels.InterfaceKey, out var panels)
            ? panels
            : null;
    }

    [MethodImpl(MethodImplOptions.NoInlining)]
    public bool ShowReady(int playerId, string count) =>
        ((ICustomHudPanels)_panels!).Show(playerId, "ready", new Dictionary<string, string>
        {
            ["title"] = "Waiting for players",
            ["count"] = count,
        }, ["not-ready"]);
}
// The plugin
public override void UseSharedInterface(IInterfaceManager im)
{
    try
    {
        _hud.Bind(im);
    }
    catch (Exception ex)
    {
        Core.Logger.LogDebug(ex, "CustomHUD is not installed.");
    }
}

3. Show a panel

if (_hud.IsAvailable) _hud.ShowReady(player.PlayerID, "7/10");

The ready panel shows Waiting for players and 7/10, styled as not ready, until hidden.

  • Call from any thread; the panel draws on the next tick.
  • A later Show with only count updates the count and keeps the title.
  • Send durationSeconds for a panel that hides itself, or call Hide — HideEverywhere("ready") once the match starts.
  • A panel shows only for a player with a SteamID, and only where the player's Workshop addon has its layout. Show returns true either way.
  • Use the variables and classes the panel's layout declares — Shipped panels.

4. Style your menus

A plugin needs no reference to style its menus for CustomHUD: it sends directives in a MenuRawNode addressed to customhud.panorama, which every other renderer ignores.

internal sealed class VipButton(string text, Func<MenuActionContext, ValueTask> onSelect)
    : ButtonComponent(text, onSelect)
{
    public override MenuNode Render(IMenuComponentRenderContext context)
    {
        var node = base.Render(context);
        var raw = new MenuRawNode("customhud.panorama", "glyph=crown;tag=VIP;tagtone=gold");
        return node is MenuLineNode line
            ? line with { Children = [.. line.Children, raw] }
            : MenuLineNode.Of(node, raw);
    }
}

On CustomHUD the button gets a crown and a gold VIP pill; centre-screen HTML and chat draw the plain button.

  • Append the raw node to the component's own line, never wrap the line in another: CustomHUD reads the value from the line's first text node.
  • Replace ; and tabs in any text you put in a directive. ; ends the value, and a tab starts the next column.
  • Give every menu an id that starts with your plugin's name, such as myplugin.shop. Operators target menus by id, and the first part names your plugin's eyebrow.

5. Designed pages

CustomHUD can draw a plugin's menus as designed pages without the plugin depending on it, reading figures from the plugin's own API. That needs, from the plugin:

  1. Menu ids with the plugin's prefix, as above.
  2. Each row's Tag set to the item it stands for, and an item's own page carrying that item as IMenu.Tag.
  3. A public shared interface exposing, read-only, what a page shows: prices, ownership, live counts.

Then open a plugin menu support request.


Checklist

  • CustomHUD.Contract referenced with Private="false"
  • Acquired in UseSharedInterface, assigning on every path
  • With CustomHUD optional: one file names contract types, the field is object?, members are NoInlining, the try/catch is at the call site
  • Panel variables and classes match the panel's layout
  • Panels hidden when their moment ends, or given a duration
  • Directives appended to the component's own line
  • ; and tabs replaced in directive text
  • Menu ids start with your plugin's name

Clone this wiki locally