Hey, Listen! - Make Your Own Tutorials

Hey, Listen! - Make Your Own Tutorials 0.1.1 for Minecraft 1.21.1 (NeoForge)

First public release. Early alpha.

NEW IN 0.1.1

Two built-in lessons that teach the mod using the mod, so you learn it by being walked through it rather than by reading a format document.

• "How to make a tutorial" takes itself apart while you stand in it. It names the field its own text came from, darkens the screen and tells you which element did it, punches a hole over your hotbar to show what a parent is, and then stops talking and waits for you to really open your chat. /heylisten start heylisten:how-to-make-a-tutorial
• "How to make a quest" offers a choice so you watch a branch happen, writes a variable onto you and tells you how to read it back, then sends you off to break a block and steps aside while you do it. /heylisten start heylisten:how-to-make-a-quest

THE PLAYER RUNTIME

Everything needed to write and run a tutorial, deliberately without an in game editor: the runtime gets proven on a real pack first.

• Steps that dim the screen, cut a hole over one exact thing, say a line, and refuse to advance until the player does it.
• Every mark hangs off a parent (slot, widget, HUD region, or a letterboxed virtual canvas) resolved fresh every frame, so highlights survive a GUI scale change, a resolution change and a mod shifting its own window.
• Marks: dim, cutout, box, line, arrow, circle, freehand pen, text and image.
• Completion triggers: Next, timeout, screen opened or closed, key pressed, slot or widget clicked, kill, item obtained, item used, block placed, block broken, position, dimension, advancement.
• Input locks: freeze movement, pin a screen open, or allow only named keys, all under a hard ceiling from the config.
• Dialogue steps with branching reply buttons, writing per player variables that survive death and logout.
• Characters are folders of images and expressions are filenames. PNG, JPG, BMP and TGA. A matching _talk frame animates the mouth while text types.

AUTHORING

• Tutorials load from config/heylisten/tutorials/.json, and from a datapack at data/<pack>/heylisten/tutorials/.json for pack authors. Config files win on an id collision, so a player can override a pack's tutorial without editing the pack.
• /heylisten new <name> writes a working three step starter and loads it.
• /heylisten new quest <name> writes a quest instead: an offer with replies, a counted gather step, an advancement gate and a reward.
• /heylisten reload re-reads only your tutorials, so the edit and test loop does not rebuild every recipe in a large pack.
• /heylisten folder opens the tutorials folder in your file browser.
• The folder regenerates HOW-TO-WRITE-A-TUTORIAL.md on every launch: the whole format in one document, so you never leave the game to look up syntax.

NOBODY GETS STUCK

• /heylisten validate catches a step that locks the player out of the action that would finish it, before it ships.
• Dying releases every lock, then picks the tutorial back up at the same step once you respawn.
• Logging out and changing dimension release everything.

DISPLAY

• The guide uses the full panel while it talks, then collapses into a small corner card holding just the objective once a step is only waiting on the world, and the darkness lifts so the game is playable.
• A server counted progress figure is shown for goals that want more than one of something.
• The panel takes its position from the live HUD, so it never covers the hotbar and never covers the thing the step is pointing at.

KNOWN LIMITATIONS

• No default character art ships yet. A tutorial runs fine without it, but the guide has no face until you add a character folder.
• Mods that draw their own UI instead of using vanilla widgets, such as Create and MineColonies, are not yet verified for slot and widget highlighting. Use /heylisten debug on a screen to see what it exposes, and use a screen parent where it exposes nothing.
• The panel can cover the middle of an open screen. Clicks pass through to the slots underneath, so it works, but it is untidy.
• No in game editor yet. Tutorials are written as JSON.