Help

So far you've learned how to build your world using Entities, Scenes, and Chapters. Those pieces define what exists in your adventure.

Now it's time to make that world come alive.

Every interactive story is really a conversation between the player and your world:

The player tries something... and the world responds.

That response is powered by three simple concepts:

• ⚙️ States remember what's true about your world.
• ✋ Actions describe what the player is trying to do.
• ⚡ Events decide what happens next.

Together, they allow your world to react intelligently to everything the player does, creating puzzles, branching stories, memorable characters, and adventures that feel alive.

If you look around right now, you'll notice that everything has a state.

• The coffee is hot.
• The front door is locked.
• The cat is hungry.
• The lights are off.
• You're reading this guide.

In Quill and Stein, Entities, Scenes, and even the Player can all have states. States simply describe what's currently true about something.

These states can change throughout the story and are used by Actions and Events to decide what should happen next.

For example, imagine a door with a state called Locked.

If Locked = Yes, trying to open it might display:

"The door won't budge."

Later, after the player finds a key, an event changes the state:

Locked = No

Now the exact same Open action produces a completely different result:

"The door swings open with a satisfying click."

Nothing about the door changed except its state, but that one change completely altered how the world responds.

Think of states as your world's memory. They allow your story to remember what has happened and respond accordingly.

💡 Builder Tip: Whenever something important changes in your adventure, ask yourself, "Should the world remember this?" States are what make your world feel alive; doors stay open, lamps remain lit, characters remember past events, and puzzles evolve as players make progress.

Actions are one of the core building blocks of interactive fiction.

Every time a player types a command, they're performing an action.

Whether they're opening a door, examining an object, climbing a ladder, or talking to a suspicious stranger, almost every interaction begins with an action.

QnS separates what the player wants to do from what they're doing it to. This means the same action can produce completely different results depending on the entity involved.

For example, Open can be used on:

• 🚪 A wooden door
• 📦 A treasure chest
• 📖 An ancient book
• 🧺 A picnic basket

Each one can respond in its own unique way.

Combined with States and Events, actions become a powerful way to build puzzles, conversations, branching stories, and dynamic gameplay.

🎮 Every command your player types is another opportunity to surprise, reward, or challenge them.

Whenever a player enters a command such as:

• 👀 Look
• 🔑 Take key
• 🚪 Open door
• 💬 Talk to guard

QnS identifies both the action and the entity the player wants to interact with.

Many actions also include prepositions, allowing more natural interactions.

For example:

• 📦 Put the coin in the box
• 🪜 Climb up the ladder
• 💬 Talk to the guard
• 🔍 Look under the bed

The QnS engine includes a large collection of familiar adventure-game actions, but you're also free to create your own whenever your story calls for something unique.

💡 Builder Tip:

Types of Actions

Not every action belongs to a single object.

Sometimes an action should only affect one entity, sometimes it should work anywhere within a scene, and other times it should be available throughout an entire chapter.

To make this easy, Quill and Stein provides two types of actions, each designed for a different scope:

• 🎯 Entity Actions — Actions attached to a specific entity.
• 🎬 Scene Actions — Actions that work anywhere within a scene.

Choosing the right action type helps keep your adventure organized and avoids repeating the same logic over and over.

Entity Actions belong to a specific entity and only run when the player interacts with that entity.

Examples include:

• 🚪 Open the front door.
• 📦 Search the treasure chest.
• 🐱 Pet the cat.
• 📖 Read the ancient book.
• 💬 Talk to the village elder.

Even if two entities use the same action, each can respond differently.

For example, opening one chest might reveal treasure, while another releases an angry swarm of bees!

💡 Best used for: Characters, items, furniture, containers, doors, switches, and anything unique in your world.

Scene Actions belong to the current location rather than any specific entity.

They allow the player to perform actions that affect the entire scene or don't naturally belong to a single object.

Examples include:

• 🗣️ Whispering an ancient word that causes a hidden doorway to appear.
• 🎵 Singing a melody that awakens magical crystals throughout the cave.
• 👏 Clapping your hands to hear echoes that reveal a secret passage.
• 📢 Calling for help, causing a nearby character to enter the scene.
• ✨ Casting a detection spell, revealing every magical object in the current location.

💡 Best used for: Environmental interactions, exploration, atmosphere, and actions that involve the whole location.

A simple rule of thumb is:

• 🎯 One object? → Use an Entity Action.
• 🎬 One location? → Use a Scene Action.

Using the appropriate action type keeps your story easier to build, easier to maintain, and much more flexible as your adventure grows.

Events are where your world truly comes alive.

While Actions describe what the player is trying to do, Events decide how the world responds.

An event might:

• 💬 Display a message
• 🚪 Unlock a door
• 🎒 Give the player an item
• 👤 Move a character
• ⚙️ Change a state

Together, Conditions and Effects allow you to build puzzles, branching stories, dynamic environments, and memorable moments, all without writing code.

✨ Think of an event as your world's "If this happens... then do this" system.

Whenever a player successfully performs an action, the QnS engine executes the event attached to that action.

Each event contains two main parts:

• ✅ Conditions — Should this event run?
• 🎬 Effects — What happens if it does?

An event can also stop later events from running or allow processing to continue, giving you complete control over every interaction.

For example:

When the player opens a treasure chest:

1. Is the chest locked?
2. Does the player have the key?
3. If yes, unlock the chest.
4. Reveal the treasure.
5. Display a success message.

If the player doesn't have the key, a different event simply explains why the chest won't open.

💡 Builder Tip: Several small, focused events are usually much easier to understand and maintain than one giant event trying to do everything.

Conditions determine whether an event should run.

Before an event performs any effects, it checks each of its conditions to see if they match the current state of the game.

Conditions can check almost anything, including:

• 🔒 Whether an object is open or closed.
• 🎒 Whether the player has an item.
• 📍 The player's current location.
• 🔢 Numeric values such as counters or scores.
• ⚙️ Any custom entity state you've created.

Multiple conditions can be combined to create more flexible logic. You can require that all conditions are true, any condition is true, or build more advanced combinations to create rich puzzles, dynamic characters, and adventures that respond naturally to the player's choices.

🧩 Builder Tip: If your event isn't behaving as expected, start by checking its conditions. Most event problems are caused by a condition that never becomes true.

Effects are the things an event actually does.

Once an event's conditions have been satisfied, its effects update your world and show the player the results of their actions.

Effects can:

• 💬 Display messages
• 🚶 Move the player
• 📦 Move items or characters
• ⚙️ Change states
• 🎒 Add or remove inventory
• 🖼️ Change scene images
• 🚪 Open, close, enable, disable, or trigger actions

A single event can perform multiple effects, allowing one player action to create rich, satisfying interactions.

🎉 Builder Tip: The best effects don't just change the world, they also let the player see or experience those changes immediately.

Messages are your opportunity to tell the player what just happened.

While Effects change the world behind the scenes, Messages bring those changes to life through storytelling. You can also display a new image alongside a message, helping players see the results of their actions as well as read about them.

A good message doesn't simply repeat the player's command, it describes the result.

Instead of:

You open the door.

Try something like:

The heavy oak door groans as it slowly swings open, revealing a narrow hallway lit by flickering torches.

Pairing descriptive text with an updated image can make important moments even more immersive, whether it's revealing a hidden room, showing a character's reaction, or displaying the aftermath of an event.

Rich, descriptive messages and well-timed images reward exploration, reinforce the player's choices, and make your world feel vivid and believable.

✍️ Builder Tip: Describe what the player experiences, not what they typed. Let your messages paint the picture, and use images to enhance the moment rather than replace the storytelling.