TELLING TALES - CONSOLE PLAYER
=============================

Read and play Telling Tales .game stories in a terminal.
The examples below use Windows PowerShell.

QUICK START: BUILT OR PUBLISHED COPY
----------------------------------
Open a terminal in the folder containing Game.Console.exe and run:

    .\Game.Console.exe

Choose a game from the numbered menu. To launch a bundled game directly:

    .\Game.Console.exe the-debt-below
    .\Game.Console.exe the-names-i-answer-to
    .\Game.Console.exe tech-demo

Keep the whole build/publish folder together, including the DLL files and
GameFiles folder. Copying just the EXE is not enough.
The normal build requires the .NET 10 runtime. A self-contained published
copy includes its runtime. On systems without an EXE, use:

    dotnet Game.Console.dll

PLAY YOUR OWN GAME
------------------
Create a new editable game in a folder that does not already exist:

    .\Game.Console.exe --new "C:\Stories\My New Game"

This copies the same starter files used by the web editor:

    C:\Stories\My New Game\game.game
    C:\Stories\My New Game\styles\game.css

The destination folder must not already exist. This protects existing games
from being overwritten. Edit the copied files in a text editor, then run:

    .\Game.Console.exe "C:\Stories\My New Game"

The starter game includes @include-shared "character.game". The bundled
character file is used automatically, or use --shared when playing to select
your own shared folder. --new is a creation command and must be used by itself.

Pass the path to the main .game file:

    .\Game.Console.exe "C:\Stories\My Adventure\game.game"

Or pass a folder containing a file named game.game:

    .\Game.Console.exe "C:\Stories\My Adventure"

Relative paths are resolved from the terminal's current working folder:

    .\Game.Console.exe ".\My Stories\Adventure\game.game"
    .\Game.Console.exe "..\Stories\Adventure\game.game"

Always quote paths containing spaces. Supply one game at a time. Keep any
included chapters and other game files in their original folder structure.
Extract downloaded ZIP games before playing; ZIP files are not opened directly.

SHARED CHARACTER AND COMBAT FILES
--------------------------------
Games using @include-shared need a shared folder. For example:

    C:\Stories\character.game
    C:\Stories\combat.game
    C:\Stories\My Adventure\game.game
    C:\Stories\My Adventure\chapters\chapter1.game

Run this layout with:

    .\Game.Console.exe "C:\Stories\My Adventure" --shared "C:\Stories"

--shared takes a FOLDER, not the path to character.game. Put all shared files
needed by the game in that folder. It can be the same folder as the manifest
if that is where you keep your shared files.

If --shared is omitted, the player checks the parent of the game folder for
character.game. If it exists, that parent becomes the shared folder. Otherwise
the player uses the bundled GameFiles folder beside the application.
An explicit --shared overrides this automatic selection.

RUN FROM THE SOURCE PROJECT
---------------------------
Install the .NET 10 SDK. From the AdventureGame repository folder, run:

    dotnet run --project Console/Game.Console.csproj

Use -- to separate dotnet options from the game's arguments:

    dotnet run --project Console/Game.Console.csproj -- the-debt-below
    dotnet run --project Console/Game.Console.csproj -- --new "C:\Stories\My New Game"
    dotnet run --project Console/Game.Console.csproj -- "C:\Stories\My Adventure\game.game" --shared "C:\Stories"

To create a Release build:

    dotnet build Console/Game.Console.csproj --configuration Release

The Windows executable is then in Console\bin\Release\net10.0.

COMMANDS WHILE PLAYING
---------------------
Type a command and press Enter:

    1, 2, 3 ...   Choose a numbered option.
    A1, A2 ...    Use a listed link. Action links change the game;
                  other links display information or a URL.
    S             Save the current state.
    L             Load this game's saved state.
    R             Restart from the opening state of this run.
    Q             Quit.

Letter commands are case-insensitive. R restores the opening state already
generated for this run; it does not reload edited game files. Quit and launch
again to pick up file changes. Ending passages remain visible, and you can
still load, restart, or quit. There is no automatic save on quit.

SAVES
-----
On Windows, saves default to:

    %LOCALAPPDATA%\TellingTales\ConsoleSaves

Each game has a separate subfolder containing savegame.json. Saving again
replaces that game's previous save. S prints the exact path used.
Choose another save location with:

    .\Game.Console.exe "C:\Stories\My Adventure" --saves "C:\My Saves"

--saves selects the root folder; the player still creates a per-game subfolder.
Game identity includes the full manifest path. Moving a game can therefore
give it a new save folder. To reuse an older console save, back it up and copy
savegame.json into the new game's save folder. It must belong to a compatible
version of that game. Console saves are separate from website account saves.

CHECK A GAME WITHOUT PLAYING
---------------------------
    .\Game.Console.exe "C:\Stories\My Adventure\game.game" --validate
    .\Game.Console.exe tech-demo --validate

Add --shared if required. Warnings are printed but do not prevent play;
validation errors do. Exit code 0 means success, and 1 means an error occurred.
For a quick reminder of available arguments:

    .\Game.Console.exe --help

To display the player's build version:

    .\Game.Console.exe --version

WHAT THE TERMINAL CAN DISPLAY
-----------------------------
The console uses the website's game engine: shared modules, combat, variables,
inventory, entities, conditional choices, action links, snippets, and @goto
chains work through the same runtime.

Headings, bold, italics, underline, strike-through, colours, speech, uppercase,
and alignment have terminal equivalents. Some terminal apps display fewer
text effects than others. Aligned passages use plain text. Pictures become
descriptions or filenames; CSS fonts, sizes, backgrounds, and animation are
not reproduced. Web links are printed rather than opened automatically.

For plain output without terminal colour codes, set NO_COLOR before launch:

    $env:NO_COLOR = "1"
    .\Game.Console.exe tech-demo

To enable colours again in the same PowerShell session:

    Remove-Item Env:NO_COLOR

Redirected output is automatically plain text. Closing input exits the player.

TROUBLESHOOTING
---------------
"Game not found": check the quoted path, the current working folder, and that
the folder contains game.game. An existing local path takes precedence over
a bundled game ID of the same name.

"The game file was not found": check @include paths and the --shared folder.
Ordinary includes are relative to the file containing them.

"No saved game was found": save once with S, check --saves, and check whether
the game was moved to a different path.

"You must install or update .NET": install the .NET 10 runtime, or use a
self-contained copy supplied for your operating system.

Do not delete companion DLLs or GameFiles from a distributed player folder.
