yourpart3/docs/FALUKANT_TRANSPORT_RAIDS_SPEC.md

Falukant: Überfälle auf Transporte und Transportwachen

Dieses Dokument beschreibt das Zielmodell für einen neuen Untergrundtyp Überfälle auf Transporte sowie das ergänzende Schutzsystem Transportwachen.

Ziel:

• Untergrundspieler können bewaffnete Banden anheuern
• Banden lauern in geeigneten Regionen und überfallen dort zufällige Transporte
• Beute wird nicht vollständig, sondern nur teilweise erlangt
• Beute landet im nächstgelegenen Lager des Auftraggebers
• Opfer und Auftraggeber spüren wirtschaftliche und soziale Folgen
• Transporte können mit Wachen geschützt werden
• Überfallserfolg hängt später im Daemon an Bandengröße, Wachzahl, Region und Zufall

1. Bestandsaufnahme

Bereits vorhanden:

• Untergrundaktivitäten im Backend und UI
• Transportsystem mit Fahrzeugen, Routen, Start- und Zielniederlassung
• Lager-/Bestandssystem in Niederlassungen
• Fahrzeug- und Transportverwaltung in BranchView.vue
• Untergrundformular in UndergroundView.vue

Noch nicht vorhanden:

• Untergrundtyp raid_transport
• Bandengröße / Bandenkosten
• Wachen auf Transporten
• Kampfauflösung zwischen Überfall und Eskorte
• Beutetransfer in Lager
• Overworld-/Socket-Kommunikation für Überfälle

2. Kernidee

Ein Untergrundspieler kann eine Bande für einen Transportüberfall anheuern.

Die Bande:

• wird einer Region zugewiesen
• darf nur in Regionen vom Typ 4 oder 5 operieren
• darf nicht in town operieren
• lauert dort auf zufällige Transporte

Bei einem Überfall:

• wird nicht der gesamte Transport geraubt
• nur ein Teil der transportierten Ware wird erbeutet
• nur ein Teil kann tatsächlich abtransportiert werden
• die Beute wird in das nächstgelegene Lager des Auftraggebers eingebucht

Der Überfall wirkt:

• auf das Opfer wirtschaftlich und reputativ
• auf den Auftraggeber als Gewinnchance, aber auch als Risiko

3. Neuer Untergrundtyp

Neuer Typ:

• raid_transport

Geplanter UI-Name:

• Überfälle auf Transporte

Grundparameter:

• type: raid_transport
• regionId: Region, in der gelauert wird
• bandSize: Stärke der angeheuerten Bande
• optional später:
  • focus: eher Waren, eher Fahrzeuge, eher schwache Transporte

4. Regionsregeln

Die Aktivität darf nur in Regionen starten, die:

• Regionstyp 4 oder 5 haben
• nicht town sind

Begründung:

• Überfälle sollen auf Wegen, Randregionen oder schlecht gesicherten Zonen stattfinden
• nicht direkt im Stadtkern

UI-Regel:

• im Untergrundformular nur zulässige Regionen anbieten

Backend-Regel:

• Region validieren
• unzulässige Region serverseitig ablehnen

5. Bandensystem

5.1 Bandengröße

Der Spieler wählt eine Bandengröße, z. B.:

• small
• medium
• large

Alternativ numerisch:

• 3
• 6
• 10

Empfehlung für Version 1:

• numerischer Wert bandSize
• UI zeigt zusätzlich Stufenbezeichnung

5.2 Kosten

Die Kosten steigen überproportional, damit große Überfälle nicht trivial werden.

Beispielmodell:

• Grundkosten: 20
• pro Bandit: +12
• Risikozuschlag: bandSize * 2

Beispiel:

• 3 Banditen: 62
• 6 Banditen: 104
• 10 Banditen: 160

Die finalen Werte sind Balancing und können später angepasst werden.

6. Transportwachen

6.1 Grundidee

Für Transporte sollen Wachen mitgeschickt werden können.

Wirkung:

• geringere Überfallchance
• höhere Abwehrchance
• geringere Beute bei erfolgreichem Überfall

6.2 UI-Verhalten

Beim Erstellen eines Transports:

• zusätzliches Feld wachen
• nur positive ganze Zahl
• sichtbare Zusatzkosten

In der Transportübersicht:

• Wachenanzahl anzeigen

6.3 Kosten

Wachen verursachen direkte Transportmehrkosten.

Beispiel:

• guardCount * 4

Optional später:

• bessere Wachenstufe
• bewaffnete Eskorte

7. Überfallauflösung im Daemon

Der externe Daemon bleibt die führende Quelle für die eigentliche Auflösung.

Der Worker prüft periodisch:

1. aktive raid_transport-Aktivitäten
2. Transporte, die gerade durch passende Regionen laufen
3. ob eine Kollision zwischen Aktivität und Transport zustande kommt

7.1 Kandidatenprüfung

Ein Transport ist überfallbar, wenn:

• er aktiv ist
• seine Route durch die Zielregion der Bande führt oder dort endet
• er dem Auftraggeber nicht selbst gehört

7.2 Begegnungschance

Die Basiswahrscheinlichkeit hängt u. a. ab von:

• Bandengröße
• Regionstyp
• Transportfrequenz / Zufall
• ggf. Diskretions- oder Untergrundfaktoren

7.3 Kampfwert

Für Version 1 reicht ein abstrahierter Vergleich:

• raidPower = bandSize + random(0..bandSize)
• guardPower = guardCount + random(0..guardCount)

Modifikatoren:

• bessere Fahrzeuge können leicht entkommen
• große Transporte sind leichter sichtbar

Ergebnis:

• repelled
• partial_success
• major_success

8. Beute

Es darf niemals der komplette Transport verloren gehen.

8.1 Grundregel

Bei erfolgreichem Überfall:

• nur ein Teil der transportierten Menge wird geraubt
• nur ein Teil dieser Menge erreicht als Beute den Auftraggeber

Empfohlene Formel:

• baseLootShare = 0.15 bis 0.45
• bei major_success bis 0.60
• Wachen senken den Wert

Zusätzlich:

• Abrunden auf ganze Mengeneinheiten
• mindestens 1, wenn überhaupt Erfolg

8.2 Einlagerung

Die Beute wird in das nächstgelegene Lager des Auftraggebers eingebucht.

Priorität:

1. nächstgelegene Niederlassung des Auftraggebers
2. nur wenn dort Lager für den Produkttyp vorhanden oder anlegbar
3. falls kein geeignetes Lager existiert:

• Beute teilweise verfallen lassen
• Rest als lost_due_to_storage

Wichtig:

• nie stillschweigend alles gutschreiben
• Lagerkapazität berücksichtigen

9. Folgen

9.1 Für das Opfer

• Warenverlust
• optional kleiner Reputationsschaden
• Hinweis in Geld-/Transporthistorie
• evtl. Routenanpassung oder Absicherungsdruck

9.2 Für den Auftraggeber

• Kosten der Bande
• möglicher Beutegewinn
• optional leichter Reputations- oder Verdachtsanstieg
• Risiko von Gegenmaßnahmen in späteren Ausbaustufen

10. Datenmodell

Für eine erste technische Umsetzung werden voraussichtlich neue Felder benötigt.

10.1 Underground-Aktivität

In underground.result bzw. Payload:

• bandSize
• attempts
• successes
• lastTargetTransportId
• lastLoot
• lastOutcome

10.2 Transport

Neu empfohlen:

• guardCount
• optional später guardQuality

10.3 Transport-/Überfall-Log

Optional, aber sinnvoll:

• eigener Logeintrag oder JSON-Protokoll mit:
  • Opfer
  • Auftraggeber
  • Region
  • Bandengröße
  • Wachen
  • geraubte Mengen
  • eingelagerte Mengen

11. Socket-Events

Empfohlene Events für die UI:

11.1 Überfall auf Opferseite

{
  "event": "falukantTransportRaid",
  "user_id": 123,
  "reason": "transport_raided"
}

11.2 Überfall auf Auftraggeberseite

{
  "event": "falukantUndergroundUpdate",
  "user_id": 456,
  "reason": "raid_success"
}

Mögliche reason:

• transport_raided
• raid_repelled
• raid_success
• raid_partial_success
• raid_loot_stored

Begleitende Events:

• falukantUpdateStatus
• falukantBranchUpdate
• optional falukantUpdateDebt nicht nötig

12. UI-Anforderungen

12.1 Underground

In UndergroundView.vue:

• neuer Typ raid_transport
• Regionsauswahl mit erlaubten Regionstypen
• Wahl der Bandengröße
• Kostenanzeige
• spätere Ergebnisanzeige:
  • Erfolg / Misserfolg
  • Beute
  • Zielregion

12.2 Transport

In BranchView.vue:

• Wachenfeld beim Transportstart
• Wachenanzahl in Transportliste
• Hinweis, dass Wachen Überfälle erschweren, aber Kosten erhöhen

13. Technische Reihenfolge

TRA1. Konzept und Typerweiterung

• raid_transport als Underground-Typ anlegen
• Produktions-SQL für Bestandsdatenbank

TRA2. Lokale Projektbasis

• API akzeptiert bandSize
• UI unterstützt Bandengröße und erlaubte Regionen
• Transporte erhalten guardCount

TRA3. Daemon-Auflösung

• Worker prüft Kollisionen zwischen Aktivität und aktiven Transporten
• Überfallausgang berechnen
• Beute teilweise einlagern
• Events senden

TRA4. UI-Feinschliff

• Ergebnisflächen
• Logs
• klarere Rückmeldungen für Opfer und Auftraggeber

14. Hinweis für den Daemon

Der Daemon soll später explizit berücksichtigen:

• DB-Änderungen für guardCount und den neuen Underground-Typ werden projektseitig vorbereitet
• Überfälle dürfen nie Totalverlust erzeugen
• Lagerkapazität begrenzt reale Beute
• Wachen reduzieren Erfolgsquote und Beutemenge

15. Definition of Done

Die erste vollständige Version gilt als fertig, wenn:

1. raid_transport im Untergrund auswählbar ist
2. Transporte mit Wachen gestartet werden können
3. der Daemon aktive Überfälle gegen echte Transporte auflösen kann
4. das Opfer nie die komplette Fracht verliert
5. Beute im nächstgelegenen Lager des Auftraggebers landet
6. Opfer- und Auftraggeber-UI per Socket aktualisiert werden