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.

codes
code
insertable
defaultColor
runs
plain
escape
bleedingLines
fixBleeding

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.

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.

Seen in

Repairchecking a file on open and repairing it