yourpart3/docs/FALUKANT_CHURCH_ADVANCEMENT_DAEMON_SPEC.md

Falukant: Kirchenämter, Aufstieg und NPC-Besetzung

Dieses Dokument beschreibt das Zielmodell für das Kirchensystem in Falukant. Es fokussiert auf drei Probleme:

• Spieler können sich derzeit nicht sinnvoll auf höhere kirchliche Ämter bewerben.
• Nicht alle Ämter werden besetzt.
• NPCs sollen sich ebenfalls bewerben und Ämter aktiv besetzen.

Der Daemon soll die laufende Besetzung und Beförderung übernehmen. Der eigentliche Antrag des Spielers bleibt ein aktiver Spielzug in der UI.

1. Zielbild

Kirchliche Ämter sollen ein lebendes Hierarchiesystem sein:

• Leere Ämter werden nach und nach besetzt.
• Spieler und NPCs konkurrieren um offene Positionen.
• Höhere Amtsträger entscheiden über untere Ebenen.
• Wo kein Spieler-Entscheider vorhanden ist, übernimmt ein NPC-Amtsträger die Entscheidung.
• Wo ganze Hierarchieebenen leer sind, darf das System kontrolliert von unten nach oben oder über Interimslogik nachbesetzen.

2. Grundregeln

2.1 Bewerbung

• Ein Spieler beantragt ein Amt weiterhin aktiv über die UI.
• NPCs bewerben sich nicht per UI, sondern durch den Daemon.
• Es darf gleichzeitig mehrere Bewerber für dieselbe Position geben.
• Eine Bewerbung ist immer regionsbezogen.

2.2 Hierarchie

Kirchenämter bleiben über church_office_type.hierarchy_level geordnet.

Der normale Aufstiegspfad ist:

1. lay-preacher
2. village-priest
3. parish-priest
4. dean
5. archdeacon
6. bishop
7. archbishop
8. cardinal
9. pope

2.3 Bewerbung auf höhere Ämter

Der aktuelle Fehler "man kann sich nicht auf höhere Positionen bewerben als man gerade hat" soll ersetzt werden durch:

• Ein Charakter darf sich auf das nächsthöhere sinnvolle Amt bewerben.
• Zusätzlich darf ein Charakter sich auf ein höheres Amt bewerben, wenn sein bisher höchstes Kirchenamt die Mindestvoraussetzung erfüllt.
• Das System soll nicht nur aktuelle Ämter, sondern auch die bisher höchste kirchliche Laufbahn berücksichtigen.

Daraus folgt:

• Es reicht nicht, nur aktuelle church_office zu prüfen.
• Es muss ein Konzept von highestChurchOfficeRankEver geben.

3. Entscheidungsmodell für Bewerbungen

3.1 Grundsatz

Über eine Bewerbung entscheidet immer das direkt übergeordnete Amt.

Beispiele:

• Über village-priest entscheidet parish-priest.
• Über parish-priest entscheidet dean.
• Über dean entscheidet archdeacon.

3.2 Wenn der direkte Vorgesetzte fehlt

Falls das direkt übergeordnete Amt in der relevanten Aufsichtskette nicht besetzt ist:

• Das System sucht das nächsthöhere besetzte Amt.
• Falls überhaupt kein höheres Amt vorhanden ist, greift ein Interimsmodus.

Interimsmodus:

• Für die untersten Ebenen darf der Daemon nach Reputation und Eignung direkt besetzen.
• Für hohe Ämter oberhalb von bishop soll das nur sehr zurückhaltend geschehen.

4. NPC-Bewerbungen

4.1 Ziel

NPCs sollen das Kirchensystem lebendig halten und offene Ämter nach und nach füllen.

4.2 Wann NPCs sich bewerben

Der Daemon prüft täglich:

• offene Sitze pro Region und Amt
• vorhandene Spielerbewerbungen
• vorhandene NPC-Kandidaten

NPC-Bewerbungen entstehen bevorzugt wenn:

• ein Amt offen ist
• keine ausreichende Zahl an Bewerbungen existiert
• in der Region oder der Elternregion geeignete NPCs vorhanden sind

4.3 Geeignete NPCs

Ein NPC ist grundsätzlich geeignet, wenn:

• er lebt
• er nicht bereits ein gleiches oder höheres unvereinbares Kirchenamt innehat
• sein bisher höchstes Kirchenamt oder seine bisherige Laufbahn die Stufe plausibel macht
• seine Reputation ausreichend ist

Zusätzliche Faktoren für NPC-Eignung:

• Alter
• Gesundheit
• Adelstitel
• Reputation
• bestehendes Kirchenamt
• bisher höchstes Kirchenamt

5. Auswahl- und Beförderungslogik

5.1 Bewertungswert

Für jede Bewerbung wird ein Score berechnet:

churchCandidateScore

Bestandteile:

• bisher höchstes Kirchenamt
• aktuelles Kirchenamt
• Reputation
• Adelstitel
• Alter in idealem Bereich
• regionale Nähe
• ggf. geringe Bonuspunkte für lange Wartezeit

5.2 Entscheidung durch Spieler

Wenn der zuständige Vorgesetzte ein Spielercharakter ist:

• Die Bewerbung erscheint wie bisher in der UI.
• Der Spieler kann annehmen oder ablehnen.
• Solange eine Spielerentscheidung aussteht, entscheidet der Daemon nicht automatisch.

Optionaler Timeout:

• Nach längerer Untätigkeit darf später ein automatischer Verfall oder eine automatische Daemon-Entscheidung ergänzt werden.
• Das ist nicht Teil der ersten Ausbaustufe.

5.3 Entscheidung durch NPC

Wenn der zuständige Vorgesetzte ein NPC ist:

• Der Daemon entscheidet automatisch.
• Maßgeblich ist primär der Bewerber-Score.
• Zusätzlich wirkt die Reputation des NPC-Vorgesetzten als "Strengefaktor".

6. Reputation des NPC-Vorgesetzten

Wenn ein NPC ein Amt innehat, entscheidet er über die unter ihm liegende Position anhand von Reputation.

Das bedeutet:

• Ein angesehener NPC-Vorgesetzter bevorzugt reputationsstarke, standesgemäße und stabile Bewerber.
• Ein schwacher oder verrufener NPC-Vorgesetzter entscheidet unberechenbarer.

Empfohlenes Modell:

• supervisorInfluence = supervisor.reputation / 100
• je höher dieser Wert, desto stärker zählt der objektive Bewerber-Score
• bei niedriger Reputation steigt der Zufallsanteil

Praktische Wirkung:

• Hohe NPC-Reputation:
  • bessere, berechenbarere Besetzung
• Niedrige NPC-Reputation:
  • mehr Fehlbesetzungen
  • mehr schwankende Entscheidungen

7. Fehlende historische Kirchenlaufbahn

Damit ein Charakter sich später auf höhere Ämter bewerben kann, braucht das System mehr als nur aktuelle church_office.

Es wird deshalb ein persistierter Höchstwert benötigt:

• highestChurchOfficeRankEver

Empfehlung:

• eigener Wert am Charakter oder in einer Laufbahntabelle
• beim erstmaligen Erreichen eines höheren Kirchenamts aktualisieren
• bei Verlust des Amts nicht zurücksetzen

Ohne diesen Wert bleibt höherer Aufstieg nach Amtsverlust oder Umstrukturierung unzuverlässig.

8. Verfügbarkeit in der UI

Die UI soll später drei Dinge klar darstellen:

• aktuelle Ämter
• verfügbare Bewerbungen
• eigene höchste Kirchenlaufbahn

Zusätzlich sinnvoll:

• ob die Entscheidung durch einen Spieler oder NPC getroffen wird
• wer der zuständige Vorgesetzte ist
• ob eine Position automatisch nachbesetzt wird

9. Daemon-Aufgaben

Der Daemon soll täglich folgende Schritte ausführen:

9.1 Kirchenlage erfassen

• offene Sitze je church_office_type und Region zählen
• aktuelle Amtsträger laden
• Spielerbewerbungen laden
• NPC-Kandidaten bestimmen

9.2 NPC-Bewerbungen erzeugen

• für vakante Positionen fehlende NPC-Bewerbungen anlegen
• keine Doppelbewerbungen für dieselbe Position erzeugen

9.3 Bewerbungen bewerten

• Bewerber-Score berechnen
• zuständigen Vorgesetzten ermitteln
• falls NPC-Vorgesetzter: Entscheidung automatisch treffen
• falls Spieler-Vorgesetzter: Bewerbung offen lassen

9.4 Beförderungen und Besetzungen durchführen

• church_office anlegen oder aktualisieren
• alte widersprechende Bewerbungen schließen
• highestChurchOfficeRankEver aktualisieren

9.5 Sonderfall komplett leere Hierarchie

Wenn eine Hierarchiestufe samt Vorgesetzten fehlt:

• untere Ebene darf durch den Daemon interimistisch mit dem besten Kandidaten besetzt werden
• dies soll selten und regelgeleitet geschehen
• für hohe Spitzenämter deutlich restriktiver als für niedrige Ämter

10. Event-Kommunikation zwischen Daemon und UI

Neue oder präzisierte Events:

10.1 falukantUpdateChurch

{
  "event": "falukantUpdateChurch",
  "user_id": 123,
  "reason": "applications"
}

Zulässige reason-Werte:

• applications
• appointment
• promotion
• vacancy_fill
• npc_decision

10.2 UI-Reaktion

• applications:
  • Bewerbungslisten neu laden
• appointment:
  • aktuelle Ämter und verfügbare Ämter neu laden
• promotion:
  • aktuelle Ämter, verfügbare Ämter, ggf. Sozialstatus/Ansehen neu laden
• vacancy_fill:
  • aktuelle Ämter und verfügbare Positionen neu laden
• npc_decision:
  • supervised applications und current positions neu laden

Zusätzlich kann weiterhin falukantUpdateStatus gesendet werden.

11. Backend-Anpassungen außerhalb des Daemons

Die Daemon-Logik allein reicht nicht. Das Backend muss angepasst werden:

• getAvailableChurchPositions() darf nicht nur aktuelle Ämter als Voraussetzung ansehen
• es muss die bisher höchste Kirchenlaufbahn berücksichtigen
• freie Positionen dürfen nicht nur an schon exakt lineare Amtshalter gebunden sein
• Spielerbewerbungen und NPC-Bewerbungen müssen dieselbe Bewertungslogik unterstützen

12. Empfohlene Umsetzung in Phasen

Phase C1

• Konzept highestChurchOfficeRankEver einführen
• getAvailableChurchPositions() auf höchste Kirchenlaufbahn erweitern
• UI lesbar machen

Phase C2

• NPC-Bewerbungen im Daemon
• automatische NPC-Entscheidungen

Phase C3

• Interimsbesetzung für leere Hierarchien
• Feintuning von Reputation und Zufall

13. Wichtige Designentscheidungen

• Spieleraufstieg bleibt antragsbasiert
• NPCs füllen das System aktiv auf
• hohe Reputation eines NPC-Vorgesetzten verbessert die Besetzungsqualität
• höhere Ämter sollen auch dann erreichbar bleiben, wenn der Charakter das Voramt nicht mehr aktuell innehat
• komplett leere Kirchenstrukturen dürfen sich wieder aufbauen

14. Offene Punkte

• Wo genau highestChurchOfficeRankEver gespeichert wird
• ob es zusätzlich highestChurchOfficeTypeEver geben soll
• ob automatische NPC-Entscheidungen ein Timeout für offene Spielerbewerbungen bekommen
• wie stark Reputation gegenüber Adelstitel und Alter gewichtet wird