Hyperion live guide

Start here

Hyperion plays the original StarCraft with an engine of its own. While it runs, a map editor, a script or an AI can drive it over a live channel: switch the game to a map it is editing, and play a scene on that map with the camera, fades, words and units, without restarting anything. This page shows each of those, lets you try each on the game, and gives the code to do the same from your own program.

Getting it running

1. Unpack Hyperion into a StarCraft 1.17 folder and start it with the channel open: Hyperion.exe --control. Started that way it goes straight to its menus, with no opening cinematic.
2. Open http://127.0.0.1:27117/guide (this page, served by Hyperion). The dot at the top turns green when it is connected.
3. Press Push a test map at the top, or any button marked with a map, and try the rest on it. Escape in the game ends a scene that plays.

Only programs on the same machine reach the channel: it listens on 127.0.0.1. A browser page may talk to it only when Hyperion served the page; a program that is not a browser may always.

The channel

A WebSocket on ws://127.0.0.1:27117/?t=<key> (another port with --control=<port>). Each message is one JSON object with a cmd; each answer carries the message's id and ok, and error, a sentence, when it is false.

The key is made each time Hyperion starts and written to a file only you can read: %LOCALAPPDATA%\Hyperion\control-27117.key on Windows, ~/.local/share/Hyperion/control-27117.key elsewhere (the number is the port). The C++ and Python clients read it themselves; a page Hyperion serves has it in the link Debug Tools' Copy link gives. A connection without it is refused, so no other program on the machine can drive the game.

{"id": 7, "cmd": "map_push", "tileset": "jungle", "width": 128, "height": 128}
{"id": 7, "ok": true, "tileset": "jungle", "size": [128, 128], "state": "going out"}

{"id": 8, "cmd": "map_push", "tileset": "jungle", "width": 100}
{"id": 8, "ok": false, "error": "width and height are each 64, 96, 128, 192 or 256 tiles"}

Send one message and wait for its answer before the next. status is cheap; poll it a few times a second while waiting for something, and once a second or so to show where the game is.

What status says

A client in a few lines

The C++ client is tools\hxlive_cpp\hxlive.h: one header, Windows' own WinHTTP, nothing else. The Python one is tools\hxlive.py, the standard library only. In a browser or Node, the WebSocket is built in.

Map switches

Two messages switch the game to another map. Both work from a single-player game and from Hyperion's menus. From a game the picture goes out over ms milliseconds, the old game is left as Quit Mission leaves it, the new map starts, and it comes in as a skirmish's start does.

The switch, step by step

Wait for the switch by polling status until map_swap is "none" and state is "game"; if map_swap_error appears instead, the map could not be started and it says why. Hyperion stays on its menus then. A pushed map starts explored but fogged: send {"cmd": "reveal"} once it runs to lift the fog, which a camera tour wants.

Push tiles

Left without tiles, the ground is the tileset's first plain buildable group, varied as a brush varies it. tiles is the MTXM values row by row (group × 16 + variation); tiles_b64 is the same as base64 of the little-endian 16-bit values, which is the MTXM section's own bytes and the better choice from a program; rects paints boxes over them. Sizes are those the original offers: 64, 96, 128, 192 or 256 tiles a side.

Push a map file's terrain

from takes a map file's tileset, size and tiles; Hyperion reads .scm, .scx and .hxm itself. A full path is used as it is; a name is looked for as the game looks for a map, in Hyperion's data folder, the StarCraft folder (so maps\(2)Volcanis.scm finds the install's), then each --maps folder, and failing that by the file's name alone in any folder under them, so (4)Lost Temple.scm finds the one in maps\ladder\. The units, locations and triggers stay behind: that is map_load's.

Load a map

As melee the player gets their race's start and the other starts get computers, as --map plays a map; as Use Map Settings the map's own slots, units and triggers decide. A map that cannot play (an .hxm that names a mod's unit while the mod is not on, for one) answers with map_swap_error, and hyperion_hxm.log in the Hyperion folder says why.

Find maps

maps lists every map file Hyperion finds: the data folder's maps, the StarCraft folder's and each --maps folder, with the folders in them, each with its name, folder, root and full path. filter keeps those whose folder and name hold it; the folders are read again after ten seconds, or at once with fresh: true. map_info {path} reads one map: its size, tileset, player slots, the title and description it shows in the game, its start locations in pixels with their player, whether map_push can take its terrain, and preview, its minimap with the starts marked, a picture served under /snapshots/. Debug Tools' panel lists the maps the same way.

Camera

Places are map pixels, 32 to a tile, from the map's top left: the middle of tile (40, 12) is (1296, 400). A camera step glides the middle of the view to x, y and the zoom to zoom over ms, with an ease; either part may be left out. zoom 1 is the game's own view, 2 shows twice the map across, and a scene may go as close as 0.5.

{"do": "camera", "x": 2048, "y": 1500, "zoom": 1.4, "ms": 3000, "ease": "in_out"}

The eases

How a move covers its distance over its time. The dot under each curve moves as the camera would.

Moves to try

Each plays around where the camera looks now, on whatever map runs.

Follow

{"do": "follow", "unit": "lings", "zoom": 1.2, "ms": 800} glides onto a unit and stays on it as it moves, until the next camera step. unit is a label a spawn gave, a unit's id, or a list of them (the first alive is followed). The tracking shot above uses it.

Picture transitions

Black over the picture, a zoom of the picture itself, cinema bars and the console, each on its own clock, so they combine: a fade can carry a zoom while the bars come in.

Words and sound

Left without ms, words stay for a reading time: a second and a half and 0.06 s a letter.

Units in a scene

Units made and ordered as the trigger actions do it, in a single-player game; the game is then marked as changed. A scene that only moves the camera, the picture and words also plays in a replay.

A unit type is a name, as .hxm maps use (terran_marine, zerg_zergling, protoss_dragoon, terran_siege_tank_siege_mode), or the original's number. Players count from 0. The units a scene made are listed by label in cutscene_status and in status's cutscene.

Timing

Steps run in turn, each waiting for the one before. A step sent with "async": true lets the next start at once, under it: a caption stays up while the camera moves, a fade runs while a zoom eases.

A new cutscene_play ends the one playing; cutscene_stop ends it as Escape does. The steps are checked before any runs, and the answer names the first wrong one.

Sample scenes

Five scenes made while the channel was built, each showing a different way to use it. Play switches to the map each was made for, then plays it. They are in tools\cutscenes\ to read and copy; each file names its map in map: push for a made map, or from for a map file with or as a stand-in when that file is not there.

Scene builder

Write or paste a scene, check it, play it on the game. Each button below adds a step of that kind with its fields filled in from where the camera looks now.

In your editor

What a Test in Hyperion button needs, in the order it happens. The C++ here uses tools\hxlive_cpp\hxlive.h; tools\hxlive_cpp\example.cpp is the same as a whole program.

1. Start Hyperion, or find it running

Try to connect first: a Hyperion the player already started answers. If nothing answers, start Hyperion.exe --control from the player's StarCraft 1.17 folder (the folder with StarCraft.exe, where Hyperion was unpacked), as its working directory, and connect again until it answers; it takes a few seconds. Keep it running between tests: every test after the first is a switch, a few seconds, not a start.

2. Send the map

For a terrain change, send the MTXM you hold in memory with map_push, no saving needed. For a test of units, locations and triggers, save the map and send its path with map_load (with "ums": true for a map made for Use Map Settings). Keep one connection and send one message at a time, from a worker thread so the editor stays responsive while it waits.

3. Wait for it, then the extras

Poll status until the switch has ended (above, under Map switches). Then reveal if the tester wants the whole map in view, and a scene if they asked for one; a scene can also ride along with the switch as its scene field, so it starts the moment the map comes in.

4. Scenes from the editor's own data

A scene is a list of steps, so an editor can make one from what it already has:

• Camera keys from the viewport. The editor's view of the map gives the x, y of a camera step directly (map pixels are the editor's tile × 32 + 16 for a tile's middle); its zoom gives zoom. A list of saved views with a time each is a camera path.
• Places from locations. A location's middle is a good x, y for a spawn, an order or a camera step: (left + right) / 2, (top + bottom) / 2 of its rectangle.
• Units by label. Give each spawn an as named after what it is in the editor ("the convoy") and later steps can order or follow it by that name.
• A timeline. Steps with "async": true run under the next, so a track per kind (camera, picture, words, units) on a timeline turns into a step list by sorting the starts and putting a wait between them.

The scene's format is the same one that will be kept in an .hxm and started by its triggers, when that comes: what an editor builds for live tests now carries over.

5. When something is wrong

• ok: false answers say why in a sentence a tester can read: show it as it is.
• A refused connection means Hyperion is not running with --control, or listens on another port.
• map_swap_error means the map did not start; Hyperion's logs in its Hyperion folder say more (hyperion_hxm.log for an .hxm, hyperion_canvas.log for a push).
• On a player's very first start without --control, the original's opening cinematic plays first; Escape skips it.

Message reference

The messages an editor uses. docs\live-channel-for-editors.md has the same with more detail; the channel has more, for Debug Tools (list, set, perf and others).

Tilesets

badlands, platform, install, ashworld, jungle, desert, ice, twilight, or "0" to "7" in that order (a map's ERA).

What is planned

• Scenes kept in an .hxm map and started by its triggers, in this same step format.
• Cutscene styles of Hyperion's own, beyond the classic look: other captions, bars and transitions.
• map_push with units, locations and triggers, and past 256 tiles through .hxm.