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.pyDas 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:
| Kategorie | Anzahl | Groesse |
|---|---|---|
| Voice-Lines (8 NPCs + 8 Klassen + Generic) | 227 | 13 MB |
| SFX Phase 1 (Mob/Boss/Skill/UI/Combat) | 227 | 8 MB |
| SFX Phase 2 (Footsteps/Status/Crafting/Menu/Quest) | 78 | 3 MB |
| SFX Phase 3 (Decor/Trap/Weather/Pakt/Atmos/...) | 128 | 5 MB |
| SFX Total | 433 | ~16 MB |
| Stock-Sounds (Freesound, CC0) | 267 | 45 MB |
| Music-Tracks | 2 | 9 MB |
| Gesamt-Audio | ~927 Files | ~80 MB |
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)
| Akt | Region | Hub | Lore-Hook |
|---|---|---|---|
| 1 | Salzkueste | Brassweir | Drei Doerfer fehlen — die Salzwunde lockt |
| 1b | Zhar-Eth | Wandernde Karawane | Speerschwestern-Mondbund |
| 2 | Glasgoldene Ruinen | Echo-Markt | Das alte Imperium erinnert sich an seinen Tod |
| 3 | Aschenfelder | Saeulen-von-Helst | Wo Valsa fiel. Tribunal-Inquisition jagt dich |
| 4 | Wurzelgrab | Knoten-Markt | Shulavh, die Faden-Mutter, hat dich gewaehlt |
| 5 | Spiegelstadt Velharn | Spiegelhof | Drei Zeit-Schichten — Glasgolden, Goetterkrieg, Gegenwart |
| 6 | Drei Wunden | Wunden-Lager | Salzwunde, Aschwunde, Hohlwunde — den Pakt lesen |
| 7 | Hohlwort | Drei Muetter | Konfrontation mit Im-Nesh, dem Hundertzuengigen |
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.pyGame 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:
- ElevenLabs-Account erstellen (elevenlabs.io) — Creator-Plan (~22 EUR/mo) empfohlen
- API-Key holen unter Settings → API Keys
- Im Projekt-Root
ElevenLabs.txtanlegen mit dem Key (eine Zeile, nichts sonst) - In
docs/design/_legacy/VELGRAD_VOICE_CASTING.mddievoice_idfuer einen NPC ersetzen - 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:
- In
docs/design/VELGRAD_SFX_BIBEL.mdden ElevenLabs-Prompt anpassen - Im SFX-Manifest die
statusaufpendingsetzen (sounds/sfx/sfx_manifest.json) python tools/sfx_gen.pyrufen
- 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