yourpart3/docs/FALUKANT_UI_WEBSOCKET.md

Falukant: UI-Anpassung – WebSocket & Familie / Liebschaften

Dieses Dokument beschreibt die Nachrichten, die der externe Falukant-Daemon für Familien-, Ehe- und Liebschaftsänderungen sendet, damit die UI gezielt reagieren kann.

Transport:

• Alle Clients erhalten denselben Broadcast.
• Die UI muss nach user_id filtern und nur Events für die eingeloggte Session verarbeiten.

1. Übersicht der Events

event	Pflichtfelder	Typische UI-Reaktion
falukantUpdateFamily	user_id, reason	Gezielter Refresh von Familie, Liebschaften und je nach reason auch Geld oder Ruf
falukantUpdateStatus	user_id	Allgemeiner Falukant-Status-/Spielstands-Refresh
children_update	user_id	Kinderliste und Familienansicht aktualisieren
falukant_family_scandal_hint	relationship_id	Optionaler Hinweis oder Logeintrag; kein user_id

2. JSON-Payloads

2.1 falukantUpdateFamily

{
  "event": "falukantUpdateFamily",
  "user_id": 123,
  "reason": "daily"
}

reason ist immer genau einer dieser festen Strings:

• daily
• monthly
• scandal
• lover_birth

Es gibt keine weiteren reason-Werte.

2.2 falukantUpdateStatus

{
  "event": "falukantUpdateStatus",
  "user_id": 123
}

Dieses Event wird typischerweise direkt nach falukantUpdateFamily mit derselben user_id gesendet.

2.3 children_update

{
  "event": "children_update",
  "user_id": 123
}

Dieses Event tritt bei Geburt aus einer Liebschaft auf, meist zusammen mit:

• falukantUpdateFamily mit reason: "lover_birth"
• falukantUpdateStatus

2.4 falukant_family_scandal_hint

{
  "event": "falukant_family_scandal_hint",
  "relationship_id": 456
}

Hinweis:

• Dieses Event enthält kein user_id.
• Die UI kann es ignorieren oder optional nur für Log-/Toast-Zwecke verwenden.
• Die eigentliche nutzerbezogene Aktualisierung läuft über falukantUpdateFamily mit reason: "scandal".

3. Fachliche Bedeutung von reason

reason: "daily"

daily ist der Sammelgrund für tägliche Änderungen im Familien- und Liebschaftssystem.

Darunter fallen insbesondere:

• tägliche Drift und Änderung der Ehezufriedenheit
• Ehe-Buffs und temporäre Zähler wie Geschenk-, Fest- oder Haus-Effekte
• tägliche Liebschaftslogik für aktive Beziehungen
• Rufverlust bei zwei oder mehr sichtbaren Liebschaften
• Zufalls-Mali wie Gerücht oder Tadel

Wichtig:

• Es gibt kein separates Event für „nur Ehe-Buff“.
• Es gibt kein separates Event für „nur zwei sichtbare Liebschaften“.
• Es gibt kein separates Event für „nur Gerücht/Tadel“.
• Alles davon erscheint in der UI ausschließlich als falukantUpdateFamily mit reason: "daily".

reason: "scandal"

scandal wird zusätzlich zu einem gelungenen Skandalwurf gesendet.

Typischer Ablauf:

• optional falukant_family_scandal_hint
• falukantUpdateFamily mit reason: "scandal"
• falukantUpdateStatus

Danach kann für denselben Nutzer am selben Tag zusätzlich noch daily folgen.

reason: "monthly"

monthly steht für Monatsverarbeitung, insbesondere:

• laufende Kosten
• Unterversorgung
• Geldänderungen

reason: "lover_birth"

lover_birth signalisiert ein neues Kind aus einer Liebschaft.

Meist folgen zusammen:

• falukantUpdateFamily mit reason: "lover_birth"
• children_update
• falukantUpdateStatus

4. Empfohlene Handler-Logik

onMessage(json):
  if json.user_id exists and json.user_id != currentUserId:
    return

  switch json.event:
    case "falukantUpdateStatus":
      refreshPlayerStatus()
      return

    case "children_update":
      refreshChildrenAndFamilyView()
      return

    case "falukantUpdateFamily":
      switch json.reason:
        case "daily":
          refreshFamilyAndRelationships()
          refreshReputationIfNeeded()
          break
        case "monthly":
          refreshMoney()
          refreshFamilyAndRelationships()
          break
        case "scandal":
          showScandalToastOptional()
          refreshFamilyAndRelationships()
          refreshReputationIfNeeded()
          break
        case "lover_birth":
          refreshChildrenAndFamilyView()
          break
      return

    case "falukant_family_scandal_hint":
      // optional: nur als Hinweis verarbeiten
      return

5. Deduplizierung

Am selben Tag kann ein Nutzer mehrere relevante Events erhalten, zum Beispiel:

• scandal
• danach daily
• danach falukantUpdateStatus

Die UI sollte deshalb:

• Refreshes bündeln oder entprellen
• idempotente Reloads verwenden
• nicht davon ausgehen, dass jeder fachliche Effekt einen eigenen reason hat

6. Welche Daten sollten neu geladen werden?

Situation	Sinnvolle Reaktion
Jede falukantUpdateFamily	Family-/Relationship-Daten neu laden
reason: "monthly"	Family-Daten plus Geld/Status neu laden
reason: "daily"	Family-Daten neu laden, bei Bedarf auch Ruf-/Statusdaten
reason: "scandal"	Family-Daten plus Ruf-/Statusdaten neu laden
children_update / lover_birth	Kinderdaten und FamilyView neu laden

7. Sonderfälle

Fall	Verhalten
NPC ohne user_id	Keine nutzerbezogenen Family-Socket-Events
Mehrere Events kurz hintereinander	Normal; UI sollte damit robust umgehen
Nur falukantUpdateStatus ohne Family-Event	Kann von anderen Falukant-Workern kommen