Hyperion v0.7.3-beta for Linux (x64)

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
- 64-bit Linux on x86-64 (Intel or AMD), with glibc 2.35 or newer: Ubuntu 22.04, Debian 12 or Fedora 36,
  a later release of one of them, or another distribution of the same age or newer.
- A graphics driver with Vulkan (Mesa's, or the card maker's).
- Sound through PulseAudio, PipeWire or ALSA, as a desktop has. Without any, the game
  plays silent.
- StarCraft: Brood War's data files, either:
  - Remastered's: StarCraft from Battle.net, installed through Wine or Lutris, or its folder
    copied from a Windows install; Settings, Data and mods, Game files names where it is.
  - 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,
    copied from a Windows install. 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 archive into a folder of its own, anywhere, for example ~/Games/Hyperion, and
run ./Hyperion.x86_64 there. Not into the 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 (it
offers Lutris's and Wine's usual places when StarCraft is there), and which of them the game
reads; Settings, Data and mods, Game files switches to the other later. Names in the game's
folder may be in any case, as on Windows. The map list shows the game's own maps from that
folder beside Hyperion's.

Beside Hyperion.x86_64 are libSDL3.so.0, 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.x86_64. The folders docs, notes, tools and web and maps/Hyperion an older version left
beside Hyperion.x86_64 may be deleted: only maps/Hyperion, not maps, which holds the game's own
maps.

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

For map editors
    ./Hyperion.x86_64 --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.x86_64 --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.py is a client in Python's standard library alone, for the command line:
    python3 Data/tools/hxlive.py status
    python3 Data/tools/hxlive.py map push --tileset jungle --size 128x128 --scene Data/tools/cutscenes/temple-flyover.json --reveal
    python3 Data/tools/hxlive.py map push --from "maps/(2)Volcanis.scm" --scene Data/tools/cutscenes/volcanis-last-stand.json --reveal
    python3 Data/tools/hxlive.py map load <map file> --ums --wait
    python3 Data/tools/hxlive.py cutscene play Data/tools/cutscenes/canvas-sample.json
    python3 Data/tools/hxlive.py cutscene play Data/tools/cutscenes/temple-flyover.json --on-map
    python3 Data/tools/hxlive.py map list temple
    python3 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 in a window, and on the standard
error when it was started from a terminal, with where that log is. When Data/ cannot be written
to, the log goes to $TMPDIR/Hyperion/, or /tmp/Hyperion/.
- libSDL3.so.0 must stay beside Hyperion.x86_64.
- "Permission denied": the archive's program lost its mark as one; chmod +x Hyperion.x86_64.
- A message that names GLIBC_2.xx: the distribution is older than Hyperion needs (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 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, before
you close the window, since what is copied goes with it unless a clipboard manager keeps it.
The same text is on the standard error. 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 home folder as ~, and not your computer's or your own name.
