Adventure Builder Pro

Was ist Adventure Builder Pro?

Adventure Builder Pro ist ein Werkzeug für alle, die Text-Adventure-Spiele erstellen möchten – ohne Programmieren zu müssen. Du gestaltest alles im Browser: Orte, Gegenstände, Charaktere, Rätsel und Geschichte. Das Ergebnis ist eine JSON-Datei, die du mit dem Player spielen kannst.

Der Arbeitsablauf

Die Editor-Tabs auf einen Blick

Neue Editor-Features

Minimalstruktur eines Spiels (JSON)

Jedes Spiel besteht im Kern aus diesen Bausteinen:

{
 "title": "Mein Abenteuer",
 "author": "Dein Name",
 "startLocation": "ort_id", // Startort des Spielers
 "defaultTheme": "modern", // Visuelles Thema
 "locations": {}, // Alle Orte
 "items": {}, // Alle Gegenstände
 "npcs": {}, // Alle Charaktere
 "recipes": [], // Kombinierrezepte
 "flags": {}, // Spielzustände
 "sounds": {}, // 🔊 Sound-Bibliothek (optional)
 "gameEnds": { "win": [], "lose": [] },
 "cutscenes": {}, // Story-Sequenzen
 "displaySettings": {} // Layout-Einstellungen
}

Ort-Eigenschaften

{
 "ort_id": {
 "name": "Dunkler Keller",
 "description": "Es riecht modrig hier unten.",
 "image": "https://...", // Bild oder Video (WebM/MP4)
 "imageLoop": true, // Video wiederholen?
 "sound": "data:audio/...", // Hintergrundmusik
 "soundLoop": true,
 "silence": false, // Alle Sounds stummschalten
 "theme": "dark", // Ort-spezifisches Theme
 "exitTransition": "fade", // Übergangseffekt beim Verlassen
 "exits": {},
 "objects": [],
 "npcs": [],
 "conditionalNpcs": [],
 "playCutscene": "keller_intro", // Cutscene beim Betreten
 "playCutsceneOnce": true
 }
}

HTML in Beschreibungen verwenden

Orts- und Objekt-Beschreibungen werden im Grafik- und Parser-Modus als HTML dargestellt. Du kannst sie also mit einfachen HTML-Tags formatieren – fett, kursiv, farbig, mit Zeilenumbrüchen und mehr. Es gibt keine feste Liste erlaubter Tags; sinnvoll fürs Formatieren sind vor allem diese:

Ausgänge (Exits)

Neu: Überarbeiteter Tab Anzeige v4.4

Der Tab Anzeige ist in 5 thematische Sektionen gegliedert:

• 🎨 Darstellung & Theme – Standard-Theme, Kompakt-Modus, Container-Größe
• 🖼️ Bilder & Thumbnail-Größen – Objekte, NPC Portraits, Modals
• 📦 Objekte & Ausgänge – Ausgänge (Bild/Farbe/Layout), Raum-Layout
• 🎒 Inventar – Thumbnail, Position, Mechanik, Spalten, Button-Modus
• 👁️ Sichtbarkeit & Spielmodi – Text-Anzeige, Parser, Nur-Text, Unterstützung, Ziele

A) Einfache Ausgänge

Richtwörter als Keys oder beliebige Texte – was du schreibst, erscheint als Button.

"exits": {
 "N": "wald_nord", // Standard: N S O W H R
 "Durch die Tür": "raum_2", // Eigener Text möglich
 "Ins Wasser": "see"
}

B) Ausgang mit Flag-Bedingung

Der Ausgang ist nur nutzbar wenn eine bestimmte Flag gesetzt ist.

"exits": {
 "N": {
 "to": "geheimraum",
 "requiredFlag": "tuer_offen",
 "deniedMessage": "Die Tür ist noch verschlossen."
 }
}

C) Ausgang mit Item-Bedingung

Der Spieler muss ein bestimmtes Item im Inventar haben.

"exits": {
 "O": {
 "to": "schatzkammer",
 "requiredItem": "goldener_schluessel",
 "deniedMessage": "Du brauchst den goldenen Schlüssel!"
 }
}

D) Ausgang mit kombinierten Bedingungen

"exits": {
 "Portal": {
 "to": "andere_dimension",
 "requiredFlag": "portal_aktiviert",
 "requiredItem": "magischer_kristall",
 "deniedMessage": "Das Portal reagiert nicht..."
 }
}

// Objekt im Ort: Eisentür
{
 "itemName": "Eisentür",
 "canTake": false,
 "usableWith": [{
 "itemId": "rost_schluessel",
 "success": "Die Tür quietscht auf!",
 "setFlag": "tuer_offen",
 "removeItem": true
 }]
}

// Ausgang des Ortes
"N": {
 "to": "naechster_raum",
 "requiredFlag": "tuer_offen",
 "deniedMessage": "Die Tür ist verschlossen!"
}

E) ODER-Verknüpfung zweier Bedingungen 🆕 v4.5

Sind requiredFlag und requiredItem gesetzt, gilt normalerweise UND (beides nötig). Mit conditionLogic: "OR" genügt eine erfüllte Bedingung – z. B. „Taschenlampe im Inventar oder Strom ist an“.

"Teeküche": {
 "to": "kueche",
 "requiredItem": "Taschenlampe",
 "requiredFlag": "strom_an",
 "conditionLogic": "OR"
}

Objekte im Ort

Objekte sind Dinge, die der Spieler sieht und mit denen er interagieren kann – anfassen, untersuchen, ein Item darauf anwenden.

A) Einfaches nehmbares Objekt

{
 "itemId": "rost_schluessel", // Referenz auf ein definiertes Item
 "canTake": true
}

B) Objekt mit Item-Anwendung (usableWith)

Was passiert, wenn ein Spieler ein bestimmtes Item aus dem Inventar auf dieses Objekt anwendet?

{
 "itemId": "truhe",
 "canTake": false,
 "failMessage": "Das bringt hier nichts.",
 "usableWith": [{
 "itemId": "schluessel",
 "actionLabel": "🔓 Aufschließen",
 "success": "Die Truhe öffnet sich!",
 "changeObject": "offene_truhe", // Objekt wird ersetzt
 "spawnObject": "gold", // Neues Objekt erscheint
 "spawnCanTake": true,
 "removeItem": true, // Schlüssel wird verbraucht
 "setFlag": "truhe_geoeffnet",
 "playCutscene": "truhe_oeffnen"
 }]
}

🔗 spawnObjectId – usableWith aus Item-Definition erben v4.4

Wenn ein gespawntes Objekt sofort interaktiv sein soll, reicht spawnObject allein nicht – das erzeugte Objekt hätte ein leeres usableWith. Mit spawnObjectId verweist die Aktion auf den Item-Eintrag im items{}-Dict, und der Player übernimmt dessen usableWith automatisch.

"usableWith": [{
  "actionLabel": "🔍 Mauer absuchen",
  "requireFlag": "fackel_entzuendet",
  "removeObject": true,
  "spawnObject": "Hebel",
  "spawnObjectId": "hebel",  // ← verknüpft mit items["hebel"]
  "spawnCanTake": false,
  "message": "Du entdeckst einen verborgenen Hebel!"
}]

💡 Der Editor setzt spawnObjectId automatisch wenn du im Spawn-Dropdown ein Item auswählst.

⚠️ spawnObject ohne spawnObjectId – altes Verhalten, weiterhin gültig.

E) Variablen in Objekt-Aktionen

Aktionen können Variablen prüfen (Bedingung) und ändern (Effekt). Der Editor zeigt den blauen 🔢 Variable-Block im Aktions-Modal.

// Kühlschrank: gibt Apfel, kostet 1 Energie
{
 "actionLabel": "Apfel holen",
 "success": "Du nimmst einen Apfel. (-1 Energie)",
 "givesItem": "Apfel",
 "addVar": { "name": "energie", "val": -1 }
}

// Münzbrunnen: braucht min. 1€, kostet 1€, gibt 5 Punkte
{
 "actionLabel": "Wunsch machen (1 €)",
 "requireVar": { "name": "geld", "op": ">=", "val": 1 },
 "success": "Du wirfst eine Münze ins Wasser. +5 Punkte!",
 "varActions": [
 { "name": "geld", "val": -1 },
 { "name": "punkte", "val": 5 }
 ]
}

// Backofen: braucht Energie ≥ 2 + Flag, gibt Kuchen + Punkte
{
 "actionLabel": "🎂 Kuchen backen!",
 "requireFlag": "zutaten_gekauft",
 "requireVar": { "name": "energie", "op": ">=", "val": 2 },
 "success": "Du backst einen Geburtstagskuchen! +50 Punkte!",
 "givesItem": "Geburtstagskuchen",
 "setFlag": "kuchen_gebacken",
 "varActions": [
 { "name": "energie", "val": -2 },
 { "name": "punkte", "val": 50 }
 ]
}

C) Direkte Aktion (ohne Item) Direct Action

Ein Button der immer sichtbar ist – zum Untersuchen, Zählen, Aktivieren.

"usableWith": [{
 "itemName": "", // Leer = kein Item nötig
 "actionLabel": "🔍 Untersuchen",
 "success": "Du findest einen versteckten Hinweis!",
 "spawnObject": "hinweis",
 "spawnCanTake": true
}]

D) Mehrfach-Verwendung (Quantity)

Der Button ist nur eine begrenzte Anzahl von Malen nutzbar.

"usableWith": [{
 "itemName": "",
 "actionLabel": "🍪 Keks nehmen",
 "success": "Lecker! Du nimmst einen Keks.",
 "quantity": 5,
 "quantityMessage": "Die Dose ist leer!",
 "spawnObject": "keks",
 "spawnCanTake": true
}]

E) Bedingte NPCs im Ort

Manche Charaktere erscheinen nur unter bestimmten Bedingungen.

"conditionalNpcs": [
 { "npcId": "geist_id", "requireFlag": "mitternacht" },
 { "npcId": "drache_id", "forbidFlag": "drache_besiegt" }
]

F) Ausgänge erweitern: Bild, Farbe & Layout v4.4

Seit v4.4 können Ausgangs-Buttons optisch aufgewertet werden. Alle Einstellungen im Editor unter Tab Anzeige → 🚪 Ausgänge.

🖼️ Bild für einen Ausgang

Im Ausgang-Modal (Ort bearbeiten → Ausgang ✏️) kannst du ein Bild hochladen. Das Bild bestimmt dann die Größe des Buttons – der Text erscheint darunter oder daneben.

"exits": {
  "N": {
    "to": "dunkler_gang",
    "image": "data:image/png;base64,..."
  }
}

🎨 Ausgangs-Farbe (global)

Im Tab Anzeige → 🚪 Ausgänge → Button-Farbe kannst du eine CSS-Farbe eingeben, die alle Ausgangs-Buttons überschreibt. Leer = Theme-Farbe.

"displaySettings": {
  "exitButtonColor": "#1e1f1e",
  "exitButtonStyle": "compact",
  "exitLayout": "horizontal",
  "thumbSizeExits": 80
}

🔐 Bedingter Ausgang: Item im Inventar

Das requiredItem-Feld prüft den Anzeigenamen des Items. Im Editor gibt es ein Dropdown mit allen vorhandenen Item-Namen.

"N": {
  "to": "dunkler_gang",
  "requiredItem": "Fackel",
  "deniedMessage": "Es ist zu dunkel ohne Licht."
}

💡 requiredItem enthält den Anzeigenamen, nicht die interne ID.

Items definieren

Alle Items werden zentral im Tab 📦 Objekte angelegt. Jedes Item bekommt eine eindeutige ID – so kann es überall im Spiel referenziert werden, ohne dass das Spiel kaputt geht wenn du den Namen änderst.

"items": {
 "goldener_schluessel": {
 "id": "goldener_schluessel",
 "name": "🔑 Goldener Schlüssel",
 "description": "Ein prächtiger Schlüssel aus purem Gold.",
 "image": "data:image/png;base64,...", // auch WebM/MP4 möglich
 "sfx": "snd_1234_abc" // 🔊 Sound-ID aus der Bibliothek – spielt beim Aufnehmen
 }
}

Selbst-Verwendung (selfUse)

Was passiert, wenn der Spieler ein Item direkt im Inventar benutzt? Es gibt zwei Felder: selfUse: true macht das Item benutzbar, onUse definiert was passiert. Im Player zeigt jedes benutzbare Item dann automatisch einen grünen ▶️-Knopf direkt im Inventar (neben dem ℹ️-Knopf) – ein Klick benutzt es sofort. Items ohne selfUse zeigen den Knopf nicht.

// Beispiel 1: Heiltrank (HP)
"heiltrank": {
 "name": "💊 Heiltrank",
 "selfUse": true,
 "onUse": {
 "message": "Du trinkst den Heiltrank. +20 HP!",
 "healHP": 20,
 "removeItem": true
 }
}

// Beispiel 2: Apfel gibt +4 Energie (Variable)
"apfel": {
 "name": "🍎 Apfel",
 "selfUse": true,
 "onUse": {
 "message": "Mmm, lecker! +4 Energie!",
 "removeItem": true,
 "varActions": [{ "name": "energie", "val": 4 }]
 }
}

// Beispiel 3: Zaubertrank – HP und Energie gleichzeitig
"zaubertrank": {
 "name": "✨ Zaubertrank",
 "selfUse": true,
 "onUse": {
 "message": "Du trinkst den Trank. +10 HP, +5 Energie!",
 "healHP": 10,
 "removeItem": true,
 "varActions": [{ "name": "energie", "val": 5 }]
 }
}

Item-Obergrenze & nicht ablegbare Items

Zwei optionale Item-Felder steuern, wie viele Exemplare existieren dürfen und ob sich ein Item ablegen lässt.

Maximale Anzahl (maxCount)

maxCount begrenzt, wie viele Exemplare eines Items gleichzeitig in der Welt existieren dürfen (Raum-Objekte + Inventar zusammengezählt). Besonders nützlich bei Items, die per spawnObject erzeugt oder per Rezept gecraftet werden – so entstehen nie versehentlich zwei.

"tasse_wasser": {
"name": "Tasse mit heißem Wasser",
"maxCount": 1
}

Nicht ablegbar (noDrop)

noDrop: true verhindert, dass der Spieler ein Item fallen lässt – auch der Textbefehl LEGE AB wird abgewiesen (v4.5). Über noDropMessage steuerst du das Verhalten: Mit Meldung bleibt der 🗑️-Knopf sichtbar und antwortet beim Klick im LucasArts-Stil („Das behalte ich lieber…“); ohne Meldung wird der 🗑️-Knopf komplett ausgeblendet. So verhinderst du Sierra-Sackgassen, ohne auf Charaktermomente zu verzichten.

"amulett": {
"name": "🔮 Verfluchtes Amulett",
"noDrop": true,
"noDropMessage": "Das Amulett klebt wie festgewachsen an dir – du wirst es nicht mehr los."
}

Start-Inventar (🎒) 🆕 v4.5

Items mit "startInventory": true liegen ab Spielbeginn im Inventar des Spielers.

"programmheft": {
 "name": "Programmheft",
 "startInventory": true
}

Inventar-Freischaltung

Normalerweise ist das Inventar von Anfang an sichtbar. Mit dieser Mechanik bleibt es versteckt, bis der Spieler ein bestimmtes Objekt aufnimmt – eine Tasche, einen Rucksack, eine magische Truhe.

Basis-Definition

"haendler": {
 "name": "Alter Händler",
 "dialog": "Willkommen! Was darf es sein?", // Statischer Text
 "portrait": "data:image/png;base64,...", // Bild oder Video
 "portraitSize": "medium", // small/medium/large/full
 "playCutscene": "haendler_intro", // Cutscene VOR Dialog
 "playCutsceneOnce": true,
 "playCutsceneAfter": "haendler_abschied", // Cutscene NACH Dialog
 "givesItems": [],
 "receivesItems": [],
 "dialogTree": {} // Verzweigter Dialog → Kapitel 5
}

NPC gibt Items (givesItems)

Der Spieler erhält beim Gespräch ein oder mehrere Items – kostenlos, ohne Gegenleistung.

"givesItems": [{
 "name": "Heiltrank",
 "description": "Stellt Lebenspunkte wieder her",
 "playCutscene": "trank_geschenk",
 "playCutsceneOnce": true
}]

Bedingte Geschenke 🆕 v4.5

Ein Geschenk kann an Bedingungen geknüpft werden – der 🎁-Knopf erscheint erst, wenn alle gesetzten Bedingungen erfüllt sind:

"givesItems": [{
 "name": "Teebeutel",
 "requireFlag": "strom_an",
 "requireFlagNot": "konzert_gestartet",
 "requireItem": "Ausweis"
}]

NPC nimmt Items (receivesItems – Tausch)

A) Einfacher Tausch

"receivesItems": [{
 "itemId": "altes_schwert",
 "message": "Ein feines Stück! Hier, nimm das dafür.",
 "givesItemId": "neues_schwert",
 "setFlag": "upgrade_erhalten"
}]

B) Tausch mit Bedingungen

"receivesItems": [{
 "itemId": "brief",
 "message": "Danke für die Lieferung!",
 "givesItemId": "belohnung",
 "requireFlag": "quest_aktiv", // Muss gesetzt sein
 "requireFlagNotSet": "brief_abgegeben", // Muss NICHT gesetzt sein
 "failTitle": "❌ Abgelehnt",
 "failMessage": "Das kann ich jetzt nicht annehmen.",
 "setFlag": "brief_abgegeben"
}]

Kampfsystem (HP-basiert)

Wenn ein NPC maxHP gesetzt hat, kann er mit Items angegriffen werden. Der Spieler klickt auf den NPC → wählt ein Waffen-Item → der NPC verliert HP. Bei 0 HP: onDefeat.

"drache": {
 "name": "Roter Drache",
 "maxHP": 100,
 "counterDamage": 15, // Schaden beim Gegenschlag (opt.)
 "usableWith": [{
 "itemName": "Drachenschwert",
 "damage": 25,
 "success": "Du triffst den Drachen!",
 "onDefeat": {
 "message": "Der Drache ist besiegt! 🎉",
 "givesItem": "drachenschuppe",
 "teleportTo": "thronsaal",
 "setFlag": "drache_besiegt",
 "clearFlag": "drache_lebt",
 "playCutscene": "sieg_drache"
 }
 }]
}

Was sind Dialog-Bäume?

Statt einem starren Dialog-Satz kann jeder NPC jetzt einen echten Gesprächsbaum führen. Der Spieler wählt Antworten, die die Geschichte in verschiedene Richtungen lenken. Flags können gesetzt, Items vergeben und Cutscenes ausgelöst werden.

Aufbau: Knoten und Antworten

Ein Dialog-Baum besteht aus Knoten. Jeder Knoten ist ein Gesprächs-Moment. Der Knoten mit der ID start ist immer der Einstieg.

"dialogTree": {
 "start": {
 "npcText": "Was kann ich für dich tun?",
 "choices": [
 {
 "text": "Ich brauche Informationen.",
 "next": "info_knoten"
 },
 {
 "text": "Hier ist der Brief für dich.",
 "next": "brief_uebergeben",
 "requireFlag": "brief_gefunden" // Nur sichtbar wenn Flag gesetzt
 },
 {
 "text": "Auf Wiedersehen!",
 "next": null // null = Gespräch endet
 }
 ]
 },

 "info_knoten": {
 "npcText": "Der Schlüssel liegt im alten Turm!",
 "setFlag": "hinweis_erhalten", // Flag beim Betreten
 "choices": [
 { "text": "Danke!", "next": null }
 ]
 }
}

flagBranch: Automatische Umleitung

Wenn der Spieler denselben NPC nach einem wichtigen Ereignis erneut anspricht, soll dieser anders reagieren. Dafür gibt es flagBranch: Wenn eine Flag gesetzt ist, leitet der Spieler automatisch zu einem anderen Knoten um.

"start": {
 "flagBranch": [
 { "flag": "brummi_zurueck", "goto": "nach_brummi" },
 { "flagNot": "quest_aktiv", "goto": "kein_quest" }
 ],
 "npcText": "Ich fahre nicht ohne Brummi!",
 // Wird nur gezeigt wenn KEIN Branch greift
 ...
},
"nach_brummi": {
 "npcText": "BRUMMI! 🎉 Jetzt bin ich bereit!",
 "choices": [
 { "text": "Na dann – ab ins Kino!", "next": null }
 ]
}

Einrichten im Editor

// Node: Mama gibt Geld beim Betreten des Knotens
"geld_geben": {
 "npcText": "Hier sind 8 €! Kauf Mehl, Zucker und Butter.",
 "setFlag": "geld_bekommen",
 "varActions": [{ "name": "geld", "val": 8 }]
}

// Choice: Backzutaten kaufen – kostet Geld, gibt Punkte
"choices": [{
 "text": "Ich kaufe die Backzutaten (5 €)",
 "next": "kaufen",
 "requireVar": { "name": "geld", "op": ">=", "val": 5 },
 "varActions": [
 { "name": "geld", "val": -5 },
 { "name": "punkte", "val": 10 }
 ]
}]

Was sind Flags?

Eine Flag ist ein einfacher Schalter: entweder ein (true) oder aus (false). Damit kann das Spiel sich merken, was der Spieler schon gemacht hat: eine Tür geöffnet, einen Kampf gewonnen, einen Brief abgegeben.

"flags": {
 "tuer_offen": false,
 "schatz_gefunden": false,
 "quest_aktiv": true // true = Flag startet schon gesetzt
}

Flags setzen und löschen

Flags können an vielen Stellen gesetzt oder gelöscht werden:

Automatische Flags

Flags als Bedingungen verwenden

Fast überall im System kann eine Flag als Bedingung geprüft werden:

Was ist eine Cutscene?

Eine Cutscene ist eine Abfolge von Slides – jede mit einem Bild (oder Video), einem Text und optionaler Musik. Der Spieler klickt sich durch und sieht so eine Geschichte, eine Erklärung oder einen dramatischen Moment.

"cutscenes": {
 "wald_intro": [
 {
 "image": "data:image/png;base64,...",
 "text": "Es war einmal ein dunkler Wald...",
 "bgm": "data:audio/mpeg;base64,...",
 "bgmLoop": true,
 "sfx": "snd_abc123", // 💥 Einmal-Effekt beim Erscheinen
 "theme": "dark",
 "transition": "fade"
 },
 {
 "image": "data:image/png;base64,...",
 "text": "Ein Held betrat ihn..."
 }
 ]
}

10 Trigger – überall einsetzbar

Cutscenes können an 10 verschiedenen Stellen ausgelöst werden. Alle sind vollständig im Editor konfigurierbar:

JSON für Flag-basierten Trigger (Nr. 10)

"cutsceneTriggers": [{
 "requireFlag": "schatz_gefunden",
 "playCutscene": "siegesfeier",
 "playOnce": true
}]

So funktioniert Crafting

Der Spieler wählt im Inventar zwei Items aus und klickt "Kombinieren". Gibt es ein passendes Rezept, verschwinden beide Items und das Ergebnis erscheint. Gibt es keins – passiert nichts.

"recipes": [
 {
 "item1Id": "eimer_wasser", // Item-ID (empfohlen)
 "item2Id": "seife",
 "resultId": "eimer_seifenwasser",
 "message": "Du mischst die Seife ins Wasser – es schäumt!",
 "playCutscene": "misch_animation", // Optional
 "playCutsceneOnce": true,
 "sfx": "snd_1234_abc" // 🔊 Sound aus der Bibliothek (optional)
 }
]

Aufbau einer Endbedingung

Ein Ende besteht aus einer Bedingung (was muss eingetreten sein?) und optional zusätzlichen Bedingungen, einer Cutscene, einem Teleport und der Abschlussmeldung.

"gameEnds": {
 "win": [{
 "type": "flag", // item | flag | location
 "value": "papa_informiert", // ID oder Name je nach Typ
 "requireFlag": "basti_gluecklich", // Zusatzbedingung
 "playCutscene": "fahrt_ins_kino", // Cutscene davor
 "teleportTo": "kino", // Ort nach Cutscene
 "message": {
 "title": "🎬 ZOO VERRÜCKT 3!",
 "message": "Du hast den Samstag gerettet!",
 "buttonText": "🍿 Film ab!"
 }
 }],
 "lose": [{
 "type": "flag",
 "value": "player_dead",
 "message": "Du bist gestorben..."
 }]
}

Alle Felder einer Endbedingung

Reihenfolge der Ereignisse

Tod-Szenarien mit verschiedenen Meldungen

"lose": [
 {
 "type": "flag", "value": "player_dead",
 "requireFlag": "vergiftet",
 "message": "Das Gift war zu stark..."
 },
 {
 "type": "flag", "value": "player_dead",
 "requireFlag": "im_kampf",
 "message": "Du wurdest im Kampf besiegt..."
 },
 {
 "type": "flag", "value": "player_dead",
 "message": "Du bist gestorben." // Fallback
 }
]

Was ist das Aufgaben-System?

Mit dem Aufgaben-System kannst du dem Spieler eine sichtbare Liste von Zielen mit Fortschrittsbalken anzeigen. Jedes Ziel ist an ein Flag gebunden – sobald das Flag im Spielverlauf gesetzt wird, gilt das Ziel als erfüllt und wird visuell abgehakt.

Einrichten im Editor

Tab 🎨 Anzeige → Abschnitt 🎯 Aufgaben / Ziele.

JSON-Struktur

{
 "displaySettings": {
 "goalsEnabled": true,
 "goalsTitle": "🎯 Aufgaben",
 "goalsPosition": "sidebar", // "sidebar" | "accordion" | "modal"
 "goals": [
 {
 "text": "Pizza bestellen",
 "flag": "pizza_bestellt",
 "secret": false
 },
 {
 "text": "Geheimende finden",
 "flag": "geheim_ende",
 "secret": true,
 "secretLabel": "???" // bis Flag erfüllt
 },
 {
 "text": "Den Kater gestreichelt",
 "flag": "kater_gestreichelt",
 "hiddenUntilDone": true // 🫥 taucht erst NACH Erfüllung auf
 }
 ]
 }
}

Die drei Anzeigeoptionen

Features im Player

Konzept

ABP nutzt die im Browser eingebaute Web Speech API (kein Internet nötig, DSGVO-konform). Fährt der Spieler mit der Maus über ein Element, wird dessen Text vorgelesen. Der Spieler steuert vollständig was und wann vorgelesen wird.

Was wird vorgelesen?

Automatische Stimmen-Auswahl

Beim ersten Start wählt ABP automatisch die beste verfügbare deutsche Stimme nach dieser Priorität:

Die manuelle Wahl des Spielers wird in localStorage gespeichert (abp_tts_voice, abp_tts_rate) und beim nächsten Start automatisch geladen. Das Dropdown im Einstellungsmenü zeigt 🌐 Online-Stimmen und 📴 Offline-Stimmen.

Zeitansagen in natürlichem Deutsch

Zeiten werden nicht als 01:23 (TTS: „1 Uhr 23") sondern als natürliche Sprache ausgegeben:

// Beispiele für TTS-Zeitansagen
17 Sekunden // statt „00:17"
1 Minute und 23 Sekunden // statt „01:23"
1 Stunde und 5 Minuten und 30 Sekunden

Designer-Einstellungen

Was sind Variablen?

Variablen sind benannte Zahlenwerte die sich während des Spiels verändern. Im Gegensatz zu Flags (true/false) können Variablen beliebige ganzzahlige Werte annehmen – perfekt für Geld, Punkte, Energie, Schlüsselanzahl oder jeden anderen Zähler.

Definition in der JSON

{
 "variables": {
 "geld": {
 "default": 0, // Startwert
 "min": 0, // Minimum (optional)
 "max": 50, // Maximum (optional)
 "label": "💰 Geld", // Anzeigename im HUD
 "showInHUD": true // In Sidebar anzeigen
 }
 }
}

Mit showInHUD: true erscheint die Variable in der Spieler-Sidebar. Ist ein max-Wert gesetzt, wird ein Fortschrittsbalken angezeigt.

Aktionen – Variablen verändern

// Eine Variable: addVar
"addVar": { "name": "geld", "val": 8 }

// Mehrere Variablen gleichzeitig: varActions-Array
"varActions": [
 { "name": "geld", "val": -5 },
 { "name": "punkte", "val": 10 }
]

Editor-Wege – Wo stelle ich was ein?

Bedingungen – Variablen prüfen

"requireVar": { "name": "geld", "op": ">=", "val": 8 }

Wo funktionieren Variablen?

Beispiel 1: Taschengeld kauft Pizza

Sophie startet mit 3€. Mama gibt ihr 5€. Die Pizza kostet 8€.

// Variable definieren
"geld": { "default": 3, "min": 0, "label": "💰 Geld", "showInHUD": true }

// NPC Mama – Dialog gibt Geld
"dialogTree": {
 "start": {
 "text": "Hier sind 5€ Taschengeld!",
 "addVar": { "name": "geld", "val": 5 }
 }
}

// Objekt Handy – Pizza bestellen, nur mit genug Geld
"usableWith": [{
 "itemName": "Handy",
 "requireVar": { "name": "geld", "op": ">=", "val": 8 },
 "success": "Du bestellst eine Pizza! (-8€)",
 "addVar": { "name": "geld", "val": -8 },
 "setFlag": "pizza_bestellt"
}]

Beispiel 2: Punkte bei Kampf-Sieg

Für jeden besiegten Gegner gibt es 50 Punkte – direkt im onDefeat-Block.

"punkte": { "default": 0, "label": "⭐ Punkte", "showInHUD": true }

"usableWith": [{
 "itemName": "Schwert",
 "damage": 30,
 "onDefeat": {
 "message": "Drache besiegt! +50 Punkte!",
 "addVar": { "name": "punkte", "val": 50 },
 "setFlag": "drache_besiegt"
 }
}]

Beispiel 3: Energie-Balken

Rennen kostet Energie, Schlafen lädt auf. Ohne Energie ist der Wald-Ausgang gesperrt.

"energie": { "default": 10, "min": 0, "max": 10, "label": "⚡ Energie", "showInHUD": true }

// Bett: Energie aufladen
{ "actionLabel": "Schlafen", "success": "Du schläfst. (+5⚡)", "addVar": { "name": "energie", "val": 5 } }

// Ausgang: nur mit Energie > 0
{ "direction": "norden", "targetLocation": "wald",
 "requireVar": { "name": "energie", "op": ">", "val": 0 } }

Variablen vs. Flags vs. HP

3 Speicherslots im Einstellungen-Menü

ABP bietet ein eingebautes Speicher-System ohne Server oder Backend. Alle Spielstände liegen im localStorage des Browsers – funktioniert lokal und auf dem Webserver.

Leere Slots zeigen nur den 💾-Button. Belegte Slots zeigen Ortsname und Datum/Uhrzeit des letzten Speichervorgangs.

Was wird gespeichert?

Der komplette gameState wird gesichert:

Technische Details

Der localStorage-Schlüssel ist spieltitelgebunden – verschiedene Spiele überschreiben sich nicht gegenseitig:

// Schlüssel-Format
abp_save_{spieltitel}_slot1
abp_save_{spieltitel}_slot2
abp_save_{spieltitel}_slot3

// Beispiel: "Sophies großer Tag" → Slot 2
abp_save_Sophies_grosser_Tag_slot2

Was sind Achievements?

Achievements sind unsichtbare Bedingungen die der Designer vorab definiert. Sobald ein Spieler die Bedingung erfüllt, erscheint automatisch eine goldene Toast-Meldung – einmalig, 5 Sekunden sichtbar, kein Klicken nötig. Mit aktiviertem TTS wird die Trophäe auch vorgelesen.

JSON-Format

"achievements": {
 "sparfuchs": {
 "title": "💰 Sparfuchs!",
 "message": "Du hast noch 5 € übrig nach dem Einkauf.",
 "requireFlag": "zutaten_gekauft",
 "requireVar": { "name": "geld", "op": ">=", "val": 5 }
 },
 "blitzlieferung": {
 "title": "⚡ Blitzlieferung!",
 "message": "Kuchen in unter 3 Minuten fertig!",
 "requireFlag": "kuchen_uebergeben",
 "requireMaxTime": 180
 }
}

Übersicht im Player

Achievements sind nicht nur Toast-Meldungen – der Spieler kann sie jederzeit einsehen:

Praktische Beispiele

// Trophäe für Vollständigkeit: alle Räume besucht
"entdecker": {
 "title": "🗺️ Entdecker!",
 "message": "Du hast jeden Winkel erkundet.",
 "requireFlag": "alle_raeume_besucht"
}

// Trophäe für hohe Punktzahl
"punktekoenig": {
 "title": "⭐ Punktekönig!",
 "requireVar": { "name": "punkte", "op": ">=", "val": 100 }
}

// Trophäe für Speedrun (unter 2 Minuten)
"speedrunner": {
 "title": "🚀 Speedrunner!",
 "requireFlag": "spiel_gewonnen",
 "requireMaxTime": 120
}

// Trophäe für Gründlichkeit (mindestens 5 Minuten gespielt)
"gruendlich": {
 "title": "🔍 Gründlich!",
 "requireFlag": "spiel_gewonnen",
 "requireMinTime": 300
}

Wie es funktioniert

ABP misst die Spielzeit automatisch im Hintergrund – ab dem Moment wenn das Spiel startet bis zum Spielende. Die Zeit läuft auch wenn der Spieler das ⚙️-Menü öffnet. Beim Neustart wird die Uhr zurückgesetzt.

Timer in der Sidebar anzeigen

Wenn aktiviert, erscheint ein grüner ⏱️ Spielzeit-Kasten in der Sidebar. Das Format ist MM:SS (unter einer Stunde) oder H:MM:SS (ab einer Stunde). Mit TTS vorlesbar durch Hover.

In der JSON: "displaySettings": { "showTimerInHUD": true }

Spielzeit am Spielende

Die finale Spielzeit erscheint automatisch in der Sieg- oder Niederlage-Meldung – als grüner Balken unterhalb des Textes. Das kann nicht deaktiviert werden. Mit TTS wird die Zeit in natürlicher Sprache vorgelesen:

// Anzeige: 01:23
// TTS liest: "Spielzeit: 1 Minute und 23 Sekunden"

Spielzeit in Achievements

Die Zeit lässt sich als Bedingung in Achievements nutzen – für Speedrun- oder Gründlichkeits-Trophäen:

// Speedrun: Spiel in unter 3 Minuten gewonnen
"speedrunner": {
 "title": "🚀 Speedrunner!",
 "message": "Spiel in unter 3 Minuten abgeschlossen!",
 "requireFlag": "kuchen_uebergeben",
 "requireMaxTime": 180
}

// Gründlich: Mindestens 10 Minuten gespielt
"gruendlich": {
 "title": "🔍 Gründlicher Entdecker!",
 "requireFlag": "kuchen_uebergeben",
 "requireMinTime": 600
}

Verfügbare Themes

Anzeige-Einstellungen (displaySettings)

"displaySettings": {
 // ── Inventar ──────────────────────────────────────────────
 "inventoryPosition": "right", // right | left | bottom
 "allowInventoryChange": true,
 "inventoryHiddenAtStart":false,
 "unlockInventoryItemId": "",
 "inventoryLayout": "vertical", // horizontal | vertical
 "inventoryColumns": "1",
 "inventoryWidth": "300",

 // ── Thumbnails ────────────────────────────────────────────
 "thumbSizeInventory": 70,
 "thumbSizeRoomObjects": 80,
 "thumbSizeNPCs": 80,
 "thumbSizeModal": 300,

 // ── Layout ────────────────────────────────────────────────
 "roomLayout": "horizontal",
 "compactMode": "normal",
 "locationImageSize": "full", // hidden | small | medium | full
 "containerMaxWidth": 1400,
 "showObjectText": true,
 "showNPCText": true,
 "showInventoryText": true,
 "hideEmptySectionTitles":false,

 // ── 3-Wege-Spielmodus ──────────────────────────────────────
 "parserEnabled": true,
 "textOnlyMode": false,
 "textModeImages": true,
 "terminalWidth": "full", // full | 600px | 700px | 800px …
 "showModeGrafik": true,
 "showModeParser": true,
 "showModeText": true,

 // ── HP-System ─────────────────────────────────────────────
 "playerHPEnabled": false,
 "playerStartHP": 100,
 "playerMaxHP": 100,
 "hpSectionTitle": "❤️ Spieler",
 "hpUnit": "HP",

 // ── Skill-System ──────────────────────────────────────────
 "skillSystemEnabled": false,
 "skillStartValue": 0,
 "skillMaxValue": 100,
 "skillSectionTitle": "⭐ Erfahrung",
 "skillLabel": "XP",

 // ── Aufgaben-System ────────────────────────────────────────
 "goalsEnabled": false,
 "goalsTitle": "🎯 Aufgaben",
 "goalsPosition": "sidebar", // sidebar | accordion | modal
 "goals": [
 { "text": "Ziel-Text", "flag": "flag_name", "secret": false }
 ]
}
 

 
Layout-Engine – HUD & Inventar positionieren
 
Mit der Layout-Engine können HUD (Status-Sidebar mit HP, Zielen, Skill) und Inventar frei positioniert werden: links, rechts, oben, unten oder ausgeblendet. Das Layout wird in displaySettings definiert und ist abwärtskompatibel – fehlen die Felder, nutzt der Player das klassische Standard-Layout.

 

 
JSON-Format
"displaySettings": {
  "containerMaxWidth": "1400",
  "containerMaxHeight": "700",
  "hud": {
    "position": "left",       // left | right | top | bottom | hidden
    "size": "220",            // Breite in px (bei left/right) oder Höhe (top/bottom)
    "sections": ["hp", "goals", "skill"]  // Sichtbare HUD-Elemente
  },
  "inventory": {
    "position": "right",      // left | right | top | bottom | hidden
    "size": "280",            // Breite in px
    "layout": "list"          // list | grid2 | row
  }
}
 

 

 
Feld
Werte
Bedeutung
 
hud.position
left · right · top · bottom · hidden
Wo HUD erscheint
 
hud.size
Zahl als String z.B. "220"
Breite (side) oder Höhe (top/bottom)
 
hud.sections
["hp","goals","skill","timer"]
Angezeigte HUD-Elemente
 
inventory.position
left · right · top · bottom · hidden
Wo Inventar erscheint
 
inventory.size
Zahl als String z.B. "280"
Breite der Inventar-Sidebar
 
inventory.layout
list · grid2 · row
Darstellung der Items im Inventar
 

 

 
💡
 
Spieler-Freiheit: Der Spieler kann die Inventar-Position in den Einstellungen ändern (sofern allowInventoryChange: true). Die HUD-Position ist vom Designer fixiert und kann nur über das JSON geändert werden.
 

 

 
🛠️
 
Layouter-Tool: Das optionale Layouter-Tool (layouter.html) ermöglicht die visuelle Konfiguration aller Layout-Einstellungen mit Live-Vorschau. Das fertige JSON kann direkt in die Game-JSON exportiert oder im Player getestet werden.
 
 

Was ist der Parser-Modus?

Jedes Spiel kann optional per Freitext gespielt werden. Ein Toggle-Button im Player-Header schaltet zwischen Klick-Modus und Parser-Modus um. Beide Modi laufen parallel – der Spieler kann jederzeit wechseln, ohne den Spielstand zu verlieren.

Vollständiges Vokabular

🗺️ Gehen

📦 Nehmen

NIMM · NEHME · AUFHEBEN · AUFNEHMEN · GREIF · STECKE EIN · SAMMLE

🗑️ Ablegen

LEGE AB · ABLEGEN · WIRF WEG · WEGWERFEN · ABGEBEN

🔍 Untersuchen

UNTERSUCHE · SCHAU AN · BETRACHTE · PRÜFE · INSPIZIERE · X · LOOK · L

Zeigt die Beschreibung eines Objekts oder Items – ohne eine Aktion auszulösen.

🔎 Durchsuchen

DURCHSUCHE · DURCHSUCHEN · SUCHE IN · WÜHLE IN · FILZE · STÖBERE IN · KRAME IN · GRABE IN

Löst Direkt-Aktionen an Raumobjekten aus – ideal für Objekte die man "durchsuchen", "öffnen" oder "aktivieren" kann ohne ein Item zu brauchen.

🔧 Benutzen (solo)

BENUTZE · VERWENDE · NUTZE · SETZE EIN · WENDE AN · KOMBINIERE · MISCHE

Erkennt automatisch ob das Argument ein Inventar-Item (→ auf passendes Raumobjekt anwenden) oder ein Raumobjekt (→ Direkt-Aktion) ist.

⚗️ Benutzen mit

Prüft zuerst Rezept (beide Items im Inventar), dann Raumobjekt. Reihenfolge ist egal.

🎁 Geben an NPC

💬 Sprechen · 🚪 Öffnen · 🎒 Inventar · ❓ Hilfe

Parser-Tipps für Game Designer

Item: "Goldener Schlüssel"
Synonyme: schluessel, rost, key

"usableWith": [{
 "itemName": "",
 "actionLabel": "🔍 Durchsuchen",
 "success": "Du wühlst zwischen den Kissen... 5 Euro!"
}]

Komplettlösung per Parser: Pizza-Katastrophe

SCHAU DICH UM
BENUTZE TELEFON
DURCHSUCHE SOFA-KISSEN
NIMM 5 EURO
GEHE IN DIE KÜCHE
DURCHSUCHE KEKSDOSE
NIMM KEKSE
GEHE ZURÜCK INS ZIMMER
NIMM STAUBSAUGER
BENUTZE STAUBSAUGER MIT STAUB
GIB STAUBSAUGER AN MAMA
NIMM 3 EURO
KOMBINIERE 5 EURO MIT 3 EURO
GEHE ZUR HAUSTÜR
GIB 8 EURO AN MARCO
-- oder: GIB KEKSE AN MARCO

Was ist die Sound-Bibliothek?

Neben der Hintergrundmusik pro Ort unterstützt ABP jetzt auch Soundeffekte (SFX) – kurze Klänge die bei konkreten Spielereignissen abgespielt werden. Alle Sounds werden einmalig in der zentralen Bibliothek gespeichert. Objekte, Rezepte und Items referenzieren den Sound dann nur noch per ID – kein doppeltes Speichern derselben Audiodatei.

JSON-Struktur der Bibliothek

"sounds": {
 "snd_1234_abc": {
 "name": "💥 Explosion",
 "data": "data:audio/mp3;base64,..."
 },
 "snd_5678_xyz": {
 "name": "🔑 Tür knarrt",
 "data": "data:audio/mp3;base64,..."
 }
}

Die IDs werden automatisch generiert. Du referenzierst sie überall im Spiel als einfacher String – z.B. "sfx": "snd_1234_abc".

SFX-Felder – wo einsetzbar

Beispiel: Schlüssel mit Pickup-Sound

"rost_schluessel": {
 "name": "🔑 Rostiger Schlüssel",
 "description": "Ein alter, verrosteter Schlüssel.",
 "sfx": "snd_1234_abc" // Knarr-Sound aus der Bibliothek
}

Beispiel: Tür öffnen mit SFX

"usableWith": [{
 "itemId": "rost_schluessel",
 "success": "Die Tür quietscht auf!",
 "setFlag": "tuer_offen",
 "removeItem": true,
 "sfx": "snd_5678_xyz" // Tür-knarrt-Sound
}]

Sound-Bibliothek im Editor verwalten

Technische Hinweise

Konzept

Eine Spielserie verbindet mehrere eigenständige JSON-Spiele (Kapitel) unter einem gemeinsamen Hauptmenü. Jedes Kapitel bleibt dabei auch einzeln spielbar. Der Player zeigt beim Laden einer serie.json automatisch ein Hauptmenü mit Kapitelauswahl, optionalen Extras und – wenn konfiguriert – Hintergrundbild und -musik.

serie.json – vollständiges Format

"title": "Zuhause-Kosmos",
"author": "Kai Blass",
"description": "Drei Abenteuer in einer Spielwelt",
"chapterSelect": true, // false = lineare Reihenfolge

// Hauptmenü-Design (optional)
"mainmenu": {
 "backgroundImage": "data:image/...", // Base64-Bild
 "backgroundMusic": "data:audio/...", // Base64-Audio
 "musicLoop": true
},

"chapters": [
 {
 "id": "ch1",
 "title": "Pizza-Katastrophe",
 "file": "pizza-katastrophe.json",
 "description": "Ein Kuchen muss her!",
 "previewImage": "data:image/...", // Vorschaubild im Menü
 "startConditions": {
 "playerHP": 100,
 "skillStart": 0,
 "startInventory": [],
 "flags": {}
 }
 }
],

"extras": [
 {
 "title": "Malbuch",
 "file": "malbuch.json",
 "description": "Zum Ausmalen!",
 "unlockCondition": "allChaptersDone", // oder "always"
 "rewardTitle": "🎉 Du hast alle Kapitel gespielt!",
 "rewardText": "Als Belohnung gibt es jetzt das Malbuch.",
 "rewardImage": "data:image/..." // optionales Belohnungsbild
 }
]

Player-Hauptmenü

Das Hauptmenü erscheint automatisch wenn eine serie.json geladen wird:

Belohnungs-System

Wenn der Spieler alle Kapitel abschließt und ein Extra mit unlockCondition: "allChaptersDone" und rewardTitle vorhanden ist, erscheint automatisch ein Belohnungs-Modal:

1. Letztes Kapitel wird gewonnen
2. Belohnungs-Modal erscheint mit Titel, Text und optionalem Bild
3. Button führt direkt zum Hauptmenü
4. Extras-Button im Hauptmenü leuchtet mit „✨ Extras freigeschaltet!"

Serie konfigurieren (Packager)

Die Serie wird im Packager v2.5 konfiguriert – kein Editor-Tab nötig:

1. Modus 📚 Spielserie auswählen
2. Serientitel, Autor, Beschreibung eingeben
3. Optional: Hintergrundbild + Hintergrundmusik hochladen
4. Kapitel hinzufügen, JSON hochladen, Vorschaubild hochladen
5. Extras mit Freischaltungsbedingung und Belohnungstext konfigurieren
6. Player-HTML hochladen → 🚀 Standalone erstellen
7. Alternativ: 💾 serie.json speichern für Online-Nutzung

Laden & Aufrufen

Was ist das?

Der Player kann eine JSON-Datei automatisch laden wenn der Dateiname als URL-Parameter übergeben wird. Damit kann ein Spiel direkt über einen Link gestartet werden – ohne dass der Spieler erst eine Datei auswählen muss.

URL-Format

player.html?JSON=pizza-katastrophe
player.html?JSON=pizza-katastrophe.json // .json optional
player.html?game=zoo-verrueckt // auch ?game= wird erkannt

Auf der Homepage einsetzen

Statt für jedes Spiel eine eigene Standalone-HTML-Datei (Packager) zu erzeugen, kannst du einfach die JSON-Datei hochladen und direkt verlinken:

<!-- Statt: -->
<a href="pizza-katastrophe.html">Spielen</a>

<!-- Einfacher: -->
<a href="player.html?JSON=pizza-katastrophe">Spielen</a>

Konditionale Item-Beschreibungen

Nicht nur das Bild – auch der Beschreibungstext eines Items kann je nach Flag-Stand wechseln. Die Beschreibung erscheint im Info-Modal (wenn der Spieler auf das Objekt klickt) und im Inventar-Detail. Erste passende Bedingung gewinnt, Fallback auf den Standard-Text.

Im Editor: Item bearbeiten → Abschnitt „📝 Konditionale Beschreibungen" → + Beschreibung hinzufügen. Jeder Eintrag hat ein Flag-Dropdown und ein Textfeld.

"items": {
  "tablet": {
    "name": "Tablet",
    "description": "Das Tablet zeigt: Kein Internetzugang.",
    "conditionalDescriptions": [
      {
        "flag": "internet_frei",
        "description": "Das Tablet ist online! Du kannst jetzt surfen."
      }
    ]
  }
}

Lässt sich beliebig mit konditionalen Bildern kombinieren – so kann das Tablet bei internet_frei = true sowohl ein neues Bild als auch einen neuen Text zeigen.

Item Inline-Editor (Objekte-Tab)

Der Objekte-Tab im Editor arbeitet ohne Popup-Modals. Alle Item-Eigenschaften werden direkt im Hauptbereich bearbeitet: Name, Item-ID, Beschreibung, Tags, Bild/Video, Self-Use (sofort benutzen ohne Ziel), konditionale Bilder und konditionale Beschreibungen. Änderungen werden beim Verlassen eines Felds automatisch gespeichert – ein separater Speichern-Button ist optional.

Die linke Liste zeigt alle Items mit ihrer ID. Klick auf ein Item → sofortiger Wechsel, alle Felder werden neu geladen.

Direct Action: Item sofort ins Inventar

Mit givesItemId in einem usableWith-Eintrag (ohne Item = Direct Action) landet ein Item sofort im Inventar des Spielers – kein zweiter Klick nötig. Perfekt für „Kiste durchsuchen", „Schublade öffnen" oder „Brief aufheben".

{
  "itemId": "werkzeugkiste",
  "canTake": false,
  "usableWith": [
    {
      "actionLabel": "🔧 Durchsuchen",
      "givesItemId": "schraubendreher",
      "message": "Du findest einen Schraubendreher!",
      "removeObject": true,
      "setFlag": "kiste_durchsucht"
    }
  ]
}

Das actionLabel erscheint als Button direkt am Objekt (kein Item im Inventar nötig). Nach dem Klick geht der Schraubendreher sofort ins Inventar, die Kiste verschwindet und der Flag kiste_durchsucht wird gesetzt.

Objekt-Aktion als Modal-Fenster (modal: true)

Standardmäßig erscheint die Erfolgsmeldung einer Objekt-Aktion als kurze Toast-Meldung. Mit modal: true wird sie als bleibendes Modal-Fenster angezeigt – ideal für Rezepte, Briefe oder Hinweisschilder.

"usableWith": [
  {
    "actionLabel": "📜 Brief lesen",
    "message": "Liebe Anna, ...\n\nDein Papa",
    "modal": true,
    "title": "📜 Ein Brief"
  }
]

Was ist der Packager?

Der Packager ist ein separates Browser-Werkzeug (packager.html) das deine Spiele für andere zugänglich macht – ohne dass dein Publikum den Editor oder die Spielstruktur sehen muss. Er kombiniert Player + Spieldaten zu einer einzigen, sofort lauffähigen Datei, oder er erzeugt eine kompakte serie.json für die Online-Veröffentlichung.

Fall 1: Einzelspiel als Standalone

Der klassische Fall – ein Spiel, eine Datei, überall spielbar.

1. Player laden: Aktuelle player.html per Drag & Drop oder Klick hochladen. Der Packager zeigt an welche Version erkannt wurde und welche Features die JSON enthält.
2. JSON laden: Die exportierte Spiel-JSON hochladen (aus dem Editor: 💾 Als JSON speichern).
3. Optional – Ladescreen-Bild: Ein Bild das während des Ladens gezeigt wird (empfohlen: 600×400px).
4. 🚀 Standalone erstellen: Erzeugt spielname_standalone.html – diese Datei enthält alles und startet sofort im Browser.

// Was in der Standalone-HTML steckt:
✅ player.html (vollständiger Spielmotor)
✅ Spieldaten (JSON eingebettet)
✅ Ladescreen-Bild (als Base64, falls hochgeladen)
✅ Fortschritts-Animation beim Start

Fall 2: Serie als Standalone

Alle Kapitel einer Serie in einer einzigen Offline-Datei.

1. Serientitel, Autor, Beschreibung eingeben.
2. Optional: Hintergrundbild und Hintergrundmusik für das Hauptmenü hochladen.
3. Kapitel hinzufügen: ➕-Button → Titel + dateiname.json eintragen.
4. Pro Kapitel: 📂 JSON laden → Spiel-JSON hochladen (wird eingebettet) · 🖼️ Vorschau → Thumbnail hochladen (wird als Base64 eingebettet).
5. Player laden und 🚀 Standalone erstellen.

Fall 3: Serie online veröffentlichen

Der eleganteste Weg für adventure-builder.de oder einen eigenen Webserver: eine schlanke serie.json mit eingebetteten Thumbnails – die Kapitel werden beim Spielen per URL nachgeladen.

1. Serienstruktur aufbauen: Titel, Kapitel-Titel und Dateinamen eintragen (z.B. pizza-katastrophe.json).
2. Kein JSON-Upload nötig! Die Kapitel-JSONs liegen später auf dem Server – der Player lädt sie beim Klick automatisch nach.
3. Thumbnails hochladen: 🖼️ Vorschau pro Kapitel → Bild hochladen → wird als Base64 eingebettet und bleibt in der serie.json.
4. 💾 serie.json speichern: Erzeugt eine schlanke JSON ohne Spieldaten – nur Struktur + Thumbnails.
5. Auf den Server hochladen: Alle Dateien in denselben Ordner.

Serverstruktur:

📁 webserver/
   player.html
   sophie_schafft_das_serie.json    ← mit Thumbnails (Base64), kein gameData
   pizza-katastrophe.json           ← Kapitel 1
   zoo-verrueckt.json               ← Kapitel 2
   oma-geburtstag.json              ← Kapitel 3

Aufruf im Browser:

https://adventure-builder.de/player.html?serie=sophie_schafft_das_serie.json

// Kurzform funktioniert auch:
https://adventure-builder.de/player.html?game=sophie_schafft_das_serie.json

Fall 4: Einzelspiel online via URL

Kein Packager nötig – der Player kann Spiele direkt per URL-Parameter laden.

https://adventure-builder.de/player.html?game=pizza-katastrophe.json

Serverstruktur:

📁 webserver/
   player.html
   pizza-katastrophe.json

Der Player erkennt automatisch ob es sich um ein Einzelspiel oder eine Serie handelt und zeigt entsprechend die Spieloberfläche oder das Serien-Hauptmenü.

Welcher Weg für welchen Zweck?

Editor-Usability – neue Funktionen

🖌️ Editor-Themes

Unter ⚙️ Einstellungen → Editor-Theme stehen 5 Farbthemen zur Wahl: 🌈 Bunt, ⚫ Dark, 🔘 Schlicht, 🔵 Klassisch und 🎮 Minecraft. Jedes Theme ändert Hintergrundfarbe, Buttons, Header und Sidebar. Die Wahl wird im Browser gespeichert (nicht im Spiel-JSON).

⚙️ Einstellungen-Tab

Der neue Tab ⚙️ Einstellungen fasst Spiel-Informationen (Titel, Autor, Version, Sprache), Editor-Theme, TTS und Spielende an einem Ort zusammen. Kampf-System und Spielmodi sind im Tab Features bzw. Anzeige. Der Header-Button „⚙️ Einstellungen" öffnet direkt diesen Tab statt einem Modal.

↕ Akkordeon-Zyklus

Der ↕-Button rechts in der Titelleiste von ORTE, Features und Anzeige schaltet zwischen drei Zuständen durch: Alle auf → Alle zu → Merker (gespeicherter Zustand). Der Editor merkt sich welche Akkordeons offen waren und kehrt auf Wunsch dorthin zurück.

⏱ Zuletzt bearbeitet

Ab 3 Orten zeigt die Orts-Sidebar oben die 3 zuletzt bearbeiteten Orte als Schnellzugriff an. Spart Scrollen bei großen Spielen.

⧉ Objekt duplizieren

Jedes Objekt in einem Ort hat jetzt einen ⧉-Button (Duplizieren). Ein Klick erstellt eine identische Kopie direkt darunter – inklusive aller Verwendungen, Flags und Bedingungen.

🔍 Schnellsuche

In der Sidebar der Tabs NPCs, Flags und Sounds gibt es jetzt ein Suchfeld zum schnellen Filtern der Liste.

🎮 Spieltitel im Header

Nach dem Laden oder Anlegen eines Spiels erscheint der Spieltitel rechts neben dem „Adventure Builder Pro"-Logo im Header. Er aktualisiert sich automatisch wenn du den Titel im Tab ⚙️ Einstellungen → 📋 Spiel-Informationen änderst.

💾 Export-Dateiname = Spieltitel

Beim Export heißt die JSON-Datei jetzt automatisch nach dem Spieltitel – z.B. Mission_Zoo_verrueckt.json. Sonderzeichen werden entfernt, Leerzeichen durch _ ersetzt. Umlaute bleiben erhalten.

📋 Spiel-Informationen inline

Titel, Autor, Version und Startort sind jetzt direkt im Tab ⚙️ Einstellungen → 📋 Spiel-Informationen inline editierbar – kein Modal mehr nötig. Der Header-Button „⚙️ Einstellungen" öffnet direkt diesen Tab.

🚩 Flag setzen beim Nehmen (canTake)

Objekte mit canTake: true können jetzt ein setFlag erhalten. Sobald der Spieler das Objekt aufnimmt, wird dieser Flag automatisch auf true gesetzt. Im Editor erscheint dafür ein Dropdown „🚩 Flag setzen beim Nehmen" im Objekt-Modal (Hinzufügen + Bearbeiten). Dies ist z.B. nützlich um bedingte Ortsbeschreibungen auszulösen (Tasche nehmen → tasche_genommen → Beschreibung ändert sich).

🏁 Spielende – Verzögerung & Partikeldesigner

Unter ⚙️ Einstellungen → 🏁 Spielende kannst du die Ende-Meldung fein einstellen:

• ⏱️ Verzögerung – Slider 0–5s (Standard: 2s). Wähle wie lange es dauert bis die Gewinn/Verlier-Meldung nach dem auslösenden Event erscheint.
• 🎨 Partikel-Effekt – drei Modi: 🎉 Emojis (frei konfigurierbar), 🎊 Konfetti (geometrische Farbflächen), 🚫 Keiner
• ✏️ Emojis konfigurieren – eigene Emojis eingeben oder aus 8 Schnellauswahl-Presets wählen (Party, Sterne, Sieg, Herzen, Natur, Space, Action, Games)
• 🔢 Menge – Slider 10–200 Partikel
• ⚡ Geschwindigkeit – 🐢 Langsam / ▶️ Normal / ⚡ Schnell

📝 forbidFlag in konditionalen Beschreibungen

Konditionale Ortsbeschreibungen unterstützen jetzt ein zweites Dropdown 🚫 Flag (darf NICHT gesetzt sein). Damit lassen sich Beschreibungen exakter steuern: z.B. „zeige diesen Text wenn Flag A gesetzt ist, aber nur solange Flag B noch nicht gesetzt ist". Außerdem gibt es einen ↑ Nach-oben-Button um die Reihenfolge der Einträge zu ändern – wichtig, da immer der erste passende Eintrag gewinnt (spezifischste Bedingungen müssen oben stehen).

Sound-Bibliothek für Hintergrundmusik

Hintergrundmusik eines Ortes wird jetzt über die 🔊 Sound-Bibliothek referenziert statt direkt als Base64 gespeichert. Im Ort-Editor erscheint ein Dropdown mit allen Bibliotheks-Sounds. Bestehende JSON-Spiele mit direkt eingebetteter Musik werden beim Laden automatisch migriert.

Vorteil: Dieselbe Musik kann mehreren Orten zugewiesen werden ohne den JSON-Export zu vergrößern. Unter Tab 🔊 Sounds sieht man bei jedem Sound wo er eingesetzt wird (z.B. „🎵 Hintergrundmusik: Küche").

Vollständige Grundstruktur

{
 // === PFLICHT ===
 "title": "Spielname",
 "startLocation": "ort_id",

 // === OPTIONAL ===
 "author": "Dein Name",
 "version": "1.0",
 "defaultTheme": "modern",
 // Start-Inventar: pro Item "startInventory": true setzen (siehe Items)

 // === KERN-DATEN ===
 "locations": { /* Orte */ },
 "items": { /* Gegenstände */ },
 "npcs": { /* Charaktere */ },
 "recipes": [ /* Rezepte */ ],
 "quests": [ /* Aufgaben */ ],
 "flags": { /* Spielzustände */ },
 "sounds": { /* 🔊 Sound-Bibliothek */ },
 "cutscenes": { /* Story-Sequenzen */ },
 "gameEnds": { "win": [], "lose": [] },
 "displaySettings": { /* Layout */ }
}

usableWith – alle Felder

Vor dem ersten Test

📁 Grundstruktur

• startLocation ist gesetzt und der Ort existiert
• Alle Orte haben Name und Beschreibung
• Kein Ort verweist auf einen nicht-existierenden Ort (Exits)
• Mindestens eine Sieg-Bedingung ist definiert

📦 Items & Inventar

• Alle Items, die in Rezepten (Zutaten/Ergebnis), an Ausgängen (requiredItem) oder in usableWith (itemName) verwendet werden, sind in items definiert – im Editor ist das der Tab 📦 Objekte. Der Abgleich läuft über den Namen (exakte Schreibweise!). Nicht verwechseln: Gemeint sind Inventar-Items – nicht die Raum-Objekte, an denen usableWith hängt.
• Wenn Inventar-Freischaltung: Freischalt-Item liegt als Raumobjekt vor, nicht als Tausch-Item

🗨️ NPCs & Dialog

• Jeder NPC hat entweder einen statischen Dialog oder einen Dialog-Baum mit start-Knoten
• receivesItems verweist auf Items die der Spieler auch wirklich finden kann
• flagBranch-Ziel-Knoten existieren im Dialog-Baum

🏁 Spielende

• Spielende-Bedingungen sind erreichbar (kein unlösbares Spiel)
• Wenn teleportTo gesetzt: Ziel-Ort existiert
• Wenn playCutscene gesetzt: Cutscene-ID existiert
• message ist ausgefüllt (title + message + buttonText empfohlen)

🎬 Cutscenes

• Alle referenzierten Cutscene-IDs existieren in cutscenes
• game_intro vorhanden (optional, aber empfohlen)
• playCutsceneOnce: true gesetzt wo nötig

🚩 Flags

• Alle Flags die als Bedingung verwendet werden, sind in flags definiert
• Flag-Namen sind konsistent (exakt gleich geschrieben)

Namenskonventionen

Story-Struktur

• Tutorial-Ort: Der erste Ort sollte die Grundmechaniken erklären – am besten durch Handeln, nicht durch langen Text
• Klare Ziele: Der Spieler sollte immer wissen was als nächstes zu tun ist – NPCs geben Hinweise
• Belohnungen: Nach jedem Rätsel eine Belohnung – ein neues Item, eine Cutscene, eine neue Tür
• Mehrere Wege: Dialog-Bäume und bedingte Ausgänge ermöglichen verschiedene Spielwege

Balance & Schwierigkeit

• Kampfsystem: Feinde mit 100–200 HP, Waffen mit 20–40 Schaden gibt 3–8 Treffer pro Kampf
• Rezepte: Nicht mehr als 2–3 Kombinationsschritte hintereinander – sonst wird's frustierend
• Hinweise: Wenn Rätsel schwer sind, sollte mindestens ein NPC einen Tipp geben können
• Sackgassen vermeiden: Teste jeden möglichen Weg – gibt es eine unbeabsichtigte Situation wo der Spieler feststeckt?

Atmosphäre & Stil

• Themes konsequent einsetzen: Wechsle das Theme nur bei wichtigen Momenten – zu viele Wechsel wirken unruhig
• Beschreibungen: Atmosphäre geht vor Fakten. "Es riecht modrig, ein Tropfen fällt in die Stille" ist besser als "Ein Keller, 3x4 Meter."
• NPC-Persönlichkeit: Jeder NPC sollte eine eigene Sprache haben – Händler reden von Profit, Wachen von Pflicht
• Cutscenes sparsam: Cutscenes sind emotionale Höhepunkte – zu viele davon verlieren ihre Wirkung

Typische Spielmuster als Vorlage

🔑 Schlüssel-Tür

Item finden → an Objekt verwenden → Flag setzen → Ausgang freischalten. Das klassischste Muster.

📜 Boten-Quest

Item A von NPC A erhalten → Item A zu NPC B bringen → Belohnung erhalten. Gut für strukturierte Quests.

⚗️ Mehrstufiges Crafting

Item A + Item B = Item C → Item C + Item D = Item E → Item E auf Objekt anwenden. Gut für Rätsel die Vorausdenken erfordern.

⚔️ Boss mit Belohnung

NPC mit maxHP → mit Waffe bekämpfen → onDefeat gibt Item und setzt Flag → Game End wird ausgelöst.

🎭 Geschichte mit mehreren Enden

Dialog-Baum mit setFlag → verschiedene Flags führen zu verschiedenen

// Schritt 1: Rezept – Mehl + Wasser = Teig
{ "item1": "mehl", "item2": "wasser", "result": "teig" }

// Schritt 2: NPC nimmt das Brot entgegen
"receivesItems": [{
 "itemId": "brot",
 "message": "Danke! Hier hast du deine Belohnung.",
 "givesItemId": "gold",
 "setFlag": "brot_abgegeben"
}]

// Schritt 3: Spielende wenn Quest abgeschlossen
"win": [{
 "type": "flag",
 "value": "brot_abgegeben",
 "message": "Du hast die Aufgabe erfüllt!"
}]

Cutscene nach Objekt-Aktion

Nach einer erfolgreichen usableWith-Aktion kann automatisch eine Cutscene gestartet werden. Optional: nur einmal abspielen (playCutsceneOnce: true). Im Editor: Itemverwendung bearbeiten → „🎬 Cutscene nach Verwendung".

"usableWith": [
  {
    "itemId": "zauberstab",
    "success": "Ein magisches Tor öffnet sich!",
    "playCutscene": "magie_cutscene",
    "playCutsceneOnce": true,
    "setFlag": "tor_offen"
  }
]

Konditionaler NPC-Dialog

Für einfache Fälle ohne Dialog-Baum: Der Gesprächstext eines NPCs wechselt automatisch je nach Flag-Zustand. Erste passende Bedingung gewinnt, Fallback auf den Standard-Dialog. Im Editor: NPC bearbeiten → Reiter „🔀 Konditional" beim Dialog-Feld.

"npcs": {
  "papa": {
    "name": "Papa",
    "dialog": "Hast du den Schraubendreher?",
    "conditionalDialogs": [
      {
        "flag": "gegeben_schraubendreher",
        "dialog": "Danke! Ich repariere das gleich."
      },
      {
        "flag": "werkzeugkiste_leer",
        "dialog": "Die Werkzeugkiste ist jetzt leer..."
      }
    ]
  }
}

Für komplexere Gespräche mit Auswahloptionen → Dialog-Baum (dialogTree) verwenden.

Standard / Konditional – Tab-System im Editor

Alle konditionalen Inhalte sind im Editor über ein einheitliches Zwei-Reiter-System erreichbar. Der Reiter Standard zeigt den normalen Inhalt, Konditional die Flag-abhängigen Varianten. Hat ein Objekt bereits Einträge, öffnet sich der Konditional-Reiter automatisch mit Badge-Zähler.

🚪 Physische Tore: So baust du eines — Schritt für Schritt

Der stärkste Baustein im QR-Modus ist ein Ausgang, der den Spieler wirklich an den echten Ort schickt — optional kombiniert mit einer Bedingung aus dem Spiel. Kopf und Füße.

Die Grundregel: Ein QR-Code kann genau eines — ein Flag setzen. Er legt nie Gegenstände ins Inventar. Die Immersion liefert die Antwort des Geheimworts („🚪 Klick! Ihr steht wirklich hier — die Tür ist entriegelt.“).

🗝️ Geheimwörter im Editor anlegen (neu in v5.0)

Ein Geheimwort ist ein Wort (oder eine Zahl), das ein Flag setzt — der Spieler tippt es über den 🗝️-Knopf ein. Damit baust du Zahlenschlösser, Passwörter und Rätsel-Lösungen. Im QR-Modus wird genau daraus der QR-Code an einem echten Ort.

Anlegen: Tab ⚙️ Features → Akkordeon 🗝️ Geheimwörter → „➕ Geheimwort“.

📷 Das QR-Tor: Der Ort wird zur Spielmechanik — neu in v5.1

Ein Ausgang oder eine Objekt-Aktion kann verlangen, dass der QR-Code am echten Ort gescannt wird. Der Ausgang bleibt sichtbar (markiert mit 📷) — beim Klick öffnet sich sofort der Scanner, und nach dem richtigen Wort läuft die Handlung direkt weiter. Kein „erst scannen, dann nochmal klicken“.

Im JSON heißt das Feld qrGate (plus optional qrPrompt). Fehlt es, verhält sich alles exakt wie bisher — Solo-Abenteuer merken nichts davon.

🎯 Kopf und Füße: Rätsel UND Ort

Der stärkste Baustein entsteht, wenn du beides verlangst — im Spiel lösen und am echten Ort stehen. An einer Objekt-Aktion geht das direkt:

1. Benötigt Flag = das Rätsel-Flag (z. B. lina_bereit) → der Kopf
2. 📷 QR-Tor = das qr_-Flag → die Füße

Die Reihenfolge im Player ist bewusst gewählt: Erst werden die Spiel-Bedingungen geprüft, dann das QR-Tor. Wer das Rätsel noch nicht gelöst hat, bekommt die normale Absage — und wird nicht sinnlos zum Scannen geschickt. Erst wenn nur noch der Ort fehlt, geht die Kamera auf.