A Beginner’s Guide to YAML for Worldbuilders

Welcome! If you’ve never written a line of “code” in your life, you’re in the right place. This guide will teach you everything you need to confidently fill in the YAML box on your tracked items. We’ll go one small step at a time, and every example is something you might actually use in a game.

Take your time. By the end, none of this will feel scary.

What is YAML?

In one breath: YAML is a tidy way to write down information so that both you and the AI can read it and change it during play.

That’s really all it is. When you store something in a tracked item, like a hero’s stats, a list of party members, or the contents of a treasure chest, YAML is the format you write it in. The AI reads what you wrote, understands it, and can update it as the story unfolds.

You don’t need to memorise anything. You just need to learn a handful of simple patterns, which is exactly what this guide gives you.

The One Golden Rule: Indentation

There is really only one rule you must respect in YAML, and it’s this:

The spaces at the start of a line show what belongs to what.

Think of it like an indented list in a notebook. When something is “tucked under” something else, it belongs to it. We line things up with spaces to show those relationships. You’ll see exactly what this means in the examples below, so don’t worry if it sounds abstract right now.

Good news: You might have heard that “spaces vs tabs” is a tricky thing in YAML. You can forget about that completely. The editor in Infinite Worlds handles all of that for you automatically. When you press indent (the TAB key), it puts the right kind of space in for you. You genuinely cannot get this wrong.

Now let’s climb the ladder, one rung at a time.

Step 1: Labelled Information

The most basic thing in YAML is a single piece of labelled information: a label, then a colon and a space, then the value.

name: Alice

Read that out loud: “name is Alice.” Simple.

The important detail is the colon followed by a space. Always name: Alice, never name:Alice squished together. That little space matters, and we’ll come back to it in the troubleshooting section because it’s the most common slip.

Step 2: A Few Labels Together

A single label is rarely enough. Usually you want to describe a whole thing, like a character. You do that by writing several labels, one per line, all lined up at the same level:

name: Alice
level: 3
home: Thornwood Village

Each line is its own label-and-value pair. Together they describe one character: Alice, who is level 3 and comes from Thornwood Village.

Notice how all three lines start at the very left edge, with no spaces in front. They’re all at the same level, so they’re all equal members of the same description.

Step 3: A List

Sometimes you don’t want labels, you just want a list of things. In YAML, a list is written with a dash and a space (- ) at the start of each line.

Here’s a list of fruit a merchant is selling:

- apples
- pears
- plums

And here’s a list of creatures lurking in a dungeon:

- goblin
- giant rat
- cave troll

Each - introduces one new item in the list. Read the dash as the word “and”: apples, and pears, and plums.

Step 4: A List of Labelled Things

Now let’s combine the last two ideas. What if you want a list, but each item in the list is itself a little description?

This is perfect for something like a party of adventurers. Each party member has a name, a class, and some hit points. So we make a list (using - ), where each entry is a block of labels:

- name: Alice
  class: Wizard
  health: 18
- name: Bjorn
  class: Warrior
  health: 30
- name: Cora
  class: Rogue
  health: 22

Look carefully at how this lines up. Each new party member starts with a - on the name: line. The other labels for that same person (class: and health:) are indented to line up underneath the name, with no dash. That indentation is what says “these belong to the same person.”

So this is a list of three party members, and each member is described by three labels.

Step 5: Nesting (a Thing Inside a Thing)

Sometimes a value isn’t just a word or number. Sometimes a value is itself a little description with its own labels. We call this nesting: tucking one set of labels inside another.

Imagine an inventory where each item has its own properties. Here’s a sword that has a damage rating and a weight:

sword:
  damage: 8
  weight: 5

Here’s how to read it: there’s a label called sword. Its value isn’t written on the same line. Instead, the things that describe the sword (damage and weight) are written on the lines below, indented to show they belong to the sword.

We can keep going and describe a whole inventory this way:

sword:
  damage: 8
  weight: 5
shield:
  defense: 4
  weight: 7
potion:
  heals: 20
  weight: 1

Three items (sword, shield, potion), each lined up at the left edge, and each with its own indented properties tucked underneath.

Step 6: Lists Inside Things

Now we mix nesting and lists together. This is the most “advanced” shape in the guide, but you already know all the pieces.

Imagine a skill tree, where some skills can only be learned after others. Each skill has an id, a name, and a list of skills it depends on.

skills:
  - id: fireball
    name: Fireball
    depends_on:
      - flame_dart
  - id: flame_dart
    name: Flame Dart
    depends_on: []
  - id: inferno
    name: Inferno
    depends_on:
      - fireball
      - flame_dart

Let’s unpack it slowly:

• There’s one top label, skills, and its value is a list (each - is one skill).
• Each skill is a block of labels: id, name, and depends_on.
• The value of depends_on is itself a list of skill ids, indented underneath it.
• Flame Dart has nothing it depends on. We write that empty list as [], which simply means “an empty list, nothing here yet.”

So Inferno depends on both Fireball and Flame Dart, Fireball depends on Flame Dart, and Flame Dart is available from the start.

Step 7: Long Text (Block Scalars)

Short values fit on one line. But what about a long item description or a character’s backstory? For long text, YAML gives you two handy symbols: | and >.

Use | to keep your line breaks

If you put a | after the colon, every line break you type is kept exactly as you wrote it. This is perfect for a backstory or anything where the layout matters:

backstory: |
  Alice grew up in Thornwood Village.
  She lost her family to a dragon's raid.
  Now she studies fire magic, seeking revenge.

The three sentences will stay on three separate lines, just as you typed them.

Use > to fold everything into one paragraph

If you put a > after the colon, YAML takes all your lines and folds them together into a single flowing paragraph. The line breaks you typed become ordinary spaces. This is great when you’ve split a long description across several lines just to make it easier to read while editing, but you want it to read as one paragraph in the game:

description: >
  This ancient blade hums with a faint blue light.
  Its edge has never dulled, and legends say it was
  forged in the heart of a fallen star.

In the game, that becomes one smooth sentence, with no awkward line breaks in the middle.

Quick way to remember: | looks like a tall wall, so it keeps your lines standing apart. > looks like it’s squeezing things together, so it folds them into one.

Step 8: Comments (Notes to Yourself)

Sometimes you want to leave yourself a little note in the YAML, a reminder that the game should completely ignore. Any line that starts with a # is a comment. The game skips it entirely.

# Starting gear for new heroes
sword:
  damage: 8
  weight: 5
# Remember to add a healing potion later

Those # lines are just for you. They never affect the game, and the AI doesn’t act on them. Use them to remind yourself why you set something up a certain way.

Step 9: When You Need Quotes (Important and Sneaky)

This is the one place where YAML can surprise you, so read this slowly. It’s not hard, but it’s worth knowing.

YAML tries to be clever about what a value is. If a value looks like a number, YAML treats it as a number. If a value is exactly true or false, YAML treats it as a true/false toggle, not as text.

Most of the time that’s helpful. But occasionally it causes a quiet surprise:

• An item code like 007 might silently turn into the number 7, losing its leading zeros.
• A value you want to be the literal word true might turn into a true/false toggle instead of the word.

Here’s the surprise in action. You write this:

item_code: 007
answer: true

But YAML quietly reads 007 as the number 7, and answer as a true/false toggle rather than the word. Not what you meant!

The fix is simple. If you want a value kept exactly as you typed it, wrap it in quotes:

item_code: "007"
answer: "true"
pi: "3.14"

Now item_code keeps its leading zeros as “007”, answer is the actual word “true”, and “3.14” stays as text rather than a number.

Rule of thumb: If the value is meant to be read as text but happens to look like a number or like true/false, put quotes around it. When in doubt, quotes are safe.

Troubleshooting: The Few Mistakes Everyone Makes

Don’t worry about getting these perfect from memory. The editor checks your YAML as you type and shows a live error message the moment something’s off, so mistakes get caught right away. Here are the three you’re most likely to bump into.

1. Forgetting the space after the colon

This is the number one slip. You must always have a space after the colon.

name:Alice

That’s wrong, and the editor will flag it. Add the space:

name: Alice

2. Indentation that doesn’t line up

Lines that belong together must start at the same distance from the left. Here, the two properties of the sword don’t line up with each other:

sword:
  damage: 8
   weight: 5

weight has one extra space, so it no longer lines up with damage. The editor will complain. Make them match:

sword:
  damage: 8
  weight: 5

3. Mixing a list and labels at the same level

Pick one or the other at each level: either a list (lines with - ) or labels (lines with something:), not both jumbled together. This is muddled:

- goblin
name: dungeon monsters

The editor won’t know what you mean. Decide what you want. If you want a labelled block with a list inside it, nest the list properly:

name: dungeon monsters
creatures:
  - goblin
  - skeleton

Now name is a label, and creatures is a label whose value is a tidy list.

You’re Ready

That’s the whole language. Labels, lists, nesting, long text, comments, and the quotes trick. Everything else is just combining these pieces in bigger and bigger shapes.

Whenever you want to experiment, you can try any of this live in the PawScript Playground. Type something in, watch what happens, and learn by playing. That’s the best way to make it stick.

Happy worldbuilding!