317 lines
8.3 KiB
Markdown
317 lines
8.3 KiB
Markdown
# Falukant: UI-Anpassung - WebSocket & Familie / Liebschaften
|
|
|
|
Dieses Dokument beschreibt die Nachrichten, die der externe Falukant-Daemon über den WebSocket-Broadcast 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 Familie/Liebe/Geld je nach `reason` |
|
|
| `falukantUpdateStatus` | `user_id` | Allgemeiner Status-/Spielstands-Refresh |
|
|
| `falukantUpdateProductionCertificate` | `user_id`, `reason`, `old_certificate`, `new_certificate` | Produkte / Produktions-UI / Zertifikat neu laden |
|
|
| `children_update` | `user_id` | Kinderliste / FamilyView aktualisieren |
|
|
| `falukant_family_scandal_hint` | `relationship_id` | Optionaler Toast oder Log; kein `user_id` |
|
|
| `falukantUpdateChurch` | `user_id`, `reason` | Kirchenämter, Bewerbungen, Ernennungen |
|
|
| `falukantUpdateDebt` | `user_id`, `reason` | Schuldturm, Verzug, Pfändung, Freilassung |
|
|
|
|
## 2. JSON-Payloads
|
|
|
|
### 2.1 `falukantUpdateFamily`
|
|
|
|
```json
|
|
{
|
|
"event": "falukantUpdateFamily",
|
|
"user_id": 123,
|
|
"reason": "daily"
|
|
}
|
|
```
|
|
|
|
`reason` ist immer genau einer dieser festen Strings:
|
|
|
|
- `daily`
|
|
- `monthly`
|
|
- `lover_installment`
|
|
- `scandal`
|
|
- `lover_birth`
|
|
|
|
### 2.2 `falukantUpdateChurch`
|
|
|
|
```json
|
|
{
|
|
"event": "falukantUpdateChurch",
|
|
"user_id": 123,
|
|
"reason": "applications"
|
|
}
|
|
```
|
|
|
|
Mögliche `reason`:
|
|
|
|
- `applications`
|
|
- `npc_decision`
|
|
- `appointment`
|
|
- `vacancy_fill`
|
|
- `promotion`
|
|
|
|
### 2.3 `falukantUpdateStatus`
|
|
|
|
```json
|
|
{
|
|
"event": "falukantUpdateStatus",
|
|
"user_id": 123
|
|
}
|
|
```
|
|
|
|
Dieses Event wird typischerweise direkt nach einem fachlichen Falukant-Event mit derselben `user_id` gesendet.
|
|
|
|
### 2.4 `falukantUpdateProductionCertificate`
|
|
|
|
```json
|
|
{
|
|
"event": "falukantUpdateProductionCertificate",
|
|
"user_id": 123,
|
|
"reason": "daily_recalculation",
|
|
"old_certificate": 2,
|
|
"new_certificate": 3
|
|
}
|
|
```
|
|
|
|
### 2.5 `children_update`
|
|
|
|
```json
|
|
{
|
|
"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.6 `falukant_family_scandal_hint`
|
|
|
|
```json
|
|
{
|
|
"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"`.
|
|
|
|
### 2.7 `falukantUpdateDebt`
|
|
|
|
```json
|
|
{
|
|
"event": "falukantUpdateDebt",
|
|
"user_id": 123,
|
|
"reason": "debtors_prison_entered"
|
|
}
|
|
```
|
|
|
|
Mögliche `reason`:
|
|
|
|
- `delinquency`
|
|
- `debtors_prison_entered`
|
|
- `asset_seizure`
|
|
- `vehicle_liquidation`
|
|
- `house_seizure`
|
|
- `branch_closure`
|
|
- `debtors_prison_released`
|
|
|
|
## 3. Fachliche Bedeutung von `reason`
|
|
|
|
### 3.1 `falukantUpdateFamily`
|
|
|
|
#### `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
|
|
- `marriage_public_stability`
|
|
- `household_tension_score`
|
|
- 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: "monthly"`
|
|
|
|
`monthly` steht für monatliche Verarbeitung, insbesondere:
|
|
|
|
- Dienerschaftskosten
|
|
- laufende Kosten
|
|
- Unterversorgung
|
|
- Geldänderungen
|
|
|
|
#### `reason: "lover_installment"`
|
|
|
|
`lover_installment` steht für die 2-Stunden-Unterhaltsbelastung von Liebschaften.
|
|
|
|
Die UI sollte dafür mindestens:
|
|
|
|
- Geld neu laden
|
|
- Family-/Liebschaftsstatus neu laden
|
|
|
|
#### `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: "lover_birth"`
|
|
|
|
`lover_birth` signalisiert ein neues Kind aus einer Liebschaft.
|
|
|
|
Meist folgen zusammen:
|
|
|
|
- `falukantUpdateFamily` mit `reason: "lover_birth"`
|
|
- `children_update`
|
|
- `falukantUpdateStatus`
|
|
|
|
### 3.2 `falukantUpdateChurch`
|
|
|
|
- `applications`: Spieler ist kirchlicher Vorgesetzter; offene Bewerbungen warten
|
|
- `npc_decision`: NPC-Vorgesetzter hat entschieden
|
|
- `appointment`: automatische Annahme älterer Bewerbung
|
|
- `vacancy_fill`: Interimsbesetzung
|
|
- `promotion`: reserviert / zukünftig
|
|
|
|
### 3.3 `falukantUpdateProductionCertificate`
|
|
|
|
- `daily_recalculation`: Zertifikat nach täglicher Prüfung geändert
|
|
|
|
### 3.4 `falukantUpdateDebt`
|
|
|
|
- `delinquency`: Mahnstufe oder Verzug aktualisiert
|
|
- `debtors_prison_entered`: Eintritt in den Schuldturm
|
|
- `asset_seizure`: Geld, Waren oder sonstige Vermögenswerte eingezogen
|
|
- `vehicle_liquidation`: Fahrzeuge zwangsverkauft
|
|
- `house_seizure`: Haus gepfändet
|
|
- `branch_closure`: Niederlassung geschlossen
|
|
- `debtors_prison_released`: Freilassung
|
|
|
|
## 4. Empfohlene Handler-Logik
|
|
|
|
```text
|
|
onMessage(json):
|
|
if json.user_id exists and json.user_id != currentUserId:
|
|
return
|
|
|
|
switch json.event:
|
|
case "falukantUpdateStatus":
|
|
refreshPlayerStatus()
|
|
return
|
|
|
|
case "falukantUpdateProductionCertificate":
|
|
refreshProductsAndProductionUi()
|
|
return
|
|
|
|
case "children_update":
|
|
refreshChildrenAndFamilyView()
|
|
return
|
|
|
|
case "falukantUpdateChurch":
|
|
refreshChurchContextByReason(json.reason)
|
|
return
|
|
|
|
case "falukantUpdateDebt":
|
|
refreshDebtAndAffectedViews(json.reason)
|
|
return
|
|
|
|
case "falukantUpdateFamily":
|
|
switch json.reason:
|
|
case "daily":
|
|
refreshFamilyAndRelationships()
|
|
refreshReputationIfNeeded()
|
|
break
|
|
case "monthly":
|
|
refreshMoney()
|
|
refreshFamilyAndRelationships()
|
|
break
|
|
case "lover_installment":
|
|
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
|
|
|
|
Ein Nutzer kann kurz hintereinander mehrere relevante Events erhalten, zum Beispiel:
|
|
|
|
- `scandal`
|
|
- danach `daily`
|
|
- danach `falukantUpdateStatus`
|
|
|
|
oder:
|
|
|
|
- `falukantUpdateDebt`
|
|
- direkt danach `falukantUpdateStatus`
|
|
- zusätzlich `falukantUpdateFamily`
|
|
|
|
Die UI sollte deshalb:
|
|
|
|
- Refreshes bündeln oder entprellen
|
|
- idempotente Reloads verwenden
|
|
- nicht davon ausgehen, dass jeder fachliche Effekt einen eigenen Spezial-Eventpfad 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: "lover_installment"` | Geld plus Family-Daten 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 |
|
|
| `falukantUpdateChurch` | Kirchenämter, Bewerbungen, freie Positionen je nach `reason` |
|
|
| `falukantUpdateProductionCertificate` | User-Status, Zertifikat, Produkte, Produktions-UI |
|
|
| `falukantUpdateDebt` | Bank, Overview, House, Branch, ggf. Family |
|
|
|
|
## 7. Sonderfälle
|
|
|
|
| Fall | Verhalten |
|
|
|------|-----------|
|
|
| NPC ohne `user_id` | Keine nutzerbezogenen Socket-Events |
|
|
| Mehrere Events kurz hintereinander | Normal; UI sollte damit robust umgehen |
|
|
| Nur `falukantUpdateStatus` ohne Fach-Event | Kann von anderen Falukant-Workern kommen |
|