👋Willkommen beim DonationTrain

Der DonationTrain ist ein privates Hobbyprojekt, das ich in meiner Freizeit entwickle und pflege.
Es handelt sich nicht um ein gewerbliches Angebot, sondern um ein freiwillig nutzbares System, das ich der Community zur Verfügung stelle.

Warum ein „Unkostenbeitrag“?

Um die laufenden Kosten wie

• Server- und Hostinggebühren

• Wartung, Updates und Weiterentwicklung

• Test- und Entwicklungsumgebung

zumindest ein Stück weit aufzufangen, biete ich dir die Möglichkeit, mich mit einem freiwilligen Unkostenbeitrag von 5 € im Monat zu unterstützen.

Das ist ausdrücklich kein Abonnement und auch keine vertragliche Gegenleistung, sondern eine Form von Wertschätzung für die investierte Zeit und Arbeit.

Wichtige Hinweise

• 🔹 Es besteht kein Anspruch auf eine Leistung im rechtlichen Sinne.

• 🔹 Es kann keine Rechnung ausgestellt werden.

• 🔹 Es fällt keine Umsatzsteuer an und es besteht keine Gewerbeanmeldung, da es sich um eine nicht-gewerbliche, private Tätigkeit handelt.

Wenn du den DonationTrain gerne nutzt und meine Arbeit unterstützen möchtest, freue ich mich über deinen Beitrag – er hilft mir, das Projekt dauerhaft am Laufen zu halten und weiterzuentwickeln.

Testzugang

Wenn du dir das Verwaltungsmenü vom DonationTrain einmal in Ruhe ansehen möchtest, kannst Du dich hier mit einem Demo-Account anmelden. Nach dem Login werden dir die Einstellungsmöglichkeiten (Testversion) angezeigt.

Demo-Login:
Benutzername: Demo-User
Passwort: Demo-User

Wichtig: Der Demo-Account hat nur Leserechte. Du kannst keine Einstellungen speichern, nichts ausführen und keine Kontodaten ändern (z.B. Profil/Passwort/E-Mail). Alle angezeigten Werte dienen ausschließlich der Ansicht einer Testkonfiguration.

🚆 DonationTrain – der Spendenzug im Stream

Der DonationTrain ist ein eigenständiges Modul für deinen Stream, das Spenden zu einem gemeinsamen Event macht.  
Sobald genug unterschiedliche Personen in kurzer Zeit spenden, startet ein mehrstufiger „Zug“ mit Leveln, Fortschrittsbalken und Timer. Alles läuft unabhängig von Twitch – die Spenden gehen direkt über deine Spendenplattform(en) an dich.

🛤️ Wie startet der DonationTrain?

Der Train startet automatisch, wenn zwei Bedingungen gleichzeitig erfüllt sind:

1. Mindestens 3 unterschiedliche Spender
2. 3 Spenden innerhalb eines gemeinsamen Zeitfensters

Technisch läuft es so:

- Jede Spende eines neuen Namens wird in einem **Gleitfenster von X Minuten** gespeichert (Wert aus `minutesPerPerson` in `donationTrainConfig.json`).  
- Innerhalb dieses Fensters werden die Beträge aufsummiert.   
- Sobald wir 3 Spender, mit verschiedenen Namen haben, startet der Train automatisch.

Damit der Start absehbar ist, gibt es eine **Pre-Start-Phase**:  
Sobald **2 von 3** benötigten Spendern im Fenster sind, wird – sofern aktiviert – das **HinweisTrain-Overlay** eingeblendet und zeigt: „Es fehlt nur noch ein Ticket, bis der Zug startet“.

🚀 Was passiert, wenn der Zug läuft?

Beim Start wird das Haupt-Overlay (z. B. `DonationTrain`-Widget) eingeblendet.   

- Der Train beginnt auf **Level 1**.
- Jedes Level hat ein eigenes **Punktziel**.
- Spenden werden in Punkte umgerechnet:  
  `Punkte = Euro × pointsPerEuro`  
  (z. B. 1 € = 100 Punkte, je nach Konfiguration).
- Wird das Punkteziel erreicht, springt der Train ins nächste Level.

Wichtig:  
Der Fortschrittsbalken zeigt **immer den Fortschritt innerhalb des aktuellen Levels**, nicht die Gesamtpunkte über alle Level. Beim Levelaufstieg startet der Balken wieder bei 0 %.   

🔁 Level-System im Überblick

Die wesentlichen Parameter werden in `config/donationTrainConfig.json` eingestellt:   

- `startGoal`  
  Punkteziel für **Level 1** (z. B. 1000 Punkte).
- `goalGrowthPercent`  
  Prozentsatz, um den das Levelziel pro Level wächst (z. B. 30 % → jedes Level braucht 30 % mehr Punkte als das vorherige).
- `maxLevel`  
  Obergrenze der Level, die in einem Lauf erreicht werden können.
- `secondsPerLevel`  
  Zeit in Sekunden, die für ein Level zur Verfügung steht.

Ablauf im Level:

- Zu Beginn eines Levels wird die **volle Levelzeit** gesetzt.
- Jede **gültige Spende** setzt den Timer des aktuellen Levels wieder auf die volle Zeit zurück.
- Läuft der Timer auf 0 und das Levelziel wurde **nicht** erreicht, endet der Train.

🎖️ Was ist im Overlay zu sehen?

Das Haupt-Overlay arbeitet mit der Datei `overlay/hypeOverlay.json` und enthält u. a.:   

- Aktueller Zustand (`active` / inaktiv)
- Aktuelles Level
- **Punkte im aktuellen Level** (`progress`) und Ziel (`goal`)
- Gesamtpunkte über den gesamten Lauf (`totalPoints`)
- Restzeit in Sekunden (`timeRemaining`)
- Liste der Spender (`donators`) und Top-Beiträge (`topContributions`)
- Optional: Letzter Spender mit Betrag (`lastContribution`), falls `showLastDonator` in der Config aktiviert ist.   

Zusätzlich gibt es – falls konfiguriert – ein **separates Hinweis-Overlay** (z. B. Widget `HinweisTrain`), das während der Pre-Start-Phase eingeblendet wird und die fast erreichte Startbedingung signalisiert.

❄️ Cooldown nach dem Zug

Nach dem Ende eines DonationTrain läuft ein **globaler Cooldown**, bevor ein neuer Zug wieder starten kann:

- Dauer in Minuten: `cooldownMinutes` in `donationTrainConfig.json`  
- Während des Cooldowns wird kein Pre-Start und kein neuer Zug gestartet.
- Der Befehl `!donocooldownreset` erlaubt es Mods/Streamer, diesen Cooldown manuell zu löschen.

Der aktuelle Status (aktiv / Cooldown / bereit) kann jederzeit per `!donotrain` oder `!donationtrain` abgefragt werden.

💡 Unterstützte Spendenquellen

Der DonationTrain wertet **Chat-Nachrichten** aus und erkennt Spenden anhand von Mustern aus der Datei `config/donationTrigger.json`.   

Standardmäßig sind u. a. vorbereitet:

- StreamElements
- Ko-fi
- Weitere Bots / Plattformen, die du selbst mit einem passenden Beispieltext einträgst

Solange eine Plattform ihre Spendenmeldung als Chat-Nachricht in deinem Kanal ausgibt, kann sie über `donationTrigger.json` eingebunden werden – unabhängig davon, ob es ein klassischer Alert-Bot oder ein eigener Account ist.

💡 Warum dieser Train?

Der DonationTrain macht aus Einzelspenden ein gemeinsames Event:

- Zuschauer sehen direkt, wie weit der Zug schon gekommen ist.
- Jeder Beitrag wirkt sich sichtbar auf Level, Balken und Timer aus.
- Der gesamte Ablauf ist **dateibasiert, konfigurierbar und unabhängig** vom restlichen Bot – ideal, um ihn getrennt zu betreiben oder anderen zur Verfügung zu stellen.