Tutorials

Tutorials combine guided steps, screen-specific guidance and short popups. Completion is versioned in one local file, so the same installation remembers a tutorial across worlds and servers; the server can request playback but does not own that progress.

What it does

Use api.tutorial.TutorialAPI on the server and api.client.tutorial.TutorialClientAPI on the client. Definitions, steps, targets, bounds and images are public types under api.client.tutorial. The manager, registry, bounds reporters and editor under client.tutorial are implementation entry points, not public facades.

Definitions are registered in Java during client initialisation. There is no tutorial JSON loader. The server packet isekaiexpansion:trigger_tutorial carries a tutorial identifier and replay boolean, without definitions or progress.

Runtime model

Definition kinds and built-ins

Only one interactive tutorial is active. Queued guided IDs are deduplicated; an already active ID is not queued again. A forced guided replay interrupts the active tutorial but does not clear the existing queue. An unknown ID logs a warning. A normal request for a screen tutorial is ignored; replay clears its completion and starts it immediately only if its screen is already open, a player exists and no other tutorial is active.

The client ticks the manager at end tick. Losing focus, a cinematic input lock, an unavailable target context or the bounds editor hides guidance and resets held progress. HUD steps require no open screen; screen targets require a matching screen. A scheduled advance is processed before most context gates, after the bounds editor check; it is not a second validation of the original action.

Progress storage

The game-directory file isekaiexpansion-tutorials.txt contains the following text format:

format 1
completed isekaiexpansion:adventurer_basics 2

Blank lines, comments beginning with #, malformed records, invalid IDs and invalid versions are ignored. Writes sort IDs, write a sibling .tmp file and replace the destination atomically where supported, with a non-atomic replacement fallback. Read/write I/O failures log warnings. No active step or queue is persisted. Disconnect clears runtime state, while completion remains.

Contracts

Definition and step fields

At runtime screen matching walks the actual class’s superclass chain. Registration order selects the first matching screen tutorial, rather than the most specific class. Completion of that first match does not cause the registry to search for another matching tutorial.

Inputs and timing

E and Escape are consumed during guidance, including release protection across transitions. Resolved non-E bindings and matching mouse buttons can still reach gameplay after scheduling advancement. Holding Escape cancels pending advancement and other hold progress. An action step has no E fallback. Releasing a held binding resets its timer.

Targets and illustrations

Internal TutorialHudBounds keeps the last valid report for the requested ID in a frame. TutorialScreenBounds accepts only the exact requested screen instance and unions its valid matching reports. Both ignore nonpositive sizes. Report in scaled GUI pixels after the corresponding frame reset; a screen report is not a persistent registration. Missing images retain their authored space and frame.

Extending it

Register this example from a client initialiser; its keys must also exist in both language assemblies. Imports come from api.client.tutorial, Minecraft Identifier and java.util.List.

public static void registerExampleTutorial() {
    Identifier tutorialId = new Identifier("example", "first_jump");
    TutorialClientAPI.register(new GuidedTutorialDefinition(
            tutorialId, 1, List.of(
                    TutorialStep.hold("tutorial.example.welcome.title",
                            "tutorial.example.welcome.body"),
                    TutorialStep.keyPress("tutorial.example.jump.title",
                            "tutorial.example.jump.body", "key.jump")
            )));
}

All facade arguments above are non-null. Playback and action calls mutate the client manager directly: invoke them on the client thread, using MinecraftClient.execute when dispatching from another thread. Register definitions before requesting them. Keep client definitions and classes out of dedicated-server initialisation; server code only needs the identifier and server facade.

For relative targets, press Control + the restart binding to open the bounds editor, drag with the left mouse button, and press Enter to copy a Java target expression to the clipboard and chat. Escape cancels. Selections must be at least 4 × 4 scaled pixels. Screen mode captures the current screen’s class and closes if that exact screen changes; HUD mode closes when a screen opens. Resizing preserves the normalised selection and ends a drag. The tool emits 6 decimal places and never edits source files.

Verifying

Use permission level 2 commands /ise dev tutorial show <id> [targets] and /ise dev tutorial replay <id> [targets]. Omitted targets require a player source. Suggestions contain only the 3 built-in IDs, but any identifier can be typed; success counts packet recipients, not actual displays.

Check normal versus forced playback, a version increase, skipping, disconnect, and a new world on the same installation. Check screen close/reopen, subclass trigger ordering, an absent bounds reporter, GUI scaling, unavailable key bindings and an action notification delivered before its step. Confirm E/Escape releases do not open inventory or pause immediately after guidance. Test a dedicated server with definitions registered only on clients, and inspect the progress file after completion or restart.

Related

• Fate Balance API — another client presentation with server-owned gameplay state.
• Persistent state — world storage, distinct from tutorial completion.