> ## Documentation Index
> Fetch the complete documentation index at: https://docs-vrsebuilder.autovrse.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Design System

> Basics of VRseBuilder

## Nomenclature

Understand the language that will serve as the base of the design system.

### Defining a Moment

A moment is one learning objective. It consists of one or more physical interactions that must be completed to meet that objective.

A chapter is a collection of moments, and a story is a collection of chapters.

```mermaid theme={null}
flowchart TD
    Story --> Chapter1
    Story --> Chapter2
    Story --> Chapter3
    Story --> ChapterN[Chapter ...]

    Chapter1 --> C1M1[Moment 1]
    Chapter1 --> C1M2[Moment 2]
    Chapter1 --> C1M3[Moment 3]
    
    Chapter2 --> C2M1[Moment 1]
    Chapter2 --> C2M2[Moment 2]
    Chapter2 --> C2M3[Moment 3]
    
    Chapter3 --> C3M1[Moment 1]
    Chapter3 --> C3M2[Moment 2]
    Chapter3 --> C3M3[Moment 3]
```

### Actions, Queries & Triggers

Every "moment" is made up of a series of actions and triggers that define what happens at that point in your experience. These are the fundamental components that are used to build your interactive narrative.

**Actions** describe changes that occur in the environment or objects.\
for eg: playing a sound, animating or moving an object, or updating a UI element

**Triggers** define when user input is needed.\
for eg: grabbing or placing an object, or pressing a button

**Query** refers to the specific object that the action or trigger is applied to.

### **Moment Lifecycle**

Each moment goes through a lifecycle of actions and triggers.

```mermaid theme={null}
flowchart TD
    Awake --> Start
    Start --> FW[FirstWarning]
    Start --> R[OnRight]
    Start --> W[OnWrong]

    %% Warning Path
    FW --> A1[Actions]
    A1 --> LW[LastWarning]
    LW --> A2[Actions]
    A2 --> FW

    %% Right Path
    R --> E[OnEnd]
    E --> NM[Next Moment]

    %% Wrong Path
    W --> A3[Actions]
    A3 --> W
```

1. **On Awake** - A list of actions
2. **On Start** - A list of actions
3. **On Right** - A list of triggers can be added here
4. **On Wrong** - A list of triggers can be added here
   1. A list of actions can happen after this
5. **On First Warning** - Automatically triggers after 5 seconds (configurable)
   1. A list of actions can happen after this
6. **On Last Warning** - Automatically triggers after 15 seconds (configurable)
   1. A list of actions can happen after this
7. **On End** - A list of actions

This structure can help you create a step by step flow for each moment of your story.

* Typically you use Awake to setup objects.
* Then perform actions that provide context to the user about what is going to happen in that step.
* Use the OnRight and OnWrong steps to collect user input; if the user does something wrong add actions that can guide them towards the right trigger.
* Warning actions assist a confused user by providing context about the step.
* End the moment and provide context as required.