Yellowood Guide

Yellowood is a multi-linear story telling platform. That means you can create and play stories with branching paths, multiple endings, and player choice.

In this guide we will cover the basics of how to create a story with Yellowood.

Story

A story is the top-level container for everything — the story title, description, scenes, characters, and other game objects.

Creating

Create a story from your user profile page. If it's your first time writing a story you can make a copy of the example story. Look for these buttons:

When you create a story you give it a few details:

• name: required
• slug: required, URL safe identifier. Auto matches the title, but can be manually set
• description: optional
• cover image: optional, image shown on the story card

A story's slug becomes its URL: /u/username/story-slug. An editor story's slug can be changed but once a story is published the slug cannot be changed.

As of now, image uploads are not supported, but you can link to any public image on the web for your cover image.

There are three types of stories on your profile:

• Editing — a story you are actively working on. Only visible to you. Can be edited and published.
• Published — a story that is live on your profile and the browse page. Visible to everyone. Cannot be edited, but can be unpublished (deleted) and republished later.
• Shared with me - a story owned by another user that you have access to edit. Visible to you and the owner. Can be edited by you, but only the owner can publish and delete it.

You can only have up to 20 editing stories, but you may have as many published stories as you want.

Editing

Select the Edit button on the story card to open the editor. The editor is where you create and edit your story's content — scenes, characters, and other game objects (more on all of this later).

If you want to collaborate with others, you can grant them access in the Settings popup. Collaborators can only edit the story, not publish or delete it. You can revoke access at any time.

Playtesting

You can playtest your story by clicking the View button in the editor. This will open a new window where you can experience your story as a player would. This page is only visible to you and other editors.

You can playtest from the @intro scene or from the currently open scene. Playtesting from the current scene is useful for quickly testing a specific part of your story without having to go through the whole thing, but keep in mind the game state (like story-events) will not be set up as it might when a player reaches that scene in a real playthrough. Because of this, it is useful to setup a test scene that points to the scene you want to playtest that applies any necessary state.

Publishing (and Extracting)

When a story is ready to share and be played, you can publish it.

To publish a story, click the Publish button in the editor to open the Publish dialog. You will first have to validate that the story can be published. Validating returns a few types of messages:

• Errors - indicate problems that must be fixed before publishing.
• Warnings indicate potential issues that won't block publishing but should be reviewed.
• Suggestions are actionable recommendations to improve the story.

When you publish a story, it becomes visible on your public profile and the browse page, and allows other users to play it. The editor story remains in your dashboard so you can make changes and republish later if you want.

When you publish a story, its slug becomes fixed. Changing the story name after publishing does not change the slug or URL. If you no longer want the story to be public, you can delete it and still have the editor story to make changes and republish later.

If you don't plan on making further changes, you can delete the editor story and the published story will still be available to play. If you deleted the editor story but want to make edits, you can extract the published story to create a new editor story with the same content.

Scenes

A story is made up of scenes.

Scenes are identified by a slug - like forest-path or boss-fight. These slugs can be used like folders, so you can have forest-path/clearing and forest-path/cave if you want to group related scenes together.

In the top right corner of the editor, use the Open button to open scenes, or the Create button to add a new scene.

To rename a scene, simply Save it with a new slug then delete the old slug from the scene list.

Required Scenes

Each story is required to have a few named scenes.

• @intro - which plays when the game is first opened
• @start - the default entry point after the intro finishes
• @end/ - any scene whose slug starts with @end/ can end the game
• @credits - which plays after the game ends

These required scenes are created automatically when a story is created. Each have a few specific restrictions on which components they can use and how they can connect to other scenes.

@intro

The @intro scene runs before the player starts the game. It is best used to set the background color or image and show the title of the game.

The @intro scene must end in a end component and cannot use scene-change components.

At the end of the @intro scene, the player is presented with the option to "Start Game".

@start

The very first scene that plays once the player starts the game is the @start scene. This is a good place to add intro narration.

The @start scene can use scene-change components to point to other scenes, but it cannot use end components.

@end/

Any scene whose slug starts with @end/ — for example @end/good-ending or @end/bad-ending can end the game. That means @end/ scenes can use end components.

@credits

The @credits scene plays after the game ends. Use it to display names of collaborators like other writers, artists, or playtesters.

The @credits scene must end in an end component and cannot use scene-change components.

Scene Types

There are two types or categories a scene can be:

• directional - a scene that leads to another scene
• return - a scene that acts like a subroutine

A scene's type can be set when a scene is created or when a scene is saved.

Directional Scenes

Directional scenes are the most common type of scene. They lead to another scene at the end. All required scenes are directional scenes.

Return Scenes

Return scenes are reusable sequences that can be called from other scenes. When a return scene finishes, it returns to the same scene component that it left from. This is useful for reusable sequences, like setting the games color config.

Return scenes must end with an end component, and cannot use scene-change components.

Scene Components

Each scene is a sequence of components that point to one another. They are run one at a time as the player progresses through the story.

Some vocabulary to know when talking about scene components:

• Scene Component - The underlying data that defines a part of a scene is called a scene component.
• Node - In the editor, scene component data is displayed in editable boxes called nodes.
• Widget - In the game, scene components with content to display are shown in a widget.

In the editor, scene components contain form field elements like dropdowns, text inputs, and toggles that you can use to configure that component's behavior.

Scene components also have handles at the top and bottom that can be connected to other components to create a path through the story. The handles at the top are for incoming connections, and the handles at the bottom are for outgoing next connections. They can be connected by clicking on any handle and dragging to another component's valid handle.

Tricks: You can create a new-node by dragging from a node's next handle to an empty part of the canvas. This will create a new-node, connected to the original node. You can also create a node of a suggested type by clicking the buttons that appear on the right side of a selected node.

Scene component nodes are color coded by type:

• green for starting components
• blue for story components
• purple for flow components
• yellow for visual components
• red for ending components
• black for comments and other editor utilities

Starting

These components, in shades of green, are typically used at the start of a scene.

start

Every scene starts with a start component. It is required to have exactly one start component on each scene. For that reason, this component cannot be added in the sidebar or deleted from the scene.

On the start component, you can see which other scenes point to this scene.

title

The title component clears the screen and displays a large text title. This is best used in the @intro and @start scenes, as well as any scene with notable changes in settings (like entering a new area).

It is recommended, but not required, to precede title components with continue components to give the player time to ready anything on screen before it clears.

continue

Shows an option the player must select to advance past this point. Use it to pace the narrative and give the player control over when to proceed. If you are going to have a large blocks of texts, perhaps you are introducing lore, it is wise to break up the text with continue components to give the player time to read everything.

Storytelling

These components, in shades of blue, are used to tell the story and make changes to the game state.

dialog

Types text across the screen. This is where the bulk of your storytelling will live. You can leave the speaker blank for narration, or attribute it to a character from the noun registry. If a character is speaking, this will show the character's name in color and print the text in a talk bubble.

The dialog itself is written in markdown.

You can **bold** or *italicize* text.
Create pauses with line breaks.

Create new paragraphs with double line breaks.

And create text colorful pills for named characters, inventory items, status effects with backticks like this: `CHARACTER_ID`.

You can also `alias|CHARACTER_ID` these pills to display different text than the noun's name. 

apply

An apply component modifies the state of the game world. Use it to:

• record a story-event
• add or remove an inventory-item
• apply or remove a status-effect
• or change a point-tracker's value

When some types of apply components are reached in game, a small line of text explaining what happened will be displayed.

These values can be configured in the Noun Registry and can be checked in the condition component to create branches in the story.

Flow

These components, in shades of purple, create branches in the story. These components often have multiple outgoing handles to create different paths through the story.

choice

Presents options to the player. Options can be written with markdown like dialog.

Returning to a choice component within the same scene will hide already chosen options, allowing you to reuse the same choice component. This is useful for when you want the player to ask for more information before moving on, or if they "chose wrong" and will need to choose again.

A choice component is allowed to have only 1 option, which is the same as a continue component but with whatever text you sent.

During gameplay, the choice widget will also pull in data from any valid action components as additional options (see action below). Because of this, a choice component is technically allowed to have no options, although it is not recommended without proper playtesting.

action

Adds an option to a choice widget's options for any choice in the whole scene. This is useful for when a player is always allowed to "Leave" the scene or use an item. When using an inventory-item in an action, that item's instances are automatically decremented by 1, so it can be used up and become unavailable in the future.

dc-roll

Rolls dice against a difficulty class and branches based on the outcome. The roll type and difficulty can be configured.

The roll type can be set to default (one d20) or advantage/disadvantage rolls (2d20), which roll two dice and take the higher or lower result respectively.

The difficulty class can be set to a static number:

• 2-20 - most common use case
• 21-30 - requiring positive status effects
• 100 - requiring a critical success

The roll node is required to branch to a success path and a fail path. It can also branch to a critical success or critical fail path.

Yellowood uses natural and pair crits. A pair crit happens when on an advantage or disadvantage roll, both dice show the same number. If that number is higher than the difficulty class, it's a pair critical success. If it's lower, it's a pair critical fail.

Rolls can be augmented with any status-effects that have remaining instances. After the roll the status-effect instances are decremented by 1. (More on status-effects in the noun registry section of the guide)

condition

Branches based on the current state of the game. For example: if the player has a key in their inventory, go one way; otherwise go another. There are many different types of conditions:

• hasProperty - if a player has a noun applied to them
• questLine - if a quest line is at a certain stage
• scorePoints - if a point tracker is above or below the threshold value (specified on the noun)
• countPoints - if a point tracker is above or below a certain value
• countCategory - if the number of nouns in a certain category is above or below a certain value
• compareCategory - if the number of nouns in one category is above or below the number in another category
• countInstancesRemaining - if a noun has a limited number of instances, this checks if the remaining count is above or below a certain value
• compareInstancesRemaining - if a noun has a limited number of instances, this checks if the remaining count is above or below the remaining count of another noun

random

Randomly selects one of several paths. Useful for varying repeated encounters or adding unpredictability. This node only has one handle at the bottom that can be connected to any number of next nodes.

Visuals

These components, in shades of yellow, change the visual appearance of the game.

color

Changes the background, text, and dice color on the screen.

visual

Can be used to change or clear the background image. It can also be used to display or hide a live point tracker.

Ending

These components, in red, end the scene or transition to another scene.

scene-change

Transitions the player to a different scene. If transitioning to a return scene, then a scene-change node will have a handle that must point to a next component.

end

Ends the current scene. In a return scene, this returns control to the calling scene. In other scenes it behaves like a scene-change but to a required scene, like @start or @credits.

Editor Utilities

comment

A comment node that can be used to leave notes to yourself or collaborators. Comment nodes are not connected to the story flow or visible to the player.

If you want to force a comment to block a publication, check the "Blocking" checkbox. Any blocking comments will show up as errors during validation.

Noun Registry

The noun registry is a database of named game objects that exist across your story. Nouns track state — inventory, quests, points — and can be applied and checked by scene components. While it is not necessary to create nouns to make a story, they can be very helpful in making your story more dynamic.

The noun registry editor can be opened by clicking any of the noun icons in the top right of the editor.

Each noun has an ID (uppercase, like MAIN_VILLAIN), and a name that can be shown in the UI. Most nouns have additional properties as well.

character

A character is a named entity with a display color. Characters are used to attribute dialog — when a dialog component references a character, the character's name and color appear alongside the text.

Characters do not have inventory or stats of their own; they are purely for display attribution.

story-event

A story-event tracks progress through a quest or narrative beat. Events are organized into quest lines and move through stages:

• start — the quest has begun
• progress — the quest is underway (can have multiple progress stages)
• end — the quest is complete
• none (represented with a hyphen) - this is an invisible progress check

Quest lines group related events and display them in the player's journal panel.

story-events can be checked in condition components by their ID or their quest line and stage.

inventory-item

An inventory-item is an item a player can hold. Items are added to the player's inventory with an apply component and can be checked with a condition component.

In addition to id and name, an inventory-item can have a:

• category - a grouping mechanism for items. For example, you could have a KEY category and then have GOLD_KEY and SILVER_KEY items within that category.
• instances - the number of times a player is allowed to use an item, -1 for unlimited use.
• color - a color for display in text, unset for hidden in inventory

Instances can be increased or decreased with an apply component, and checked with a condition component. It is also decreased automatically in action nodes when the option is selected. This allows you to make items that can be used up, like a health potion that can only be used 3 times before it's gone.

status-effect

A status-effect is a temporary or permanent state applied to the player that affects their roll outcomes.

A status effect has an ID and name like other nouns, but also has:

• modifier - the type of die that modifies the player's roll
• color - for display in text and for the die representing the status effect
• instances - the number of times a status effect can be applied, -1 for unlimited use

A modifier die can be one of:

• -d8
• -d4
• +d4
• +d8

This selection of dice was made to make all dice in game (d4, d8, and d20) have triangular faces.

status-effects can also be checked in a condition component to branch the story.

point-tracker

A numeric value used to track points. A point-tracker also contains a success value that is used in the display to show the player how much progress they have made towards a goal.

A point-tracker can be incremented and decremented in an apply component, checked with a condition component, displayed using a visual component.

What's Next?

This concludes the guide to the Yellowood editor. You should now have a good understanding of how to use the editor and its features to create your own interactive stories.