The Fiction item type is an interactive fiction activity aka "choose your own adventure." Old school computer users might remember games like "Zork" or "The Count" where the user's choices determine the direction the story takes. You can play a simple MiniLesson Fiction item example here
https://demo.poodll.com/mod/minilesson/view.php?id=1867
Yarn Format
The story is written in a text format called "Yarn". Read more about Yarn at: https://docs.yarnspinner.dev/beginners-guide
We are using version 2.0. So some of the newer syntax is not available. A very simple story looks like this.
--------------------------------------------------------
title: Start --- <<picture 01.png>> Thom: I wake up in a casino hotel room, feeling disoriented. Thom: I need to find the contact in the casino to obtain the secret data files. -> Head to the casino floor <<jump CasinoFloor>> -> Just give up <<jump TheEnd>> === title: CasinoFloor --- <<picture 02.png>> Narrator: The casino is bustling with people, lights, and sounds. I need to stay focused. -> Take the elevator <<jump ElevatorScene>> -> Just give up <<jump TheEnd>> === title: ElevatorScene --- <<picture 03.png>> Narrator: In the elevator, I encounter a suspicious guest who eyes me closely. SuspiciousGuest: You look like you're up to something. -> Give up <<jump TheEnd>> -> Return to the Casino Floor <<jump CasinoFloor>> === title: TheEnd --- Narrator: This is the end. ===
Notes on Yarn
Nodes: A story is split into sections called "nodes." You can think of them as scenes. Each node must begin with a title and then three hyphens on a new line. The title should have no spaces and be in ascii characters e.g
Title: somescene ---
NB the first node in the story must be titled: "Start"
The end of the node is three equals signs on a new line. i.e
===
NB When the end of a node is reached the story ends. So unless the story should end, nodes should jump to another node before they reach the node end.
Dialog should start with the character's name (with no spaces) a colon and the text. e,g
Jenny: Look what we have here ..
Options that the user must choose from start with arrows (a hyphen and a greater than sign): ->
After each option, and at the same level of indentation, set what follows from selecting the option. Often that will be a jump to another node. e.g
-> Give up <<jump TheEnd>> -> Return to the Casino Floor <<jump CasinoFloor>>
Commands start with << and end with >>
The most common command is:
<< jump [nodename]>>
Variable commands are used to declare and set variables. Variables must be declared before they are used. And they must be set within a node (ie not at the very top of the Yarn text file)
<<declare $varname = true>> <<declare $lives = 3>> <<set $lives = $lives - 1>> <<set $varname = true>>
You can display the value of variables in dialog output by surrounding the variable name with curly braces {}. e.g
Harry: But I only have {$lives} left!!Conditional Commands are: if else elseif and endif. Use these in combination with variables to track the state of aspects of the game, and branch the narrative accordingly
<<if $lives == 0>> <<jump theend>> <<else>> Narrator: That was lucky <<endif>>
Pictures / Audio / Video - Poodll MiniLesson adds three custom commands for adding images, audio or video to the story. The media file should be uploaded into the attachments area of the Fiction item settings page. The filename of the media file goes into the custom command, e.g
<<picture 01.png>> <<audio hungrycat.mp3>> <<video creepycastle.mp4>>
Debugging your Yarn tory
NB When there is a mistake in the Yarn format the story will crash with a red error message. If it is not clear what is wrong, you might need to paste the error AND your yarn story into Chat-GPT / Gemini / DeepSeek and ask it:
"Can you see a reason why this yarn spinner v2.0 formatted interactive story is throwing an error when parsed by bondage.js? "
[paste error]
[paste yarn text]
NB The most common error is not starting the story with a node titled "Start" . It must start with "Start"
If the story crashes midway usually it will be when you jump to a node that has an error in it. Examine the node carefully. In particular make sure that any variables used have been declared correctly, any node names referenced are correct, and check that <<if>> conditionals are closed properly with <<endif>>