api.consts

ConstsApi

Bit masks, special unit ids and the pixels-per-tile every record is written in.

The constants a plugin needs to write a record rather than read one: the bit masks in a UNIT / THG2 / MRGN record, the condition, action and argument numbers of a TRIG / MBRF one, the few unit ids the game itself treats specially, and the one conversion — 32 pixels to a tile — every object position goes through.

They are the editor's own (sections/objects.ts, editor/units.ts) and they arrive here at run time rather than in the typings on purpose: @scm-js/plugin-api is erased before the loader ever sees the specifier, so a value imported from that package type-checks and is then undefined. Anything a plugin needs while it runs has to come off api. Without this a plugin writes the hex itself, which is how a sprite's kind came to be read as flags & 0x1000 in three places.

tile
unit
sprite
location
triggers
isResource

Members

tile

readonly tile: 32;

Map pixels to a tile. UNIT and THG2 store pixels; MTXM, MRGN and the brushes count tiles.

unit

readonly unit: UnitConsts;

UNIT: the special unit ids, the default resource amounts, and the record's four bit masks.

sprite

readonly sprite: SpriteConsts;

THG2: the sprite record's flag word.

location

readonly location: LocationConsts;

MRGN: the Anywhere slot, and the elevation bits.

triggers

readonly triggers: TriggerConsts;

TRIG / MBRF: the condition and action types, and the enumerated arguments.

isResource

isResource(unitId: number): boolean;

Whether a unit type is a mineral field or a vespene geyser.

Types

Declarations only this group names.

ConditionTypeconst

const ConditionType: {
	readonly None: 0;
	readonly CountdownTimer: 1;
	readonly Command: 2;
	readonly Bring: 3;
	readonly Accumulate: 4;
	readonly Kill: 5;
	readonly CommandTheMost: 6;
	readonly CommandTheMostAt: 7;
	readonly MostKills: 8;
	readonly HighestScore: 9;
	readonly MostResources: 10;
	readonly Switch: 11;
	readonly ElapsedTime: 12;
	readonly Briefing: 13;
	readonly Opponents: 14;
	readonly Deaths: 15;
	readonly CommandTheLeast: 16;
	readonly CommandTheLeastAt: 17;
	readonly LeastKills: 18;
	readonly LowestScore: 19;
	readonly LeastResources: 20;
	readonly Score: 21;
	readonly Always: 22;
	readonly Never: 23;
}

ActionTypeconst

const ActionType: {
	readonly None: 0;
	readonly Victory: 1;
	readonly Defeat: 2;
	readonly PreserveTrigger: 3;
	readonly Wait: 4;
	readonly PauseGame: 5;
	readonly UnpauseGame: 6;
	readonly Transmission: 7;
	readonly PlayWav: 8;
	readonly DisplayText: 9;
	readonly CenterView: 10;
	readonly CreateUnitWithProperties: 11;
	readonly SetMissionObjectives: 12;
	readonly SetSwitch: 13;
	readonly SetCountdownTimer: 14;
	readonly RunAiScript: 15;
	readonly RunAiScriptAt: 16;
	readonly LeaderboardControl: 17;
	readonly LeaderboardControlAt: 18;
	readonly LeaderboardResources: 19;
	readonly LeaderboardKills: 20;
	readonly LeaderboardPoints: 21;
	readonly KillUnit: 22;
	readonly KillUnitAt: 23;
	readonly RemoveUnit: 24;
	readonly RemoveUnitAt: 25;
	readonly SetResources: 26;
	readonly SetScore: 27;
	readonly MinimapPing: 28;
	readonly TalkingPortrait: 29;
	readonly MuteUnitSpeech: 30;
	readonly UnmuteUnitSpeech: 31;
	readonly LeaderboardComputerPlayers: 32;
	readonly LeaderboardGoalControl: 33;
	readonly LeaderboardGoalControlAt: 34;
	readonly LeaderboardGoalResources: 35;
	readonly LeaderboardGoalKills: 36;
	readonly LeaderboardGoalPoints: 37;
	readonly MoveLocation: 38;
	readonly MoveUnit: 39;
	readonly LeaderboardGreed: 40;
	readonly SetNextScenario: 41;
	readonly SetDoodadState: 42;
	readonly SetInvincibility: 43;
	readonly CreateUnit: 44;
	readonly SetDeaths: 45;
	readonly Order: 46;
	readonly Comment: 47;
	readonly GiveUnits: 48;
	readonly ModifyHitPoints: 49;
	readonly ModifyEnergy: 50;
	readonly ModifyShields: 51;
	readonly ModifyResourceAmount: 52;
	readonly ModifyHangarCount: 53;
	readonly PauseTimer: 54;
	readonly UnpauseTimer: 55;
	readonly Draw: 56;
	readonly SetAllianceStatus: 57;
	readonly DisableDebugMode: 58;
	readonly EnableDebugMode: 59;
}

BriefingActionTypeconst

const BriefingActionType: {
	readonly None: 0;
	readonly Wait: 1;
	readonly PlayWav: 2;
	readonly TextMessage: 3;
	readonly MissionObjectives: 4;
	readonly ShowPortrait: 5;
	readonly HidePortrait: 6;
	readonly DisplaySpeakingPortrait: 7;
	readonly Transmission: 8;
	readonly SkipTutorialEnabled: 9;
}

PlayerGroupconst

const PlayerGroup: {
	readonly Player1: 0;
	readonly Player2: 1;
	readonly Player3: 2;
	readonly Player4: 3;
	readonly Player5: 4;
	readonly Player6: 5;
	readonly Player7: 6;
	readonly Player8: 7;
	readonly Player9: 8;
	readonly Player10: 9;
	readonly Player11: 10;
	readonly Player12: 11;
	readonly None: 12;
	readonly CurrentPlayer: 13;
	readonly Foes: 14;
	readonly Allies: 15;
	readonly NeutralPlayers: 16;
	readonly AllPlayers: 17;
	readonly Force1: 18;
	readonly Force2: 19;
	readonly Force3: 20;
	readonly Force4: 21;
	readonly Unused1: 22;
	readonly Unused2: 23;
	readonly Unused3: 24;
	readonly Unused4: 25;
	readonly NonAlliedVictoryPlayers: 26;
}

Comparisonconst

const Comparison: {
	readonly AtLeast: 0;
	readonly AtMost: 1;
	readonly Exactly: 10;
}

SwitchStateconst

const SwitchState: {
	readonly Set: 2;
	readonly Cleared: 3;
}

SwitchActionconst

const SwitchAction: {
	readonly Set: 4;
	readonly Clear: 5;
	readonly Toggle: 6;
	readonly Randomize: 11;
}

SetModifierconst

const SetModifier: {
	readonly SetTo: 7;
	readonly Add: 8;
	readonly Subtract: 9;
}

UnitStateconst

const UnitState: {
	readonly Enable: 4;
	readonly Disable: 5;
	readonly Toggle: 6;
}

Orderconst

const Order: {
	readonly Move: 0;
	readonly Patrol: 1;
	readonly Attack: 2;
}

AllianceStatusconst

const AllianceStatus: {
	readonly Enemy: 0;
	readonly Ally: 1;
	readonly AlliedVictory: 2;
}

ResourceTypeconst

const ResourceType: {
	readonly Ore: 0;
	readonly Gas: 1;
	readonly OreAndGas: 2;
}

ScoreTypeconst

const ScoreType: {
	readonly Total: 0;
	readonly Units: 1;
	readonly Buildings: 2;
	readonly UnitsAndBuildings: 3;
	readonly Kills: 4;
	readonly Razings: 5;
	readonly KillsAndRazings: 6;
	readonly Custom: 7;
}

UnitClassconst

const UnitClass: {
	readonly Any: 228;
	readonly Men: 229;
	readonly Buildings: 230;
	readonly Factories: 231;
}

ConditionFlagconst

const ConditionFlag: {
	/** Game bookkeeping. */
	readonly Unknown: 1;
	readonly Disabled: 2;
	readonly AlwaysDisplay: 4;
	readonly UnitPropertiesUsed: 8;
	readonly UnitTypeUsed: 16;
	readonly UnitIdUsed: 32;
}

ActionFlagconst

const ActionFlag: {
	/** Ignore a Wait / Transmission once (game bookkeeping). */
	readonly IgnoreWaitOnce: 1;
	readonly Disabled: 2;
	readonly AlwaysDisplay: 4;
	readonly UnitPropertiesUsed: 8;
	readonly UnitTypeUsed: 16;
	readonly UnitIdUsed: 32;
}

TriggerFlagconst

const TriggerFlag: {
	/** Game bookkeeping: every condition was met this cycle. */
	readonly ConditionsMet: 1;
	/** Ignore Defeat / Draw for this trigger. */
	readonly IgnoreGameEnd: 2;
	/** Same as a Preserve Trigger action. */
	readonly Preserve: 4;
	/** The trigger never runs. */
	readonly Disabled: 8;
	/** Skip Wait / text / view actions for the rest of this loop (game bookkeeping). */
	readonly IgnoreDisplay: 16;
	/** Game bookkeeping. */
	readonly Paused: 32;
	/** Game bookkeeping. */
	readonly WaitSkipDisabled: 64;
}

UnitConstsinterface

interface UnitConsts

`readonly startLocation: 214`	The units.dat id of the Start Location marker.
`readonly mineralFields: readonly [ 176, 177, 178 ]`	The three mineral field types — a mineral line uses all three so it is not one sprite repeated.
`readonly vespeneGeyser: 188`
`readonly defaultMinerals: 1500`	What a fresh resource is worth, as StarEdit writes it.
`readonly defaultGas: 5000`
`readonly valid: { readonly Cloak: 1; readonly Burrow: 2; readonly InTransit: 4; readonly Hallucinated: 8; readonly Invincible: 16; }`	`validProperties` (offset 0x0C): which special-property fields the game reads.
`readonly used: { readonly Owner: 1; readonly HitPoints: 2; readonly Shields: 4; readonly Energy: 8; readonly Resources: 16; readonly Hangar: 32; readonly State: 64; }`	`validStates` (offset 0x0E): which of the record's fields are set at all.
`readonly state: { readonly Cloaked: 1; readonly Burrowed: 2; readonly InTransit: 4; readonly Hallucinated: 8; readonly Invincible: 16; }`	`stateFlags` (offset 0x18): the special properties themselves.
`readonly relation: { readonly NydusLink: 512; readonly Addon: 1024; }`	`relationType` (offset 0x0A): how `relatedSerial` is linked.

SpriteConstsinterface

interface SpriteConsts

`readonly flags: { readonly PureSprite: 4096; readonly Flipped: 16384; readonly Disabled: 32768; }`	THG2 `flags`. `PureSprite` is what `spriteKind` reads: with it the id is a sprites.dat one and the game only draws it, without it the id is a units.dat one and the game creates the unit (Installation doors and traps).

LocationConstsinterface

interface LocationConsts

`readonly anywhere: 63`	The MRGN slot that is Anywhere. The editor protects it; nothing else may write it.
`readonly elevation: { readonly LowGround: 1; readonly MediumGround: 2; readonly HighGround: 4; readonly LowAir: 8; readonly MediumAir: 16; readonly HighAir: 32; }`	`elevationFlags`. A set bit excludes that elevation — the game tests a unit against the location only on the elevations whose bit is clear — so 0 means everywhere, and StarEdit's ticked "Low ground" box is bit 0 clear.

TriggerConstsinterface

interface TriggerConsts

The numbers a TRIG / MBRF record is written in: the condition and action types, and the enumerated arguments the game stores as bare bytes.

A trigger record is sixteen conditions and sixty-four actions of plain numbers — the codec knows no types — so writing one field by field means knowing that a Countdown Timer condition is type 1 and AtLeast is 0. triggers.defs says which field an argument lives in; this says what to put in it.

The keys of the argument groups are ArgDef.kind, so a generic argument editor can look one up by the kind the def gave it (api.consts.triggers[arg.kind]).

Generating a whole run of triggers is usually better done through tx.triggers.fromText, which resolves names against the open map; these are for editing a field of an existing record, and for reading one back.

`readonly condition: typeof ConditionType`	Condition `type`.
`readonly action: typeof ActionType`	Action `type` in TRIG.
`readonly briefingAction: typeof BriefingActionType`	Action `type` in MBRF, where the same byte means something else.
`readonly player: typeof PlayerGroup`	The 27 player-group values, which are also the indices of a trigger's `players`.
`readonly comparison: typeof Comparison`
`readonly switchState: typeof SwitchState`
`readonly switchAction: typeof SwitchAction`
`readonly modifier: typeof SetModifier`	Set Resources / Set Score / Modify …: `SetTo`, `Add`, `Subtract`.
`readonly unitState: typeof UnitState`	Set Doodad State / Set Invincibility: `Enable`, `Disable`, `Toggle`.
`readonly order: typeof Order`
`readonly alliance: typeof AllianceStatus`
`readonly resource: typeof ResourceType`
`readonly score: typeof ScoreType`
`readonly unitClass: typeof UnitClass`	The unit ids past units.dat that a condition or action accepts: Any unit, Men, Buildings, Factories.
`readonly conditionFlags: typeof ConditionFlag`	A condition's `flags`. `UnitTypeUsed` is the hint bit the text format cannot carry.
`readonly actionFlags: typeof ActionFlag`	An action's `flags`.
`readonly triggerFlags: typeof TriggerFlag`	A trigger's `flags`; `Preserve` is what `triggers.isPreserved` reads.
`readonly deathsTable: number`	The address of the game's death table, which is the base an EUD player value is counted from: `epd = (address - deathsTable) / 4 + 0x2000`.