Repository navigation
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.
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.
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.ps1rebuilds the contracts of the supported plugins from sibling repositories. Add the new plugin's project to its list.
| 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.
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.
Each view a page draws as is a class on the page, view-shop-grid for the view shop-grid.
- Write
resources/panorama/styles/custom_game/customhud/locker_<plugin>.vcss, with a rule per view:.lk.view-shop-grid .lk-slot. - Add
locker_<plugin>to the stylesheet lists inscripts/generate-locker-layout.ps1, both of them, and inscripts/generate-v2-sheets.ps1. - Regenerate with PowerShell 7:
scripts/generate-v2-sheets.ps1, thenscripts/generate-locker-layout.ps1. - Compile with
scripts/watch-panorama.ps1 -Once.
The stylesheet rules list what CS2 draws and what it silently drops.
When the page locker cannot draw what the plugin needs:
- Write
resources/panorama/layout/custom_game/customhud/<layout>.vxmland its stylesheet. A layout holds onlyPanel,Label,ImageandButton. - Write its profile in C#, naming every panel and variable the layout declares.
LockerProfilesandListProfilesare the models. - Name it in
BuiltInLayouts: a mouse layout inLockers, by plugin, a keyboard one inKeyboardLayouts. Make it the plugin's default inMenuChoices.
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
|
- Run
pwsh -File scripts/audit.ps1until it printsPASS. It checks the stylesheets, both languages, the soft dependency and the wiki. - In game, check every page in mouse mode and as the keyboard list, with the plugin installed and without it.
- Add the plugin to Supported Plugins and to the
Menustable in Configuration, and to the repository'sdocs/PluginIntegration.md,docs/DesignLanguage.mdanddocs/TestingGuide.md. - Ship
build/CustomHUD.zip, and republish the Workshop addon: a new stylesheet or layout reaches players only through it.
- The plugin's API exposes what its pages show, and its rows carry their items as
Tag - Contract in
lib/, referenced withPrivate="false" - Prefix in
BuiltInLayouts, profile inLockerProfilesandPageLockers, list inListProfiles.Plugins(), entry inMenuChoices - Integration with
TryCreate,OwnsandDraw, bound inIntegrationHost.Bind - No contract type outside the integration, and no
awaiton the plugin's tasks - Views styled in
locker_<plugin>.vcss, listed in both generators, regenerated and compiled - Every string in
en.jsoncandlt.jsonc - Audit
PASS, checked in game, docs updated, addon republished