Interfaces and slots

What the game opens is an interface: a <ui> returned from a function, hosting a component. The examples on this page build a trading post with two slots.

A <ui> is a definition

src/integrating.ts2

export const tradingPostUi = (): UI => (
  <ui ref={tradingPostRef} w={252} h={200} x="center" y="center">
    <TradingPost />
  </ui>
);

The return type is UI. Size a <ui> and its slots with numbers or plain constants, such as w={PLATE_W}.

The ref is the name

A createRef at module scope, bound to the <ui>, names it:

src/integrating.ts2

export const tradingPostRef = createRef('docs-integrating');

The server opens the interface by that string.

Geometry against the box it opens into

w, h, x and y on a <ui> take the layout keywords, measured against the box the interface opens into: w={{ fill: 24 }} is that box less 24, x="right" sits on its right edge.

src/integrating.ts2

<ui ref={tradingPostRef} w={252} h={200} x="center" y="center">

The default position is the top-left corner, so a fixed-size panel needs x="center" y="center".

static: a real component in the definition

Mark an element static and the server can address it, another interface can open into it, and another file can name it through its ref. A static <layer> holding one component, or nothing, is a slot:

src/integrating.ts2

<layer static ref={walletSlot} x={12} y={44} w={88} h={126}>
  <Wallet />
</layer>

src/integrating.ts2

<layer static ref={offerSlot} x={112} y={44} w={128} h={126} />

offerSlot stays empty until an interface opens into it. A slot’s position takes the layout keywords; its size is pixels, or left off to fill the interface. Put slots inside the window’s chrome, as the trading post does.

static on any element

static works on any element:

src/integrating.ts2

<rect static ref={offerWash} x="center" y="center" w={{ fill: 4 }} h={{ fill: 4 }}
      color={Colors.AMBER} fill transparency={200} hide />

The server can now show the rect.

A ref names one component across the project

Export a slot’s ref and any file can address that component:

src/integrating.ts2

export const walletSlot = createRef('docs-integrating:wallet');
export const offerSlot = createRef('docs-integrating:offer');

An importing file may pass the ref as a prop, write through it, or use it as a hook’s host. Refs has the rest.

Which interface am I?

interfaceOf(ref) is the interface id of a ref bound on a <ui> or a static element. Use it to check a value the server sends:

src/integrating.ts2

export const isTradingPost = (frame: Int): Boolean => frame === interfaceOf(tradingPostRef);