1 files changed, 123 insertions, 0 deletions
diff --git a/content/learn/04.sequences/default.md b/content/learn/04.sequences/default.md
new file mode 100644
index 0000000..cecbff8
--- /dev/null
+++ b/content/learn/04.sequences/default.md
@@ -0,0 +1,123 @@
+---
+menuTitle: Sequences
+title: "Introducing Sequences"
+weight: 4
+---
+In [the previous step](/learn/variables), we introduced variables. The story is
+starting to have branches, but writing them from within a `player_choice`
+construct is awkward. To resolve this, *sequences* are introduced.
+
+Sequences are named lists of instructions. They do *not* have to be defined
+before being used, but the definition must be found at some point. Since
+instructions do not return any value, neither do sequences.
+
+Sequences define their own context, meaning that `local` variables from outside
+the sequence cannot be accessed and, conversely, `local` variables from the
+sequence cannot be accessed outside of it.
+
+Entering a sequence can be done in two ways:
+* By visiting, in which case the sequence is executed and the story continues.
+* By jumping, in which case the sequence replaces the current story execution.
+
+When in doubt, prefer visiting to jumping, as the latter is mainly intended for
+optimization purposes.
+
+Sequences can be entered again from themselves, making recursion possible.
+
+Sequences can take parameters.
+
+
+**main.fate:**
+
+         (fate_version 1)
+
+         (global int hero_money)
+
+         (set hero_money 42)
+
+         Once upon a time, starting a story with these words wasn't considered
+         a cliche. Starting in a tavern might also not be seen as very
+         original.  Having the main character be an street orphan, raised by
+         some mysterious sage all to end up as a mercenary with an uncommonly
+         strong sense of honor probably isn't going to lead to any praises for
+         novelty either. Maybe you should drink to that.
+         (newline)
+         Or maybe you shouldn't. This isn't your first mug. Not your second
+         either.  Drinking to forget that you are a stereotypical hero isn't
+         going to solve anything. Worse, the alcoholic trait is part of the
+         image.
+         (newline)
+         As you contemplate your own pointless description, your gaze leaves
+         what turns out to be an already empty glass in your hand and finds the
+         barman.
+
+         (player_choice
+            (
+               ( Ask the barman for a refill )
+               (visit get_a_refill)
+            )
+            (
+               ( Fall asleep )
+               (jump_to fall_asleep)
+            )
+         )
+
+         (define_sequence pay ( (int cost) )
+            (set hero_money
+               (- (var hero_money) (var cost))
+            )
+         )
+
+         (define_sequence get_a_refill ()
+            (local int price_of_booze)
+
+            (set price_of_booze 12)
+
+            Staring straight at the barman, you raise your glass and proclaim:
+            (newline)
+            "This soon-to-be world savior needs more booze!"
+            (newline)
+            The barman's lack of reaction is disappointing, but seeing the beer
+            being poured does help improve the mood.
+            (newline)
+            Satisfied, you hand the barman (var price_of_booze) copper coins.
+            (visit pay (var price_of_booze))
+         )
+
+         (define_sequence fall_asleep ()
+            Deciding to break away from the expected storyline, you promptly
+            fall asleep.
+            (newline)
+            ...
+            (newline)
+            Upon waking up, your hard-trained reflexes inform you that someone
+            stole all your money.
+            (set hero_money 0)
+            (newline)
+            This set-back was more than you could take. You give up on this
+            barely coherent story.
+            (end)
+         )
+
+         (end)
+
+* `(visit get_a_refill)` makes a visit to the sequence `get_a_refill`. Since
+   that sequence does not take parameters, none need to be provided.
+* `(jump_to fall_asleep)` stops the execution of the main instruction list and
+  proceeds to using the sequence `fall_asleep` instead. Here again, no
+  arguments are expected by `fall_asleep`. Notice how the `fall_asleep` sequence
+  ends with `(end)`: since there is no return from it, the original `(end)`
+  would not be reached and thus a new one is required to end the story.
+* `(visit pay (var price_of_booze))` makes a visit to the `pay` sequence, which
+  does require a parameter.
+* `(global int hero_money)` has replaced `(local int hero_money)`, because that
+  variable needs to be accessible from within the sequences.
+* `(local int price_of_booze)` has been moved to the `get_a_refill` sequence,
+  as there is no reason to have it be defined across the whole story.
+* The `pay` sequence cannot directly access the `price_of_booze` variable, as
+  it is `local` and from another sequence, hence the use of a parameter to
+  communicate the correct amount.
+
+With this, the `player_choice` have become much more readable. However, the file
+itself is starting to become hard to read. The solution is then to [split the
+content into multiple files](/learn/files).