jssuh
Version:
Reads broodwar replays
122 lines (99 loc) • 4.1 kB
Markdown
# jssuh
jssuh reads bw replays =)
[](https://www.npmjs.org/package/jssuh)
[](https://www.npmjs.org/package/jssuh)
The most notable thing not currently implemented is action-specific data: The library can
read actions and exposes their raw bytes, but understanding the data is currently left to user.
See [example.js](./example.js) for a simple example.
This module exports a single class, `ReplayParser`, which is a `Transform` stream.
Pipe the replay file to it, and it will output an following object for each action in the replay:
```javascript
{
// Id number of a player. (Sadly, this library doesn't yet expose any player info)
player,
// Frame on which the action was issued.
frame,
// Action id.
id,
// Action parameters. Maybe there will eventually be support for better action decoding.
data,
}
```
Additionally, `ReplayParser` will emit a `replayHeader` event once it has parsed the header.
This will always happen before any of the actions have been emitted. The event has the parsed
header information in following format:
```javascript
{
// The name of the lobby.
gameName,
// The map title.
mapName,
// Game type (melee, ums, etc). Currently just exposed as a integer.
gameType,
// Game type modifier (Top vs bottom team layout, greed victory conditions, etc).
gameSubtype,
// Array of players in the game.
players,
// The duration of the game, in frames (1 / 24th of a second on fastest speed).
durationFrames,
// Initial random seed, which is also the timestamp of the replay.
seed,
// True if the replay uses StarCraft Remastered format, false for older replays.
remastered,
}
```
The player objects have the following fields:
```javascript
{
// Player id. Matters mostly in UMS which can have preplaced units for specific players.
// (Not sure if this is before or after start location randomization in maps that have it)
id,
// Name of the player.
name,
// True if the player is a computer, false if human.
isComputer,
// One of the following: 'zerg', 'terran', 'protoss', 'unknown'
race,
// Team (1-based) in team games and UMS, meaningless otherwise.
team,
}
```
## Parser options
You can specify the encoding to used for text strings of replay by passing an option object when
constructing the parser:
```javascript
const parser = new ReplayParser({ encoding: 'cp1252' })
```
The default encoding is `auto`, which attempts to use `cp949` and falls back to `cp1252` if it
does not work.
## parser.pipeChk(stream)
The replay's map (scenario.chk) can be accessed with `parser.pipeChk(stream)`. See
[bw-chk](https://github.com/neivv/bw-chk) for parsing the map data.
## parser.scrSection(tag, size, callback)
SC:R replay format can have arbitrary byte streams that are identified with a 4-byte tag
string.
If you know how the section's expected size, you can give the parser a callback
to run with section's data. Note that if the replay doesn't contain a section with the tag,
there won't be an error, the callback will just not be run.
All currently known official SC:R byte streams use the same split-to-chunk compression as the
main replay, but the format can allow arbitrary data to be added. Use `rawScrSection` if you
the extended section does not use the regular compression
Example:
```javascript
parser.scrSection('LMTS', 0x1c, bytes => {
// process...
})
```
## parser.rawScrSection(tag, callback)
Forwards SC:R replay section to a callback without assuming anything about it.
While all Blizzrd's replay sections (as of writing this) use the compression that
`parser.scrSection` can be used to decompress for you, `rawScrSection` can be used to access the
raw bytes for sections that use some other format or are not compressed at all.
Similar to `scrSection`, if the replay doesn't contain a section with the tag,
there won't be an error, the callback will just not be run.
Example:
```javascript
parser.rawScrSection('Sbat', bytes => {
// process ShieldBattery extension ...
})
```