Python 3.10+ pygame-ce Audio Status

Ein narratives 2D-ARPG in Pygame, angesiedelt in der Welt Velgrad — einer Welt, die sich selbst vergisst.

„Die Welt vergisst sich selbst. Wer erinnert dich — wenn du nicht?"

Self-contained: Game ist sofort spielbar nach git clone — alle 660 Audio-Files (Voice + SFX) sind im Repo enthalten.

Shadowfall ist ein Single-Player Action-RPG mit dichter Lore, taktischem Top-Down-Combat und einer durchgehend produzierten Audio-Pipeline. Inspiriert von Path of Exile 2, Diablo IV und Dark Souls — aber mit eigener mythologischer Welt: Sieben Aspekte, sieben Atemzuege, ein verlorener Pakt und ein Verraeter mit hundert Zungen.

Status: Foundation-Phase. Akt 1 spielbar mit vollem Audio, Akt 2–7 + Endgame in Planung.

git clone https://github.com/OsuGerman/shadowfall.git
cd shadowfall
pip install pygame-ce
python shadowfall.py

Das ist alles. Game laeuft mit komplettem Sound + 8 Klassen + Akt-1-Quests + Boss-Encounters.

• 7 Akte durch die Welt Velgrad — von der Salzkueste ueber die Glasgoldenen Ruinen bis zum Hohlwort
• 8 spielbare Klassen mit eigenen Lineages:
  • Warrior (Eisenwaechter, Kharn-Lineage)
  • Monk (Stiller Schritt, Selbst-Lineage)
  • Sorceress (Funkengeborene, Valsa-Beruehrt)
  • Witch (Knochenwitwe, Shulavh-Beruehrt)
  • Ranger (Saattraegerin, Wilde Lineage)
  • Mercenary (Mahnmal-Soeldner, Korven-Vor-Lineage)
  • Huntress (Speerschwester, Shulavh-Lineage)
  • Druid (Wandelnde, Drei-Tiere-Lineage)
• 7 Fraktionen mit Konflikt-Matrix (Erblinde Kirche, Tribunal der Asche, Mahnmal-Gilde, Knochenwitwen, Saattraeger, Speerschwestern, Stille Schritte)
• 53 Quests ausformuliert (Haupt + Faction + Side + Lore + Crafting + Bounty + Hidden) — siehe docs/lore/QUEST_BIBEL.md
• 3 Endings mit Akt-7-Wahl
• Voice-Acting fuer alle Haupt-NPCs — Korven, Helst, Vossharil, Tameris, Otreth, Mara, Vehren, Drei Muetter

• 30 Bestiarium-Mobs mit individuellen Hurt/Death-Sounds — siehe docs/gameplay/VELGRAD_BESTIARIUM.md
• 15 Boss-Encounters mit Multi-Phase-Cinematics + Spawn-Methods (rise_from_grave, assemble, descend_from_throne, emerge_from_liquid, ...)
• 50 Unique-Items — siehe docs/gameplay/VELGRAD_ITEMS_UNIQUE_BIBEL.md
• 7 Aspekt-Pakte als Skill-Gem-System (Kharn/Nheyra/Ousen/Valsa/Im-Nesh/Shulavh/Vergessen)
• Crafting: Upgrade, Reroll, Socket, Enchant, Salvage + Otreth-Gemcutter
• Mahnmal-Fast-Travel zwischen freigeschalteten Outposts
• Status-Effekte mit Element-Combos (burn + frost = shatter, etc.)
• Procedural Dungeons pro Biome mit Multi-Stage-Sub-Areas
• Quest-Engine mit 12 Stage-Types (TALK/KILL/REACH/COLLECT/INTERACT/RETURN/ESCORT/DEFEND/PUZZLE/CHOICE/TIMED/CONDITIONAL)
• Faction-Rep-System (geplant — UI-Wiring in Arbeit)

Vollstaendige Sound-Pipeline via ElevenLabs — alle Files im Repo enthalten:

Pipeline-Tools in tools/ erlauben Re-Generation mit eigenem ElevenLabs-Account (Voice-Casting-Aenderungen, neue Lines, etc.). Audio-Generierung kostete einmalig 10,35 EUR ElevenLabs Creator-Plan.

• Procedural Particle-System mit 4 Layern (Ambient/Gameplay/Telegraph/UI-Overlay)
• Dynamic Ambient Culling waehrend Boss-Encounters (~70% Reduktion fuer klare Lesbarkeit)
• Day/Night-Zyklus mit Wetter-Variation pro Biome (dust/snow/ash/pollen/sand/spore/stardust)
• Lighting-Pass mit per-Aspekt-Color-Lights
• NPC-Schedules (Tag/Nacht-Position)
• Footsteps pro Biome automatisch via pick_footstep_for_biome() (11 Material-Surfaces)
• Save-Game-Versionierung mit Migration-Pfaden
• Hardcore-Memorial-System fuer permadeath-Modus
• Engine-Wiring der Audio-Layer: Boss-Spawn-Stinger, Mahnmal-Stelen-Activation, Rarity-aware Item-Pickup, NPC-Voice beim Reden, Quest-Marker-Reach, Achievement-Unlock, Status-Apply (frozen/shock/poison/bleed/stun/silence)

Vollstaendige Lore in docs/lore/VELGRAD_LORE_BIBEL.md (588 Zeilen).

shadowfall/
├── shadowfall.py ← Game-Entry-Point (Pygame Main-Loop)
│
├── sf/ ← Engine-Code (65 Module)
│ ├── game.py ← Game-Loop, Update, Render
│ ├── combat.py ← Damage, Crit, Death-Layer, bestiary_key-Sounds
│ ├── boss_encounter.py ← Multi-Phase-Boss-Cinematics + Spawn/Phase-Stinger
│ ├── skills.py + class_skills.py ← 8 Klassen ×ばつ Skill-Pool
│ ├── enemies.py + bestiary.py ← 30 Velgrad-Mobs
│ ├── quests.py + quest_data.py ← Quest-Engine + 12 Stage-Types
│ ├── crafting.py + items.py ← Otreth-Gemcutter, Affix-System
│ ├── effects.py ← Status-Effekte mit Element-Combos
│ ├── sounds.py ← Audio-Bus, Footstep-Picker, SFX-Resolver
│ ├── voice_registry.py ← Auto-generiert: 85 Voice-Pools
│ ├── sfx_registry.py ← Auto-generiert: 433 SFX-Eintraege
│ ├── dungeon.py + dungeon_events.py + dungeon_gen.py
│ ├── sprites.py + lighting.py + weather.py + surface_fx.py + gl_post.py
│ ├── ui.py + town.py + outposts.py + shop.py + stash.py
│ ├── ai.py + entities.py + progression.py + save.py
│ ├── achievements.py + tutorial.py + crash_logger.py + tips.py
│ ├── skill_atlas.py ← POE2-Skill-Atlas (verbundener Node-Graph, ~140 Nodes)
│ ├── boss_encounter.py ← 8/15 Encounter-Configs verdrahtet
│ └── ... (regions, runes, gems, archetypes, aspects, bestiary, dialog, cutscene, ...)
│
├── tools/ ← Audio-Pipeline (Re-Generation optional)
│ ├── voice_gen.py ← ElevenLabs Voice-Generator
│ ├── voice_manifest_builder.py ← Parst Voice-Pool + Casting → JSON
│ ├── voice_list.py ← Listet ElevenLabs-Library-Stimmen
│ ├── voice_config.py ← API-Key-Loader, Pronunciation-Map
│ ├── sfx_gen.py ← ElevenLabs SFX-Generator (alle Phasen)
│ └── README.md ← Pipeline-Workflow
│
├── Sounds/ ← Audio-Assets (committet, ~70 MB)
│ ├── voice/ ← 227 Voice-Lines (8 NPCs + 8 Klassen + Generic)
│ │ ├── korven/ helst/ vossharil/ tameris/ otreth/ mara/ vehren/
│ │ ├── drei_muetter/ generic/
│ │ └── cls_warrior/ cls_monk/ cls_sorceress/ cls_witch/ ...
│ ├── sfx/generated/ ← 433 SFX in 31 Sektionen
│ │ ├── ui/ combat/ skills/ monster/ boss/ cinematic/ lore/
│ │ ├── movement/ player_combat/ status/ interact/ crafting/ menu/ quest/
│ │ ├── decor/ trap/ weather/ class_special/ currency/ event/
│ │ ├── boss_special/ flask/ player_voice/ achievement/
│ │ ├── engrave/ pakt/ daynight/ shop/ tutorial/ saveload/ atmos/
│ │ └── voice_manifest.json + sfx_manifest.json
│ ├── voice_de_legacy/ ← Vorlaeufige DE-Voice-Lines (Archiv, Pivot 2026年05月24日)
│ └── *.mp3 ← 267 Stock-Sounds (Freesound, CC0)
│
├── Nebel von Arken.mp3 ← Music-Track 1
├── Soundtrack 3.mp3 ← Music-Track 2
│
├── docs/project-mgmt/PLAN.md ← Master-Plan (Update-Tracker)
├── docs/project-mgmt/ROADMAP.md ← 5-Tier-Sprint-Plan, 149 priorisierte Tasks
├── docs/project-mgmt/WELT_AUFBAU.md ← Welt-Topologie + NPC-Roster + Phasen-Plan
├── docs/lore/QUEST_BIBEL.md ← 53 Quests ausformuliert + Stage-Definitionen
├── docs/lore/VELGRAD_LORE_BIBEL.md ← Kosmologie + 7 Aspekte + Akt-Storyline (588 Zeilen)
├── docs/gameplay/VELGRAD_BESTIARIUM.md ← 30 Mobs mit Behavior-Patterns
├── docs/gameplay/VELGRAD_ITEMS_UNIQUE_BIBEL.md ← 50 Unique-Items
├── docs/design/VELGRAD_VOICE_LINES_POOL.md ← Dialog-Texte pro NPC
├── docs/design/_legacy/VELGRAD_VOICE_CASTING.md ← Voice-IDs pro Charakter (ElevenLabs)
├── docs/design/VELGRAD_AUDIO_DESIGN_BIBEL.md ← Audio-Vision
├── docs/design/VELGRAD_SFX_BIBEL.md ← 453 SFX-Definitionen + Prompts
├── docs/gameplay/POE2_GAMEPLAY_SYSTEMS_ERWEITERUNG.md ← Mechanik-Referenz
├── docs/gameplay/POE2_SKILLS_BRIEFING_FUER_CLAUDE_CODE.md ← Skill-Tree-Referenz
├── docs/meta/CHANGELOG.md ← Update-Historie (Update #1 → #204)
├── bugreports/ ← Verifikations-Screenshots/Audio pro Update
├── tests/smoke.py ← Smoke-Tests (212 Tests, 211 grün, 1 flaky-RNG)
├── tools/ ← Asset-Pipelines (Audio + Tile + Walk-Strip)
└── Design idee/ ← UI-Mockups (HTML/JSX)

• Python 3.10+ (getestet mit 3.14)
• pygame-ce 2.5+ (Community-Fork, performanter als Mainline)

git clone https://github.com/OsuGerman/shadowfall.git
cd shadowfall
pip install pygame-ce
python shadowfall.py

Game laeuft mit vollem Sound. Keine weiteren Schritte noetig.

Falls du z. B. eine andere Stimme fuer Korven oder Vossharil willst, kannst du das Voice-Casting anpassen und neu generieren:

1. ElevenLabs-Account erstellen (elevenlabs.io) — Creator-Plan (~22 EUR/mo) empfohlen
2. API-Key holen unter Settings → API Keys
3. Im Projekt-Root ElevenLabs.txt anlegen mit dem Key (eine Zeile, nichts sonst)
4. In docs/design/_legacy/VELGRAD_VOICE_CASTING.md die voice_id fuer einen NPC ersetzen
5. Voice-Generation:

   python tools/voice_manifest_builder.py
   python tools/voice_gen.py --npc korven # nur Korven neu

Sicherheit: ElevenLabs.txt ist in .gitignore eingetragen — der Key wird nie versehentlich committet.

Analog fuer SFX, falls du z. B. den Salzhueter-Boss-Roar dramatischer haben willst:

1. In docs/design/VELGRAD_SFX_BIBEL.md den ElevenLabs-Prompt anpassen
2. Im SFX-Manifest die status auf pending setzen (sounds/sfx/sfx_manifest.json)
3. python tools/sfx_gen.py rufen

• Spielsprache: Deutsch
• Code: Englisch (Variablen, Funktionen) — Kommentare gemischt DE/EN
• Lore-Dokumente: Deutsch (Velgrad'scher Stil mit altertuemlichen Wendungen)
• NPC-Voices: Deutsch (ElevenLabs eleven_multilingual_v2)

python -m pytest tests/

Smoke-Tests in tests/smoke.py decken Engine-Importe, Save/Load, Crafting-Logik, Quest-Engine, NPC-Spawning, Akt-Progression, Skill-Atlas-Persistenz, Quest-Auto-Fail-Pfade und NPC-Marker-Konsistenz ab. 212 Tests, 211 grün (1 flaky-RNG bei dot_kill_loot_pipeline, AUDIT C.12 — bekannt).

• ✅ Pygame-Engine mit 65 Modulen
• ✅ Akt 1 (Salzkueste) komplett spielbar — Korven, Otreth, Tameris, Mara, Eldon, Mahnmal-Verwahrer, Helst-Vorpost, Brassweir-Hub
• ✅ Akt 2 in Arbeit — Echo-Markt-Outpost layoutet, 6 Akt-2-Quests im Registry, „Glasgoldener Palast"-Naming (Phase 1)
• ✅ Boss-Encounters: 8/15 Configs verdrahtet — Salzhueter-Brut, Vehren, Senator-Geist, Shulavh, Velharn-Trio, Ertrunkene Koenigin, Echo-Drache, Nicht-Gott
• ✅ POE2-Skill-Atlas (sf/skill_atlas.py) — verbundener Node-Graph (~140 Nodes), alle 8 Klassen haben echte Arme, Moench mit gameplay-aendernden Keystones (Phase 1)
• ✅ Quest-Engine mit 12 Stage-Types + Auto-Fail-Pfad (DEFEND-Grace, ESCORT-Timeout, Main-Quest-Revert statt Fail, on_quest_failed-Hook)
• ✅ Audio-Pipeline vollstaendig im Repo — 227 Voice + 433 SFX
• ✅ Crafting + Affix-System + Otreth-Gemcutter
• ✅ Mahnmal-Schrein mit 7-Aspekt-Pakt-Wahl, 22 Outpost-NPCs
• ✅ Footsteps pro Biome (11 Material-Surfaces)
• ✅ Volumetrische Wolken + Fog-Parallax, Atem-Ambient pro Biome×ばつIntensitaet
• ✅ HUD-Pass: Hotkey-Bar mit Panel, Cartouche-Portrait, Quest-Tracker, Codex, Mini-Map mit Fog-of-War + POI-Icons

• ⏳ Akt 1 vollstaendig (4 weitere Quests: Tameris-Schwester-Chain, Tribunal-Geruecht, Bounty-Salzgekreuzte, Versunkenes Grab)
• ⏳ Faction-Rep-System UI im Codex
• ⏳ Akt 2 ausbauen (Helst-NPC, Senator-Geist-Boss-Mechanik, Glass-Ruins-Biome-Tiles)
• ⏳ Skill-Atlas: Keystones/tiefere Trees fuer die 7 Nicht-Monk-Klassen
• ⏳ Music-Tracks (42 geplant — Akt-Themes, Boss-Themes, Town-Themes)
• ⏳ Ambience-Loops (14 velgrad-spezifische Loops)
• ⏳ Cutscene-Framework + 9 Pflicht-Cutscenes
• ⏳ 47 von 53 Quests aus der QUEST_BIBEL noch in sf/quest_data.py verdrahten
• ⏳ Endgame-Atlas (Welkende Welten)
• ⏳ Sprite-Pass: Procedural-Renderer ausbauen, optionale Re-Introduction externer Sprite-Sheets (Pipeline-Tools im Repo erhalten)

Detail-Roadmap in docs/project-mgmt/ROADMAP.md (5-Tier-Sprint-Plan, 149 priorisierte Tasks aus docs/project-mgmt/PLAN.md + docs/project-mgmt/WELT_AUFBAU.md + docs/lore/QUEST_BIBEL.md synthetisiert).

• Update #204 — Doku-Pass + Push-Sync der offenen Updates #181–#203 (README/CHANGELOG-Glaettung)
• Update #203 — Player/Mob-Render-Scale kleiner (PROC_SPRITE_SCALE=0.82, Mob 1.7→1.4) — kompaktere Szene, Fuesse korrekt am Boden
• Update #202 — NPC-Talk-Batch-Accept: ein Gespraech nimmt alle verfuegbaren Quests an, kein !/?-Flackern mehr
• Update #201 — HUD-Entzerrung: Cartouche-Glow raus, Hotbar-Panel, Toast-Stack hoeher, Portal-Label-Clamping
• Update #196–#200 — Akt-2-Balance, Save-Fix fuer verwaiste Node-IDs, Quest-Marker fuer abandoned/failed, HUD-Cartouche-Aufwertung
• Update #195 — Skill-Atlas: 7 Klassen-Arme + Label-Kollisions-Vermeidung
• Update #194 — Quest-Auto-Fail-Pipeline: DEFEND-Grace (6s), ESCORT-Timeout (240s, im Dungeon pausiert), on_quest_failed-Hook
• Update #184 — POE2-Skill-Atlas: ~140 Nodes, Pan/Allocate/Refund, kollisionsfreie Labels
• Update #181–#193 — Surface-FX-Wall-Clipping-Fix, Camera-Delta-Parallax, Atem-Ambient pro Biome×ばつIntensitaet, volumetrische Wolken + Fog-Parallax, procedural Detail-Sprite-Pass

Vollstaendige Update-Historie in docs/meta/CHANGELOG.md.

Das Projekt ist aktuell Solo-Dev. Bug-Reports und Lore-Ideen via GitHub-Issues willkommen. Code-Beitraege bitte erst nach Diskussion (das Game ist eng mit der Lore verzahnt — willkuerliche Mechanik-Aenderungen passen oft nicht zum Setting).

• Spielkonzept, Lore, Code: Adrian Mirwaldt (@OsuGerman)
• Stock-Sounds: Freesound.org (CC0 + verschiedene Lizenzen — Attribution in den Dateinamen)
• Voice: ElevenLabs (eleven_multilingual_v2) — kommerzielle Lizenz via Creator-Plan
• SFX: ElevenLabs Sound Effects API
• Engine: pygame-ce (LGPL)
• Genre-Inspiration: Path of Exile 2, Diablo IV, Dark Souls, Hollow Knight

Lizenz: aktuell kein offizielles Lizenz-Modell — privat / nicht-kommerzieller Open-Development. Lizenz wird vor erstem Release finalisiert. Bei Fragen zur Nutzung: Issue oeffnen.

„Du wirfst keinen Feuerball. Du erinnerst die Luft daran, dass sie einst ein Feuerball war." — Bruder Helst, Erblinder Priester, Akt 2

„Ein Schwur ist ein Faden. Ein Faden haelt die Welt. Reisst der Faden, faellt die Welt. Reisst sie nicht aus Boesheit — sondern weil niemand sie mehr hielt."

„Es gab einmal sieben Atemzuege. Sechs davon halten dich. Den siebten — den fuerchtet jeder. Den fuerchte ich am wenigsten. Er ist der einzige, der mir mein Ende laesst." — Vossharil die Dreimalige

„Atme. Wieder. Bitte." — Ousen, Endgame