Metadata-Version: 2.4
Name: skifi-adventure
Version: 0.1.1
Summary: A hand-authored Sci-Fi text adventure for your terminal.
Requires-Python: >=3.11
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Requires-Dist: questionary>=2
Requires-Dist: rich>=13
Description-Content-Type: text/markdown

# SciFi Terminal Adventure

Ein handgeschriebenes Sci-Fi-Text-Adventure für dein Terminal.

```
uvx skifi-adventure
```

Für eine nicht-technische Spieler-Anleitung siehe [`INSTALL_MACOS.md`](./INSTALL_MACOS.md).

> **Status:** v0.1 — erstes spielbares Release, Akt 1 (Cliffhanger-Ende, bewusst
> als Kapitel-Abschluss gedacht). Freie Texteingabe statt Menü — man tippt, was man
> tun will, kein Klicken durch Listen. Weitere Akte werden bei Bedarf ergänzt.

## Dev-Setup

Voraussetzung: [`uv`](https://docs.astral.sh/uv/) installiert
(`curl -LsSf https://astral.sh/uv/install.sh | sh`).

```bash
git clone git@github.com:joshuaceylan13-lab/skifi-adventure.git
cd skifi-adventure
uv sync
```

## Spielen (aus dem Quellcode)

```bash
uv run skifi-adventure
```

Läuft direkt gegen den Code in `src/` — kein separater Build-Schritt nötig.

## Tests & Linting

```bash
uv run pytest              # Engine-Tests + Content-Graph-Tests
uv run scripts/lint_content.py   # Standalone Content-Linter (dieselbe Logik wie die Tests)
```

Der Content-Linter prüft:
- keine toten `target`-Referenzen in Choices
- keine verwaisten Szenen (von `start` aus nicht erreichbar)
- alle `ending: true`-Szenen sind erreichbar

## Spielprinzip: freie Texteingabe statt Menü

Es gibt bewusst **kein Auswahlmenü** — Spieler:innen tippen frei, was ihre Figur tun
soll (`nimm keycard`, `flieh zur schleuse`, ...). Das übernimmt
`src/skifi_adventure/engine/parser.py`: ein kleiner, statischer Verb/Nomen-Matcher
(keine Laufzeit-KI) — jede `Choice` listet Verb- und optionale Nomen-Synonyme, gegen
die die Eingabe abgeglichen wird. Global immer erkannt: `hilfe`, `inventar`, `schau`,
`sichern`, `beenden`.

## Content schreiben

Story-Szenen liegen als YAML unter `src/skifi_adventure/content/actN/*.yaml`
(eine Datei kann eine Liste mehrerer Szenen enthalten). Format:

```yaml
- id: eindeutige_szenen_id
  act: 1
  text: |
    Mehrzeiliger Fließtext der Szene.
  choices:
    - label: "Was der Spieler sieht (für Hinweise/Meldungen, kein Menü)"
      target: naechste_szenen_id
      verbs: ["nimm", "nehmen", "hol"]    # Pflicht — mind. 1 Verb-Synonym
      nouns: ["item", "gegenstand"]       # optional — leer = Verb allein reicht
      requires:                           # optional
        flags: { irgendein_flag: true }
        inventory: ["item_id"]
      effects:                            # optional
        flags: { anderes_flag: true }
        add_inventory: ["item_id"]
        remove_inventory: ["anderes_item"]
```

Faustregeln fürs `verbs`/`nouns`-Design:
- Hat eine Szene nur **eine** sinnvolle Handlung (z. B. "weiterrennen"), `nouns` leer
  lassen — dann reicht jedes gelistete Verb allein.
- Haben mehrere Choices in derselben Szene überlappende Verben (z. B. mehrere
  "nimm ..."-Optionen), müssen sie sich über `nouns` unterscheiden lassen.
- Keine Füllwörter (die/der/das/...) in `verbs`/`nouns` nötig — die werden vom
  Parser automatisch ignoriert.

Ending-Szenen brauchen `ending: true` und `ending_id: irgendein_name` statt `choices`.
Jede Story braucht genau eine Szene mit `id: start` als Einstiegspunkt.

Nach dem Schreiben immer `uv run pytest` laufen lassen — der Content-Graph-Test
schlägt fehl, falls ein Link kaputt ist oder eine Szene nie verlinkt wurde.

## Projektstruktur

```
src/skifi_adventure/
├── engine/          # Story-Loader, Choice-Resolution, Save/Load, Linter
├── content/actN/    # Die eigentliche Story (YAML)
└── render.py        # Terminal-Styling (rich)
```

## Release / Publish

```bash
uv build                                    # baut sdist + wheel nach dist/
uv publish                                  # auf PyPI veröffentlichen (braucht Login/Token)
```

Vor jedem Release einmal die Fremd-Nutzer-Simulation durchspielen:

```bash
uvx --from ./dist/skifi_adventure-<version>-py3-none-any.whl skifi-adventure
```
