Skip to content

Integrating A Plugin

shmitzas edited this page Nov 12, 2026 · 1 revision

Integrating a Plugin

The steps that turned ShopCore's menus into designed pages, for another plugin. This is work in CustomHUD's own source: clone the repository and build it as Building shows. The plugin itself needs no change, as long as its API exposes what its pages show.

  • A plugin you maintain can style its own menus with directives instead, with no change to CustomHUD — API Integration.
  • A plugin with no API, such as MixScrims, takes steps 3, 5 and 6 only: its views come from its menu ids, and it sends its own directives.

1. Read the plugin's API

Designed pages read the plugin's public API, never anything it sends the renderer. Check that it has:

Needs ShopCore
A shared interface IShopCoreApiV2, key ShopCore.API.v2
Menu ids that share a prefix shopcore.
Each row's Tag: the item the row stands for ShopItemDefinition
An item page's IMenu.Tag: that item ShopItemDefinition, on shopcore.buy.item
Read-only members for what a page shows GetCredits, GetItemState, GetSellPrice

A plugin missing one of these needs it added there first, by its author.


2. Reference the contract

Copy the plugin's contract assembly into lib/, and reference it in CustomHUD.csproj:

<Reference Include="ShopCore.Contract" HintPath="lib/ShopCore.Contract.dll" Private="false" />
  • Private="false" keeps the contract out of CustomHUD's zip. The plugin ships its own copy, and a second copy is a second type that never resolves.
  • scripts/update-contracts.ps1 rebuilds the contracts of the supported plugins from sibling repositories. Add the new plugin's project to its list.

3. Register the plugin

File Add ShopCore
src/Config/BuiltInLayouts.cs Its menu id prefixes, in Plugins ("ShopCore", ["shopcore."])
src/Config/LockerProfiles.cs Its page profile: eyebrow, a view per menu id, sidebar icons Shop()
src/Config/BuiltInLayouts.cs That profile, in PageLockers ["ShopCore"] = Pages(Named(LockerProfiles.Shop(), name))
src/Config/ListProfiles.cs Its keyboard list, in Plugins() ["ShopCore"] = Keys("shop")
src/Config/MenuChoices.cs A property with its default layouts, and its case in For ShopCore = MenuChoice.Locker()

The new Menus entry appears in every server's config.jsonc at its next start.


4. Draw its pages

Create src/Integrations/<Plugin>/<Plugin>Integration.cs:

internal sealed class ShopIntegration(IShopCoreApiV2 api) : IPageIntegration
{
    public string Provider => "ShopCore";

    [MethodImpl(MethodImplOptions.NoInlining)]
    public static IPageIntegration? TryCreate(IInterfaceManager interfaces)
    {
        ApiProbe.Require(typeof(IShopCoreApiV2), "ShopCore 1.1.9", nameof(IShopCoreApiV2.GetSellPrice));
        return interfaces.TryGetSharedInterface<IShopCoreApiV2>("ShopCore.API.v2", out var api) && api is not null
            ? new ShopIntegration(api)
            : null;
    }

    public bool Owns(IMenu menu) => menu.Id.StartsWith("shopcore.", StringComparison.Ordinal);

    public string? RegionOf(IMenu menu, IMenuComponent component) => null;

    public void Draw(PageDraw page)
    {
        var credits = api.GetCredits(page.Player);
        page.AddHeader($"{Directive.Money(credits)}\t{page.Text("customhud.shop.credits")}", "chip=gold;glyph=credits");
        for (var k = 0; k < page.Components.Count; k++)
            if (page.Components[k] is MenuComponentBase { Tag: ShopItemDefinition item })
                page.Draw(k, $"{Directive.Clean(api.GetItemDisplayName(page.Player, item))}\t{Directive.Money(item.Price)}", "vglyph=credits");
    }
}

The balance becomes a chip over the page, and each item a row with its price beside the credits icon.

Then bind it in IntegrationHost.Bind, beside the others:

Create("ShopCore", "ShopCore.API.v2", interfaces, ShopIntegration.TryCreate),
Rule Why
No type but the integration names a contract type SwiftlyS2 loads every type in CustomHUD.dll, so one that needs a missing contract stops CustomHUD on every server without the plugin. The audit's soft-dependency check catches it
No async method awaits the plugin's tasks; load through page.TryLoad An await compiles to a type that holds the contract
TryCreate checks the members it reads with ApiProbe.Require An older plugin logs one line and draws as plain rows, rather than failing mid-page
Every word goes through page.Text("customhud.<plugin>.<key>") Players read it in their language

What each directive draws: Directives, and in full in What a Page Sends.


5. Style its views

Each view a page draws as is a class on the page, view-shop-grid for the view shop-grid.

  1. Write resources/panorama/styles/custom_game/customhud/locker_<plugin>.vcss, with a rule per view: .lk.view-shop-grid .lk-slot.
  2. Add locker_<plugin> to the stylesheet lists in scripts/generate-locker-layout.ps1, both of them, and in scripts/generate-v2-sheets.ps1.
  3. Regenerate with PowerShell 7: scripts/generate-v2-sheets.ps1, then scripts/generate-locker-layout.ps1.
  4. Compile with scripts/watch-panorama.ps1 -Once.

The stylesheet rules list what CS2 draws and what it silently drops.

A layout of its own

When the page locker cannot draw what the plugin needs:

  1. Write resources/panorama/layout/custom_game/customhud/<layout>.vxml and its stylesheet. A layout holds only Panel, Label, Image and Button.
  2. Write its profile in C#, naming every panel and variable the layout declares. LockerProfiles and ListProfiles are the models.
  3. Name it in BuiltInLayouts: a mouse layout in Lockers, by plugin, a keyboard one in KeyboardLayouts. Make it the plugin's default in MenuChoices.

6. Translate

Add every string to both resources/translations/en.jsonc and lt.jsonc:

Key Holds
customhud.eyebrow.<eyebrow> The plugin's name over its pages: customhud.eyebrow.shop
customhud.<plugin>.<key> Every word its pages draw: customhud.shop.credits

7. Check and ship

  1. Run pwsh -File scripts/audit.ps1 until it prints PASS. It checks the stylesheets, both languages, the soft dependency and the wiki.
  2. In game, check every page in mouse mode and as the keyboard list, with the plugin installed and without it.
  3. Add the plugin to Supported Plugins and to the Menus table in Configuration, and to the repository's docs/PluginIntegration.md, docs/DesignLanguage.md and docs/TestingGuide.md.
  4. Ship build/CustomHUD.zip, and republish the Workshop addon: a new stylesheet or layout reaches players only through it.

Checklist

  • The plugin's API exposes what its pages show, and its rows carry their items as Tag
  • Contract in lib/, referenced with Private="false"
  • Prefix in BuiltInLayouts, profile in LockerProfiles and PageLockers, list in ListProfiles.Plugins(), entry in MenuChoices
  • Integration with TryCreate, Owns and Draw, bound in IntegrationHost.Bind
  • No contract type outside the integration, and no await on the plugin's tasks
  • Views styled in locker_<plugin>.vcss, listed in both generators, regenerated and compiled
  • Every string in en.jsonc and lt.jsonc
  • Audit PASS, checked in game, docs updated, addon republished

Clone this wiki locally