Hyperion v0.7.3-beta

Hyperion plays StarCraft: Brood War with an engine of its own: the game's maps, and its
classic replays and saved games, play as the original plays them, and Hyperion's own maps
go past the original's limits (up to 512 tiles a side and 32 players for now).

Test maps
Data\maps\Hyperion\ holds remade maps for Hyperion. Those past 32 players or 512 tiles
a side, beyond what Hyperion aims at for now, are in Data\maps\Hyperion\Experimental\.

What it needs
- Windows 10 or 11, 64-bit, and a graphics card with Direct3D 12 or Vulkan.
- StarCraft: Brood War's data files, either:
  - Remastered's: StarCraft from Battle.net (free), installed by Battle.net.
  - Classic's: a StarCraft folder with the game's MPQ files (StarDat.mpq, BrooDat.mpq,
    patch_rt.mpq, and StarCraft.mpq and BroodWar.mpq, the CDs' files) and Local.dll.
    StarCraft.exe is not needed.
  Hyperion reads the game's art, sounds and maps from those files; it holds none of them.

Installing
Unpack this zip into a folder of its own, anywhere, for example C:\Games\Hyperion, and start
Hyperion.exe. Not into a StarCraft folder: Hyperion leaves the game's folders as they are.
At its first start Hyperion asks for the folder of each StarCraft you have, filled in with the
ones it finds (StarCraft from Battle.net where Battle.net installed it), and which of them the
game reads; Settings, Data and mods, Game files switches to the other later. The map list shows
the game's own maps from that install beside Hyperion's.

Beside Hyperion.exe are SDL3.dll, this README, docs\ with the documents
(docs\licenses\ has the licenses of the typefaces inside Hyperion), and Data\ with
everything else Hyperion brings: its mods, maps, tools and web pages. Hyperion keeps
everything of its own in Data\ too: profiles, saved games, replays, settings, logs and its
cache. To remove Hyperion, delete its folder.

From an earlier Hyperion: unpacked into the same folder as before, Hyperion moves what its
folder Hyperion\ held into Data\ at its first start, profiles, saves and replays included,
and the Hyperion folder can go once that is done. An earlier Hyperion in a StarCraft
folder can stay there or move out: copy its Hyperion folder into the new folder, then start
the new Hyperion.exe. The folders docs, notes, tools and web and maps\Hyperion an older
version left beside Hyperion.exe may be deleted: only maps\Hyperion, not maps, which holds
the game's own maps.

Hyperion.exe is not signed. Windows Defender or SmartScreen may warn about it, or put it
in quarantine, as a false positive; restore it or allow it if so.

HUDs
Settings, HUD, chooses the console you play with: the original's, or one of Hyperion's
designs, across the foot of the screen or as a column at either side, with a picture of how it
looks on your screen. A HUD of your own goes in Data\huds\, as a folder or a .hud package;
    Hyperion.exe --hud-check <file, folder or .hud>
checks one without starting a game. The designs need the GPU renderer (Settings, Graphics).

Starting a game from the command line
    Hyperion.exe --map <map file> [--race zerg|terran|protoss|random] [--computers <n>]
    Hyperion.exe --map <map file> --ums      (Use Map Settings: the map's triggers run)
    Hyperion.exe --map <map file> --rules classic|hyperion   (the original game's rules, or Hyperion's, the default)
    Hyperion.exe --replay <replay file>
    Hyperion.exe --load <saved game>
Give full paths. A map can be .scm, .scx or Hyperion's own .hxm.

For map editors
    Hyperion.exe --hxm-check <map.hxm> [<report.txt>]
checks a map an editor wrote, without starting the game: errors and warnings a line each, exit
code 0 when it plays, 1 when it is refused, 2 when it cannot be read. It needs no game files.
docs\hxm-for-editors.md says what a Hyperion map is and how to support it;
docs\hxm-format.md is the format field by field.

Testing live
    Hyperion.exe --control
opens Hyperion's live channel, a WebSocket on 127.0.0.1 port 27117, through which an editor,
a script or an AI changes the running game: it pushes a map's tiles at any of the game's sizes and
switches to it with a fade, loads a map file the same way, and plays scripted cutscenes
(camera moves and zooms, fades, cinema bars, captions, transmissions, units made and
ordered). Started with --control, Hyperion goes straight to its menus, with no opening
cinematic. A program connects with the key Hyperion writes as it opens the channel, to
control-27117.key in Hyperion's folder of the user's application data; the clients here
read it themselves.

While it runs, http://127.0.0.1:27117/guide in a browser is the live guide: every capability
explained and tried on the game from there, the sample scenes played on their maps, a scene
builder, and the code for each in C++, Python and JavaScript. docs\live-guide.html
is the same to read offline, and docs\live-channel-for-editors.md has the messages
and the cutscene steps in full. http://127.0.0.1:27117/ is Debug Tools' panel: among its
tools, a list of every map Hyperion finds (with a minimap, its size, players and description,
and buttons to play it) and the sample scenes, each played on the map it was made for.

For an AI assistant: Copy for AI, in Debug Tools' panel and in its overlay in a game (F6),
copies a briefing on the live channel with this install's paths and the game's state, to paste
into the assistant's chat; it is also served at http://127.0.0.1:27117/ai-context.

Data\tools\hxlive_cpp\hxlive.h is a client for C++ in one header over Windows' WinHTTP,
with example.cpp and build.bat beside it. Data\tools\hxlive.py is one in Python's
standard library alone, for the command line:
    python Data\tools\hxlive.py status
    python Data\tools\hxlive.py map push --tileset jungle --size 128x128 --scene Data\tools\cutscenes\temple-flyover.json --reveal
    python Data\tools\hxlive.py map push --from "maps\(2)Volcanis.scm" --scene Data\tools\cutscenes\volcanis-last-stand.json --reveal
    python Data\tools\hxlive.py map load <map file> --ums --wait
    python Data\tools\hxlive.py cutscene play Data\tools\cutscenes\canvas-sample.json
    python Data\tools\hxlive.py cutscene play Data\tools\cutscenes\temple-flyover.json --on-map
    python Data\tools\hxlive.py map list temple
    python Data\tools\hxlive.py map info "(4)Lost Temple.scm"
A map can be given by its file name alone; Hyperion looks for it in every maps folder.


What is new in each version: Patch Notes in the menu, and docs\release-notes.md.
Settings shows the version and build at the bottom left.

If Hyperion doesn't start
Each start writes Data\hyperion_startup.log, a line for each step, and the five starts before
it are kept in Data\logs\. When a start fails, Hyperion says so and where that log is. When
Data\ cannot be written to, the log goes to Windows' folder for temporary files,
%TEMP%\Hyperion\.
- Hyperion.exe needs SDL3.dll beside it: unpack the whole zip into a folder, then start
  Hyperion.exe from there, not from inside the zip.
- If Windows Defender put Hyperion.exe in quarantine, restore it (above).
- If Hyperion seems to start and nothing comes, the log's last line says the step it stopped
  at.

If Hyperion stops on an error
It saves a report in a folder of its own in Data\crashes\, with report.txt, report.json, a
minidump and the session's logs. Data\hyperion_crash.log is a copy of the last report.

When you ask for help
The window that says a start failed or Hyperion stopped has the details in a box: press Copy
to clipboard and paste it in a GitHub issue or on Discord, with what you were doing. It names
no folder, network address or name of yours. The logs and the report hold more if they are
asked for; they name the folders Hyperion uses, with your user folder as %USERPROFILE%, and
not your computer's or your own name.
