Guide

Build a Game

Create LLM-driven text adventures with character sheets, game state, and a player input loop — all in Margarita.

Margarita
dungeon-quest.mgx
---
model: claude-sonnet-4-6
---

@state type
<<
Ask the user to pick between a mage and a fighter.
Ignore any other response and ask them again.

Set the `type` variable with their choice (lowercase).
>>

@effect run
@effect context clear

<< This is your Character >>
if type == "mage":
    [[ src/mage.mg ]]
elif type == "fighter":
    [[ src/fighter.mg ]]

<<
Tell the user about their character — name, backstory, abilities.
>>

@effect run
@effect context clear

if type == "mage":
    [[ src/mage.mg ]]
elif type == "fighter":
    [[ src/fighter.mg ]]

@state isFree = false
@state health = 100

<<
Your character awakens in a dungeon. The goal is to escape.

Use the character sheet to inform encounters and decisions.

Each turn:
1. Give a narrative response to the player's action.
2. Present the player with choices.
3. Track `health` — if it reaches 0 they die.
4. When they escape, set `isFree` = true.

Begin: the player awakens in the dungeon with no memory of how they got there.
>>
@effect run

for i in range(0, 100):
    @effect input "What do you do?" => action

    <<
    Turn: ${i}
    Action: ${action}

    Respond and create the next choice.
    >>

    @effect run

    if health <= 0:
        << The Dungeon has claimed your soul. Try again! >>
        @effect run
        break

    if isFree:
        << Congratulations — you have escaped the dungeon! >>
        @effect run
        break

src/mage.mg

Character sheet for Lyra Veyne. Included via [[ src/mage.mg ]] whenever the player chooses the mage class.

---
description: Mage character sheet — Lyra Veyne, the Ashen Seer
---
<<
## Character Sheet: Lyra Veyne — The Ashen Seer

**Age:** 32  |  **Origin:** Borderlands of a fallen empire

### Backstory
Sole survivor of a mage order whose forbidden ritual went catastrophically wrong.
Driven by visions of the catastrophe she failed to prevent — and the next one she
keeps seeing in flames.

### Attributes
- Intelligence: High
- Willpower: Very High
- Perception: High
- Constitution: Low

### Magic
- **School:** Pyromancy & Divination
- *Cinder Sight* — glimpses possible futures in flame
- *Ashfall* — rains burning embers over an area
- *Ember Step* — short-range teleport through fire

### Combat Style
Mid-range control and burst damage. Strong against groups, fragile if cornered.

### Gear
Obsidian focus ring (cracked), half-burned spellbook, vials of ash and sulfur.
>>

src/fighter.mg

Character sheet for Garrick Holt. Included via [[ src/fighter.mg ]] whenever the player chooses the fighter class.

---
description: Fighter character sheet — Garrick Holt, the Ironbreaker
---
<<
## Character Sheet: Garrick Holt — The Ironbreaker

**Age:** 41  |  **Origin:** Northern frontier strongholds

### Backstory
Former captain of the Stoneguard, sole survivor of a doomed defensive battle.
Carries survivor's guilt but channels it into protecting others. Looking for a
cause worth standing ground for again.

### Attributes
- Strength: Very High
- Endurance: Very High
- Perception: High
- Charisma: Low

### Combat
- **Style:** Heavy weapons, defensive frontline with shield control
- *Shieldbreak* — staggers enemies with a crushing bash
- *Last Stand* — fights on despite critical wounds
- *Lineholder* — holds the line and steadies allies

### Gear
Tower shield, warhammer with a cracked haft, old military insignia.
>>

Ready to run the dungeon?

Grab the example from the Margarita playground and start your own game.

Read the Margarita Docs Back to Margarita