Hyperion v0.7.3-beta for Mac

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).

This is a test build.

Maps
Data/maps/Hyperion/ holds Hyperion's own maps, the ones its skirmish tests and the
benchmark play: the Big Game Hunters sizes up to 32 players and the remade Elderlands and
Garden of Aiur. Those past 32 players or 512 tiles a side, beyond
what Hyperion aims at for now, are in Data/maps/Hyperion/Experimental/. The game's own maps
are listed beside them from the StarCraft install Hyperion reads; the canvas (--control, then
the live guide) needs none, and its sample scenes play on a map made on the spot when theirs
is missing.

What it needs
- A Mac with Apple silicon (M1 or later) and macOS 13 Ventura or later.
- StarCraft: Brood War's data files, either:
  - Remastered's: StarCraft from Battle.net (free), installed where Battle.net puts it,
    /Applications/StarCraft. Settings, Data and mods can name another place.
  - Classic's: a StarCraft folder copied from a Windows install, 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
Unzipped, this is a folder holding Hyperion.app and the folders it uses. Keep it where you
like, in your home folder for example (not Downloads or Desktop, which macOS guards), and not
inside 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 StarCraft from
Battle.net when it is in /Applications/StarCraft, and which of them the game reads; Settings,
Data and mods, Game files switches to the other later.

Beside Hyperion.app are 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: in 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; so can the maps folder an earlier package put
beside Hyperion.app, unless you keep maps of your own in it.

The first start
Hyperion is not signed by Apple, so macOS stops it the first time with a message that it
cannot check it. To allow it once: open System Settings, Privacy & Security, scroll to
Security, and click Open Anyway beside Hyperion's name, then start it again and confirm.
Or, in Terminal, clear the download's mark on the folder, then start Hyperion.app as usual:
    xattr -dr com.apple.quarantine <the folder>
macOS may also ask whether Hyperion may find devices on your local network: allow it to
play LAN games.

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

For map editors
    Hyperion.app/Contents/MacOS/Hyperion --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.app/Contents/MacOS/Hyperion --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 classic
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 load <map file> --ums --wait
    python3 Data/tools/hxlive.py cutscene play Data/tools/cutscenes/canvas-sample.json
    python3 Data/tools/hxlive.py map list temple
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, with where that
log is. When Data/ cannot be written to, the log goes to macOS's folder for temporary files,
in Hyperion/ there ($TMPDIR in Terminal).
- When macOS stops Hyperion before it starts, see The first start above: Hyperion writes no
  log until macOS lets it run.
- 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; macOS's own report
is in Console, Crash Reports.

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 home folder as ~, and not your
computer's or your own name.
