station-master-startos/instructions.md

# Station Master

## Documentation

Everything is served by this package, so it is always available and always describes the version you
have installed. Open the **Multiplayer Table** interface and find it under **This Game → Guide**, or
go straight to `/quickstart.html` on this service's address.

- **Quickstart** — what the game is, how you win, what is on the screen, and a first twenty minutes.
  Start here; it links the rest.
- **Rules** — the rules in full, with a FAQ.
- **Home deck** and **Mainline deck** — every card, what it does and where it may be played.
- **Components** — rolling stock, the yards, Crew Trays, the Offices and the Fedora.

## What you get on StartOS

This service runs the multiplayer server: a lobby, and a table for 2 to 4 players to play a
competitive or cooperative game together from their own browsers. Everything a player needs — the
game itself, the lobby, and the connection back to this server — is served from the single web
interface below; there is nothing else to install or configure on a player's side.

It also serves **solitaire**, from that same web interface: a single-player game that runs entirely
in your own browser and needs nothing from the server, plus a **replay viewer** for saved games. One
address covers all three.

## Getting set up

1. Run the **Get Join Secret** action from this service's Actions menu, and copy the value it
   returns.
2. Share that secret, and this service's address, with everyone you want to play with. Anyone
   holding the secret can create a new game or join one that hasn't started yet.
3. Open this service's **Multiplayer Table** interface. You'll land on the front page, which
   offers three ways in: solitaire, the replay viewer, and multiplayer.
4. Click **Play multiplayer**, then **Create Game** (or **Join Game** with a game code someone
   else created), and enter the join secret when asked.

## Using Station Master

### Multiplayer Table

The front page offers solitaire, the replay viewer, and multiplayer. **Play multiplayer** takes you
to the lobby: create or join a game, seat players (including filling empty seats with a bot), and
start. Once a game is underway, this same interface is where every player plays their turns and
watches the table — there is nothing else to open.

Solitaire runs entirely in your own browser and needs nothing from the server, so it works here
exactly as it does on the public Station Master site.

**Leaving, and coming back.** Anyone may leave a lobby, and the host can clear a chair, so a
mis-join or somebody who wanders off does not block a table that cannot start until every seat is
taken. A **Leave game** button appears once a game is running: it keeps your seat and the table
waits for you, and the lobby lists every game this browser is in, so you can rejoin it — or join a
different one without losing the first.

**A seat lives in one browser.** Rejoining uses a token kept there, and that token is the only proof
of who a player is. So a different browser or device, cleared site data, or **Forget** on the lobby's
list will all lose a seat, and none of them can be undone by the player.

**You can put them back.** Run the **Restore a Seat** action: it issues a single-use link, valid
thirty minutes, that returns a player to their seat. Deciding somebody has lost a seat is a
judgement, which is why minting the link is yours and not theirs.

**A save replays under the rules of the build that opens it.** When a rule changes, a save made
before it may stop part-way — the server says which move it stopped on and leaves the file
untouched, so re-installing the earlier version will still finish that game.

### Get Join Secret

Run this whenever you need the current join secret again, or want to shut out anyone still
holding an old one. Every run replaces the secret and immediately puts the new one into effect —
players already seated in a game are unaffected, but the old secret stops working for creating or
joining games from that point on.

### Games in Progress

Shows every game on the server: who is playing, which Day and Stage they have reached, and whose
turn it is. It changes nothing, so run it whenever you are curious. It is also how you spot a game
nobody is coming back to — one whose last move was days ago, still waiting on a particular player.

### Manage Game

Pick a game, then either save a copy of it or end it.

**Export** hands you the whole game as text and leaves it running. Save that text as a `.json`
file and you can open it in the replay viewer later to watch the game back.

**End the game** deletes it and disconnects anyone still watching. This is the only way to clear
a game that will never be finished — otherwise it sits there, and comes back every time the
service restarts. It cannot be undone, so the game's save is handed back to you when it happens:
that text is the only copy left, so keep it if the game was worth watching.

### Restore a Seat

Use this when a player cannot get back into a game they are already in — they open the page and find
an empty lobby, with no game code and no name filled in, as though they had never joined.

That happens because the only proof of who you are is kept by your own browser. Clear your browsing
data, come back in a private window, or sit down at a different browser, and that proof is gone —
even though the game is still running on the server and the seat is still yours.

Pick the player from the list and this hands you a link. Send it to them, and opening it in their own
browser puts them straight back in their seat. **The link works once and expires after 30 minutes**,
and whoever opens it takes that seat — so send it to that person directly rather than posting it
somewhere public. If it expires before they get to it, just run the action again.

> **Games in progress normally survive an update of this service.** When the update changes the
> rules of the game itself, a half-played game cannot be resumed under rules it was not played by,
> and that game is set aside rather than continued — you would see it disappear from the lobby.
> Nothing is ever deleted, so going back to the previous version makes it playable again.