Basic Concepts

📚

Verstehen Sie die Grundlagen interaktiven Storytellings

1

Variables

2

Edge Types

3

Node Types

4

Graph Structure

🎯

Wichtige Konzepte

✓

Edge-Semantik

3 Typen: contains, flow, link

✓

Validierung

Nur flow-Edges sind testbar

✓

Hierarchie

contains für strukturelle Zugehörigkeit

✓

Referenzen

link für lose, nicht-testbare Verbindungen

💡

Warum das wichtig ist

→

Klare Semantik

Jeder Edge-Typ hat eine eindeutige Bedeutung

→

Bessere Validierung

Automatische Tests prüfen flow-Completeness

→

Intuitive UI

Unterschiedliche Darstellung je nach Typ

→

Saubere Architektur

Trennung von Struktur, Ablauf und Referenzen

🔢 Variables & Query DSL

TellsTree verwendet eine eigene Domain-Specific Language (DSL) für den Zugriff auf Daten in Ihrer Geschichte. Mit dieser Query-Syntax können Sie auf Nodes, Edges, Project-Informationen und Variables zugreifen.

💡 Wichtig: Die DSL ermöglicht dynamische Inhalte, bedingte Verzweigungen und variable Dialoge. Sie ist das Herzstück der interaktiven Funktionen in TellsTree.

📝 Query Syntax

Grundformat:

<entity>[<selector>].<field>[<key>]

entity — Der Entitätstyp: node, edge, self, project
selector — ID oder self (optional)
field — Das Datenfeld: content, variables, label, type, etc.
key — Array-Schlüssel für verschachtelte Daten (optional)

✅ Gültige Queries:

node[21].content[name]

self.variables[level]

node[self].content[speaker]

edge[5].condition[type]

project.title

node[42].label

💡 Erläuterungen:

node[21] — Zugriff auf Node mit ID 21
self — Aktueller Node oder Edge im Kontext
content[name] — Feld "name" aus content-Objekt
variables[level] — Variable "level"
project.title — Projekttitel (ohne Selektor)

🎯 Verfügbare Entities

🔵 node

Zugriff auf Story-Knoten (Charaktere, Dialoge, Szenen, etc.)

Verfügbare Fields:

content — Content-Daten (Array)
variables — Gespeicherte Variablen
media — Media-URLs
label — Anzeigename
type — Node-Typ
node_id / id — Eindeutige ID

Beispiele:

node[15].content[dialog_text]

node[self].variables[health]

node[42].type

🔗 edge

Zugriff auf Verbindungen zwischen Nodes

Verfügbare Fields:

condition — Bedingungsdaten (Array)
type — Edge-Typ (flow/contains/link)
edge_id / id — Eindeutige ID
from_node_id — Start-Node
to_node_id — Ziel-Node

Beispiele:

edge[8].condition[operator]

edge[self].type

edge[5].from_node_id

⭐ self

Referenz auf die aktuelle Entity im Kontext (Node oder Edge)

Verwendung:

Zugriff auf eigene Daten
Relative Referenzen
Kontext-abhängige Queries

Beispiele:

self.content[name]

self.variables[score]

self.label

📁 project

Zugriff auf Projekt-Metadaten

Verfügbare Fields:

project_id / id — Projekt-ID
title — Projekttitel
description — Beschreibung
is_public — Öffentlich?

Beispiele:

project.title

project.is_public

🎨 Template Resolution

Queries können in Templates mit doppelten geschweiften Klammern eingebettet werden.

Syntax:

Hello, {{node[15].content[name]}}!

→ Wird zu: Hello, Alice! (wenn node 15 name="Alice" hat)

🔄 Verschachtelte Queries:

TellsTree unterstützt verschachtelte Query-Resolution. Innerste Queries werden zuerst aufgelöst.

{{node[{{self.content[speaker]}}].content[name]}}

1. {{self.content[speaker]}} → 15
2. node[15].content[name] → Alice

Beispiele:

"Your level: {{self.variables[level]}}"

→ Your level: 5

"{{node[8].content[greeting]}}, {{self.content[player_name]}}"

→ Hello, John

Anwendungsfälle:

✓ Dynamische Dialog-Texte
✓ Variable Edge-Labels
✓ Bedingte Anzeige-Texte
✓ Player-spezifische Inhalte
✓ Kontext-abhängige UI

⚖️ Bedingungen (Conditions)

Queries können in Bedingungen verwendet werden, um Edges oder UI-Elemente konditional anzuzeigen.

Struktur:

{
  "query": "self.variables[level]",
  "operator": ">=",
  "value": 5
}

→ Bedingung ist wahr wenn level ≥ 5

Verfügbare Operatoren:

== / equals

Gleich

=== / strict_equals

Strikt gleich

!= / not_equals

Ungleich

> / greater_than

Größer als

>= / greater_or_equal

Größer gleich

< / less_than

Kleiner als

<= / less_or_equal

Kleiner gleich

contains

Enthält Substring

in

In Array

Beispiel-Bedingungen:

self.variables[has_key] == true

Spieler hat Schlüssel

node[42].content[health] > 0

Charakter lebt noch

self.variables[level] >= 10

Level-Requirement erfüllt

🎯 Verwendung in Edges:

Flow-Edges können Bedingungen haben. Nur Edges mit erfüllter Bedingung werden im Gameplay aktiviert. Dies ermöglicht branching narratives basierend auf Spieler-Entscheidungen und Status.

🔒 Sicherheit & Permissions

Automatische Permission-Checks:

✓ Alle Queries werden gegen Projekt-Zugriff validiert
✓ Nur Nodes/Edges im aktuellen Projekt sind zugreifbar
✓ User-Permissions werden automatisch geprüft
✓ Öffentliche Projekte sind für alle lesbar
✓ Private Projekte nur für Besitzer/Mitglieder

💡 Hinweis: Ungültige Queries (z.B. fehlende Permissions, nicht existierende IDs) geben null zurück und werden geloggt. Das System ist fail-safe designed.

💎 Best Practices

✅ Do:

• Verwende self für relative Referenzen
• Nutze sprechende Variablen-Namen
• Teste Bedingungen vor Production
• Verwende Templates für dynamische Inhalte
• Halte Queries einfach und lesbar

❌ Don't:

• Vermeide zu tief verschachtelte Queries
• Keine Queries auf nicht-existierende IDs
• Keine zirkulären Referenzen
• Keine sensiblen Daten in Variables
• Nicht mehr als 10 Verschachtelungs-Level

🔗 Edge Types

In TellsTree unterscheiden wir drei grundlegende Edge-Typen, die jeweils unterschiedliche semantische Bedeutungen haben und sich in ihrer Darstellung und Validierung unterscheiden.

💡 Wichtig: Die richtige Wahl des Edge-Typs ist entscheidend für die Validierung und Darstellung Ihrer interaktiven Geschichten. Nur flow-Edges können getestet werden und bilden den logischen Ablauf.

📦 1️⃣ contains — Strukturelle Zugehörigkeit

Beschreibt hierarchische Beziehungen und Besitz. Dieser Edge-Typ definiert, dass ein Element Teil eines anderen ist.

Eigenschaften:

Beschreibt Besitz, Teilmenge, Einbettung
Keine zeitliche Komponente
Keine Richtung im Sinne von Ablauf
Keine Bedingungen möglich
Nicht test-relevant

Semantische Aliase:

located_in appears_in owns wears has_trait

Beispiele:

Chapter → Scene

Scene → Story-Segment

Dialog → Dialog-Entry

Inventory → Item

Character → Trait

Stage → Gameplay-Segment

Alle diese Beziehungen bedeuten: "A gehört zu B"

➡️ UI-Darstellung:

✗ Kein Pfeil
✓ Sidelane / Grouping / Umrandung
✓ Rein organisatorisch

🌊 2️⃣ flow — Gerichtete, bedingte Abfolge

Dies ist der einzige Edge-Typ, der zeitlich, testbar und logisch relevant ist. Flow-Edges definieren den tatsächlichen Ablauf Ihrer Geschichte.

Eigenschaften:

Immer gerichtet
Optional: Bedingungen (conditions)
Optional: Effekte / Events
Relevant für Validierung
Kann "offene Enden" erzeugen

Semantische Varianten:

follows branches_to unlocks requires blocks completes fails talks_to

✅ Kritische Regel:

Alle flow-Verbindungen müssen von Start bis Ende gehen. Nur flow-Edges bilden Graphen, die man testen kann.

Beispiel-Ablauf:

Start → Scene 1

follows

Scene 1 → Choice A

Scene 1 → Choice B

branches_to (mit Bedingungen)

Choice A → End

➡️ UI-Darstellung:

✓ Gerichteter Pfeil
✓ Bedingungen anzeigen
✓ Highlighting bei Validierung
✓ "Offene Enden" rot markieren

🔗 3️⃣ link — Lose, nicht-sequenzielle Verbindung

Ein Edge-Typ, den viele Systeme nicht sauber trennen. Links sind rein referenziell und haben keine logische oder zeitliche Bedeutung.

Eigenschaften:

Keine zeitliche Komponente
Keine Reihenfolge
Keine Validierungslogik
Rein semantisch / referenziell
Optional ein-/ausblendbar

Semantische Varianten:

mentions connects_to references related_to

Beispiele:

Character A ⋯→ Character B

mentions (in dialogue)

Location A ⋯→ Location B

connects_to (map reference)

Scene 5 ⋯→ Scene 12

references (callback)

⚠️ Wichtig:

Link-Edges sind niemals testrelevant. Sie dienen nur der Dokumentation und semantischen Verbindung, nicht dem logischen Ablauf.

➡️ UI-Darstellung:

✓ Gestrichelte Linie oder Pfeil
✓ Label / Beschreibung anzeigen
✓ Optional ein-/ausblendbar
✗ Niemals in Validierung einbeziehen

📊 Vergleichstabelle

Eigenschaft	contains	flow	link
Zeitlich	❌	✅	❌
Gerichtet	❌	✅	➖ (optional)
Bedingungen möglich	❌	✅	❌
Testrelevant	❌	✅	❌
UI-Darstellung	Grouping	Pfeil →	Gestrichelt ⋯→
Validierung	Organisatorisch	Vollständig	Keine

📦 Nodes

Coming soon...

🕸️ Graph Structure

Coming soon...