> For the complete documentation index, see [llms.txt](https://docs.siminsights.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.siminsights.com/spark/building-a-spark.md).

# Building a Spark

The scenario flow, state actions, transitions, character settings and knowledge base behind a Spark.

[spark.siminsights.com](https://spark.siminsights.com) lists the Sparks that you own or that are shared with you. **Create New**, top right, starts one. The **My Sparks** dropdown switches to Sparks other people have shared with you. On each row, the pencil opens the editor, the play button experiences it as a learner would, and the three dots share or delete it.

<figure><img src="https://2704613365-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYaaXoZ4YGbVdAnAhdcE%2Fuploads%2FgzTMjwefwLdW0wSnBhfS%2Fimage.png?alt=media&#x26;token=b263a8ab-5be6-4646-8e26-e7f02ba6e6ce" alt=""><figcaption></figcaption></figure>

## Scenario Flow

The scenario flow controls the order of events. It is a graph of states: each one holds **state actions** that fire when the learner arrives, and **transitions** that decide when they move on.

| State action                | What it does                                                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Set Data**                | Creates the AI character: name, profile picture and voice.                                                                               |
| **Speak**                   | A scripted line from that character.                                                                                                     |
| **Narration**               | A line belonging to no character. It appears differently in the chat panel.                                                              |
| **Display Message**         | A popup, usually used to introduce the scenario. It stays in the chat history so the learner can look back at it. Markdown is supported. |
| **Change Character Prompt** | Swaps the instructions the character is running on.                                                                                      |
| **Add Feedback Log**        | Sets what the learner sees when they end the Spark. See [Scoring and feedback](https://docs.siminsights.com/spark/scoring-and-feedback). |
| **Reset chat**              | Clears the chat history. Worth doing straight after changing the character prompt, so the character has no memory of what came before.   |

Transitions:

* **Voice intent** moves on when the learner's input contains one of the phrases you list.
* **Wait** moves on after a set time.

<figure><img src="https://2704613365-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYaaXoZ4YGbVdAnAhdcE%2Fuploads%2FPiv1kwIpTgNHC1wbn1la%2Fimage.png?alt=media&#x26;token=7b52ad7e-5e40-41d8-a705-b2c6fe30f582" alt=""><figcaption></figcaption></figure>

## AI Settings

**AI Behavior** is the character: its picture, name and prompt.

**Character voice** comes from Google or ElevenLabs. Google is faster and free; ElevenLabs sounds more natural.

**Enable AI Chat** is always on in a Spark, because the chat box always uses AI Chat. This setting cannot be changed.

**Language Model** picks which model runs the conversation: GPT-4o mini, GPT-4, GPT-4o or Gemini. See [Large Language Models & Data Privacy](https://docs.siminsights.com/hyperskill-studio-authoring/ai-features/large-language-models-and-data-privacy).

**Chunk Response** streams the reply as it is written instead of waiting for the whole thing.

**Enable PDF Context** lets the character use documents you upload under Knowledge Base.

## Agents

Agents analyze the conversation and produce outputs. They run when the learner ends the conversation. Their outputs fill feedback templates and, when scoring is enabled, write to user-attribute scores. See [Scoring and feedback](https://docs.siminsights.com/spark/scoring-and-feedback).

## Knowledge Base

PDFs the character can refer to during the conversation. Upload them here, and turn on **Enable PDF Context** under AI Settings, or they are ignored.

## Appearance

**Layout** is either **Background with chat**, which puts a scenario image behind the chat panel, or **Chat full-screen**, which is the chat alone. The background is a PNG or JPG up to 8MB.

<figure><img src="https://2704613365-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYaaXoZ4YGbVdAnAhdcE%2Fuploads%2FjmVgnkKGbRM3GVjHc9LL%2Fimage.png?alt=media&#x26;token=10702b8c-86f3-44e9-8161-5274aba260f3" alt=""><figcaption></figcaption></figure>

## Settings

Turn microphone input on or off. This is the difference between a Spark a learner can speak to and one they can only type in.

## Publishing

The top bar of the editor shows a **Saved** indicator, then help, share and save icons, the **Open experience** button and a close button. **Open experience** plays the Spark as a learner would, on spark.siminsights.com in a new tab.

A Spark is published when you play it once. Playing it generates a public link, and until you do, nobody outside the editor can open it.