Vai al contenuto

Creating a scenario

This guide walks through creating a complete scenario step by step, from planning to publication. For interface details, see Scenario Editor Interface.

Plan before building

Before opening the editor, it's useful to have a clear picture of the path structure:

  • What is the starting point?
  • What are the key decision points?
  • What are the possible endings?
  • Are there paths that reconverge or loops?

A sketch on paper or a mind map helps visualize the structure. It doesn't need to be perfect: the scenario will evolve during creation, but starting with a clear idea prevents getting lost.

1. Configure metadata

Open scenario-editor.html in your browser. The editor presents a new empty scenario containing only the Start node.

Before working on nodes, set up metadata by clicking Settings:

  • Title: the name that will appear in the Navigator header
  • Description: a brief description (optional, useful for remembering the purpose)
  • Author: the author's name (optional)

If the scenario will be in a language other than English, or you want to use different button texts, you must also customize the UI Labels to translate button texts (Step, Start Over, End of this path, etc.).

2. Build from the initial node

Start from the Start node and proceed depth-first:

  1. Select the node in the left column
  2. Write content in the Content block using Markdown syntax
  3. Add choices in the Choices block
  4. For each choice, select an existing node or create a new one with + Create new node

Continue this way for all nodes, branching the structure according to the initial plan.

Identifier conventions

Use short, descriptive names without spaces: intro, question_1, answer_ok, positive_ending. Identifiers are not visible to users but help navigate the structure.

3. Verify with the map

Periodically, use the Map button to visualize the entire structure. The map shows:

  • The general flow of paths
  • Any orphan nodes (red border) to connect or delete
  • Terminal nodes (orange border)
  • Loops, highlighted with orange connections

For color code details, see Map view.

4. Save regularly

There is no auto-save. Click Save frequently to avoid losing work. The button generates a JSON file to download.

The status bar at the bottom always shows if there are unsaved changes.

Managing terminal nodes

A node without choices is automatically a terminal node. In the Navigator, instead of buttons, the message "End of path" and a restart button appear.

  • To create a terminal: remove all choices from the node
  • To transform a terminal into an intermediate node: add at least one choice

Managing orphan nodes

An orphan node exists in the scenario but is not reachable from the start node through any path. The editor marks them with the "orphan" label in the list and red border in the map.

Orphan nodes are typically created when:

  • A node that was the only connection to other nodes is deleted
  • A choice that was the only path to a node is removed

To resolve: connect the node by adding a choice that points to it from some other node, or delete it if no longer needed.

Deleting nodes safely

To delete a node, select it and click DELETE in the Node block.

Warning

Deleting a node that has children can make those children orphans if they have no other connections.

Best practice: delete nodes starting from leaves (terminal nodes) and working back toward the root. This way you don't accidentally create orphans.

Creating loops

It's possible to create paths that go backward by connecting a node to one of its ancestors. In the map view, these connections are highlighted in orange.

Typical use cases:

  • Allow users to review a section
  • Create a main menu to return to
  • Handle errors with "try again"
  • Represent repeat ... until structures (or equivalents)

Adding resources

To attach documents, links, or videos to a node, use the Resources block. For details on available types and configuration, see Resources.

Resources appear in the Navigator as buttons below the node content.

Local resources

For local files (PDFs, documents), it's recommended to create a docs/ subfolder and use relative paths like docs/manual.pdf.

Modifying an existing scenario

To resume work on a scenario:

  1. Click Open and select the JSON file
  2. The scenario loads with all nodes in the left column
  3. Select a node to modify it
  4. Save changes with Save

From creation to publication

Once the scenario is complete:

  1. Save the JSON file with a descriptive name (e.g., new-employee-onboarding.json)
  2. Copy the file to the Navigator folder
  3. Modify config.json to point to the new scenario
  4. Test by opening choicemap.html

For details on publication options (intranet, GitHub Pages, embedding), see Publication.