diff --git a/apps/web/public/assets/hud-elements/x.png b/apps/web/public/assets/hud-elements/x.png new file mode 100644 index 0000000..2652085 Binary files /dev/null and b/apps/web/public/assets/hud-elements/x.png differ diff --git a/apps/web/src/app/features/combat/combat-page/combat-page.component.html b/apps/web/src/app/features/combat/combat-page/combat-page.component.html index 8d2a1c4..d214f1d 100644 --- a/apps/web/src/app/features/combat/combat-page/combat-page.component.html +++ b/apps/web/src/app/features/combat/combat-page/combat-page.component.html @@ -1,6 +1,6 @@
@if (combat(); as combat) { -
+
diff --git a/apps/web/src/app/features/combat/combat-page/combat-page.component.scss b/apps/web/src/app/features/combat/combat-page/combat-page.component.scss index c00b699..ccd4d81 100644 --- a/apps/web/src/app/features/combat/combat-page/combat-page.component.scss +++ b/apps/web/src/app/features/combat/combat-page/combat-page.component.scss @@ -20,7 +20,12 @@ container-type: inline-size; grid-template-rows: auto minmax(0, 1fr) auto; gap: var(--ar-space-4); - min-block-size: 26rem; + // The sprites are sized as a share of the stage, so the stage has to carry a + // height of its own. With only a min-block-size the tallest cut-out -- the + // road bandit -- sized the battlefield row from its intrinsic height and + // pushed the page into a scrollbar. The subtracted 12.5rem is the shell + // chrome around the main column: top bar, footer and its own padding. + block-size: max(24rem, calc(100dvh - 12.5rem)); padding: var(--ar-space-4); overflow: hidden; border: 1px solid var(--ar-border); @@ -182,7 +187,11 @@ position: relative; z-index: 1; display: grid; + // The single row is spelled out rather than left implicit: only then is it a + // definite height, and only then do the sprites' percentage heights resolve + // against the battlefield instead of against their own artwork. grid-template-columns: 1fr 1fr; + grid-template-rows: minmax(0, 1fr); align-items: end; min-block-size: 0; } @@ -602,7 +611,7 @@ } .combat__stage { - min-block-size: clamp(24rem, 55vh, 34rem); + block-size: clamp(20rem, 55dvh, 34rem); } .combat__log { diff --git a/apps/web/src/app/features/combat/combat-page/combat-page.component.spec.ts b/apps/web/src/app/features/combat/combat-page/combat-page.component.spec.ts index 626528e..d048986 100644 --- a/apps/web/src/app/features/combat/combat-page/combat-page.component.spec.ts +++ b/apps/web/src/app/features/combat/combat-page/combat-page.component.spec.ts @@ -162,7 +162,8 @@ describe('CombatPageComponent', () => { expect(sprite?.classList.contains('sprite--hit')).toBe(true); expect(monster?.classList.contains('sprite--lunge')).toBe(true); expect(monster?.classList.contains('sprite--flinch')).toBe(false); - expect(stage?.classList.contains('combat__stage--shaken')).toBe(true); + // The stage jolt is wired up but no longer fires on an ordinary hit. + expect(stage?.classList.contains('combat__stage--shaken')).toBe(false); expect(element.textContent).toContain('90 / 100'); expect(countOccurrences(element.textContent, monsterHitLine)).toBe(2); diff --git a/apps/web/src/app/features/combat/combat-page/combat-page.component.ts b/apps/web/src/app/features/combat/combat-page/combat-page.component.ts index 320c240..38f13ed 100644 --- a/apps/web/src/app/features/combat/combat-page/combat-page.component.ts +++ b/apps/web/src/app/features/combat/combat-page/combat-page.component.ts @@ -28,6 +28,8 @@ const SWING_MS = 540; const RECOIL_MS = 540; // Beat between the player's blow landing and the monster striking back. const RIPOSTE_DELAY_MS = 260; +// Length of the stage jolt keyframes, see `stage-shake` in the stylesheet. +const STAGE_SHAKE_MS = 200; @Component({ selector: 'app-combat-page', @@ -47,9 +49,15 @@ export class CombatPageComponent implements OnInit { private readonly displayed = signal(null); private readonly replaying = signal(false); + // The stage jolt stays wired up but is no longer fired by an ordinary hit -- + // it was too much for every single round. Call `shakeStage()` to bring it + // back for a specific ability. + private readonly stageShaking = signal(false); + protected readonly combat = this.displayed.asReadonly(); protected readonly phase = signal('idle'); protected readonly monsterPhase = signal('idle'); + protected readonly stageShake = this.stageShaking.asReadonly(); protected readonly busy = computed(() => this.replaying() || this.combatStore.actionPending()); protected readonly playerIcon = PLAYER_ICON; @@ -125,6 +133,16 @@ export class CombatPageComponent implements OnInit { } } + /** Jolts the whole stage once. Reserved for abilities; no attack triggers it. */ + protected shakeStage(): void { + this.stageShaking.set(true); + setTimeout(() => { + if (!this.destroyed) { + this.stageShaking.set(false); + } + }, STAGE_SHAKE_MS); + } + protected retry(): void { void this.loadFromRoute(); } diff --git a/apps/web/src/app/layout/app-shell/app-shell.component.html b/apps/web/src/app/layout/app-shell/app-shell.component.html index a3fe8f0..07ff3cd 100644 --- a/apps/web/src/app/layout/app-shell/app-shell.component.html +++ b/apps/web/src/app/layout/app-shell/app-shell.component.html @@ -1,12 +1,14 @@
-
+
- + @if (!inCombat()) { + + }
diff --git a/apps/web/src/app/layout/app-shell/app-shell.component.scss b/apps/web/src/app/layout/app-shell/app-shell.component.scss index 9f90797..4a5bd13 100644 --- a/apps/web/src/app/layout/app-shell/app-shell.component.scss +++ b/apps/web/src/app/layout/app-shell/app-shell.component.scss @@ -16,6 +16,12 @@ min-block-size: 0; } +// Without the context rail the main column takes its place. The narrow layouts +// below re-declare the template, so they keep working either way. +.app-shell__content--no-context { + grid-template-columns: minmax(11rem, 13rem) minmax(0, 1fr); +} + .app-shell__main { min-inline-size: 0; min-block-size: 0; diff --git a/apps/web/src/app/layout/app-shell/app-shell.component.ts b/apps/web/src/app/layout/app-shell/app-shell.component.ts index eea9c19..c8160f4 100644 --- a/apps/web/src/app/layout/app-shell/app-shell.component.ts +++ b/apps/web/src/app/layout/app-shell/app-shell.component.ts @@ -1,5 +1,5 @@ import { Component, inject } from '@angular/core'; -import { RouterOutlet } from '@angular/router'; +import { Router, RouterOutlet, isActive } from '@angular/router'; import { WorldStore } from '../../features/world/world.store'; import { ContextPanelComponent } from '../context-panel/context-panel.component'; import { GameFooterComponent } from '../game-footer/game-footer.component'; @@ -20,4 +20,8 @@ import { TopBarComponent } from '../top-bar/top-bar.component'; }) export class AppShellComponent { protected readonly worldStore = inject(WorldStore); + + // The fight has its own log rail and wants the width, and the area info + // belongs to the world view anyway, so the rail is dropped during combat. + protected readonly inCombat = isActive('/combat', inject(Router)); } diff --git a/docs/Ashen_Realms_Story_Narrative_Implementation_V1.md b/docs/Ashen_Realms_Story_Narrative_Implementation_V1.md new file mode 100644 index 0000000..0983511 --- /dev/null +++ b/docs/Ashen_Realms_Story_Narrative_Implementation_V1.md @@ -0,0 +1,1916 @@ +# Ashen Realms – Story & Narrative Implementation Specification V1 + +## Purpose of this document + +This document defines the narrative foundation of **Ashen Realms** and explains how the story must be integrated into the existing world, progression, locations, NPCs, quests, encounters, items, and UI. + +It is intended as a binding reference for: + +- narrative design +- quest design +- world and location design +- NPC implementation +- item and loot descriptions +- environmental storytelling +- frontend implementation +- backend story-state implementation +- AI-assisted content generation + +This document does **not** define every final dialogue line or every quest. It defines the canonical story structure, reveal order, and implementation rules that future content must follow. + +--- + +# 1. Narrative vision + +Ashen Realms should not begin as a story about a chosen hero saving the world. + +The player starts as an unknown adventurer in a frontier region where several local problems appear to be unrelated: + +- caravans disappear +- bandits control old roads +- animals become unnaturally aggressive +- ancient dead begin to rise +- forgotten ruins become dangerous again + +The player gradually discovers that these events are connected. + +The central narrative principle is: + +> **Every region presents a believable local problem first. Only later does the player understand that it is part of a much older and larger mystery.** + +The story should create curiosity through discovery rather than exposition. + +The player should frequently think: + +> **"Something is wrong here, and I want to know what caused it."** + +--- + +# 2. Core narrative premise + +Centuries ago, an old kingdom discovered a strange black mineral deep beneath the earth. + +The material became known as **Blackstone**. + +Blackstone was valuable because it could be used to create unusually durable weapons, retain heat, and interact with forces that the people of the old kingdom did not fully understand. + +The king ordered increasingly deep excavation. + +Eventually, the miners uncovered something beneath the kingdom that should have remained sealed. + +What exactly was discovered is intentionally **not defined in V1**. + +It must remain a long-term mystery. + +The important fact is that the excavation released a corrupting influence that later generations would simply call: + +## The Ash + +The Ash is not ordinary fire residue. + +It is a supernatural or unknown influence connected to the depths beneath the old kingdom and to Blackstone. + +Its effects change depending on what it reaches. + +Examples: + +- barren land becomes dry, burned, and unnaturally warm +- animals become aggressive or distorted +- plants and water become corrupted +- strong memories, vows, and unfinished duties can bind the dead to the world +- ancient magical or ritual structures can become unstable + +The Ash must not initially be explained as a simple disease, curse, demon, or magical element. + +Its true nature is a long-term mystery of Ashen Realms. + +--- + +# 3. The old kingdom + +The name of the old kingdom is intentionally not final in V1. + +Future documentation may assign a canonical name. + +The kingdom once controlled the lands surrounding the current game regions. + +During its final era, it became increasingly dependent on Blackstone. + +The reasons may later include: + +- war +- economic collapse +- famine +- political instability +- external enemies + +The important narrative rule is: + +> **The king must not initially be presented as a purely evil ruler.** + +He should eventually be understood as a ruler who made increasingly dangerous decisions while trying to preserve a failing kingdom. + +This gives later history moral ambiguity. + +--- + +# 4. The Broken King + +The final ruler of the old kingdom is remembered only through fragmented legends. + +Later generations call him: + +## The Broken King + +The title does not necessarily mean that he became physically corrupted. + +It may refer to: + +- the destruction of his kingdom +- his conflict with his own soldiers +- his obsession with Blackstone +- his final decisions +- his eventual fate + +The true story of the Broken King should not be fully revealed during the first three regions. + +Existing item names such as **Blade of the Broken King** should function as early hints that this forgotten ruler remains important. + +--- + +# 5. The Last Watch + +When the dangers beneath the kingdom became impossible to ignore, an order of soldiers and guardians turned against the continued excavation. + +They became known as: + +## The Last Watch + +The Last Watch eventually fought to contain the disaster. + +Their final mission was not to conquer an enemy. + +It was to prevent anyone from reaching the deepest Blackstone excavations again. + +They sealed tunnels, guarded ruins, destroyed records, and died protecting access points to the depths. + +Their symbols and relics survive across the current game world. + +Existing content connected to the Last Watch includes: + +- Helm of the Last Watch +- Breastplate of the Last Watch +- Seal of the Last Watch +- Banner Fragment of the Last Watch +- Chapel of the Last Watch +- Sir Varos, the Broken + +The Last Watch is one of the primary connective elements between regions. + +--- + +# 6. The sealing + +The Last Watch ultimately succeeded in sealing the deepest excavations. + +The old kingdom collapsed regardless. + +Over the following centuries: + +- cities were abandoned +- roads disappeared +- ruins were reclaimed by nature +- surviving communities created new settlements +- the true purpose of the sealed mines was forgotten +- historical events became legends + +Knowledge of Blackstone slowly disappeared from common memory. + +The sealing was never meant to last forever. + +It only ensured that future generations would have to deliberately break it before the danger could return. + +--- + +# 7. Graufurt in the present day + +Graufurt is a frontier settlement built long after the fall of the old kingdom. + +It is not the political center of the world. + +It survives through: + +- trade +- hunting +- travelers +- local merchants +- nearby roads and settlements + +Graufurt is important because it provides the player with a grounded starting perspective. + +At the beginning of the game, most people in Graufurt believe the region has practical problems: + +- increased bandit activity +- missing caravans +- dangerous wildlife +- unsafe roads + +Very few people believe these events are connected to ancient history. + +The player begins with the same limited understanding. + +--- + +# 8. Player role + +The player is not the chosen one. + +There is no prophecy requiring the player to solve the central mystery. + +The player becomes important because they repeatedly: + +- survive dangerous places +- investigate unusual events +- return with evidence +- gain the trust of local people +- discover connections others have missed + +The player's importance is earned through actions. + +This directly supports the reputation-based progression philosophy of Ashen Realms. + +Narrative recognition should increasingly reflect what the player has actually accomplished. + +Examples: + +Early NPC reaction: + +> "I don't know you. If you're heading south, stay close to the road." + +Later reaction: + +> "You're the one who cleared the Ashen Bandits from the old road, aren't you?" + +Much later: + +> "If you say something is moving beneath Velkar, I'll believe you." + +--- + +# 9. Narrative structure of the first saga + +The first major story arc is structured as follows: + +1. **Smoke on the Road** – Ashen Fields +2. **The Sick Forest** – Duskwood +3. **The Last Oath** – Forgotten Ruins +4. **Beneath Black Stone** – Blackstone Mine +5. **The Guilt of the Living** – later region +6. **The Broken Realm** – later major arc + +Only the first three chapters are fully defined in this document. + +Blackstone Mine is established as the next major narrative destination. + +--- + +# 10. Reveal philosophy + +The narrative must follow a strict reveal order. + +## The player must not learn the complete truth too early. + +Each region answers one question and creates another. + +The intended sequence is: + +### Beginning + +Question: + +> Why are the roads becoming dangerous? + +### End of Ashen Fields + +Answer: + +> The bandits are deliberately collecting strange black material. + +New question: + +> Who wants Blackstone, and why? + +### Duskwood + +Answer: + +> The same influence is corrupting the forest and wildlife. + +New question: + +> Has this happened before? + +### Forgotten Ruins + +Answer: + +> Yes. The Last Watch fought the same phenomenon centuries ago. + +New question: + +> What did they seal beneath the old kingdom? + +### End of Forgotten Ruins + +Answer: + +> Someone has reopened the old Blackstone excavations. + +New question: + +> Who reopened them, and what are they trying to obtain? + +This question becomes the hook for the next major region. + +--- + +# 11. Chapter I – Smoke on the Road + +## Region + +**Ashen Fields** + +## Player-facing local problem + +The old trade route south of Graufurt has become increasingly dangerous. + +Caravans disappear. + +Bandits attack travelers. + +Parts of the road appear to have burned. + +The immediate objective is simple: + +> Restore enough safety to the southern road to understand what is happening. + +## Initial assumption + +The player and most NPCs believe: + +> Bandits are responsible for the destruction. + +This assumption should feel reasonable. + +--- + +# 12. Ashen Fields environmental storytelling + +The region should contain visual clues before NPCs explain them. + +Examples: + +## Burned wagons + +Some wagons appear burned from the inside rather than attacked with normal fire. + +Possible inspection text: + +> **The wood is blackened from within. There are no signs of oil or an external fire.** + +## Black dust + +Fine black residue can be found between broken cargo crates. + +Possible inspection text: + +> **A layer of heavy black dust coats the inside of the crate. It is strangely warm.** + +## Old symbols + +The abandoned watchpost contains a damaged emblem associated with the Last Watch. + +The player does not yet know what it means. + +Possible inspection text: + +> **A weathered emblem is carved into the stone. Most of it has been deliberately chiseled away.** + +The UI may record this as an unknown symbol. + +--- + +# 13. Ashen Fields story progression + +## South Gate of Graufurt + +Narrative function: + +- establish the unsafe road +- introduce missing caravans +- introduce local rumors +- establish that the player is still unknown + +NPCs should not talk about ancient kingdoms or supernatural corruption here. + +The tone remains grounded. + +--- + +## Burned Road + +Narrative function: + +- first strange environmental evidence +- first indication that normal bandit activity does not explain everything + +Recommended story interactions: + +- inspect burned caravan +- inspect unusual cargo residue +- question a survivor or guard +- recover marked bandit cargo + +The player should leave the Burned Road thinking: + +> **"The bandits are looking for something specific."** + +--- + +## Abandoned Watchpost + +Narrative function: + +- connect current events to older ruins +- first appearance of the Last Watch symbol +- reveal more organized bandit activity + +Recommended story interactions: + +- speak with the remaining watchman +- inspect old military markings +- recover bandit notes +- discover references to the Ash Pit + +The watchman should know the symbol is old but not necessarily understand its original purpose. + +--- + +## Ash Pit + +Narrative function: + +- end the local bandit conflict +- reveal that the bandits were gathering Blackstone for someone else + +The **Captain of the Ashen Band** must not be the mastermind of the wider story. + +He is a local criminal leader working for profit. + +After defeating him, the player discovers evidence of a larger operation. + +Recommended evidence: + +- delivery order +- crate markings +- payment ledger +- map fragment + +Example recovered document: + +> **Delivery Order** +> +> Twelve sealed crates. Black stone only. No ore, no iron, no ashwood. +> +> Deliver to the old forest road after nightfall. +> +> Payment on receipt. + +The sender must remain unidentified in V1. + +--- + +# 14. Ashen Fields chapter ending + +The player returns with evidence that: + +- the bandits were not randomly looting caravans +- Blackstone is being deliberately collected +- the material is being moved toward Duskwood + +This should unlock the narrative transition toward the forest. + +The chapter ending should not say: + +> "The ancient evil has returned." + +Instead: + +> **Someone is buying Blackstone.** + +That is the first major story hook. + +--- + +# 15. Chapter II – The Sick Forest + +## Region + +**Duskwood** + +## Player-facing local problem + +Hunters report increasingly aggressive animals. + +Several species show unusual physical changes. + +Paths have become dangerous. + +The immediate assumption is: + +> A disease or local corruption is spreading through the forest. + +--- + +# 16. Elyra, the Exiled Huntress + +Elyra is the primary narrative NPC of Duskwood. + +She must not function only as a quest dispenser. + +Her role is to help the player interpret the forest. + +She has observed that the corruption does not spread like a normal disease. + +Important observations: + +- isolated animals show similar symptoms +- corruption clusters near water and low ground +- affected roots contain black residue +- the oldest signs appear near stone formations beneath the forest + +Elyra's key narrative insight is: + +> **The animals are not spreading the corruption. Something beneath the forest is reaching them.** + +--- + +# 17. Duskwood environmental storytelling + +Examples: + +## Black veins in trees + +Possible inspection text: + +> **Thin black lines run beneath the bark like veins. The wood around them is warm and brittle.** + +## Corrupted water + +Possible inspection text: + +> **Dark sediment has collected beneath the water. It resembles the residue found in the burned caravans.** + +## Stone beneath the roots + +Possible inspection text: + +> **The roots have grown around a slab of worked stone. A familiar damaged emblem is visible beneath the moss.** + +This visually reconnects the forest to the unknown symbol from Ashen Fields. + +--- + +# 18. Duskwood story progression + +## Forest Edge + +Narrative function: + +- show first corrupted wildlife +- make the problem appear biological +- introduce hunting evidence + +The player should initially believe the forest itself is becoming sick. + +--- + +## Mist Path + +Narrative function: + +- increase the scale of the corruption +- connect water, roots, and Blackstone residue + +Recommended interactions: + +- inspect contaminated water +- follow animal tracks +- collect corrupted biological material +- discover buried stonework + +--- + +## Ruined Hunter Shrine + +Narrative function: + +- provide a semi-safe narrative hub +- establish Elyra as the region expert +- reveal the first readable reference to the Last Watch + +The shrine contains an older inscription. + +Suggested inscription: + +> **Where the black vein lies open, the Ash will follow.** + +A second fragment may contain the name: + +> **Velkar** + +The player does not yet know whether Velkar is a person, city, fortress, or region. + +--- + +## Thorn Clearing + +Narrative function: + +- demonstrate that corruption creates stronger predators +- introduce Graufang as a visible progression target +- reinforce that affected creatures are victims rather than organized servants + +Graufang and other corrupted animals should not speak, serve a villain, or carry artificial orders. + +They are ecological consequences of the deeper problem. + +--- + +# 19. The Shadow Alpha + +The Shadow Alpha is the chapter boss. + +Narratively, it must not be presented as an evil commander. + +It was once a powerful natural predator. + +The Ash altered it. + +Its lair should contain evidence showing that the corruption reached it physically. + +Possible examples: + +- Blackstone fragments embedded in a wound +- a crack in the stone beneath its lair +- warm black sediment in underground water + +After the fight, the player's conclusion should be: + +> **The forest is being poisoned from below.** + +This makes the boss tragic rather than purely villainous. + +--- + +# 20. Duskwood chapter ending + +Elyra combines the player's evidence with the old shrine inscription. + +The same symbol found in Ashen Fields appears here. + +The name **Last Watch** becomes known for the first time. + +The player learns that the Last Watch existed centuries ago and apparently knew about Blackstone and the Ash. + +The trail points toward the Forgotten Ruins and Velkar. + +The central question becomes: + +> **What happened here the last time the Ash appeared?** + +--- + +# 21. Chapter III – The Last Oath + +## Region + +**Forgotten Ruins** + +## Player-facing local problem + +The dead have begun to rise among ancient ruins and crypts. + +At first, the player may assume the Ash simply animates corpses. + +This assumption is incomplete. + +The deeper truth is: + +> **The Ash can bind the dead to powerful memories, duties, and unfinished vows.** + +The soldiers of the Last Watch died while defending sealed access to the depths. + +Their final duty became the thing that kept them from truly dying. + +--- + +# 22. The undead of the Last Watch + +The undead should behave according to fragments of their old identities. + +This must influence both lore and combat design. + +Examples: + +## Fallen Knight + +Uses defensive stances because the soldier died protecting a position. + +## Bonecaller + +Calls fallen soldiers back to battle because their unit must continue holding the line. + +## Nameless Banner Bearer + +Still carries a ruined standard because maintaining the banner was their final duty. + +## Sir Varos, the Broken + +Retains military discipline, defensive techniques, and execution-style attacks. + +His behavior should feel like a corrupted continuation of his former role. + +The enemies are dangerous, but many are also tragic remnants of a failed defense. + +--- + +# 23. Brother Caelan, Last Keeper + +Brother Caelan is the primary narrative NPC of the Forgotten Ruins. + +He belongs to a later order that preserved fragments of the Last Watch's history. + +He does **not** know the entire truth. + +He knows: + +- the Last Watch existed +- they guarded Velkar +- they sealed something beneath the old kingdom +- the king and the Watch came into conflict +- many historical records were intentionally destroyed + +Caelan initially treats some of these stories as incomplete religious or military traditions. + +The player's evidence makes the old stories credible again. + +Narrative rule: + +> **Caelan interprets history. The player provides the evidence that changes his interpretation.** + +--- + +# 24. Forgotten Ruins environmental storytelling + +Examples: + +## Old banners + +The same symbol first seen at the abandoned watchpost now appears clearly on military banners. + +## Sealed doors + +Several passages were sealed from the inside. + +Possible inspection text: + +> **The locking mechanism was built to prevent anyone from leaving the lower passage.** + +This creates ambiguity about what the Last Watch feared. + +## Broken records + +Names and locations have been deliberately removed from stone tablets and archives. + +## Blackstone restrictions + +Military orders may contain phrases such as: + +> **No miner, merchant, soldier, or noble shall pass below the Third Seal.** + +These fragments should suggest that Blackstone was once controlled and feared. + +--- + +# 25. Forgotten Ruins story progression + +## Broken Gate + +Narrative function: + +- introduce undead soldiers +- show the Last Watch symbol openly +- establish that the ruins were a military defensive complex + +The player now recognizes the symbol from previous regions. + +--- + +## Courtyard of the Fallen + +Narrative function: + +- show that undead behavior reflects old military roles +- reveal that the defenders were guarding access deeper underground +- introduce interruptible rituals and defensive behavior through combat mechanics + +Narrative and combat should support each other here. + +--- + +## Chapel of the Last Watch + +Narrative function: + +- safe narrative hub +- introduce Brother Caelan +- consolidate the history discovered so far +- explain the basic purpose of the Last Watch without revealing the full truth + +The chapel should contain: + +- preserved insignia +- damaged memorials +- records of fallen soldiers +- references to the sealing + +--- + +## Crypts of Velkar + +Narrative function: + +- reveal the human cost of the sealing +- introduce Sir Varos +- show that the Last Watch died in large numbers while holding the lower passages + +The crypts should make the player question whether defeating these undead is liberation, desecration, or simply necessary survival. + +--- + +# 26. Sir Varos, the Broken + +Sir Varos was once an officer or champion of the Last Watch. + +He is not a servant of the Ash by choice. + +He is bound to his final duty. + +His combat mechanics should reflect his history: + +- Shield Wall +- Execution +- Last Oath + +His fight should reveal that the Last Watch expected enemies to come from both directions. + +This can imply that the Watch eventually fought not only whatever came from below, but also forces loyal to the king who wanted access to Blackstone restored. + +This point may remain ambiguous in V1. + +--- + +# 27. The Bone Lord + +The Bone Lord is the final boss of the Forgotten Ruins chapter. + +Narrative concept: + +> **The Bone Lord is not trying to release the Ash. He believes he is still preventing anyone from reaching it.** + +He was once one of the highest-ranking defenders involved in the final sealing. + +The Ash preserved and distorted his oath. + +His original command may have been: + +> **No one passes the seal.** + +After centuries, all context is gone. + +Only the command remains. + +He therefore treats: + +- raiders +- scholars +- Caelan +- the player + +as equal threats. + +This makes him a tragic antagonist rather than a simple villain. + +--- + +# 28. The major reveal after the Bone Lord + +After the Bone Lord is defeated, the player gains access to an old supply tunnel behind or beneath the hall. + +The tunnel was previously believed to be sealed. + +Inside, the player discovers evidence that is clearly modern. + +Examples: + +- fresh tool marks +- new timber supports +- recently used ropes +- tracks from mining carts +- lamp oil that has not dried +- a broken modern tool +- a trade seal or company marking + +The critical conclusion is: + +> **The ancient danger did not simply wake up. Someone reopened the Blackstone excavations.** + +This is the end-of-slice narrative hook. + +--- + +# 29. The first major story twist + +Until this point, the player is encouraged to believe: + +> An ancient evil is returning. + +The stronger interpretation at the end of the Forgotten Ruins is: + +> **Living people caused the current crisis by reopening something that previous generations deliberately sealed.** + +This creates a more flexible long-term story. + +Future antagonists may include: + +- mining companies +- merchants +- nobles +- scholars +- military powers +- religious groups +- local rulers + +Not all of them need to understand the true danger of Blackstone. + +Some may have legitimate reasons for wanting it. + +This allows the story to move beyond a simple good-versus-evil structure. + +--- + +# 30. Blackstone Mine setup + +The next major region after the current three-region arc is the **Blackstone Mine**. + +Its purpose is to answer: + +> **Who reopened the old mine?** + +It should then create a larger question: + +> **Why was Blackstone important enough for an entire kingdom to destroy itself over it?** + +The Blackstone Mine should not immediately reveal the ultimate source or nature of the Ash. + +The mystery must continue beyond it. + +--- + +# 31. Reputation and story progression + +Ashen Realms uses reputation as a natural way to represent the player's growing importance in the world. + +The narrative must reinforce this system. + +## Regional reputation + +Regional reputation represents trust and recognition within a specific region. + +Examples: + +### Ashen Fields reputation + +Represents recognition among: + +- Graufurt guards +- local merchants +- caravan workers +- surviving watch personnel + +### Duskwood reputation + +Represents recognition among: + +- hunters +- Elyra's contacts +- shrine keepers +- forest traders + +### Forgotten Ruins reputation + +Represents recognition among: + +- Caelan's order +- relic keepers +- scholars +- expedition members + +--- + +# 32. World reputation + +World reputation represents the player's broader standing. + +It should increase primarily through meaningful achievements rather than normal enemy kills alone. + +Examples: + +- solving a major regional threat +- defeating an important elite +- defeating a region boss +- discovering major evidence +- restoring an important route +- helping a recognized faction + +World reputation should gradually replace the narrative function traditionally associated with character levels. + +NPCs should react to accomplishments rather than abstract numbers whenever possible. + +Example merchant restriction: + +> **"I don't sell relic steel to strangers. Earn the trust of the Watch first."** + +Preferred over: + +> **"Requires Level 5."** + +--- + +# 33. Story rewards and proof items + +Normal enemies should not advance the main narrative merely because they were killed. + +Story progression should be connected to evidence, discoveries, trophies, and important events. + +Examples: + +- Ashen Band insignia +- sealed Blackstone crate +- corrupted animal tissue +- damaged Last Watch emblem +- Banner Fragment of the Last Watch +- broken seal fragment +- mining ledger +- delivery order + +These items may function as: + +- quest items +- reputation turn-ins +- lore discoveries +- evidence used in dialogue + +Important narrative proof items should not consume normal inventory capacity unless deliberately designed to do so. + +--- + +# 34. Narrative integration with the local location view + +Each location should have a local view that communicates story through the environment. + +The location view should support: + +- location artwork +- present NPCs +- important landmarks +- inspectable objects +- available actions +- discovered story clues + +Example for the Abandoned Watchpost: + +Visible elements may include: + +- surviving watchman +- damaged Last Watch emblem +- burned supply cart +- path toward the Ash Pit + +Possible actions: + +- Speak to Watchman +- Inspect Emblem +- Search Supplies +- Hunt Nearby +- Travel + +The story should therefore exist spatially in the UI rather than only inside the quest log. + +--- + +# 35. Narrative integration with hunting + +Hunting remains primarily a gameplay system. + +It must not display major story exposition after every fight. + +Instead, story can occasionally intersect with hunting through: + +- rare encounters +- quest-specific enemies +- evidence drops +- special tracks +- environmental discoveries + +Example: + +A normal Dusk Wolf may drop trade material. + +A quest-relevant corrupted wolf may additionally provide: + +> **Blackened Fang** + +Description: + +> **The root of the tooth contains the same dark residue found near the forest streams.** + +This connects normal gameplay to investigation without turning every encounter into a cutscene. + +--- + +# 36. Narrative integration with combat + +Combat mechanics should reinforce enemy identity and story whenever possible. + +Examples: + +## Bandits + +- heavy strikes +- defensive stances +- practical combat behavior + +## Corrupted beasts + +- bleeding +- aggressive behavior at low health +- poison +- frenzy + +## Last Watch undead + +- defensive formations +- interruptible calls +- parries +- military-style abilities + +The player should be able to infer something about an enemy from how it fights. + +Narrative and combat design must not contradict each other. + +--- + +# 37. Narrative integration with items + +Important equipment should support world history. + +Item names and descriptions may reveal fragments of lore. + +Examples: + +## Seal of the Last Watch + +Suggested flavor text: + +> **The seal bears the same emblem found throughout the ruins of Velkar. The reverse side has been scratched clean.** + +## Blade of the Broken King + +Suggested flavor text: + +> **No surviving record agrees on whether the king carried this blade into battle or whether it was raised against him.** + +Important rule: + +> **Item descriptions may suggest history, but should not reveal facts the player has not yet discovered through the main story.** + +Lore text should respect progression state when necessary. + +--- + +# 38. Narrative integration with merchants + +Merchants should help make reputation feel real. + +Their dialogue and available inventory may change based on regional or world reputation. + +Examples: + +Low reputation: + +> **"Supplies are for people I know will come back alive."** + +Medium reputation: + +> **"Elyra says you've been useful. I can show you the better stock."** + +High reputation: + +> **"If you're going back into those ruins, take this. I'd rather see it used than buried in my cellar."** + +This is preferable to purely mechanical unlock messaging. + +--- + +# 39. Narrative integration with quests + +Quests have four main narrative functions. + +## 1. Direction + +Help the player understand where a meaningful problem exists. + +## 2. Context + +Explain why an activity matters to the people in the world. + +## 3. Evidence + +Let the player gather information that changes the understanding of events. + +## 4. Recognition + +Allow NPCs and factions to acknowledge what the player has accomplished. + +Quests should not be the only way to discover the world. + +Exploration and optional interactions must also provide information. + +--- + +# 40. Main quest structure per region + +Each region should use a small number of major narrative beats instead of a long linear quest chain. + +Recommended structure: + +1. **Arrival problem** +2. **First evidence** +3. **Complication** +4. **Regional expert or key NPC** +5. **Major discovery** +6. **Elite or dangerous location** +7. **Region boss** +8. **Evidence pointing to the next region** + +Optional quests may expand local characters, history, or world detail without being required for understanding the main plot. + +--- + +# 41. Story-state implementation + +Story progression must be server-authoritative. + +The client must not decide whether major story events are completed. + +Recommended conceptual data model: + +```text +StoryArcDefinition +StoryChapterDefinition +StoryBeatDefinition +StoryDiscoveryDefinition +CharacterStoryState +CharacterDiscovery +``` + +This does not require all entities to exist immediately. + +The first implementation may use a smaller model as long as the state remains data-driven and server-authoritative. + +--- + +# 42. Story beat concept + +A **Story Beat** is a meaningful progression step in the narrative. + +Example: + +```text +Key: ASHEN_FIELDS_BANDIT_LEDGER_FOUND +Chapter: SMOKE_ON_THE_ROAD +Trigger: Player investigates the Ashen Band captain's camp after victory +Effect: +- unlock discovery BLACKSTONE_DELIVERY_ORDER +- update main objective +- enable dialogue option with Graufurt NPC +- enable story route toward Duskwood +``` + +Story beats should be triggered by meaningful actions rather than arbitrary kill counts whenever possible. + +--- + +# 43. Recommended story trigger types + +Story content may be triggered by: + +- entering a location for the first time +- interacting with an object +- speaking to an NPC +- defeating a specific elite or boss +- obtaining a specific evidence item +- reaching a regional reputation threshold +- completing a quest objective +- discovering a location +- returning to an NPC with evidence + +Avoid using generic triggers such as: + +> Kill 20 enemies to unlock the next story scene. + +unless the task itself makes narrative sense. + +--- + +# 44. Discovery system + +Important lore findings should be represented as discoveries that can later be referenced by UI, dialogue, and quests. + +Examples: + +```text +UNKNOWN_WATCH_SYMBOL +BLACKSTONE_RESIDUE +BLACKSTONE_DELIVERY_ORDER +LAST_WATCH_NAME +VELKAR_REFERENCE +LAST_WATCH_SEALING +MODERN_MINING_ACTIVITY +``` + +A discovery is a permanent piece of knowledge the character has obtained. + +This allows dialogue to react naturally. + +Example: + +Without `LAST_WATCH_NAME`: + +> **"You've seen that symbol before?"** + +With `LAST_WATCH_NAME`: + +> **"The Last Watch. That symbol belonged to them."** + +--- + +# 45. Suggested initial story beat keys + +## Ashen Fields + +```text +AF_01_ROAD_TROUBLE_HEARD +AF_02_BURNED_CARAVAN_INSPECTED +AF_03_BLACKSTONE_RESIDUE_FOUND +AF_04_UNKNOWN_WATCH_SYMBOL_FOUND +AF_05_ASH_BAND_OPERATION_DISCOVERED +AF_06_ASH_BAND_CAPTAIN_DEFEATED +AF_07_BLACKSTONE_DELIVERY_ORDER_FOUND +AF_08_DUSKWOOD_TRAIL_UNLOCKED +``` + +## Duskwood + +```text +DW_01_CORRUPTED_WILDLIFE_OBSERVED +DW_02_ELYRA_MET +DW_03_CORRUPTED_WATER_FOUND +DW_04_BURIED_WATCH_STONE_FOUND +DW_05_LAST_WATCH_NAMED +DW_06_VELKAR_REFERENCE_FOUND +DW_07_SHADOW_ALPHA_DEFEATED +DW_08_UNDERGROUND_CORRUPTION_CONFIRMED +DW_09_FORGOTTEN_RUINS_TRAIL_UNLOCKED +``` + +## Forgotten Ruins + +```text +FR_01_LAST_WATCH_BANNERS_FOUND +FR_02_CAELAN_MET +FR_03_SEALING_RECORD_FOUND +FR_04_LAST_OATH_DISCOVERED +FR_05_SIR_VAROS_DEFEATED +FR_06_BONE_LORD_IDENTITY_REVEALED +FR_07_BONE_LORD_DEFEATED +FR_08_OLD_SUPPLY_TUNNEL_OPENED +FR_09_MODERN_MINING_EVIDENCE_FOUND +FR_10_BLACKSTONE_MINE_TRAIL_UNLOCKED +``` + +Implementation note: + +Use one consistent naming convention in code. The exact keys may be changed before implementation. + +--- + +# 46. Story and region access + +Ashen Realms should avoid hard narrative walls whenever possible. + +The player may discover or physically reach dangerous locations before completing all story beats. + +However, some specific actions may require knowledge or access earned through story progression. + +Examples: + +Allowed: + +- travel early into a dangerous region +- encounter stronger enemies +- discover locations + +Potentially gated: + +- opening a sealed crypt door +- convincing an NPC to reveal restricted information +- entering a faction-controlled chamber +- accessing a boss-specific ritual or doorway + +The preferred gating tools are: + +- physical key or item +- reputation +- discovery +- NPC trust +- completed world interaction + +Avoid arbitrary level gates. + +--- + +# 47. Story and boss access + +Bosses should normally require the player to understand why they are fighting them. + +This does not necessarily mean a long mandatory quest chain. + +Recommended boss access conditions: + +## Captain of the Ashen Band + +Requires discovering the Ash Pit or following the bandit trail. + +## Shadow Alpha + +Requires discovering its lair through Elyra, tracks, or exploration. + +## Bone Lord + +Requires reaching the Hall and breaking or opening the relevant seal. + +Boss access should feel like a world interaction rather than a menu unlock. + +--- + +# 48. Narrative UI rules + +Story information must use the existing Ashen Realms visual language. + +Prefer: + +- environmental artwork +- NPC portraits +- inspection panels +- short dialogue sections +- location interactions +- quest summaries +- discovery notifications + +Avoid: + +- large walls of text during normal gameplay +- repeated modal popups +- exposition after every fight +- lengthy unskippable scenes + +The player should be able to continue playing even when they are not interested in reading every optional lore entry. + +--- + +# 49. Quest log presentation + +The quest log should distinguish between: + +## Main Story + +Tracks the current regional mystery. + +## Regional Tasks + +Supports local NPCs and reputation. + +## Hunts + +Repeatable or targeted combat goals. + +## Discoveries + +Optional lore and exploration objectives. + +The main story objective should usually be concise. + +Example: + +**Follow the Blackstone Trail** + +> The Ashen Band was transporting Blackstone toward Duskwood. Find out who is receiving it. + +--- + +# 50. Discovery log presentation + +A later Discovery or Lore view may record important findings. + +Example entry: + +## Blackstone + +> A dense black mineral found among the cargo of attacked caravans. The Ashen Band was collecting it deliberately. Its purpose is unknown. + +The text should update only when new knowledge is earned. + +It must not reveal future information. + +--- + +# 51. Writing style for narrative text + +All player-facing narrative text should follow these principles. + +## Tone + +- dark fantasy +- grounded +- restrained +- mysterious +- serious without becoming melodramatic + +## Avoid + +- constant prophecy language +- excessive archaic English +- long speeches explaining the entire plot +- villains revealing their plans without reason +- every NPC understanding ancient history +- modern comedy that breaks the atmosphere + +## Preferred sentence style + +Short to medium sentences. + +Clear modern English with occasional fantasy vocabulary. + +Example: + +Good: + +> **"The wolves started coming closer to the shrine three weeks ago. Then the river turned black after the rain."** + +Avoid: + +> **"Lo, for upon the third waning of the crimson moon did the beasts of shadow descend upon our hallowed sanctuary."** + +unless used intentionally in an ancient inscription. + +--- + +# 52. Ancient text style + +Ancient inscriptions may use more formal language, but they must remain understandable. + +Example: + +> **Where the black vein lies open, the Ash will follow. Seal the road below and speak no name of what sleeps beneath it.** + +Ancient text should be short and memorable. + +--- + +# 53. Naming rules + +Names should feel connected to the world rather than randomly generated fantasy words. + +Current established names should remain stable unless deliberately revised: + +- Graufurt +- Ashen Fields +- Burned Road +- Abandoned Watchpost +- Ash Pit +- Duskwood +- Ruined Hunter Shrine +- Thorn Clearing +- Forgotten Ruins +- Chapel of the Last Watch +- Crypts of Velkar +- Sir Varos +- Bone Lord +- Blackstone Mine +- Elyra +- Brother Caelan +- Last Watch +- Broken King +- Blackstone +- the Ash + +If German location names remain in the German UI later, localization should be handled separately. Narrative source text in this document is English. + +--- + +# 54. Canonical mysteries that must remain unresolved after Region 3 + +The following questions must **not** be fully answered during the first three regions: + +1. What exactly is the Ash? +2. What lies beneath the deepest Blackstone excavation? +3. What happened to the Broken King? +4. Why did the old kingdom originally begin large-scale Blackstone mining? +5. Who reopened the Blackstone Mine in the present day? +6. Does the modern group understand what they are risking? +7. Did the Last Watch tell the complete truth? +8. Is Blackstone inherently corrupting, or does it merely carry something else? + +These unresolved questions provide long-term narrative space. + +--- + +# 55. Canonical facts established by the end of Region 3 + +By the end of the Forgotten Ruins, the player should reliably know: + +1. Blackstone exists and is being deliberately collected. +2. The strange events in the Ashen Fields and Duskwood are connected. +3. The Ash can affect land, animals, and the dead in different ways. +4. The Last Watch encountered the same phenomenon centuries ago. +5. The Last Watch sealed underground passages connected to Blackstone. +6. The old kingdom collapsed around the same historical period. +7. The Bone Lord and other undead defenders are remnants of the Last Watch. +8. Someone in the present has reopened at least part of the old mining network. + +This is the minimum narrative payoff of the current three-region arc. + +--- + +# 56. Narrative content priorities for implementation + +For the first playable implementation, story should be added in layers. + +## Priority 1 – Required + +- regional main objective +- story state / discoveries +- NPC interactions at key locations +- inspectable environmental clues +- boss completion story beats +- transition hook to next region + +## Priority 2 – Strongly recommended + +- item flavor text +- regional side quests +- reputation-aware NPC dialogue +- rare evidence drops +- discovery log + +## Priority 3 – Later polish + +- alternate dialogue based on exact previous choices +- extensive optional lore archives +- cinematic sequences +- voiced dialogue +- complex branching narrative + +The story must not delay implementation of the core gameplay loop. + +--- + +# 57. Minimal narrative implementation for the first technical slice + +The first technical slice currently focuses on: + +- Graufurt / South Gate +- Burned Road +- Ash Rat +- Road Bandit +- travel +- hunting +- combat +- loot +- equipment + +The minimum story layer for this slice should therefore be small. + +Recommended implementation: + +## South Gate + +Display a short regional situation text: + +> **Caravans traveling south have stopped arriving on schedule. Graufurt's watch has neither the people nor the supplies to patrol the entire road.** + +## Burned Road + +Add one inspectable object: + +**Burned Caravan** + +First inspection unlocks: + +```text +AF_02_BURNED_CARAVAN_INSPECTED +``` + +Text: + +> **The wagon is burned almost completely through, but there are no scorch marks on the surrounding ground. Something inside the cargo burned hotter than the fire around it.** + +No further major lore is required yet. + +This proves the narrative delivery mechanism without overbuilding the story system. + +--- + +# 58. Narrative expansion order + +After the first technical slice works, implement story content in this order: + +```text +South Gate narrative setup +→ Burned Road evidence +→ Abandoned Watchpost story node +→ Ash Pit chapter ending +→ Duskwood investigation +→ Elyra and Hunter Shrine +→ Shadow Alpha reveal +→ Forgotten Ruins history +→ Brother Caelan +→ Sir Varos +→ Bone Lord +→ Blackstone Mine hook +``` + +This mirrors the player's actual progression. + +Do not fully implement future-region lore before the current region is playable. + +--- + +# 59. Rules for AI-assisted implementation + +When an AI coding or content agent adds story content, it must follow these rules: + +1. Read this document before creating new major narrative content. +2. Preserve the reveal order. +3. Do not explain the Ash completely. +4. Do not introduce a chosen-one prophecy. +5. Do not make every regional problem a direct command from one villain. +6. Do not make corrupted animals intelligent servants of the antagonist. +7. Preserve the Last Watch as a tragic historical faction. +8. Present the Broken King with ambiguity rather than as a simple evil tyrant. +9. Use environmental clues before exposition whenever possible. +10. Major story progression must be server-authoritative. +11. Story state should be data-driven. +12. Avoid hard level gates for narrative access when reputation, discovery, items, or world interactions are more natural. +13. NPC knowledge must be limited to what that NPC could reasonably know. +14. Item descriptions must not spoil future discoveries. +15. New regions should reveal one meaningful part of the larger mystery and create at least one new question. + +--- + +# 60. Relationship to existing game systems + +The story exists to support the core Ashen Realms loop: + +```text +Explore +→ Travel +→ Hunt +→ Fight +→ Recover materials and evidence +→ Return to NPCs / merchants +→ Gain equipment and reputation +→ Access stronger opportunities +→ Defeat elite / boss +→ Discover new region +→ Learn more about the world +``` + +Story should never replace the gameplay loop with long passive sequences. + +Instead, narrative gives the gameplay meaning. + +--- + +# 61. Relationship to the reputation progression system + +The current project direction replaces traditional kill-XP progression with reputation-oriented progression. + +Narratively, this is strongly compatible with the story. + +The player's growth should be communicated as: + +- becoming known +- earning trust +- gaining access to better equipment +- proving competence +- becoming involved in increasingly important problems + +Enemy kills should primarily provide: + +- materials +- trophies +- evidence where appropriate + +Turning these in can provide: + +- silver +- regional reputation +- world reputation for meaningful achievements + +Story-critical discoveries and boss victories may grant reputation directly. + +The exact numerical reputation economy belongs in the balancing documentation, not in this story document. + +--- + +# 62. Narrative success criteria + +The first three-region story arc succeeds if the player experiences the following progression of understanding: + +### After Ashen Fields + +> **"The bandits were collecting something."** + +### During Duskwood + +> **"The same thing is poisoning the forest."** + +### During Forgotten Ruins + +> **"This happened before."** + +### After the Bone Lord + +> **"Someone has started it again."** + +The player should want to enter the Blackstone Mine because they want an answer, not merely because it has stronger loot. + +--- + +# 63. Final narrative identity + +The central story of Ashen Realms is not about a hero destined to defeat an ancient evil. + +It is about a world that forgot why certain places were abandoned, why certain doors were sealed, and why entire generations chose to bury parts of their own history. + +The player begins by solving practical frontier problems. + +Those problems lead to forgotten symbols. + +The symbols lead to an old military order. + +The order leads to a buried kingdom. + +And beneath that kingdom lies a truth that people in the present have begun digging toward again. + +The guiding narrative statement is: + +> **Centuries ago, the Last Watch buried something beneath the ruins of their kingdom. The world forgot why. Now someone is digging it up again.** + +--- + +# 64. Source alignment + +This narrative specification is designed to extend, not replace, the existing Ashen Realms project foundations: + +- **Design Manifest V1** – illustrated persistent world, open danger-based progression, PvE focus, item-driven power, exploration and discovery +- **Vertical Slice – World & Content Design V1** – Graufurt, Ashen Fields, Duskwood, Forgotten Ruins, Last Watch locations, Elyra, Brother Caelan, Sir Varos, Bone Lord, and the route toward Blackstone Mine +- **Balancing, Items & Loot Design V1** – existing Last Watch and Broken King item identities, targeted loot and region progression +- **UI & Visual Design Specification V1** – artwork-first presentation, location-focused UI, NPC and contextual information areas +- **Technical Foundation & Monorepo Implementation Plan** – server-authoritative game state and data-driven content architecture + +Where older documents still reference traditional XP/level progression, the newer reputation-based progression direction should be treated as the intended future replacement. This document intentionally avoids making story progression dependent on XP. diff --git a/docs/references/verbrannte_strasse_in_den_aschenfeldern.png b/docs/references/verbrannte_strasse_in_den_aschenfeldern.png new file mode 100644 index 0000000..89f4859 Binary files /dev/null and b/docs/references/verbrannte_strasse_in_den_aschenfeldern.png differ diff --git a/docs/superpowers/plans/Ashen_Realms_Verbrannte_Strasse_Local_View_Implementation_Plan.md b/docs/superpowers/plans/Ashen_Realms_Verbrannte_Strasse_Local_View_Implementation_Plan.md new file mode 100644 index 0000000..de47db7 --- /dev/null +++ b/docs/superpowers/plans/Ashen_Realms_Verbrannte_Strasse_Local_View_Implementation_Plan.md @@ -0,0 +1,1020 @@ +# Verbrannte Straße Local Location View – Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Die erste wiederverwendbare lokale Ortsansicht für Ashen Realms implementieren. Die Verbrannte Straße dient als Referenzort und wird zwischen bestehenden Karten-/Reiseflow und bestehenden Jagdflow integriert. + +**Architecture:** Die Ortsansicht wird als datengetriebener Screen innerhalb des bestehenden World-Features umgesetzt. Das Backend bleibt Quelle der Wahrheit für den aktuellen Ort und liefert die Daten für Orts-Artwork, POIs, Hauptaktionen und Kontextinformationen. Jagd und Reise werden nicht neu implementiert, sondern über die bereits vorhandenen Flows aufgerufen. + +**Tech Stack:** Angular 22.x, NestJS 11.x, TypeScript, TypeORM 1.x, PostgreSQL, SCSS, bestehender Ashen-Realms-App-Shell und bestehendes Design-System. + +**Spec:** `docs/local-location-view-design-spec.md` oder die mitgelieferte Datei `Ashen_Realms_Local_Location_View_Design_Spec_V1.md` + +**Visual Reference:** `verbrannte_strasse_in_den_aschenfeldern.png` + +## Global Constraints + +- Vor Änderungen zuerst das bestehende Repository analysieren. +- Vorhandene AppShell-, TopBar-, SideNavigation-, Footer-, Panel-, Button-, Icon-, API-Client-, World-, Travel- und Hunt-Strukturen wiederverwenden. +- Keine zweite Reiselogik bauen. +- Keine zweite Jagdlogik bauen. +- Authentifizierung ist nicht Teil dieses Features. +- Für diesen Slice keine generische Questengine, Dialogengine, Event-Skriptsprache oder Loot-aus-Suchaktionen-System bauen. +- Der Screen muss für zukünftige Orte wiederverwendbar sein und darf die Verbrannte Straße nicht als One-off-Komponente hardcoden. +- Zentrale Spiellogik bleibt serverautoritativ. +- Desktop ist primäres Ziel. +- Der Referenzscreen ist Zielrichtung, keine pixelgenaue Vorgabe. +- Bestehende Design-Tokens und UI-Komponenten haben Vorrang vor neuen parallelen Styling-Systemen. + +--- + +# 1. Erwarteter Spielerflow + +Nach Abschluss muss folgender Ablauf funktionieren: + +```text +Karte +→ Reise zur Verbrannten Straße +→ Reise endet +→ Ortsansicht öffnet sich +→ Spieler sieht Artwork und lokale POIs +→ Spieler kann: + - Jagd beginnen + - Spuren untersuchen + - verlassenen Wagen durchsuchen + - mit verwundetem Kundschafter sprechen + - zur Karte zurückkehren +→ Jagd verwendet den bestehenden Jagd-Screen +→ Zurück aus der Jagd führt zur Ortsansicht +→ nach normalem Kampf-/Lootabschluss wird, sofern mit dem bestehenden Flow kompatibel, zur Ortsansicht zurückgekehrt +``` + +Die Ortsansicht wird zum normalen Nicht-Kampf-Screen des aktuellen physischen Ortes. + +--- + +# 2. Route und Navigation + +Neue Route: + +```text +/location +``` + +Die persistente linke Navigation enthält: + +```text +Ort +Karte +Jagd +Quests +Inventar +Charakter +Shop +``` + +`Ort` navigiert nach `/location` und ist dort aktiv. + +Die bestehenden Routen für Karte und Jagd bleiben erhalten. + +Wenn die Karte aktuell `/world` verwendet, bleibt `/world` bestehen. + +Keine bestehenden Routen allein für dieses Feature umbenennen. + +--- + +# 3. Zielstruktur im Frontend + +Die Ortsansicht soll innerhalb des bestehenden World-Features liegen. + +Neue Dateien, sofern nicht bereits gleichwertige Komponenten existieren: + +```text +apps/web/src/app/features/world/location-page/ +├── location-page.component.ts +├── location-page.component.html +├── location-page.component.scss +└── location-page.component.spec.ts + +apps/web/src/app/features/world/local-location/ +├── local-location.models.ts +├── local-location.service.ts +└── local-location.service.spec.ts + +apps/web/src/app/features/world/location-poi/ +├── location-poi.component.ts +├── location-poi.component.html +├── location-poi.component.scss +└── location-poi.component.spec.ts + +apps/web/src/app/features/world/location-interaction-panel/ +├── location-interaction-panel.component.ts +├── location-interaction-panel.component.html +├── location-interaction-panel.component.scss +└── location-interaction-panel.component.spec.ts +``` + +Existieren bereits passende Shared Components, müssen diese erweitert oder wiederverwendet werden statt neue Duplikate zu erzeugen. + +--- + +# 4. Shared Frontend Models + +Typed Contracts ergänzen oder an bestehende Contracts anpassen: + +```ts +export type LocationInteractionType = + | 'HUNT' + | 'INVESTIGATE' + | 'SEARCH' + | 'NPC' + | 'MAP' + | 'TRAVEL' + | 'SHOP' + | 'QUEST' + | 'BOSS' + | 'DUNGEON'; + +export interface LocalLocationPointOfInterestDto { + key: string; + title: string; + actionLabel?: string; + type: LocationInteractionType; + iconKey: string; + xPercent: number; + yPercent: number; + enabled: boolean; +} + +export interface LocalLocationPrimaryActionDto { + key: string; + label: string; + description?: string; + type: LocationInteractionType; + iconKey: string; + enabled: boolean; +} + +export interface EncounterPreviewDto { + key: string; + name: string; + iconPath?: string; +} + +export interface RewardPreviewDto { + key: string; + label: string; + iconPath: string; +} + +export interface LocalLocationViewDto { + locationId: string; + locationKey: string; + name: string; + regionName: string; + description: string; + locationType: string; + artworkPath: string; + dangerRating: string; + recommendationLabel?: string; + huntingEnabled: boolean; + pointsOfInterest: LocalLocationPointOfInterestDto[]; + primaryActions: LocalLocationPrimaryActionDto[]; + encounterPreview: EncounterPreviewDto[]; + rewardPreview: RewardPreviewDto[]; +} + +export interface LocationInteractionResultDto { + interactionKey: string; + title: string; + text: string; +} +``` + +Wenn Cross-Boundary-DTOs im Projekt bereits unter `packages/shared` liegen, gehören diese Contracts dorthin statt in duplizierte Frontend-Modelle. + +--- + +# 5. Backend API + +Den bestehenden Current-Location-Endpunkt wiederverwenden, sofern er sauber um die Ortsansicht erweitert werden kann. + +Bevorzugter Endpoint: + +```text +GET /api/world/current-location +``` + +Beispielresponse: + +```json +{ + "locationId": "uuid", + "locationKey": "burned-road", + "name": "Verbrannte Straße", + "regionName": "Aschenfelder", + "description": "Ein alter Handelsweg, der durch Feuer und Krieg in Asche gelegt wurde.", + "locationType": "HUNTING_GROUND", + "artworkPath": "/assets/locations/ashen-fields/burned-road.webp", + "dangerRating": "MATCH", + "recommendationLabel": "1–2", + "huntingEnabled": true, + "pointsOfInterest": [], + "primaryActions": [], + "encounterPreview": [], + "rewardPreview": [] +} +``` + +Minimaler Endpoint für lokale Interaktionen: + +```text +POST /api/world/current-location/interactions/:interactionKey +``` + +Request Body: + +```json +{} +``` + +Beispielresponse: + +```json +{ + "interactionKey": "inspect-tracks", + "title": "Verdächtige Spuren", + "text": "Zwischen Asche und zerbrochenen Steinen erkennst du mehrere frische Stiefelabdrücke. Sie führen nach Osten, in Richtung des verlassenen Wachtpostens." +} +``` + +Der Server muss prüfen, dass die angeforderte Interaktion zum **tatsächlichen aktuellen Ort des Charakters** gehört und aktiviert ist. + +Der Client darf keinen beliebigen `locationId` senden können, um Interaktionen an einem anderen Ort auszuführen. + +--- + +# 6. Backend-Datenmodell + +Zuerst die bestehende `LocationDefinition` und die aktuelle Seed-Strategie prüfen. + +Bestehende Content-Definitionen erweitern, statt eine parallele Location-Tabelle einzuführen. + +Falls die aktuelle Entity lokale Darstellungsdaten nicht sauber abbilden kann, folgende Felder oder gleichwertige Strukturen ergänzen: + +```text +locationType +localDescription +localArtworkPath +``` + +Für V1 dürfen lokale POIs und Hauptaktionen als JSONB-Content auf `LocationDefinition` gespeichert werden, sofern dies zur aktuellen Content-Strategie passt. + +Empfohlene V1-Felder: + +```text +localPointsOfInterest jsonb +localPrimaryActions jsonb +localRewardPreview jsonb +``` + +Die bestehenden `LocationMonster`-/Encounter-Daten bleiben Quelle der Wahrheit für die Jagd. + +Der gewichtete Encounter-Pool darf nicht in den Ortsansichtsdaten dupliziert werden. + +Die Encounter-Vorschau soll möglichst aus bestehenden Monster-/Location-Daten abgeleitet werden. + +Wenn JSONB nicht zur bestehenden Architektur passt, dürfen fokussierte Content-Definitionen modelliert werden. Dafür kein generisches CMS-System bauen. + +--- + +# 7. Content der Verbrannten Straße + +Für `burned-road` bzw. den bereits existierenden stabilen Key der Verbrannten Straße folgende Daten seeden oder konfigurieren. + +## Header + +```text +Name: Verbrannte Straße +Region: Aschenfelder +Location Type: HUNTING_GROUND +Empfehlung: 1–2 +Gefahr: MATCH / Passend +``` + +Beschreibung: + +```text +Ein alter Handelsweg, der durch Feuer und Krieg in Asche gelegt wurde. Verbrannte Karren, zerbrochene Waffen und verstummte Schreie säumen den Pfad in die Aschenfelder. +``` + +## Artwork + +Das bereits vorbereitete echte Artwork der Verbrannten Straße aus dem Repository verwenden. + +Der mitgelieferte Screenshot ist ausschließlich Kompositionsreferenz: + +```text +verbrannte_strasse_in_den_aschenfeldern.png +``` + +Nicht den vollständigen UI-Screenshot selbst als Hintergrundbild verwenden. + +--- + +# 8. POIs der Verbrannten Straße + +Vier POIs konfigurieren. + +Die Prozentwerte dürfen nach dem ersten visuellen Rendering leicht angepasst werden. Die Speicherung bleibt prozentbasiert. + +## 8.1 Jagdgebiet + +```json +{ + "key": "hunt-area", + "title": "Jagdgebiet", + "actionLabel": "Jagd beginnen", + "type": "HUNT", + "iconKey": "hunt", + "xPercent": 62, + "yPercent": 30, + "enabled": true +} +``` + +Verhalten: + +In den vorhandenen Jagdflow wechseln. + +Keine Encounter-Karten auf der Ortsansicht erzeugen. + +## 8.2 Verdächtige Spuren + +```json +{ + "key": "inspect-tracks", + "title": "Verdächtige Spuren", + "actionLabel": "Untersuchen", + "type": "INVESTIGATE", + "iconKey": "investigate", + "xPercent": 43, + "yPercent": 68, + "enabled": true +} +``` + +Interaktionsresultat: + +```text +Zwischen Asche und zerbrochenen Steinen erkennst du mehrere frische Stiefelabdrücke. Sie führen nach Osten, in Richtung des verlassenen Wachtpostens. +``` + +## 8.3 Verlassener Wagen + +```json +{ + "key": "search-abandoned-wagon", + "title": "Verlassener Wagen", + "actionLabel": "Durchsuchen", + "type": "SEARCH", + "iconKey": "search", + "xPercent": 27, + "yPercent": 53, + "enabled": true +} +``` + +Interaktionsresultat: + +```text +Der Wagen wurde gründlich geplündert. Zwischen verbrannten Brettern findest du nur leere Kisten und Spuren eines hastigen Aufbruchs. +``` + +Diese erste Version vergibt noch keinen Loot. + +## 8.4 Verwundeter Kundschafter + +```json +{ + "key": "wounded-scout", + "title": "Verwundeter Kundschafter", + "actionLabel": "Sprechen", + "type": "NPC", + "iconKey": "speak", + "xPercent": 64, + "yPercent": 57, + "enabled": true +} +``` + +Interaktionsresultat: + +```text +„Die Straße ist nicht mehr sicher. Die Plünderer kommen aus Richtung des alten Wachtpostens. Wenn du weitergehst, halte die Augen offen.“ +``` + +Diese Interaktion erzeugt in diesem Slice noch keine Quest. + +--- + +# 9. Primäre Aktionen + +Folgende vier Buttons in dieser Reihenfolge rendern: + +```text +1. Jagd beginnen +2. Spuren untersuchen +3. Umgebung durchsuchen +4. Zur Karte +``` + +Verhalten: + +## Jagd beginnen + +Verwendet `HUNT` und den bestehenden Jagdflow. + +## Spuren untersuchen + +Führt `inspect-tracks` aus und öffnet das lokale Interaktionspanel. + +## Umgebung durchsuchen + +Führt `search-abandoned-wagon` aus und öffnet das lokale Interaktionspanel. + +## Zur Karte + +Navigiert zur bestehenden Kartenroute. + +Wenn die Kartenroute aktuell `/world` ist, bleibt `/world` bestehen. + +--- + +# 10. Encounter-Vorschau + +In der rechten Sidebar folgende repräsentative Gegner anzeigen: + +```text +Aschenratte +Verwilderter Straßenhund +Straßenräuber +Verkohlter Plünderer +``` + +Die Daten möglichst aus vorhandenen `LocationMonster`-/Monsterdefinitionen ableiten. + +Die Vorschau verändert den aktuellen Hunt-Roll nicht und dupliziert keine Gewichtungslogik. + +--- + +# 11. Belohnungsvorschau + +Kleine Vorschau-Icons für bereits im Projekt existierende Kategorien anzeigen, beispielsweise: + +```text +Handelswert / Silber +Ausrüstung +Material / regionale Handelsware +Heiltrank +seltener Loot +``` + +Die Vorschau ist rein informativ. + +Keine neuen Reward-Grants implementieren, nur um diese Sidebar zu füllen. + +Falls das aktuell implementierte Progressionssystem direkte Monster-XP/-Silber bereits zugunsten von Materialien und Rufabgabe ersetzt hat, muss die Ortsansicht die **aktuelle** Progressionslogik darstellen und keine veralteten XP-/Silbertexte wieder einführen. + +--- + +# 12. Layout der Ortsansicht + +Die Desktop-Komposition des Referenzscreens nachbauen. + +Im bestehenden App-Shell: + +```text +┌─────────────────────────────────────────┬─────────────────────┐ +│ Ortskopf │ Kontext-Sidebar │ +│ │ │ +│ Großes Artwork │ Ortsinfos │ +│ + positionierte POIs │ Gefahr │ +│ │ Begegnungen │ +│ │ Interaktionen │ +│ │ Belohnungen │ +│ │ │ +│ Primäre Aktionsleiste │ │ +└─────────────────────────────────────────┴─────────────────────┘ +``` + +Das Artwork muss den größten Anteil der verfügbaren Fläche einnehmen. + +Keine Umsetzung als Grid aus vielen kleinen Dashboard-Cards. + +--- + +# 13. Verhalten der POI-Komponente + +`LocationPoiComponent` ist ausschließlich verantwortlich für: + +- Icon rendern +- Titel rendern +- Aktionslabel rendern +- Position über `left: xPercent%` und `top: yPercent%` +- Klick auslösen +- Hover-/Focus-Zustand +- Disabled-Zustand + +Konzeptionelles Input/Output: + +```ts +@Input({ required: true }) poi!: LocalLocationPointOfInterestDto; +@Output() activate = new EventEmitter(); +``` + +Zur Positionierung beispielsweise verwenden: + +```text +transform: translate(-50%, -50%) +``` + +oder den bereits im Projekt etablierten äquivalenten Ansatz. + +Keyboard Accessibility: + +- POI ist fokussierbar +- Enter aktiviert +- Space aktiviert +- sichtbarer Fokuszustand + +--- + +# 14. Interaktionspanel + +Kurze lokale Interaktionen öffnen keine eigene Seite. + +Ein Panel/Modal im bestehenden Ashen-Realms-Stil zeigt: + +```text +Titel +Ergebnistext +[Schließen] +``` + +Auch der NPC-Dialog der ersten Version darf dasselbe Panel verwenden. + +Keine verzweigten Antwortmöglichkeiten in diesem Slice. + +Beim Schließen bleibt der Spieler auf derselben Ortsansicht. + +--- + +# 15. Verhalten nach Reiseabschluss + +Den bestehenden Travel-Completion-Flow analysieren. + +Nach erfolgreicher Reise und nachdem `currentLocation` serverseitig auf den Zielort gesetzt wurde, navigiert das Frontend zu: + +```text +/location +``` + +Nicht direkt zur Jagd wechseln. + +Wenn das Frontend aktuell nach Reiseabschluss auf der Karte bleibt, nur dieses Navigationsverhalten ändern. + +Nicht ändern: + +- Timerlogik +- `arrivesAt` +- serverseitigen Reiseabschluss +- Travel-Validierung + +--- + +# 16. Zurück aus der Jagd + +Die Aktion `Zurück` im Jagd-Screen führt im normalen lokalen Gameplay zu: + +```text +/location +``` + +Die Encounter-Generierung bleibt unverändert. + +Falls das Projekt Deep Links oder mehrere Einstiegspfade unterstützt, den einfachsten bereits vorhandenen Navigationsmechanismus verwenden und keinen neuen globalen Router-State einführen. + +--- + +# 17. Rückkehr nach dem Kampf + +Den bestehenden Post-Combat-/Loot-Flow analysieren. + +Wenn der aktuelle Flow einen abgeschlossenen normalen Jagdkampf zurück zu Jagd oder Welt führt, bevorzugtes Ziel: + +```text +/location +``` + +Nicht verändern: + +- Combat-Auflösung +- Loot-Berechnung +- Encounter-State + +Falls der Post-Combat-Navigationsflow noch nicht existiert oder außerhalb des aktuellen Slices liegt, Combat-Code unangetastet lassen und die noch offene Routenanpassung dokumentieren. + +--- + +# 18. Loading- und Fehlerzustände + +## Loading + +Während `GET /api/world/current-location` lädt: + +- Topbar / Navigation / Footer bleiben sichtbar +- zurückhaltender Ladezustand im Hauptbereich +- keine falsch positionierten Platzhalter-POIs anzeigen + +## API-Fehler + +Anzeigen: + +```text +Ort konnte nicht geladen werden. +[Erneut versuchen] +``` + +Karten-Navigation bleibt verfügbar. + +## Ungültige Interaktion + +Wenn der Server eine lokale Interaktion ablehnt: + +- kompakte Fehlermeldung im Interaktionspanel oder bestehenden Toast-System +- keine Navigation + +--- + +# 19. Schutz bei aktivem Kampf + +Wenn bestehende Backend-/Client-Logik einen noch offenen Kampf erkennen kann, darf `/location` nicht zum Umgehen des Kampfes verwendet werden. + +Bestehenden Combat-Resume-Flow wiederverwenden. + +Keinen zweiten Combat-State-Mechanismus bauen. + +--- + +# 20. Visuelle Umsetzung + +Kompositionsreferenz: + +```text +verbrannte_strasse_in_den_aschenfeldern.png +``` + +Bestehende Ashen-Realms-Sprache übernehmen: + +- dunkle Metallrahmen +- gealterter Stein / Eisen +- dezente Goldverzierungen +- großes Orts-Artwork +- Fantasy-Serif-Titel +- gut lesbare UI-Schrift +- dunkle rechte Sidebar +- runde / ornamentale POI-Marker +- blauer aktiver Zustand für `Ort` +- zurückhaltende Grün-/Orange-/Rot-Funktionsfarben + +Nicht neu einführen: + +- Material-UI-Look +- Bootstrap-Card-Grid +- Glassmorphism +- weiße moderne Cards +- große runde SaaS-Panels +- übermäßigen Glow +- Neon-/Cyberpunk-Farben + +Bestehende Design-Tokens und Komponenten zuerst verwenden. + +--- + +# 21. Tests + +## Frontend Component Tests + +Mindestens prüfen: + +### Location Page + +```text +- lädt Current-Location-Daten +- rendert Ortsnamen +- rendert Region +- rendert Artwork +- rendert vier POIs +- rendert primäre Aktionen +- rendert Encounter-Vorschau +``` + +### POI Component + +```text +- positioniert anhand von Prozentwerten +- löst Aktivierung bei Klick aus +- kann per Keyboard aktiviert werden +- deaktivierter POI löst nichts aus +``` + +### Primäre Aktionen + +```text +- Jagd öffnet bestehenden Jagdflow +- Karte öffnet bestehende Kartenroute +- Untersuchen ruft Interaction API auf +- Durchsuchen ruft Interaction API auf +``` + +### Interaction Panel + +```text +- zeigt zurückgegebenen Titel und Text +- schließt ohne Navigation +``` + +## Backend Tests + +Mindestens prüfen: + +```text +- current-location liefert lokale View-Daten für den tatsächlichen aktuellen Ort +- aktivierte Interaktion des aktuellen Ortes funktioniert +- Interaktion eines anderen Ortes wird abgelehnt +- deaktivierter/unbekannter Key wird abgelehnt +- Request kann keinen beliebigen Zielort auswählen +``` + +## Regression Tests + +Sicherstellen: + +```text +- Kartenreise funktioniert weiterhin +- Hunt verwendet weiterhin den vorhandenen gewichteten Encounter-Pool +- Combat-Logik bleibt unverändert +- Loot-Logik bleibt unverändert +``` + +--- + +# 22. Implementierungsaufgaben + +### Task 1: Bestehenden World-, Travel-, Hunt- und Shell-Code analysieren + +**Files:** nur bestehendes Repository + +**Interfaces:** +- Consumes: App-Shell, Routen, World API, Travel Flow, Hunt Flow +- Produces: bestätigte Wiederverwendungspunkte und exakte Dateien für Tasks 2–8 + +- [ ] Angular-Routen öffnen und kanonische Map-/Hunt-Routen ermitteln. +- [ ] Side-Navigation öffnen und aktiven Zustand / Konfiguration verstehen. +- [ ] Current-Location-Controller/-Service und DTO öffnen. +- [ ] Travel-Completion-Code und aktuelle Navigation nach Reiseende finden. +- [ ] Hunt Page und `Zurück`-Verhalten prüfen. +- [ ] Bestehende Design-Tokens, Panel- und Button-Komponenten prüfen. +- [ ] Stabilen Key der Verbrannten Straße bestätigen. +- [ ] Erst danach Implementierungsdateien ändern. + +### Task 2: Local-Location-Contracts und Backend-Content ergänzen + +**Files:** +- Shared DTO-/Model-Dateien gemäß bestehender Struktur anpassen oder erstellen. +- Bestehendes World-/Location-Modell nur soweit notwendig erweitern. +- Seed der Verbrannten Straße erweitern. +- Migration hinzufügen, falls das DB-Schema geändert wird. +- Backend-Tests beim bestehenden World-Modul ergänzen. + +**Interfaces:** +- Produces: `LocalLocationViewDto`, lokale POIs/Aktionen +- Consumes: Current Character Location, LocationDefinition, bestehender Monster-/Location-Content + +- [ ] Failing Test für zusätzliche Current-Location-Felder schreiben. +- [ ] Failing Test schreiben, dass Verbrannte Straße vier POIs liefert. +- [ ] Minimale Content-Struktur implementieren. +- [ ] Exakten Content aus Abschnitt 7–11 seeden. +- [ ] Encounter-Vorschau möglichst aus bestehenden Monsterdaten ableiten. +- [ ] Backend-Tests ausführen. +- [ ] Bei Schemaänderung TypeORM-Migration generieren und SQL prüfen. +- [ ] Backend-/Content-Änderung committen. + +### Task 3: Endpoint für lokale Interaktionen ergänzen + +**Files:** +- Bestehenden World Controller/Service erweitern oder fokussierte Local-Interaction-Dateien im World-Modul anlegen. +- Backend-Tests ergänzen. + +**Interfaces:** +- Produces: `POST /api/world/current-location/interactions/:interactionKey` +- Consumes: Character + tatsächliche Current Location + +- [ ] Failing Success-Test für `inspect-tracks` schreiben. +- [ ] Failing Rejection-Test für Interaktion eines anderen Ortes schreiben. +- [ ] Failing Rejection-Test für unbekannten Key schreiben. +- [ ] Current-Location-Validierung implementieren. +- [ ] Exakte V1-Texte aus Abschnitt 8 zurückgeben. +- [ ] Backend-Tests ausführen. +- [ ] Committen. + +### Task 4: Wiederverwendbare Angular Location Page bauen + +**Files:** +- `apps/web/src/app/features/world/location-page/*` oder äquivalenter bestehender World-Pfad. +- Local-Location-Service/-Models erstellen oder vorhandene Strukturen erweitern. +- Component Tests ergänzen. + +**Interfaces:** +- Produces: `/location` +- Consumes: `GET /api/world/current-location` + +- [ ] Failing Page-Test mit gemocktem `LocalLocationViewDto` schreiben. +- [ ] `/location`-Route ergänzen. +- [ ] Current Location über vorhandenes API-Client-Pattern laden. +- [ ] Header, Artwork, Sidebar und Aktionsbereich rendern. +- [ ] Loading-/Error-State ergänzen. +- [ ] Frontend-Tests ausführen. +- [ ] Committen. + +### Task 5: Wiederverwendbare POI-Overlay-Komponente bauen + +**Files:** +- `apps/web/src/app/features/world/location-poi/*` oder äquivalenter Pfad. +- Component Tests ergänzen. + +**Interfaces:** +- Produces: wiederverwendbarer positionierter POI-Marker +- Consumes: `LocalLocationPointOfInterestDto` + +- [ ] Failing Render-/Positionstests schreiben. +- [ ] Failing Keyboard-Test schreiben. +- [ ] Prozentbasierte Positionierung implementieren. +- [ ] Icon, Titel und Aktionslabel rendern. +- [ ] Hover-/Focus-/Disabled-State mit bestehenden Tokens umsetzen. +- [ ] Vier POIs auf der Ortsansicht integrieren. +- [ ] Frontend-Tests ausführen. +- [ ] Committen. + +### Task 6: Interaction Panel und lokale Aktionen umsetzen + +**Files:** +- `location-interaction-panel/*` erstellen oder bestehendes Modal/Panel wiederverwenden. +- Location Page/Service erweitern. +- Tests ergänzen. + +**Interfaces:** +- Produces: Darstellung von Investigate/Search/NPC-Resultaten +- Consumes: `POST /api/world/current-location/interactions/:interactionKey` + +- [ ] Failing Test für Spuren-Interaktion schreiben. +- [ ] Failing Test für Wagen-Suche schreiben. +- [ ] Failing Test für Kundschafter-Dialog schreiben. +- [ ] API-Aufruf implementieren. +- [ ] Titel/Text im Panel anzeigen. +- [ ] Schließen ohne Navigation implementieren. +- [ ] Frontend-Tests ausführen. +- [ ] Committen. + +### Task 7: Jagd- und Kartenaktionen verbinden + +**Files:** +- Action Handling der Location Page ändern. +- Hunt-Zurück-Navigation nur falls notwendig anpassen. +- Tests ergänzen/anpassen. + +**Interfaces:** +- Consumes: bestehende Map-/Hunt-Routen +- Produces: Ort → Jagd/Karte sowie Jagd → Ort + +- [ ] Failing Test schreiben, dass `Jagd beginnen` den bestehenden Hunt Flow öffnet. +- [ ] Failing Test schreiben, dass `Zur Karte` die bestehende Kartenroute öffnet. +- [ ] Hunt-Back-Test ergänzen/anpassen. +- [ ] Navigation implementieren, ohne Hunt-Generierung zu ändern. +- [ ] Frontend-Tests ausführen. +- [ ] Committen. + +### Task 8: Ortsansicht als Ziel nach Reiseabschluss verwenden + +**Files:** +- Nur vorhandenen Post-Travel-Navigationscode ändern. +- Tests anpassen. + +**Interfaces:** +- Consumes: bestehender serverautoritärer Reiseabschluss +- Produces: abgeschlossene Reise → `/location` + +- [ ] Test für Navigation nach erfolgreichem Reiseabschluss schreiben/anpassen. +- [ ] Zielroute auf `/location` setzen. +- [ ] Sicherstellen, dass Current Location bereits durch den bestehenden Serverflow aktualisiert wird. +- [ ] Timer, Ankunftsberechnung und Travel-Validierung nicht ändern. +- [ ] Relevante Frontend-/Backend-Travel-Tests ausführen. +- [ ] Committen. + +### Task 9: `Ort` in persistente Navigation aufnehmen + +**Files:** +- Bestehende Side-Navigation konfigurieren/ändern. +- Navigationstests anpassen. + +**Interfaces:** +- Produces: permanenter `Ort`-Eintrag +- Consumes: `/location` + +- [ ] Failing Test für `Ort` schreiben. +- [ ] Eintrag mit passendem vorhandenen Fantasy-Icon hinzufügen. +- [ ] Aktiven Zustand analog zu bestehenden Navigationseinträgen umsetzen. +- [ ] Menü-Reihenfolge aus Abschnitt 2 verwenden. +- [ ] Frontend-Tests ausführen. +- [ ] Committen. + +### Task 10: Visuelle Prüfung und Responsive Check + +**Files:** nur gezielte SCSS-/Layoutkorrekturen aus vorherigen Tasks + +**Interfaces:** +- Consumes: fertige Ortsansicht +- Produces: visuell geprüfter Desktop-Screen + +- [ ] Anwendung mit Verbrannter Straße als aktuellem Ort starten. +- [ ] Mit `verbrannte_strasse_in_den_aschenfeldern.png` vergleichen. +- [ ] Prüfen, dass Artwork den Hauptbereich dominiert. +- [ ] Prüfen, dass POIs lesbar sind, aber die Szene nicht verdecken. +- [ ] Prüfen, dass vier Hauptaktionen im Desktop-Viewport ohne Scrollen sichtbar bleiben. +- [ ] Prüfen, dass Sidebar das Artwork nicht zu stark verkleinert. +- [ ] Browserbreite innerhalb Desktop-/Tabletbereich ändern und POI-Verankerung prüfen. +- [ ] Textüberläufe in Rahmen prüfen. +- [ ] Sichtbare Tastatur-Fokuszustände prüfen. +- [ ] vollständige Web- und API-Test-Suites ausführen. +- [ ] Production Build ausführen. +- [ ] abschließende Layoutkorrekturen committen. + +--- + +# 23. Acceptance Criteria + +Das Feature ist fertig, wenn: + +- `/location` existiert und den bestehenden Ashen-Realms-App-Shell verwendet. +- `Ort` dauerhaft in der Navigation vorhanden und auf `/location` aktiv ist. +- der tatsächliche aktuelle Ort des Charakters vom Backend geladen wird. +- Verbrannte Straße mit dem echten lokalen Artwork gerendert wird. +- `Verbrannte Straße` und `Aschenfelder` sofort erkennbar sind. +- vier POIs über Prozentkoordinaten auf dem Artwork liegen. +- `Jagdgebiet` den bestehenden Jagdflow öffnet. +- `Verdächtige Spuren` den definierten Untersuchungstext anzeigt. +- `Verlassener Wagen` den definierten Suchtext anzeigt und noch keinen Loot vergibt. +- `Verwundeter Kundschafter` den definierten Dialog anzeigt, ohne eine Questengine einzuführen. +- die untere Aktionsleiste genau die vier in diesem Plan definierten Hauptaktionen enthält. +- die rechte Sidebar Ortsidentität, Gefahr/Kontext, Encounter-Vorschau, Interaktionen und Belohnungsvorschau zeigt. +- die Ortsansicht keine Hunt-Encounters würfelt. +- die Ortsansicht keine Reiseabschlusslogik implementiert. +- bestehende Map-, Travel-, Hunt-, Combat- und Loot-Logik intakt bleibt. +- abgeschlossene Reise die Ortsansicht öffnet. +- `Zurück` aus der Jagd zur Ortsansicht führt. +- ein zweiter zukünftiger Ort durch andere Content-Daten statt durch eine neue Page-Komponente dargestellt werden kann. +- Frontend- und Backend-Tests erfolgreich sind. +- Production Build erfolgreich ist. + +--- + +# 24. Explizite Non-Goals + +Nicht Teil dieser Umsetzung: + +- verzweigte NPC-Dialoge +- Questannahme beim Kundschafter +- zufälliger Loot aus dem Wagen +- Cooldowns für lokale Suchaktionen +- Hidden-Object-Mechaniken +- freie Charakterbewegung +- animiertes NPC-Pathfinding +- neue Reisemechaniken +- neue Jagdmechaniken +- Boss-UI +- Dungeon-UI +- generische Event-Skriptsprache +- CMS-Tooling + +Diese Systeme werden erst ergänzt, wenn konkreter Content sie benötigt. + +--- + +# 25. Leitprinzip für die Umsetzung + +Das Ergebnis muss eine dauerhafte Weltregel etablieren: + +> **Wenn der Spieler irgendwohin reist, kommt er an einem Ort an – nicht in einem weiteren Menü.** + +Die Verbrannte Straße ist nur die erste Implementierung. Komponenten und Content-Struktur müssen danach auch Südtor, Verlassener Wachtposten, Aschengrube, Dämmerwald-Orte und spätere Regionen darstellen können, ohne die Screen-Architektur neu zu bauen. diff --git a/docs/superpowers/specs/Ashen_Realms_Local_Location_View_Design_Spec_V1.md b/docs/superpowers/specs/Ashen_Realms_Local_Location_View_Design_Spec_V1.md new file mode 100644 index 0000000..6196f60 --- /dev/null +++ b/docs/superpowers/specs/Ashen_Realms_Local_Location_View_Design_Spec_V1.md @@ -0,0 +1,921 @@ +# Ashen Realms – Local Location View Design Specification V1 + +## Zweck + +Dieses Dokument definiert die dauerhaften Design- und Content-Regeln für die **lokale Ortsansicht** von Ashen Realms. + +Die Ortsansicht bildet die fehlende Weltebene zwischen der globalen Karte und spezialisierten Aktivitäten wie Jagd, Kampf, Händler, Quests, Dungeons oder Bossen. + +Sie beantwortet dem Spieler unmittelbar vier Fragen: + +1. **Wo bin ich?** +2. **Wie sieht dieser Ort aus und wie fühlt er sich an?** +3. **Wer oder was befindet sich hier?** +4. **Was kann ich hier tun?** + +Diese Spezifikation soll auch für zukünftige Gebiete und Orte gültig bleiben. Einzelne Orte dürfen sich visuell und spielerisch deutlich unterscheiden, verwenden aber dieselbe grundlegende Struktur und dasselbe Interaktionsmodell. + +--- + +# 1. Rolle im Kernloop + +Die lokale Ortsansicht wird zum normalen Ankunfts- und Ausgangsscreen, solange sich der Charakter physisch an einem Ort befindet. + +Empfohlener Ablauf: + +```text +Karte +→ Reise +→ Ortsansicht +→ Aktivität + → Jagd + → NPC + → Untersuchung + → Händler + → Quest + → Boss / Dungeon +→ zurück zur Ortsansicht +``` + +Die Karte beantwortet: + +**Wohin kann ich reisen?** + +Die Ortsansicht beantwortet: + +**Was gibt es hier?** + +Die Jagd beantwortet: + +**Was kann ich hier bekämpfen?** + +Der Kampf beantwortet: + +**Wie besiege ich diesen Gegner?** + +Diese Verantwortlichkeiten sollen getrennt bleiben. + +--- + +# 2. Position in der Navigation + +Die persistente linke Navigation erhält einen eigenen Eintrag: + +```text +Ort +Karte +Jagd +Quests +Inventar +Charakter +Shop +``` + +`Ort` ist aktiv hervorgehoben, solange der Spieler die lokale Ortsansicht betrachtet. + +Der Spieler soll grundsätzlich jederzeit zu dieser Ansicht zurückkehren können, sofern kein blockierender Gameplay-Zustand aktiv ist, beispielsweise ein noch nicht abgeschlossener Kampf. + +--- + +# 3. Ziel des Spielerlebnisses + +Ein Ort muss sich wie ein **Ort** anfühlen und nicht wie ein Datensatz oder Menüpunkt. + +Der Screen soll beim Spieler das Gefühl erzeugen: + +> Ich befinde mich gerade hier. Das ist meine Umgebung. Diese Personen und interessanten Punkte befinden sich hier. Von hier aus entscheide ich, was ich als Nächstes tue. + +Die Ortsansicht ist deshalb kein Dashboard aus vielen kleinen Karten. + +Das zentrale Artwork ist die wichtigste Präsentationsebene. + +UI liegt darum herum oder gezielt darüber. + +--- + +# 4. Grundaufbau des Screens + +Jede Ortsansicht verwendet den bestehenden Ashen-Realms-App-Shell: + +- persistente Topbar +- persistente linke Navigation +- große zentrale Artwork-Fläche +- kontextuelle rechte Sidebar +- persistenter Footer / Weltstatus + +Der eigentliche Ortsinhalt besteht aus fünf funktionalen Ebenen. + +## 4.1 Ortskopf + +Zeigt: + +- Ortsname +- Gebiet / Region als Breadcrumb +- kurze atmosphärische Beschreibung + +Beispiel: + +```text +Verbrannte Straße +Gebiet 1 > Aschenfelder + +Ein alter Handelsweg, der durch Feuer und Krieg in Asche gelegt wurde. +``` + +Die Beschreibung sollte meist in 1–3 kurzen Zeilen auskommen. + +Längere Lore gehört in Dialoge, Quests, Bücher oder eigene Lore-Inhalte. + +--- + +## 4.2 Großes Orts-Artwork + +Das Orts-Artwork ist das visuelle Zentrum des Screens. + +Es soll vermitteln: + +- Biom +- lokale Gefahr +- Wetter / Atmosphäre +- Architektur +- Spuren vergangener Ereignisse +- wichtige Landmarken + +Beispiele: + +### Aschenfelder +- verbrannte Straßen +- Asche +- Glut +- tote Bäume +- zerstörte Wagen +- Rauch + +### Dämmerwald +- dichte Vegetation +- Nebel +- dunkles Blätterdach +- überwucherte Ruinen +- Spuren verdorbener Tiere + +### Vergessene Ruinen +- alter Stein +- Gräber +- eingestürzte Mauern +- Banner +- Krypteneingänge +- kaltes magisches Licht + +Interaktionsbeschriftungen dürfen **nicht fest in das Artwork eingebrannt** sein. + +Marker und Labels werden durch die UI gerendert. + +--- + +# 5. Points of Interest und Hotspots + +Ein Ort kann direkt auf dem Artwork interaktive **Points of Interest (POIs)** besitzen. + +Ein POI besteht aus: + +- Icon +- Titel +- optionalem kurzen Aktionslabel +- normalisierter X-/Y-Position im Artwork +- Interaktionstyp +- optionalem Verfügbarkeitszustand + +Beispiel: + +```text +[Truhen-Icon] +Verlassener Wagen +Durchsuchen +``` + +POIs sollen sich optisch in die Szene integrieren. + +Der Screen darf dadurch nicht zu einem Hidden-Object-Spiel werden. + +Empfohlene sichtbare Anzahl: + +- einfacher Übergangsort: 1–3 +- normaler Ort: 2–5 +- großer Hub: 3–7 + +Wenn deutlich mehr Aktionen notwendig sind, müssen sie gruppiert oder in eigene Panels/Screens ausgelagert werden. + +--- + +# 6. Wiederverwendbare Interaktionstypen + +Die erste gemeinsame Interaktionssprache lautet: + +```text +HUNT +INVESTIGATE +SEARCH +NPC +MAP +TRAVEL +SHOP +QUEST +BOSS +DUNGEON +``` + +Nicht jeder Typ muss bereits im ersten Slice vollständig umgesetzt sein. + +Wichtig ist, dass neue Orte aus wiederverwendbaren Interaktionstypen aufgebaut werden und nicht jeweils eigene Angular-Spezialkomponenten erhalten. + +## 6.1 HUNT + +Zweck: + +Startet die normale Jagd-/Encounter-Schleife des aktuellen Ortes. + +Ablauf: + +```text +Ortsansicht +→ Jagd +``` + +Die Ortsansicht würfelt oder rendert selbst keine Encounter-Auswahl. + +--- + +## 6.2 INVESTIGATE + +Zweck: + +Untersucht Spuren, Ruinen, Symbole, Leichen, Zeichen oder andere Hinweise in der Umgebung. + +Mögliche Ergebnisse: + +- atmosphärischer Text +- Lore-Hinweis +- Hinweis auf einen Ort +- später Questfortschritt +- später versteckte Verbindung + +Für die erste Umsetzung reicht ein serverseitig geliefertes Ergebnis-Panel. + +--- + +## 6.3 SEARCH + +Zweck: + +Durchsucht ein konkretes Objekt oder einen kleinen Bereich. + +Beispiele: + +- verlassener Wagen +- alte Vorratskiste +- Lagerreste +- Kryptennische + +Später mögliche Ergebnisse: + +- Item +- Währung +- Verbrauchsgegenstand +- Hinweis +- nichts + +Sobald eine Interaktion echte Belohnungen vergibt, muss sie serverautoritativ sein. + +Die erste Version darf reine Text-/Informationsresultate verwenden. + +--- + +## 6.4 NPC + +Zweck: + +Interaktion mit einem sichtbar am Ort vorhandenen NPC. + +Für V1 reicht ein einfaches Dialogpanel. + +Spätere Erweiterungen können sein: + +- Quests +- Händler +- Ruf-/Tauschsystem +- Dienstleistungen +- Fraktionsinteraktionen + +NPCs sollen möglichst im Kontext der Szene sichtbar sein und nicht ausschließlich als Textliste in einem Panel erscheinen. + +--- + +## 6.5 MAP + +Zweck: + +Öffnet die bestehende Karten-/Reiseansicht. + +```text +Ortsansicht +→ Karte +``` + +--- + +## 6.6 TRAVEL + +Reisen bleibt Bestandteil des bestehenden Karten-/Reisesystems. + +Die Ortsansicht darf visuell Ausgänge oder Ziele zeigen, soll aber im Normalfall in den vorhandenen Reiseflow weiterleiten statt eine zweite Reiselogik zu bauen. + +--- + +## 6.7 SHOP, QUEST, BOSS, DUNGEON + +Diese Typen sind Erweiterungspunkte für späteren Content. + +Sie verwenden dieselben POI- und Aktionsregeln, öffnen aber jeweils einen eigenen Screen, ein Panel oder einen spezialisierten Flow. + +--- + +# 7. Primäre Aktionsleiste + +Die wichtigsten lokalen Aktionen werden zusätzlich in einer großen Aktionsleiste unterhalb des Artworks dargestellt. + +Diese Dopplung ist beabsichtigt. + +POIs erzeugen Atmosphäre und räumlichen Kontext. + +Die Aktionsleiste sorgt für klare Bedienbarkeit. + +Empfohlenes Maximum: + +**4 primäre Ortsaktionen** + +Beispiel: + +```text +[Jagd beginnen] +[Spuren untersuchen] +[Umgebung durchsuchen] +[Zur Karte] +``` + +Sekundäre Aktionen dürfen ausschließlich als POI oder in der rechten Sidebar erscheinen. + +--- + +# 8. Rechte Kontext-Sidebar + +Die rechte Sidebar fasst die spielerische Bedeutung des aktuellen Ortes zusammen. + +Empfohlene Bereiche: + +## Ortsidentität + +- Gebiet / Region +- Ortsname +- Ortstyp + +## Progressionskontext + +- empfohlener Fortschrittsbereich oder Empfehlung +- relative Gefahr + +Diese Information darf keine harte Zugangssperre sein. + +Der bestehende Ashen-Realms-Grundsatz bleibt: + +> Die Welt kommuniziert Gefahr, ohne Experimente künstlich zu verbieten. + +## Mögliche Begegnungen + +Zeigt repräsentative Gegner oder Encounter-Kategorien. + +Das ist nur Vorschauinformation. + +Der tatsächliche Encounter-Wurf erfolgt weiterhin im Jagdsystem. + +## Verfügbare Interaktionen + +Beispiele: + +- Jagd +- Untersuchen +- Durchsuchen +- Sprechen + +## Mögliche Belohnungen + +Optionale Vorschau-Icons für: + +- Ausrüstung +- Materialien +- Verbrauchsgegenstände +- Handelswaren +- regionsspezifische Belohnungen + +Es dürfen keine exakten Belohnungen versprochen werden, wenn der zugrunde liegende Content diese nicht garantiert. + +--- + +# 9. Ortstypen + +Orte können über wiederverwendbare Typen ihre grundlegende Rolle ausdrücken. + +Empfohlene Startwerte: + +```text +SAFE_HUB +TRANSITION +HUNTING_GROUND +QUEST_LOCATION +OUTPOST +ELITE_ZONE +BOSS_LOCATION +DUNGEON_ENTRANCE +``` + +Der Typ beeinflusst Präsentation und verfügbare Aktionen, benötigt aber keine eigene Page-Implementierung. + +Beispiele: + +### Südtor von Graufurt + +```text +TRANSITION +``` + +Fokus: + +- Wachposten +- Reise +- Gebietsinformation +- wenig oder keine reguläre Jagd + +### Verbrannte Straße + +```text +HUNTING_GROUND +``` + +Fokus: + +- Jagd +- Umgebungsinformationen +- Spuren +- erste NPC-Begegnung + +### Verlassener Wachtposten + +```text +OUTPOST / QUEST_LOCATION +``` + +Fokus: + +- NPC +- stärkere Jagd +- Untersuchung +- Storyfortschritt + +### Aschengrube + +```text +ELITE_ZONE / BOSS_LOCATION +``` + +Fokus: + +- Gefahr +- Elite-/Bosszugang +- kaum zivile Interaktionen + +--- + +# 10. Wiederverwendbares Content-Modell + +Die Ortsansicht soll datengetrieben sein. + +Ein konzeptionelles View-Model sollte mindestens enthalten: + +```ts +interface LocalLocationView { + locationId: string; + locationKey: string; + name: string; + regionName: string; + description: string; + locationType: LocationType; + artworkPath: string; + dangerRating: DangerRating; + recommendationLabel?: string; + huntingEnabled: boolean; + pointsOfInterest: LocationPointOfInterest[]; + primaryActions: LocationAction[]; + encounterPreview: EncounterPreview[]; + rewardPreview: RewardPreview[]; +} +``` + +Konzeptionelles POI-Modell: + +```ts +interface LocationPointOfInterest { + key: string; + title: string; + actionLabel?: string; + type: LocationInteractionType; + iconKey: string; + xPercent: number; + yPercent: number; + enabled: boolean; +} +``` + +Koordinaten werden als Prozentwerte gespeichert, damit Hotspots beim Skalieren des Artworks an derselben Stelle bleiben. + +Beispiel: + +```text +xPercent: 42.5 +yPercent: 66.0 +``` + +--- + +# 11. Interaktionsergebnisse + +Lokale Interaktionen sollen ein vorhersehbares Ergebnisformat zurückgeben. + +Konzeptionell: + +```ts +interface LocationInteractionResult { + interactionKey: string; + title: string; + text: string; + nextAction?: { + type: string; + target?: string; + }; +} +``` + +Die erste Version bleibt bewusst klein. + +Nicht nur für diesen Screen bauen: + +- generische Visual-Novel-Engine +- verzweigte Dialogengine +- Event-Skriptsprache +- komplexen Questgraph + +--- + +# 12. Navigationsregeln + +## Nach abgeschlossener Reise + +Der Spieler landet in der lokalen Ortsansicht des neuen aktuellen Ortes. + +```text +Reise abgeschlossen +→ current location aktualisiert +→ Ortsansicht +``` + +## Nach normalem Kampf + +Empfohlener Standard: + +```text +Kampfergebnis / Loot +→ Ortsansicht +``` + +Von dort kann der Spieler erneut jagen. + +## Beim Verlassen der Jagd + +`Zurück` führt zur Ortsansicht. + +## Karte + +`Zur Karte` öffnet die Karte, verändert aber nicht den aktuellen Ort. + +--- + +# 13. Screen-Zustände + +Die Ortsansicht muss mindestens folgende Zustände definieren. + +## Loading + +- App-Shell bleibt sichtbar +- zurückhaltender Ladezustand im Hauptbereich + +## Loaded + +- Artwork +- POIs +- Aktionen +- Kontext-Sidebar + +## Interaktion geöffnet + +- Ort bleibt im Hintergrund sichtbar +- kurze Untersuchungen und einfache NPC-Dialoge öffnen kein komplett neues Seitenlayout + +## Aktion nicht verfügbar + +- sichtbar deaktiviert +- optional kurze Erklärung / Tooltip + +## API-Fehler + +- Navigation bleibt benutzbar +- kompakter Retry-Zustand + +## Aktiver Kampf + +Wenn der Server einen noch nicht abgeschlossenen Kampf meldet, darf die Ortsansicht nicht zum Umgehen dieses Kampfes genutzt werden. + +Der bestehende Combat-Resume-Flow hat Vorrang. + +--- + +# 14. Visuelle Regeln + +Die Ortsansicht folgt vollständig der bestehenden Ashen-Realms-UI-Spezifikation. + +Wichtig: + +- Artwork zuerst +- dunkles Metall / Stein / Leder +- dezente Goldverzierungen +- keine weißen SaaS-Cards +- kein Glassmorphism +- keine Neon-Dashboard-Optik +- Fantasy-Serif für große Überschriften +- sehr gut lesbare UI-Schrift für normalen Text +- zurückhaltender Glow +- eindeutige Interaktionszustände +- konsistente Icon-Sprache + +POI-Marker müssen erkennbar sein, dürfen aber das Artwork nicht dominieren. + +Bevorzugt werden kleine runde oder schildartige Fantasy-Marker statt moderner Map-Pins. + +--- + +# 15. Responsive Verhalten + +Desktop bleibt das primäre Ziel. + +## Desktop + +- volle linke Navigation +- Artwork mit positionierten POIs +- rechte Sidebar sichtbar +- primäre Aktionsleiste sichtbar + +## Tablet + +- rechte Sidebar darf einklappbar werden +- Hauptaktionen bleiben sichtbar +- POIs bleiben durch Prozentkoordinaten korrekt verankert + +## Mobile – später + +Nicht V1-Priorität. + +Mögliche spätere Anpassung: + +- Artwork oben +- POI-Liste unterhalb des Artworks +- rechte Sidebar wird einklappbare Ortsinfo +- Aktionen als zweispaltiges Grid + +Das Desktop-Design soll jetzt nicht zugunsten von Mobile kompromittiert werden. + +--- + +# 16. Content-Regeln für zukünftige Orte + +Bei jedem neuen Ort werden in dieser Reihenfolge definiert: + +1. **Zweck des Ortes** +2. **Visuelle Szene** +3. **Wichtigste Spielerentscheidung** +4. **2–5 sinnvolle POIs** +5. **Bis zu 4 primäre Aktionen** +6. **Encounter-Vorschau, falls relevant** +7. **Informationen für die rechte Sidebar** +8. **Rückkehr- und Weiterreise-Flow** + +Für jeden relevanten Ort muss beantwortet werden: + +> Warum soll sich der Spieler an diesen Ort erinnern und ihn nicht nur als weiteren Menüpunkt wahrnehmen? + +Mindestens ein identitätsstiftendes Element sollte vorhanden sein: + +- markanter NPC +- besondere Landmarke +- Untersuchung +- spezieller Service +- Elitezugang +- Bosszugang +- ungewöhnlicher Encounter-Pool +- Story-Hinweis +- visuelles Ereignis + +--- + +# 17. Was ausdrücklich nicht gebaut werden soll + +Die Ortsansicht ist kein: + +- frei begehbarer Screen +- WASD-Bewegungssystem +- Point-and-Click-Adventure +- Hidden-Object-Spiel +- zweiter Kartenscreen +- Ersatz für die Jagd +- Ersatz für Quests +- universelles Modal für alle Spielsysteme + +Vermeiden: + +- dutzende Hotspots +- individuelle Komponenten pro Ort +- Kampflogik im Orts-Screen +- clientseitige Loot-Rolls +- clientseitiger Reiseabschluss +- duplizierte Jagdlogik +- lange Lore-Textwände direkt auf der Szene + +--- + +# 18. V1-Referenzort – Verbrannte Straße + +Die erste Referenzimplementierung ist die **Verbrannte Straße** in den **Aschenfeldern**. + +## Zweck + +Beweisen, dass die Ortsansicht Weltgefühl, Jagd, einfache Exploration und NPC-Präsenz verbinden kann, ohne ein neues komplexes Subsystem zu werden. + +## Visuelle Identität + +- verbrannte Handelsstraße +- zerstörter Wagen +- aschebedeckter Boden +- glühende Risse / Glut +- tote Bäume +- Wachtstrukturen in der Ferne +- Rauch +- Spuren früherer Kämpfe + +## POIs + +### Jagdgebiet + +Typ: + +```text +HUNT +``` + +Aktion: + +```text +Jagd beginnen +``` + +### Verdächtige Spuren + +Typ: + +```text +INVESTIGATE +``` + +Aktion: + +```text +Untersuchen +``` + +Beispielresultat: + +> Zwischen Asche und zerbrochenen Steinen erkennst du mehrere frische Stiefelabdrücke. Sie führen nach Osten, in Richtung des verlassenen Wachtpostens. + +### Verlassener Wagen + +Typ: + +```text +SEARCH +``` + +Aktion: + +```text +Durchsuchen +``` + +Beispielresultat für die erste Umsetzung: + +> Der Wagen wurde gründlich geplündert. Zwischen verbrannten Brettern findest du nur leere Kisten und Spuren eines hastigen Aufbruchs. + +In der ersten Implementierung muss diese Aktion noch keine Belohnung vergeben. + +### Verwundeter Kundschafter + +Typ: + +```text +NPC +``` + +Aktion: + +```text +Sprechen +``` + +Beispieldialog: + +> „Die Straße ist nicht mehr sicher. Die Plünderer kommen aus Richtung des alten Wachtpostens. Wenn du weitergehst, halte die Augen offen.“ + +Für diese erste NPC-Interaktion ist noch kein Quest-System notwendig. + +## Primäre Aktionen + +```text +Jagd beginnen +Spuren untersuchen +Umgebung durchsuchen +Zur Karte +``` + +## Encounter-Vorschau + +Repräsentative Gegner: + +- Aschenratte +- Verwilderter Straßenhund +- Straßenräuber +- Verkohlter Plünderer + +Die Vorschau ist rein informativ. + +Sie ersetzt nicht den gewichteten Encounter-Pool der Jagd. + +--- + +# 19. Visuelle Referenz + +Für dieses Konzept wurde folgender Referenzscreen erzeugt: + +```text +verbrannte_strasse_in_den_aschenfeldern.png +``` + +Der Screenshot definiert Komposition und Zielgefühl, aber keine pixelgenauen Maße. + +Zukünftige Ortsansichten sollen insbesondere beibehalten: + +- denselben App-Shell +- dominantes Orts-Artwork +- dieselbe POI-Markersprache +- primäre Aktionsleiste unten +- kontextuelle rechte Sidebar +- klare Trennung zwischen Ort, Karte, Jagd und Kampf + +--- + +# 20. Definition of Done für zukünftige Orte + +Eine Ortsansicht ist fertig, wenn: + +- aktueller Ort und Region sofort erkennbar sind +- das Artwork den Ort eindeutig vermittelt +- verfügbare Aktionen klar sind +- wichtige NPCs / POIs im Kontext sichtbar sind +- POIs beim Skalieren korrekt positioniert bleiben +- Jagdaktionen den bestehenden Jagdflow verwenden +- Reisen den bestehenden Karten-/Reiseflow verwenden +- lokale Interaktionen keine fremden Systeme duplizieren +- serverautoritative Aktionen serverautoritativ bleiben +- derselbe Komponentenaufbau den nächsten Ort nur über andere Daten rendern kann +- der Screen wie ein Bestandteil desselben Ashen-Realms-UI-Systems wirkt + +--- + +# 21. Leitprinzip + +> **Die Karte zeigt dem Spieler, wohin er gehen kann. Die Ortsansicht lässt ihn spüren, wo er gerade ist.** + +Jede zukünftige Ortsansicht soll genau diese Trennung stärken.