Menu System

The menu system is a component-based framework for per-player menus. A menu is an arrangement of components (APIIMenuComponent) drawn by a renderer (APIIMenuRenderer) and driven by a keymap, through Core.Menu (APIISwiftlyCore.Menu, type APIIMenuService).

Components describe what to show and how they react to actions; renderers decide how it looks. A menu opened as centre-screen HTML (the default) can be switched to chat lines by the server owner without any plugin change.

Quick Start

using SwiftlyS2.Shared.Menu;
using SwiftlyS2.Shared.Menu.Components;
 
var menu = Core.Menu.CreateMenu("myplugin.settings")
    .WithTitle("Settings")
    .Add(new ButtonComponent("Say hello", ctx =>
    {
        ctx.Player.SendChat("Hello!");
        return ValueTask.CompletedTask;
    }))
    .Add(new ToggleComponent("Show damage", defaultValue: true, onChanged: change =>
    {
        change.Player.SendChat($"Show damage: {change.NewValue}");
    }))
    .Build();
 
menu.Open(player);

1. Core.Menu.CreateMenu(id) starts an APIIMenuBuilder.
2. Configure it (With* methods) and add components to the header, body or footer.
3. Build() returns the APIIMenu. Open it with menu.Open(player) or menu.OpenForAll().

The menu id is also its configuration scope for key binds, renderer and input method (see Server Configuration). Namespace it with your plugin id, such as "myplugin.shop".

The Menu Service

APIIMenuService is your plugin's entry point. Everything you create or register through it belongs to your plugin and is released when the plugin unloads, so one plugin unloading never disturbs another plugin's menus.

A player has at most one open menu at a time, across every plugin. Opening a menu replaces the one they had.

Building a Menu

Every APIIMenuBuilder method returns the builder, except Build():

Only components with IsFocusable == true in the body can hold the selection. Non-focusable body entries (dividers, spacers, progress bars) scroll past.

Components

All built-in components live in SwiftlyS2.Shared.Menu.Components.

Every constructor also takes an optional trailing id (a stable id, generated when omitted).

Common Properties

These come from APIMenuComponentBase and apply to every built-in component:

Text-based components (APITextComponent and everything derived from it) also have Text, TextProvider (Func<IMenuSession, string?> for per-player text), Style (APIMenuTextStyle), DisabledColor, MaxWidth and Overflow. Overflow is a APIMenuTextOverflow: None, TruncateEnd, TruncateBothEnds, ScrollLeftFade, ScrollRightFade, ScrollLeftLoop or ScrollRightLoop.

Colours are hex strings such as "#FFD700".

Buttons

var close = new ButtonComponent("Apply and close", async ctx =>
{
    await SaveAsync(ctx.Player);
    ctx.Player.SendChat("Saved.");
})
{
    CloseOnSelect = true,
    FocusedColor = "#FFD700"
};

OnSelect is asynchronous: while it runs, the button draws WaitingText and ignores further presses from the same player. Set CloseOnSelect to close the menu once it finishes.

Per-Player Values

Value components (toggle, slider, choice, selector, input) keep their value in the player's session, so one component instance serves every player without their values touching. The value is gone when the menu closes: persist it in OnChanged and read it back with DefaultValueProvider.

var volume = new SliderComponent("Volume", min: 0, max: 100, defaultValue: 50, step: 10)
{
    TotalBars = 10,
    DefaultValueProvider = session => LoadVolume(session.Player),
    OnChanged = change => SaveVolume(change.Player, change.NewValue)
};
 
var quality = new ChoiceComponent("Quality", ["Low", "Medium", "High"], defaultIndex: 1,
    onItemChanged: change => Core.Logger.LogInformation("{Old} -> {New}", change.OldValue, change.NewValue));
 
var team = new SelectorComponent<string>("Team", ["T", "CT", "Spectator"]);

You can also read and write a player's value directly:

float current = volume.GetValue(session);
volume.SetValue(session, 80f); // returns true when the value actually changed

OnChanged receives a APIMenuValueChangedContext`1 with Session, Component, OldValue, NewValue and Player. For choice and selector components the underlying value is the index (OnChanged gets int), while OnItemChanged gets the item itself; GetItem(session) reads the current item.

Input

var nickname = new InputComponent(
    "Nickname",
    defaultValue: "",
    validator: value => value.Length >= 3,
    onChanged: change => change.Player.SendChat($"Nickname set to {change.NewValue}"))
{
    MaxLength = 24
};

Activating the component captures that player's next chat message as the value. The message never reaches the chat, and activating again while waiting cancels. Rejected values show InvalidText. Empty input is always rejected.

Progress Bars

var bar = new ProgressBarComponent(
    "Round progress",
    session => RoundProgress(),   // 0..1
    multiLine: true);

The bar polls ProgressProvider and redraws on its own whenever the number of filled segments changes, so you do not need to invalidate anything.

Submenus

var advanced = Core.Menu.CreateMenu("myplugin.advanced")
    .WithTitle("Advanced")
    .Add(new TextComponent("Nothing here yet"))
    .Build();
 
var main = Core.Menu.CreateMenu("myplugin.main")
    .WithTitle("Main")
    .Add(new SubmenuComponent("Advanced", advanced))
    .Add(new SubmenuComponent("Built on demand", session =>
        Core.Menu.CreateMenu("myplugin.lazy").WithTitle("Lazy").Build()))
    .Build();

A submenu without a parent of its own adopts the menu that opened it, so closing it returns the player there. The factory overloads (sync and ValueTask) can return null to cancel the open.

Dynamic Components

Components can be added to or removed from an open menu. Sessions redraw automatically.

var online = new TextComponent { TextProvider = _ => $"Players online: {Core.PlayerManager.PlayerCount}" };
menu.Insert(MenuRegion.Body, 0, online);
menu.Add(MenuRegion.Footer, new DividerComponent());
menu.Remove(online);
var body = menu.GetComponents(MenuRegion.Body);

Actions and Key Binds

Navigation is built from actions, each bound to a APIMenuKey. Every menu inherits the built-in actions from APIMenuActions:

APIMenuKey is a [Flags] enum, so one action can use several keys: MenuKey.E | MenuKey.Mouse1. Available keys: Mouse1, Mouse2, Space, Ctrl, W, A, S, D, E, Esc, R, Alt, Shift, Weapon1, Weapon2, Grenade1, Grenade2, Tab, F.

Custom Actions

WithAction declares an extra key for one menu. With a handler it runs regardless of which row is selected:

var menu = Core.Menu.CreateMenu("myplugin.shop")
    .WithTitle("Shop")
    .WithAction("Refresh", MenuKey.R, async ctx =>
    {
        await ReloadStockAsync();
        ctx.Session.Invalidate();
    }, label: "Reload")
    .Add(new ButtonComponent("Buy"))
    .Build();

• The key shows in the footer as label: KEY (the name is used when label is null).
• Declaring an action with the name of a built-in one (for example "Close") rebinds it for this menu only.
• The focused component is offered every action first (APIIMenuComponent.HandleActionAsync). The menu-level handler only runs when it does not consume the key.
• For full control use the APIMenuActionDescriptor overload (Id, DefaultKey, Label, ShowInFooter, Order).

Handlers receive a APIMenuActionContext with Action, Key, Session, Player and Menu.

Key Resolution

For each action the key is taken from the first source that answers, highest priority first:

Renderer and input method resolve the same way (APIIMenuRendererSource, APIIMenuInputMethodSource).

Input Methods

APIMenuInputMethod decides how players interact:

• Buttons - keyboard keys bound to actions, as above.
• Chat - players type !1, !2, ... to select the entry with that number on the current page, and !0 to close. Keyboard keys are ignored for that menu, and matching messages never reach the chat.

If you do not set one, menus drawn by the chat renderer use Chat and every other menu uses Buttons.

Renderers

var menu = Core.Menu.CreateMenu("myplugin.info")
    .WithRenderer(MenuRendererIds.Chat)
    .WithTitle("Info")
    .Build();

Components produce a tree of APIMenuNode values (MenuTextNode, MenuLineNode, MenuStackNode, MenuBlankNode, MenuSelectionNode, MenuRawNode) instead of markup, which is why every component works on every renderer. A plugin can add its own renderer, see Custom Renderers.

Custom Renderers

A renderer turns a composed frame into output and delivers it to the player. It never looks at concrete component types, only at APIMenuNode trees, so a custom renderer can draw every built-in component and every custom one.

Implementing IMenuRenderer

APIIMenuRenderer has an Id, a Render method and a Clear method:

using SwiftlyS2.Shared.Menu;
using SwiftlyS2.Shared.Players;
 
public sealed class PlainChatRenderer : IMenuRenderer
{
    public string Id => "myplugin.plain";
 
    public void Render(IMenuRenderContext context)
    {
        var frame = context.Frame;
        var player = context.Player;
 
        foreach (var node in frame.Header.Concat(frame.Body).Concat(frame.Footer))
        {
            foreach (var line in Flatten(node, context))
            {
                player.SendChat(line);
            }
        }
    }
 
    public void Clear(IPlayer player)
    {
        // Nothing persistent on screen, so nothing to remove.
    }
 
    private static IEnumerable<string> Flatten(MenuNode node, IMenuRenderContext context)
    {
        switch (node)
        {
            case MenuTextNode text:
                yield return text.Text;
                break;
 
            case MenuLineNode line:
                yield return string.Concat(line.Children.SelectMany(c => Flatten(c, context)));
                break;
 
            case MenuStackNode stack:
                foreach (var line in stack.Children.SelectMany(c => Flatten(c, context)))
                {
                    yield return line;
                }
                break;
 
            case MenuBlankNode blank:
                for (var i = 0; i < blank.Lines; i++)
                {
                    yield return " ";
                }
                break;
 
            case MenuSelectionNode selection:
                yield return selection.Focused ? ">" : " ";
                break;
 
            case MenuRawNode raw when raw.RendererId == "myplugin.plain":
                yield return raw.Payload;
                break;
 
            case MenuRawNode:
                break; // aimed at another renderer, ignore it
 
            default:
                context.ReportUnsupported(node);
                break;
        }
    }
}

Register it from your plugin, then select it by id like any other renderer:

public override void Load(bool hotReload)
{
    _renderer = Core.Menu.Renderers.Register(new PlainChatRenderer());
}
 
public override void Unload()
{
    _renderer?.Dispose(); // optional, released on unload anyway
}
 
var menu = Core.Menu.CreateMenu("myplugin.info")
    .WithRenderer("myplugin.plain")
    .WithTitle("Info")
    .Build();

• Register returns an IDisposable; disposing it removes the renderer. Registering an id that already exists replaces the old renderer.
• Registrations made through Core.Menu are released when your plugin unloads.
• Use a plugin-namespaced id ("myplugin.plain") so it never clashes with another plugin or with MenuRendererIds.
• A menu that asks for an unregistered id fails in Build(). The server owner can also force your renderer on any menu with "Renderer": "myplugin.plain" in menus.jsonc.

The Render Context

APIIMenuRenderContext carries everything a frame needs:

Header, Body and Footer

A frame is split into three regions. The split is made by the menu, never by the renderer: components are placed in a region when added (AddHeader / WithTitle, Add, AddFooter, or MenuRegion with menu.Add / menu.Insert), and the renderer receives one node list per region.

• Draw the regions top to bottom: header, body, footer. Keep the header and footer visible on every page.
• Only the body is paged. MaxVisibleLines and WithItemsPerPage limit body entries, so header and footer lines are extra.
• A region can be empty. Draw nothing for it, not a blank gap.
• Visibility is already applied: components hidden by Visible / VisibleWhen are absent from the lists.

By the time Render is called, focus, paging and visibility are already resolved. Frame.Body holds only the visible page, Frame.PageOffset is the index of its first entry and Frame.TotalItems the number of focusable entries across all pages, which is enough to draw a page indicator.

Node Types

Rules for a well-behaved renderer:

• Skip a node type you do not understand and call ReportUnsupported. Never throw, since new node types can appear.
• Map MenuTextSize (ExtraSmall to ExtraLarge) and colours onto whatever your output supports, or ignore them.
• Pair your renderer with an input method: menus drawn by the chat renderer default to MenuInputMethod.Chat, every other renderer defaults to Buttons. If your output shows !1, !2, ... numbers, call WithInputMethod(MenuInputMethod.Chat) on the menu, or add a WithInputMethodSource.
• Frames are sent only when a session is invalidated, so a renderer does not need its own refresh loop.
• Remove anything you keep on screen in Clear. It runs when the session closes.

Component Renderers

Components draw themselves through Render. To give one component type richer output on one particular renderer, implement APIIComponentRenderer and register it:

public sealed class SliderPlainRenderer : IComponentRenderer
{
    public string RendererId => "myplugin.plain";
    public Type ComponentType => typeof(SliderComponent); // derived types match too
 
    public bool TryRender(IMenuComponent component, IMenuComponentRenderContext context, out MenuNode? node)
    {
        var slider = (SliderComponent)component;
        node = new MenuTextNode($"{slider.Text}: {slider.GetValue(context.Session)}");
        return true;
    }
}
 
_componentRenderer = Core.Menu.Renderers.RegisterComponentRenderer(new SliderPlainRenderer());

• Return false from TryRender to fall back to the component's own Render.
• RendererId can be a built-in one (MenuRendererIds.Chat) to change how a component looks there. This is how a plugin teaches an existing renderer about a component it has never seen.
• APIIMenuComponentRenderContext gives Component, Menu, Session, Player, IsFocused, IsEnabled and RendererId.
• Without a matching component renderer the component's own output is used, so an unrecognised component is never an error.
• Like renderers, component renderers are released when your plugin unloads.

To target a renderer from inside a custom component instead, check context.RendererId in Render and return a MenuRawNode. Always return usable generic nodes when the id is not one you know.

Menus, Sessions and Events

APIIMenu is the shared definition; APIIMenuSession is one player's live view of it.

IMenu is IDisposable; disposing closes it for everyone and clears its components.

menu.Opened += session => Core.Logger.LogInformation("{Player} opened {Menu}", session.Player.PlayerID, session.Menu.Id);
menu.Closed += session => SaveSettings(session.Player);
menu.FocusChanged += session => { /* selection moved */ };

Writing a Custom Component

Derive from APIMenuComponentBase and override Render. Keep per-player data in session state, never on the component, so one instance can be shared across menus and players.

public sealed class CounterComponent : MenuComponentBase
{
    public override bool IsFocusable => true;
 
    public override MenuNode Render(IMenuComponentRenderContext context)
    {
        var count = context.Session.GetState<CounterState>(this).Count;
        var color = context.IsFocused ? "#FFD700" : "#FFFFFF";
        return new MenuTextNode($"Clicks: {count}", MenuTextStyle.Default.WithColor(color));
    }
 
    public override ValueTask<bool> HandleActionAsync(MenuActionContext context)
    {
        if (!Matches(context, MenuActions.Select))
        {
            return ValueTask.FromResult(false); // not ours, let the menu handle it
        }
 
        return ActivateAsync(context, ctx =>
        {
            ctx.Session.GetState<CounterState>(this).Count++;
            ctx.Session.Invalidate();
            return ValueTask.CompletedTask;
        });
    }
 
    private sealed class CounterState
    {
        public int Count { get; set; }
    }
}

• Return true from HandleActionAsync to consume the action; return false to let the menu navigate or close as usual.
• ActivateAsync runs your work through the shared pipeline: it honours Enabled, Validating and the busy/waiting state.
• Override LineCount when Render returns more than one line (a MenuStackNode costs the sum of its children, a MenuBlankNode its Lines). Otherwise the page is budgeted for one line and overflows.
• Override GetHint to show a hint while focused, and NeedsRedraw(session, now) for animated or live content (asked once per tick for every visible component, so keep it cheap).
• Return a MenuLineNode to put several styled parts on one line, and a MenuRawNode to aim output at one specific renderer id.

Server Configuration

Server owners tune menus in configs/menus/menus.jsonc. The file is optional and reloaded live; configs/menus/menus.example.jsonc ships as a template:

{
    "Menus": {
        // "Renderer": "centerhtml",   // for every menu
        // "InputMethod": "buttons",   // for every menu
        "core.menu": {
            "NavigateUp": "shift",
            "NavigateDown": "f",
            "NavigateLeft": "a",
            "NavigateRight": "d",
            "Select": "e",
            "Close": "tab"
        }
        // , "myplugin.shop": { "Renderer": "chat", "Select": ["e", "space"], "Close": "esc" }
    },
    "MenuLayout": { "MaxVisibleLines": 5 },
    "MenuSounds": {
        "Scroll": { "Name": "UI.ContractType", "Volume": 0.75 },
        "Select": { "Name": "Vote.Cast.Yes", "Volume": 0.75 },
        "Exit": { "Name": "Vote.Failed", "Volume": 0.75 },
        "Fail": { "Name": "Vote.Cast.No", "Volume": 0.75 }
    }
}

Key binds only apply to menus using the Buttons input method. An unregistered Renderer id makes that menu fail to build.

Common Pitfalls

• Give every menu a unique, plugin-namespaced id, or server key binds for one menu will apply to another.
• Do not store per-player data on a component; use session state or OnChanged/DefaultValueProvider.
• Call session.Invalidate() after changing anything displayed from outside a component.
• Declare LineCount on custom multi-line components.
• Keep NeedsRedraw and TextProvider cheap; they run every tick/frame.