.STAGE

Verwaltet Stages (Bot-Abschnitte) und die Navigation dazwischen (RAGAI.STAGE).

Hintergrund

Eine Stage ist ein benannter Zustand des Bots mit eigener Skill-Auswahl, optionalem Enter-/Exit-Callback und Footer-Sichtbarkeit - das Grundgerüst für mehrstufige Dialoge, Quiz oder geführte Abläufe (State Machine). Beim Wechsel läuft immer erst exitFn der alten, dann enterFn der neuen Stage. hidden-Stages bleiben über goToName()/goToIndex() direkt ansteuerbar, tauchen aber nicht in visibleStages (z. B. für RAGAI.CARDS-Navigationslisten) auf. sortFloat bestimmt nur die Reihenfolge für next()/prev()/goToIndex(), nicht die Registrierungsreihenfolge. goTo() akzeptiert neben Index/Name auch die Spezialwerte "___PREV_STAGE___", "___NEXT_STAGE___", "___FIRST_STAGE___", "___LAST_STAGE___" (u. a. für generierten Blockly-Code).

Methoden

.add(name, stage?)

Fügt eine neue Stage hinzu.

Parameter	Typ	Beschreibung
name	string | z.input<typeof stageAddSchema>	Name der neuen Stage, oder ein Objekt gemäß stageAddSchema.
stage	Partial<Omit<StageDefinition, "name">>	Weitere Stage-Eigenschaften (Titel, Skills, Sichtbarkeit etc.).

Objekt-Form (validiert über stageAddSchema):

Feld	Typ	Pflicht	Beschreibung
name	string	✔	Eindeutiger Name der neuen Stage.
title	string	–	Anzeigetitel der Stage.
skills	array	–	Skills, die in dieser Stage aktiv sind.
hidden	boolean	–	true, um die Stage aus der Stage-Liste auszublenden.
footer	boolean	–	true, um den Footer in dieser Stage anzuzeigen.
forceSkills	boolean	–	true, um die Skills dieser Stage zu erzwingen.
sortFloat	number	–	Sortierposition der Stage.

Rückgabewert: void

.remove(name)

Entfernt eine Stage.

Parameter	Typ	Beschreibung
name	string | z.input<typeof stageGoToNameSchema>	Name der zu entfernenden Stage, oder ein Objekt gemäß stageGoToNameSchema.

Objekt-Form (validiert über stageGoToNameSchema):

Feld	Typ	Pflicht	Beschreibung
name	string	✔	Name der Ziel-Stage.

Rückgabewert: void

.hide(name)

Blendet eine Stage aus der Stage-Liste aus.

Parameter	Typ	Beschreibung
name	string | z.input<typeof stageGoToNameSchema>	Name der auszublendenden Stage, oder ein Objekt gemäß stageGoToNameSchema.

Objekt-Form (validiert über stageGoToNameSchema):

Feld	Typ	Pflicht	Beschreibung
name	string	✔	Name der Ziel-Stage.

Rückgabewert: void

.show(name)

Blendet eine zuvor ausgeblendete Stage wieder ein.

Parameter	Typ	Beschreibung
name	string | z.input<typeof stageGoToNameSchema>	Name der einzublendenden Stage, oder ein Objekt gemäß stageGoToNameSchema.

Objekt-Form (validiert über stageGoToNameSchema):

Feld	Typ	Pflicht	Beschreibung
name	string	✔	Name der Ziel-Stage.

Rückgabewert: void

.goToRandom(possibleNames?)

Navigiert zu einer zufälligen (sichtbaren) Stage.

Parameter	Typ	Beschreibung
possibleNames	string[] | z.input<typeof stageGoToRandomSchema>	Optionale Einschränkung auf bestimmte Stage-Namen, oder ein Objekt gemäß stageGoToRandomSchema.

Objekt-Form (validiert über stageGoToRandomSchema):

Feld	Typ	Pflicht	Beschreibung
possibleNames	array	–	Einschränkung auf bestimmte Stage-Namen; ohne Angabe alle sichtbaren Stages.

Rückgabewert: Promise<void>

Nichts.

.goToIndex(index)

Navigiert zu einer Stage per Index.

Parameter	Typ	Beschreibung
index	number | z.input<typeof stageGoToIndexSchema>	Index der Ziel-Stage, oder ein Objekt gemäß stageGoToIndexSchema.

Objekt-Form (validiert über stageGoToIndexSchema):

Feld	Typ	Pflicht	Beschreibung
index	number	✔	Index der Ziel-Stage.

Rückgabewert: Promise<void>

Nichts.

.goTo(value)

Navigiert zu einer Stage per Index, Name oder Spezial-Wert (___PREV_STAGE___, ___NEXT_STAGE___, ___FIRST_STAGE___, ___LAST_STAGE___).

Parameter	Typ	Beschreibung
value	number | string	Ziel-Index, Stage-Name oder Spezial-Wert.

Rückgabewert: Promise<void>

Nichts.

.goToName(name)

Navigiert zu einer Stage per Name.

Parameter	Typ	Beschreibung
name	string | z.input<typeof stageGoToNameSchema>	Name der Ziel-Stage, oder ein Objekt gemäß stageGoToNameSchema.

Objekt-Form (validiert über stageGoToNameSchema):

Feld	Typ	Pflicht	Beschreibung
name	string	✔	Name der Ziel-Stage.

Rückgabewert: Promise<void>

Nichts.

.next()

Navigiert zur nächsten Stage.

Rückgabewert: Promise<void>

Nichts.

.prev()

Navigiert zur vorherigen Stage.

Rückgabewert: Promise<void>

Nichts.

.restore()

Stellt die zuletzt gespeicherte Stage wieder her (z. B. nach Seiten-Reload).

Rückgabewert: Promise<void>

Nichts.

.list(includeHidden?)

Gibt die Namen aller Stages zurück.

Parameter	Typ	Beschreibung
includeHidden	boolean | z.input<typeof stageListSchema>	true, um auch ausgeblendete Stages einzuschließen, oder ein Objekt gemäß stageListSchema.

Objekt-Form (validiert über stageListSchema):

Feld	Typ	Pflicht	Beschreibung
includeHidden	boolean	–	true, um auch ausgeblendete Stages einzuschließen.

Rückgabewert: string[]

Liste der Stage-Namen.