neural-hunt/V4.5_PLACE_REWARD_ECONOMY.md

V4.5 — Place Reward Economy

V4.5 erweitert die Neural-Place-Ökonomie um zusätzliche Spielanreize zwischen seltenen Score-Fortschritten. Ein Pixel besitzt weiterhin keinen Zeit-Cooldown; stattdessen können mehrere nachvollziehbare Hunt-Ereignisse Place-Punkte erzeugen.

Reward-Quellen

1. Score-Fortschritt

Unverändert erzeugt jede dauerhaft gespeicherte persönliche Best-Score-Steigerung Place-Punkte. Standard:

DEFAULT_PLACE_POINTS_PER_SCORE=100

+1,00 Score-Prozentpunkte ergeben damit 100 Place-Punkte.

2. Tipp wird tatsächlich gezogen

Wenn die Guess-Lotterie aktiv ist und ein gültiger Tipp am Fensterende wirklich ausgewählt wird, erhält der Spieler unabhängig davon, ob der Tipp anschließend den persönlichen Highscore verbessert, einen Draw-Bonus.

Standard:

DEFAULT_PLACE_DRAW_POINTS=25
DEFAULT_PLACE_DRAW_BEACON_MULTIPLIER=1

Bei normaler Lotterie beträgt der Reward damit 25 Punkte. Im Beacon-Hunt-Modus verwendet V4.5 auf Wunsch dasselbe effektive Pfadgewicht wie die gewichtete Ziehung. Beispiel bei DEFAULT_BEACON_BONUS_WEIGHT=2:

• gewählter Pfad ist nicht der Boost-Pfad → 25 × 1 = 25 Punkte,
• gewählter Pfad ist der Boost-Pfad → 25 × 2 = 50 Punkte.

DEFAULT_PLACE_DRAW_BEACON_MULTIPLIER=0 deaktiviert ausschließlich diese Multiplikation. DEFAULT_PLACE_DRAW_POINTS=0 deaktiviert Draw-Rewards vollständig.

Draw-Rewards sind über Task + Task-Revision + Client/Worker + Sequenz idempotent. Ein Retry kann daher denselben gezogenen Tipp nicht doppelt vergüten; nach einem Task-Reroll mit zurückgesetzter Sequenz bleibt die neue Revision davon unabhängig.

3. Investierte aktive Hunt-Zeit

Gültige, signierte Hunt-Aktivität mit aktiver Presence baut Spielzeit auf. Standard:

DEFAULT_PLACE_TIME_POINTS=20
DEFAULT_PLACE_TIME_INTERVAL_SEC=60
DEFAULT_PLACE_TIME_MAX_GAP_SEC=120

Damit entstehen alle 60 Sekunden aktiver Teilnahme 20 Punkte. Bei Pixelkosten von 100 Punkten kann ein dauerhaft aktiver Spieler allein über Zeit nach ungefähr fünf Minuten einen Pixel finanzieren; Score- und Draw-Rewards kommen zusätzlich dazu.

Die Zeit wird nicht durch einen bloß geöffneten Browser-Tab erzeugt. Gezählt wird nur die Zeit zwischen aufeinanderfolgenden gültigen, signierten Hunt-Requests. Ist die Lücke größer als DEFAULT_PLACE_TIME_MAX_GAP_SEC, wird diese Pause nicht angerechnet. Bereits zuvor tatsächlich investierte Restzeit bleibt erhalten, Offline-Zeit wird aber niemals nachträglich aufgefüllt.

DEFAULT_PLACE_TIME_POINTS=0 deaktiviert Zeit-Rewards.

Hosted Worker

Für Score-, Draw- und Zeit-Rewards gilt dieselbe identity_delegations-Logik. Ist die auslösende Identität ein verknüpfter Hosted Worker, landet die Gutschrift im Wallet des Owners. Die Worker-ID bleibt im Audit als Quelle sichtbar.

Damit können Browser, CLI und mehrere Worker dasselbe Place-Wallet aufbauen, ohne Identitäten zusammenzulegen.

Admin-Gutschriften

Unter Admin → RUNTIME → PLACE-PUNKTE MANUELL VERGEBEN kann ein Admin jetzt:

• eine vorhandene Client- oder Worker-ID auswählen,
• eine positive Punktmenge bis auf 0,001 Punkte genau eingeben,
• optional einen Grund / eine Support-Notiz hinterlegen,
• die Gutschrift sofort ausführen.

Wird eine Worker-ID angegeben, wird auch eine manuelle Gutschrift konsistent auf das Owner-Wallet geroutet.

Die letzten Draw-, Aktivzeit- und Admin-Bonusereignisse werden direkt im Admin-Portal angezeigt.

Audit und Persistenz

Neu ist place_bonus_events als unveränderliches Audit für draw, time und admin, inklusive Quelle, Owner, Punkte, Multiplikator, Einheiten und Detailtext. Das bestehende place_progress_events bleibt für exakte Score-Deltas bestehen. Das Spieler-Wallet führt beide Audit-Quellen chronologisch in recent_earnings zusammen.

Die noch nicht ausgezahlte Restzeit der aktiven Zeitmessung wird absichtlich nur im Serverprozess gehalten, damit gewöhnliche gültige Hunt-Requests ohne fälliges Zeitintervall keinen zusätzlichen SQLite-Write verursachen. Bei einem Server-Neustart kann dadurch höchstens das aktuell noch unvollständige Zeitintervall verloren gehen; bereits ausgezahlte Zeitpunkte und deren Audit-Ereignisse bleiben dauerhaft in SQLite erhalten.

Admin-API

Zusätzlich stehen im privaten Control Plane zur Verfügung:

GET  /api/admin/place/earnings?limit=50&client_id=<optional>
POST /api/admin/place/points

Beispiel für eine manuelle Gutschrift:

{
  "target_client_id": "<client-or-worker-id>",
  "points": 100,
  "reason": "Event-Bonus"
}

Runtime-Konfiguration

Alle relevanten Werte sind unter Admin → RUNTIME änderbar:

place_points_per_score
place_draw_points
place_draw_beacon_multiplier
place_time_points
place_time_interval_sec
place_time_max_gap_sec
place_pixel_cost

Zusammen mit beacon_bonus_weight lässt sich damit genau steuern, wie schnell sich ein Pixel über Fortschritt, gezogene Tipps und investierte Zeit erspielen lässt.