api.text

TextApi

StarCraft's <XX> text control codes: what they mean, and what a string looks like drawn.

Bytes 0x01–0x1F in a string are colour and layout codes. This is the editor's own table of what each one does — the same one the String Editor's buttons and preview are drawn from — plus the reading of a string that turns those bytes into what the game shows.

A plugin that displays or rewrites map text should use this rather than carrying a copy: the numbering is easy to get wrong (the editor's own table was, from 0x12 up, until it was checked against the classic player palette).

Remastered

runs models Remastered's rule, where a colour set on one line carries onto the next. StarCraft 1.16.1 reset the colour at every line break, so a string written before the remaster can draw in colours its author never chose — bleedingLines finds exactly those lines and fixBleeding writes the reset the old game supplied. Pass resetPerLine to runs to see the old rendering.

The other thing the old game did and a modern renderer does not is honour every alignment code on a line, stacking the pieces between them in one place: stackedLines finds those lines and flattenStacks lays them out left to right. runs is one of the renderers that cannot show them — TextLine.align is one alignment for the whole line.

codes
code
insertable
defaultColor
runs
plain
escape
bleedingLines
fixBleeding
stackedLines
flattenStacks

Members

codes

codes(): TextCode[];

Every byte the game gives a meaning, in order; rgb is set for the colours only.

code

code(byte: number): TextCode | null;

One byte's meaning, or null for a byte the game ignores.

insertable

insertable(): TextCode[];

The codes worth offering as buttons: no tab, newlines or the do-nothing byte.

defaultColor

defaultColor(): string;

#rrggbb — what the game starts a string in, and what 1.16.1 reset to at a line break.

runs

runs(text: string, options?: RunOptions): TextLine[];

The string split into lines of coloured runs, the way the game draws it.

plain

plain(text: string): string;

The text with every control byte removed — what the string actually says.

escape

escape(byte: number): string;

<0E>, the way every StarCraft editor writes a control byte.

bleedingLines

bleedingLines(text: string): BleedingLine[];

The lines of text that Remastered draws in a colour 1.16.1 did not: a line that sets no colour of its own, after one that left a colour set. Empty for a single-line string.

fixBleeding

fixBleeding(text: string): string;

text with the default colour written at the head of every bleeding line, so both games draw it alike. Idempotent, and never changes what the string says.

stackedLines

stackedLines(text: string): StackedLine[];

The lines of text that 1.16.1 drew at more than one alignment at once — the "stacked" lobby and unit names a classic map is built with. A line whose only alignment code sits at its head is not one: that code places the line.

flattenStacks

flattenStacks(text: string): string;

text with every stacked line laid out left to right: the alignment codes that split it dropped and its pieces joined in writing order, a space between two that would otherwise run together. Colours and every other byte survive, so nothing the string says is lost — only where each piece sat. Idempotent.

Types

Declarations only this group names.

CodeEffecttype

type CodeEffect = "color" | "mimic" | "invisible" | "align" | "clip" | "nothing" | "space";

What a control byte does. Colours carry an rgb; the rest are layout or visibility.

TextCodeinterface

interface TextCode

`byte: number`
`code: string`	`<0E>`, the way every StarCraft editor writes it.
`label: string`
`effect: CodeEffect`
`rgb: string \| null`	`#rrggbb` for `effect: "color"`, else null.
`player?: number`	Which player's colour this is, for the ones that are a player colour (1-based).

Aligntype

type Align = "left" | "right" | "center";

TextRuninterface

interface TextRun

One stretch of text in a single colour.

`text: string`
`color: string`	`#rrggbb`; the default colour until a code says otherwise.
`invisible: boolean`	After `<0B>` / `<14>`: the game draws nothing, but the text is still there.
`clipped: boolean`	After `<0C>` in the large font: the rest of the line is dropped.

TextLineinterface

interface TextLine

`runs: TextRun[]`
`align: Align`

RunOptionsinterface

interface RunOptions

`resetPerLine?: boolean`	Reset to `DEFAULT_TEXT_COLOR` at every newline, the way 1.16.1 did. Remastered carries the colour across, which is the default here.
`initialColor?: string`	What `<01>` mimics and what the string starts in.

BleedingLineinterface

interface BleedingLine

`line: number`	0-based index of the line that inherits a colour it did not set.
`carried: TextCode`	The code Remastered carries onto it — the whole entry, so a caller can name it.

StackedLineinterface

interface StackedLine

A line the game draws in more than one place at once. 0x12 and 0x13 move the text that follows them to the right or the centre of the line they are on, and 1.16.1 honoured every one of them: Name<12>by Author drew Name at the left and by Author at the right of the same line. Lobby names, unit names and briefings were built out of that — the "stacked" text a classic map shows and a renderer that takes one alignment for the whole line does not.

runsOf is one of those renderers: TextLine.align holds a single alignment, the last one the line set, so every piece before it lands somewhere its author did not choose.

`line: number`	0-based index of the line within the string.
`pieces: number`	How many pieces of text the line draws, each at its own alignment.

Seen in

Repairchecking a file on open and repairing it