Skip to content

Quick start

Every example on this page is a piece of one panel, a general store.

A component is a function whose name starts with a capital letter and whose return type is Component:

src/shop.ts2
const ShopInfo = (): Component => (
<SunkenBox>
<text x="center" y={12} w={{ fill: 16 }} h={48} font={Fonts.PLAIN}
text="This shop restocks every few minutes. Selling to it lowers what it pays."
align="center" shadow color={Colors.DIM} lineHeight={16} />
</SunkenBox>
);

Lowercase tags like <text> are ts2’s seven built-in elements. Capitalised tags like <SunkenBox> are components, and you nest them the same way:

src/shop.ts2
export const Shop = (): Component => (
<Window title="General Store">
<layer x={10} y={42} w={{ fill: 20 }} h={{ fill: 52 }}>
<ShopTabs />
<ShopContents />
<CoinPurse />
</layer>
</Window>
);

Window and SunkenBox aren’t part of ts2. They’re ordinary components, written in the project’s src/chrome.ts2.

A component returns one element. To return several, wrap them in a <layer>, or in <>…</> if you don’t want a container. Return null to draw nothing. Close every tag, and put expressions in braces:

src/shop.ts2
<text x="right" y="center" w={60} h={16} text={`${price} gp`} font={Fonts.PLAIN}
align="right" valign="middle" shadow color={Colors.AMBER} />

Every element takes x, y, w and h, as pixels or keywords:

src/shop.ts2
<layer x={10} y={42} w={{ fill: 20 }} h={{ fill: 52 }}>
x="left" | "center" | "right"anchored to an edge of the parent, or centred
y="top" | "center" | "bottom"the same, vertically
w="fill" / h="fill"as large as the parent
w="50%"half the parent
w={{ fill: 8 }}the parent, less 8 pixels
x={{ center: -20 }}centred, then shifted 20 left

Layout has the full set.

A component receives props through its one parameter, destructured and typed:

src/shop.ts2
const StockRow = ({ item, name, price, stock }: {
item: Item; name: String; price: Int; stock: Int;
}): Component => (
<layer x={6} w={{ fill: 12 }} h={ROW_H}>
…
<sprite x={0} y="center" w={36} h={32} item={item} itemCount={-1} />

You pass them like attributes:

src/shop.ts2
<StockRow item={row.item} name={row.name} price={row.price} stock={row.stock} y={4 + i * ROW_H} />

StockRow doesn’t declare y, so the y you pass goes onto the row’s root <layer>.

Use && to draw something or nothing:

src/shop.ts2
{stock > 0 && (
<text x={44} y={19} w={116} h={12} text={`${stock} in stock`} font={Fonts.SMALL}
valign="middle" shadow color={Colors.DIM} />
)}

Use ? : to choose between two things. Either arm may be null:

src/shop.ts2
{stock === 0
? (
<text x="right" y="center" w={60} h={16} text="Sold out" font={Fonts.PLAIN}
align="right" valign="middle" shadow color={Colors.RED} />
)
: (
<text x="right" y="center" w={60} h={16} text={`${price} gp`} font={Fonts.PLAIN}
align="right" valign="middle" shadow color={Colors.AMBER} />
)}

Write stock === 0, not !stock.

A constant array can hold records, and each field keeps its type:

src/shop.ts2
const STOCK = [
{ item: Items.BRONZE_DAGGER, name: 'Bronze dagger', price: 12, stock: 30 },
{ item: Items.IRON_SCIMITAR, name: 'Iron scimitar', price: 154, stock: 8 },
{ item: Items.OAK_SHORTBOW, name: 'Oak shortbow', price: 80, stock: 0 },
{ item: Items.ADAMANT_KITESHIELD, name: 'Adamant kiteshield', price: 5_440, stock: 2 },
];

.map() makes one component per entry:

src/shop.ts2
const BuyList = (): Component => (
<SunkenBox>
{STOCK.map((row, i) => (
<StockRow item={row.item} name={row.name} price={row.price} stock={row.stock} y={4 + i * ROW_H} />
))}
</SunkenBox>
);

.map() also runs over a list you declared or a table the game ships. Rendering lists covers the three kinds.

Pass a function to an event prop:

src/shop.ts2
<layer x={i * 79} y={0} w={74} h={22} onClick={() => { setTab(i); }}>

To make a component clickable, wrap it in a <layer> and put the handler there. Events lists every handler.

To read anything the server owns, use a hook:

src/shop.ts2
const CoinPurse = (): Component => {
const inventory = useInventory(Inventories.INVENTORY);
const coins = inventory.total(Items.COINS);

Use useServerState for game variables and useSkill for skills.

A cell holds state that belongs to your interface rather than the game, like which tab is open. If two components share it, declare it at the top of the file:

src/shop.ts2
const openTab = sessionState(0);

useState returns its value and a setter:

src/shop.ts2
const ShopContents = (): Component => {
const [tab] = useState(openTab);
return (
<layer x={0} y={28} w="fill" h={152}>
{tab === 0 && <BuyList />}
{tab === 1 && <SellList />}
{tab === 2 && <ShopInfo />}
</layer>
);
};

If only one component needs it, use useState(0). A sessionState lasts until the player logs out, and a persistedState is saved on the player’s device. Interface state has the details.

A function that returns a <ui> is an interface the game can open:

src/shop.ts2
const shopRef = createRef('docs-shop');
export const shopUi = (): UI => (
<ui ref={shopRef} w={252} h={260}>
<Shop />
</ui>
);

The string you give createRef is the interface’s name outside your code. w and h take the same keywords as a layer, measured against the box the interface opens into. Interfaces and slots covers the rest.

Read the chapters in order from Writing markup, or look anything up in the Reference.