Tracery is a JavaScript library, by GalaxyKate, that uses grammars to generate surprising new text.
It's already been used to generate text in several released games and projects, but we're still discovering what it's for!
Tracery is still a work in progress, and we hope to soon have a code-free, hosted online version, but this tutorial will help you get Tracery working with an existing Javascript project.
This is an interactive tutorial that will teach you the basics of Tracery syntax. For a real project, you'd import the library, create a grammar, and then create new text with mygrammar.flatten('someRule'), with detailed instructions at the GitHub repo.
this tutorial is also a work in progress! send feeback to kate {{galaxykate at gmail}}
1: Generating text!
Tracery uses grammars to generate text.
A replacement grammar takes a starting symbol, and replaces it with one of several rules
On the right (or below, depending on your screen size), you can see the json object that represents this very simple grammar. Farther right is the current start symbol ('animal') and a list of possible texts that it can generate.
Press the reroll button a few times to generate more. Not very interesting, yet, so lets get more complicated!
start symbol: animal
scorpion
sparrow
zebra
sparrow
sparrow
zebra
coyote
2: Rules within rules
Rules can call rules!
Take a look at the rule for 'sentence': 'The #color# #animal# of the #natureNoun# is called #name#'. Each of the words between two hashtags is a symbol to be replaced.
Try adding your name to the list of names, surrounded by quotation marks like all the other options. It will now appear in some of the generated text!
Note: JSON is very very fussy. There must be a comma between every option, but none after the last option
start symbol: sentence
The black raven of the tree is called Izzi
The black eagle of the ocean is called Yuuma
The black sparrow of the sky is called Mia
The purple sparrow of the forest is called Mia
The blue unicorn of the desert is called Chiaki
The indigo zebra of the river is called Arjun
The orange duck of the forest is called Mia
3: Adding your own symbols
Try adding a new symbol and a set of replacement rules.
How should this story end? You could add a 'mood' symbol so that Darcy the blue raven is [happy, sad, angry].
Or an 'occupation' so that Darcy is [a firefighter, a wizard, a scientist].
Again, JSON is fussy, so you must put a comma after every symbol line except the last. Advanced users can check the error log to see errors, but better error checking is coming soon -- kate
start symbol: sentence
Izzi the orange eagle was ... something.
Azra the purple sparrow was ... something.
Lina the orange lizard was ... something.
Darcy the turquoise sparrow was ... something.
Mia the white scorpion was ... something.
Darcy the purple lizard was ... something.
Mia the grey owl was ... something.
4: Modifiers
Sometimes you want to be able to capitalize or pluralize a symbol, or add a/an without worrying about which is correct. We provide a few modifier that you can put on the end of symbols with a dot separating them: 'animal.s.capitalize' will make an animal plural and capitalize it.
Useful modifiers are 's' for plural, 'ed' for past tense, 'capitalize' and 'capitalizeAll', and '.a' to add a/an in front. We are adding and improving these modifiers as we go. Advanced users can add more modifiers (drunk talk, pirate speak!) with javascript.
start symbol: sentence
White owls are almost always impassioned.
A raven is sometimes astute, unless it is an indigo one.
A zebra is often wistful, unless it is a turquoise one.
Purple sparrows are often impassioned.
A kitten is almost always wistful, unless it is a grey one.
A scorpion is rarely astute, unless it is an indigo one.
An eagle is always astute, unless it is a white one.
5: Saving Data
The syntax for saving information is powerful, but still getting worked out. Use it as you like, but in the future there may be a different syntax for future versions of Tracery!
Often you want to save information. Tracery allows you to call actions, which are bracketed statements that appear before symbols in a tag #[someAction]someSymbol#. In their basic form, they create some new rules and push them onto a symbol, creating that symbol if it didn't exist, or hiding its previous value if it did.
start symbol: origin
Izzi traveled with her pet lizard. Izzi was never astute, for the lizard was always too impassioned.
Chiaki traveled with her pet zebra. Chiaki was never wistful, for the zebra was always too astute.
Azra traveled with her pet owl. Azra was never wistful, for the owl was always too courteous.
Chiaki traveled with her pet eagle. Chiaki was never astute, for the eagle was always too astute.
Izzi traveled with her pet zebra. Izzi was never courteous, for the zebra was always too impassioned.
Darcy traveled with her pet duck. Darcy was never impassioned, for the duck was always too wistful.
Izzi traveled with her pet coyote. Izzi was never impassioned, for the coyote was always too courteous.
6: Super Advanced!
The syntax for saving information is powerful, but still getting worked out. Use it as you like, but in the future there may be a different syntax for future versions of Tracery!
Here is some especially advanced syntax for pushing new values, but choosing between multiple options to push. This demonstrates some of the power of the new syntax, for difficult tasks like specifying pronouns, or setting matched sets of objects.
start symbol: origin
Shadow was a great warrior, and this song tells of her adventure. Shadow saved a village from a dragon, then she saved a village from a dragon, then she went home to read a book.
Cheri was a great warrior, and this song tells of their adventure. Cheri saved a village from a witch, then they saved a village from a witch, then they went home to read a book.
Cheri was a great baker, and this song tells of her adventure. Cheri made croissants, then she baked bread, then she went home to read a book.
Cheri was a great warrior, and this song tells of their adventure. Cheri saved a village from a goblin, then they defeated a golem, then they went home to read a book.
Brick was a great warrior, and this song tells of their adventure. Brick saved a village from a witch, then they defeated a warlord, then they went home to read a book.
Zelph was a great baker, and this song tells of his adventure. Zelph folded dough, then he folded dough, then he went home to read a book.
Shadow was a great warrior, and this song tells of their adventure. Shadow saved a village from a dragon, then they fought a sphinx, then they went home to read a book.
7: Nesting stories
The syntax for saving information is powerful, but still getting worked out. Use it as you like, but in the future there may be a different syntax for future versions of Tracery!
Symbols can nest very deeply, and can even call themselves in a loop, so that stories can call stories about stories. But always have a non-recursive option, or your story will spin forever.
start symbol: origin
Once upon a time, Arjun the paleodoctor set sail for adventure. Arjun found an ancient book and opened it. As Arjun read, the book told a mysterious legend: Once upon a time, Izzi the time detective set sail for adventure. Izzi went home.
Once upon a time, Mia the technoscientist set out for adventure. Mia found an ancient book and opened it. As Mia read, the book told an eerie tale: Once upon a time, Chiaki the gentleman wizard left their home. Chiaki found an ancient book and opened it. As Chiaki read, the book told a mysterious legend: Once upon a time, Izzi the professional priest went to seek his forture. Izzi found an ancient book and opened it. As Izzi read, the book told a mysterious saga: Once upon a time, Darcy the space priest left her home. Darcy found an ancient book and opened it. As Darcy read, the book told an enchanting legend: Once upon a time, Azra the occult ballerina set sail for adventure. An old space detective told Azra a story. 'Listen well' she said to Azra, 'to this mysterious legend. ' Once upon a time, Mia the time spy set sail for adventure. Mia found an ancient book and opened it. As Mia read, the book told an enchanting legend: Once upon a time, Darcy the superpriest set out for adventure. Darcy went home.'
Once upon a time, Chiaki the professional scientist went to seek his forture. Chiaki went home.
Once upon a time, Chiaki the gentleman detective set out for adventure. Chiaki found an ancient book and opened it. As Chiaki read, the book told a strange saga: Once upon a time, Arjun the gentleman criminal set sail for adventure. Arjun found an ancient book and opened it. As Arjun read, the book told a mysterious saga: Once upon a time, Chiaki the professional lumberjack set out for adventure. Chiaki found an ancient book and opened it. As Chiaki read, the book told a mysterious tale: Once upon a time, Mia the erotic detective set out for adventure. Mia went home.
Once upon a time, Yuuma the paleodetective went to seek their forture. Yuuma went home.
Once upon a time, Chiaki the space wizard set sail for adventure. Chiaki found an ancient book and opened it. As Chiaki read, the book told a portentous legend: Once upon a time, Lina the supercriminal left his home. Lina found an ancient book and opened it. As Lina read, the book told a portentous legend: Once upon a time, Lina the time pirate went to seek his forture. Lina found an ancient book and opened it. As Lina read, the book told an enchanting story: Once upon a time, Darcy the space captain set sail for adventure. Darcy found an ancient book and opened it. As Darcy read, the book told a mysterious legend: Once upon a time, Azra the time spy set sail for adventure. Azra went home.
Once upon a time, Izzi the space scientist went to seek her forture. Izzi went home.