fxgl-narrative

name	fxgl-narrative
description	Implement cutscenes, dialogue, and video scenes in FXGL — create text cutscenes with CutsceneService, load and play branching dialogue graphs from JSON, run the DialogueScriptRunner with function nodes, play video cutscene files, trigger narrative scenes from collision or game events, and build custom dialogue UI. Use this skill when adding story sequences, NPC conversations, intro/outro scenes, branching player choices, or scripted in-game events.
triggers	["cutscene","dialogue","DialogueGraph","CutsceneService","branching dialogue","NPC conversation","VideoScene","narrative","story","dialogue tree","script runner"]
compatibility	Java 17+, FXGL 21.x. CutsceneService must be registered. Video requires JavaFX Media.
category	fxgl/narrative
tags	["fxgl","java","javafx","narrative"]
metadata	{"author":"fxgl-skills","version":"1.0","fxgl-version":"21.1"}
allowed-tools	["Read","Write","Edit","Bash"]

FXGL Narrative System

Setup

// Register in initSettings
settings.addEngineService(CutsceneService.class);

Text Cutscene (Line-by-line)

A cutscene is a sequence of spoken lines. The player clicks to advance. The game loop pauses automatically.

// Build a cutscene programmatically
List<CutsceneLine> lines = new ArrayList<>();
lines.add(new CutsceneLine("Guard",   List.of("Halt! Who goes there?")));
lines.add(new CutsceneLine("Player",  List.of("I am the chosen one.", "Stand aside.")));
lines.add(new CutsceneLine("Guard",   List.of("By the king's order...", "...you may pass.")));

Cutscene scene = new Cutscene(lines);

// Play the cutscene
getCutsceneService().startCutscene(scene, () -> {
    // called when player clicks through all lines
    openGate();
    resumeGame();
});

Dialogue Graph (Branching Dialogue)

The dialogue graph is created in the FXGL Dialogue Editor (or authored as JSON). Save dialogue files to src/main/resources/assets/scripts/dialogues/.

Loading and playing

// Load graph from asset
DialogueGraph graph = getAssetLoader().loadDialogueGraph("dialogues/merchant.json");

// Play — game pauses during dialogue
getCutsceneService().startDialogueScene(graph, () -> {
    // called when dialogue reaches EndNode
    enableMerchantTrade();
});

Wiring function nodes to game code