bw-chk

Brood war map file parsing library.



This library only read the uncompressed scenario.chk files, which must be extracted
from the .scx or .scm files first.

$3

- Map size, title, description, tileset
- UMS force layout
- Position/type/owner of units
- Sprite coordinates
- Image generation

$3

- Map-specific player colors (The image rendering functionality has hardcoded colors)
- Locations
- Tech restrictions
- Special unit flags

See examples/singlemap.js for an example that uses
scm-extrator to open a complete map, and
display its information. If you have bw's data files extracted to disk, it can also
generate a image of the map.

Class: Chk

$3

Parses the chk synchronously. If the buffer is not a valid chk, an exception with name
ChkError is thrown.

options can be used to specify encoding:

``javascript
{
encoding: 'auto',
}
`

Setting encoding to auto causes the library to use a simple heuristic for determining between
Western (cp1252), Korean (cp949) and UTF-8 (utf8) encodings. If auto is specified, the guessed
encoding can be read from chk.encoding

$3


A convinience function that creates a Duplex stream, outputting a Chk object. If
callback(err, chk) is passed, it will also be called once the Chk has been parsed.

$3

Map size in tiles [width, height]

$3

Map title

$3

Map description

$3

Map tileset as a integer.

$3

Map tileset as a human-friendly string. This does not correspond 1:1 to the tileset data
file names.

$3

The force layout. Only relevant in UMS games. It is an array of 4 forces, where each
force has the following properties:

- name Force name
- flags Raw force flags:
- 0x1 Random start locations
- 0x2 Start as allied
- 0x4 Start with allied victory
- 0x8 Start with shared vision
- players Array of players, or empty if the force is unused. Players have the following
properties:
- id Player id, 0-based.
- computer Boolean, is the slot is owned by a computer?
This is same as type !== 'human', though the details of various non-human types
have differences.
- type Gives some idea of player's type:
- computer, human, and rescueable are common ones
- neutral is a computer that spawns in game, is not shown in lobby,
and is allied to everyone
- unknown is used for various odd ones which seem to behave inconsistently
- typeId is the type as integer, as seen by the game.
- race Race as a integer. Only 0x5 allows players to select their race in UMS games.
- 0x0 Zerg
- 0x1 Terran
- 0x2 Protoss
- 0x5 User selectable
- 0x6 Forced random

$3


Array of all units in the map. Each unit has the following properties:
- x, y are the coordinates in pixels
- unitId is the unit type (integer)
- player is the owning player (0-based, player 11 is neutral)
- resourceAmt is the amount of resources, or undefined if unitId is not a resource

$3

Array of sprites/doodads/map decorations. Note that the 'Unit sprites' are part of
chk.units, as the game treats them almost same as 'true' units (They just get loaded
before the map is properly initialized).
Each sprite has the following properties:
- x, y are the coordinates in pixels
- spriteId is the sprite type (integer)

$3

The encoding specified in constructor, or the heuristically determined one if 'auto' was
specified. Note that most English maps may be reported to have Korean (cp949) encoding, as
both encodings are ASCII-compatible. If the map was detected to use multiple encodings,
'mixed' will be returned.

$3

Returns the amount of human players that can play the map. As the player limit can be
different between UMS and melee, the mode has to be specified in isUms parameter.

Note that even though UMS player count can also be determined from counting human players
in chk.forces, melee games may allow more players than there are computer and
human slots combined.

$3


Asynchronously generates a 24-bit RGB Buffer containing a image of the map, with
dimensions of width and height.

As this requires using bw's tileset and sprite files, it is handled by using a fileAccess object.
If the files have been extracted to a directory, they can be simply used with

`javascript
chk.image(Chk.fsFileAccess('path/to/root/directory'), width, height)
`

If there is a need for creating several images, using a single fileAccess object for all
image() calls will cache some of the file parsing work.

options is an object containing additional options. The currently supported options
(and their defaults) are:
`
{
// Whether to render only units which exist in melee games: Start locations, neutral
// resources and neutral unit sprites.
melee: false,
// Whether to render player start locations.
startLocations: true,
}
`

$3


Returns an object which is Iterable, producting Trigger objects.
The returned object also has size property for retrieving total amount of triggers,
and iterateFrom(n) method for iterating starting from nth trigger.

$3

Iterates through triggers of the map, returning true, if any of the triggers use EUD
conditions or actions. The check is done in a way that is 100% compatible with SC:R's check,
which includes checking conditions and actions that could never be executed by the game.

$3

Creates a FileAccess object, which can be passed to chk.image() for accessing bw's files which
have been extracted to directory.

$3

Creates a FileAccess object with a custom function for reading files.

The function takes in a string containing the filename (e.g. 'unit\\terran\\marine.grp'),
and must return a promise which resolves to a Buffer containing the file's data.

$3

Returns an object with constants for action ID integers. See Constants.md for
a list of the constant names and their values.

$3

Returns an object with constants for condition ID integers. See Constants.md for
a list of the constant names and their values.

Class: Trigger

Triggers are returned by calling chk.triggers().

$3

Returns array containing player and group ids representing the players that get a copy
of this trigger.

$3

Returns an object which is Iterable, producting Condition objects for the trigger.

$3

Returns an object which is Iterable, producting Condition objects for the trigger,
including any disabled conditions.

$3

Returns an object which is Iterable, producting Action objects for the trigger.

$3

Returns an object which is Iterable, producting Action objects for the trigger,
including any disabled actions.

$3

Returns a shared Buffer slice to the 2400 raw bytes of the trigger structure.
Modifying this slice will affect any other Trigger referring to this trigger;
none of the trigger objects in this library take private copies of the trigger bytes.

Class: TriggerAction

$3

Returns integer ID for the action type.
See Chk.actionIds for action ID constants.

$3

Returns true if the action is disabled
(Game will not execute disabled actions)

Only necessary when using trigger.allActions(); trigger.actions() already filters
out any disabled actions.

$3

Returns object containing parameters of the action.
Only fields that the action uses (Based on action ID) will be set.
Any of the enumeration fields can have 'Unknown' as a value if the raw bytes
contain an unexpected value.

`
{
// Location ID used by the action. Source location for Move Unit, Issue Order.
// Location to be searched for unit to be centered on for Move Location.
//
// NOTE: The index here is converted to be 0-based, even though internally in the map file the
// value 1 refers to the first location and value 0 makes action do nothing.
// If a map regardless has 0 for the raw location byte of a action, it becomes -1 here.
location,
// Destination location ID for Give Unit, Issue Order.
// Index is converted to be 0-based as with location.
destLocation,
// Location to be moved for Move Location.
// Index is converted to be 0-based as with location.
movedLocation,
// Text string for Display Text, Transmission, Comment.
text,
// Sound filename for Play Sound, Transmission.
soundFile,
// Time in milliseconds for Wait, Talking Portrait;
// Sound time in milliseconds for Play Sound, Transmission.
// Note that Countdown Timer action's time value and Transmission action's transmission time
// modifier is not in this field, but in amount (and in seconds in Countdown Timer's case).
time,
// Player or group the action is limited to.
player,
// Receiving player for Give Unit.
destPlayer,
// Numeric amount for the action.
amount,
// 'Add', 'Set', 'Subtract' for any action which uses amount.
modifierType,
// Unit ID for the action.
unitId,
// Amount of units affected by the action. 0 for 'All Units'.
unitAmount,
// One of 'Move', 'Attack', 'Patrol', used by Issue Order
unitOrder,
// One of 'Enemy', 'Ally', 'AlliedVictory', used by Set Alliance
allianceStatus,
// Switch ID for Set Switch.
switchId,
// One of 'Set', 'Clear', 'Toggle', 'Randomize', used by Set Switch
switchState,
// One of 'Set', 'Clear', 'Toggle', used by Set Doodad State, Set Invincibility,
// Leaderboard Computers.
state,
// One of 'Ore', 'Gas', 'OreAndGas', for actions using resources.
resourceType,
// One of 'Total', 'Units', 'Buildings', 'UnitsAndBuildings', 'Kills', 'Razings',
// 'KillsAndRazings', 'Custom' for score actions.
scoreType,
// Bool for specifying if the text is shown when subtitles are disabled,
// Used by Display Text, Transmission.
alwaysDisplay,
// 4-byte ID for an AI script. All scripts in unmodded game have IDs with meaningful
// string representation. For example the "Expansion Terran Campaign Medium" script has
// ID 0x544d4578, corresponding to ASCII 'TMEx'
aiScript,
}
`

$3

Returns a shared Buffer slice containing the 32 raw bytes of the action structure.
Modifying this slice will affect any other TriggerAction referring to this same action,
none of the trigger objects in this library take private copies of the trigger bytes.

Class: TriggerCondition

$3

Returns integer ID for the condition type.
See Chk.conditionIds for condition ID constants.

$3

Returns true if the condition is disabled.
(Game skips over disabled conditions without requiring them to pass)

Only necessary when using trigger.allConditions(); trigger.conditions() already filters
out any disabled conditions.

$3

Returns object containing parameters of the condition.
Only fields that the condition uses (Based on condition ID) will not be undefined.
Any of the enumeration fields can have 'Unknown' as a value if the raw bytes
contain an unexpected value.

`
{
// Location ID used by the condition. 1-based index, 0 here makes conditions always fail.
//
// NOTE: The index here is converted to be 0-based, even though internally in the map file the
// value 1 refers to the first location and value 0 makes condition always fail.
// If a map regardless has 0 for the raw location byte of a action, it becomes -1 here.
location,
// Player or group the condition is checking.
player,
// Numeric amount for the condition.
amount,
// 'AtLeast', 'AtMost', 'Exactly' for any condition which uses amount.
comparisionType,
// Unit ID for the condition.
unitId,
// Switch ID for the Switch condition.
switchId,
// 'Set' or 'Clear' for the Switch condition.
switchState,
// One of 'Ore', 'Gas', 'OreAndGas', for conditions using resources.
resourceType,
// One of 'Total', 'Units', 'Buildings', 'UnitsAndBuildings', 'Kills', 'Razings',
// 'KillsAndRazings', 'Custom' for score conditions.
scoreType,
}
`

$3

Returns a shared Buffer slice containing the 20 raw bytes of the condition structure.
Modifying this slice will affect any other TriggerCondition` referring to this same condition,
none of the trigger objects in this library take private copies of the trigger bytes.

License

MIT