@dada78641/bwtoolsdata

A collection of StarCraft internal data used to help process replay and map files.

Usage

This library is available via npm:

npm i --save @dada78641/bwtoolsdata

Aside from raw data, this library contains a number of utilities for people working with StarCraft replay and map files.

Reference

Function:

framesToMs(frames[, speed])

Parameters:

• frames number
  number of in-game frames per second
• speed string (default: "fastest")
  game speed (virtually always "fastest")

Returns:

• number
  the number of milliseconds representing the duration of the game frames

Used to get timestamps of game events for a given game speed. For example, this can be used to display a timestamp for a chat message, or to show the duration of a game.

---

Function:

sortRaces(raceA, raceB)

Parameters:

• raceA string
  a Brood War race string ("T", "Z", "P")
• raceB string
  a Brood War race string ("T", "Z", "P")

Returns:

• number
  -1, 0, or 1 (use as sort() compare function)

Sorts races according to which is the "active" race in the matchup.

Other than mirror matchups, this produces either ['Z', 'P'], ['P', 'T'] or ['T', 'Z']. Any letter other than {Z, P, T}, e.g. 'R' for random, is placed at the end of the list.

This should generally only be used either for sorting teams, or for 1v1 matchups. It can be used as a stable matchup indicator, so that e.g. ZvP and PvZ matchups are all sorted under the same label rather than under two different labels.

---

Function:

parseMapName(mapName)

Parameters:

• mapName string
  a raw map name (from a map or replay file)

Returns:

• object
  map name information and metadata

Parses a map name and returns a cleaned map name and an object of metadata. This is designed to produce a more "presentable" name for a given map, without things like version numbers, starting location counts or clan tags.

The metadata returned includes a version, a list of tags, and an object of miscellaneous tags, depending on what is found.

---

Function:

getSwatchFromSlotID(id)

Parameters:

• id number
  slot ID to return the color for

Returns:

• string
  swatch name for the color associated with that player slot ID

Every player ID has a default color; for example, player 1 is red, player 2 is blue, etc. This function is used to return the color swatch name associated with a given ID.

---

Function:

stripEscapeCodes(string)

Parameters:

• string number
  input string

Returns:

• string
  the string, with Brood War escape codes stripped out

Brood War reuses several ASCII invisible escape sequences, e.g. for setting colors. This function strips them out.

---

Function:

getSwitchedSwatch(teamID, matchTypeID)

Parameters:

• teamID number
  team ID of the player
• matchTypeID number
  replay game type ID (e.g. 0x0f for Top vs Bottom)

Returns:

• string
  swatch name of the color a player gets when swatches are swapped when viewing a replay

Normally, when watching a replay, you can see the player's original team color; when hitting Shift+Tab, this can be changed to a set of default colors with better visibility.

However, this only works correctly when the right match type is set (e.g. Top vs Bottom). This function tells you what the colors will be after enabling color swapping.

---

Function:

getColorFromSwatch(swatch[, returnType])

Parameters:

• swatch string
  swatch name to return the color value for
• returnType string<"hex" | "int"> (default: "hex")
  type of value to return; either a hex string or a number

Returns:

• string | number
  the color value of the given swatch name

This function can be used to get the actual colors to be displayed for a given swatch (e.g. "paleBlue" will return "#b8b8e8").

---

Function:

getSwatchFromSlotID(slotID)

Parameters:

• slotID string
  a number from 0-23

Returns:

• string
  color swatch name of the given ID

Each player ID has a predetermined color; red, blue, teal, purple, and so on. This returns the swatch name of a given ID.

---

In-game colors

Colors work quite inconsistently in StarCraft. There are two sets of color codes: one for briefing messages (and map names), and one for in-game chat messages. These each have their quirks that are different between Brood War (v1.16.1 and below) and Remastered.

Here's a list of all colors:

Briefing text colors
Name		Hex value		Code	Slug
Pale blue			#a4b4f8	0x02	briefingPaleBlue
Green			#4cc428	0x03	briefingGreen
Light green			#b4fc74	0x04	briefingLightGreen
Gray†			#585858	0x05	briefingGray
White			#ffffff	0x06	briefingWhite
Red			#fc0000	0x07	briefingRed
In-game text colors
Name/slot ID‡		Hex value		Code	Slug
Pale blue			#b8b8e8	0x02	ingamePaleBlue
Yellow			#dcdc3c	0x03	ingameYellow
White			#ffffff	0x04	ingameWhite
Red			#c81818	0x06	ingameRed
Green			#10fc18	0x07	ingameGreen
Gray†			#847474	0x05	ingameGray
Red	0		#f40404	0x08	playerRed
Blue	1		#0c48cc	0x0e	playerBlue
Teal	2		#2cb494	0x0f	playerTeal
Purple	3		#88409c	0x10	playerPurple
Orange	4		#f88c14	0x11	playerOrange
Brown	5		#703014	0x15	playerBrown
White	6		#cce0d0	0x16	playerWhite
Yellow	7		#fcfc38	0x17	playerYellow
Green	8		#088008	0x18	playerGreen
Pale yellow	9		#fcfc7c	0x19	playerPaleYellow
Tan	10		#ecc4b0	0x1b	playerTan
Cerulean	11		#4068d4	0x1c	playerCerulean
Pale green	12		#74a47c	0x1d	playerPaleGreen
Bluish gray	13		#9090b8	0x1e	playerBluishGray
Turquoise	15		#00e4fc	0x1f	playerTurquoise
Pink	16		#ffc4e4	–	playerPink
Olive	17		#787800	–	playerOlive
Lime	18		#d2f53c	–	playerLime
Navy	19		#0000e6	–	playerNavy
Magenta	21		#f032e6	–	playerMagenta
Gray	22		#808080	–	playerGray
Black	23		#3c3c3c	–	playerBlack

†: In StarCraft, gray is buggy: when it's used in a map name in Brood War, the rest of the name becomes gray as well—this was fixed in Remastered. In in-game text messages, gray will take over the entire rest of the line, both in Brood War and Remastered. This buggy behavior is not completely implemented in this library, and more research is needed to determine every edge case.

‡: Slot IDs 11, 14, 15 and 20 are not selectable as player colors (the color for 11 is used for the neutral player, however). 11 and 15 are still usable as text color. 14 and 20 are duplicates of Pale Yellow and Cerulean.

Tilesets

The following are all available tileset types.

A few of the aforementioned player colors are not pickable on certain tilesets (due to bad contrast).

Tileset name		Internal name	ID	Disallowed colors
Ash World		ashworld	3	Gray, Black
Badlands		badlands	0	–
Desert		desert	5	Orange
Ice†		ice	6	White
Installation‡		install	2	Blue, Navy, Bluish gray
Jungle World		jungle	4	–
Space Platform		platform	1	Gray, Black
Twilight		twilight	7	Bluish gray

†: Also called "Arctic" in the community.

‡: The Installation tileset is only used in the campaign and does not support regular custom games.

The internal names are the names used by the game files themselves, whereas the proper names are taken from the original Brood War map editor.

Game speed

Number of milliseconds per game frame for each game speed.

E.g. for "Fastest", there are approximately 1000 / 42 = ~23.81 frames in a second. This is used to convert the number of game frames into real time.

Name	㎳/frame	Frames/second	% of "Fastest"
Fastest	42	23.810	100.0%
Faster	48	20.833	87.5%
Fast	56	17.857	75.0%
Normal	67	14.925	62.7%
Slow	83	12.048	50.6%
Slower	111	9.009	37.8%
Slowest	167	5.988	25.1%

By far most replays use "Fastest" as the speed, but this table can be used for the rare cases that aren't. In the very old days of StarCraft, the ladder speed setting was "Fast" by default, but this got changed to "Fastest" relatively early on.

Notes

This library includes code for converting in-game text with escape codes to other representations (terminal escape codes, HTML). It's currently undocumented due to how experimental it is. See lib/color for more information.

License

MIT license