Storyfall

Tags & Dynamic Choices

Tags let you group variables, NPCs, factions, and characters that share common properties, and then generate choices from them automatically.

What Are Tags?

Some variables, NPCs, and other entities share characteristics. For example, if you’re building a game with a food inventory, you might create variables like “Canned Chicken”, “Energy Bar”, and “Chocolate”. These are all food items, and they all have things in common: how filling they are, what kind of morale boost they give, etc.

A tag lets you define those shared properties in one place. You’d create a tag called “Food” with properties like “satiety” and “morale boost”. When you assign the “Food” tag to “Canned Chicken”, that variable automatically gets those properties too. Now every food item has its own satiety and morale boost values that you can set individually.

Under the hood, tag properties are just regular variables. Assigning “Food” to “Canned Chicken” creates variables like “Canned Chicken >> satiety” and “Canned Chicken >> morale boost”. These work in effects and conditions like any other variable.

A few more examples:

  • An “enemy” tag with a “health” property, assigned to NPCs like “Guard Captain” and “Bandit Leader”.
  • A “class” tag with a “spellSlots” property, assigned to characters to give class-specific abilities.

Creating Tags

  1. Open the Tags panel in the workshop sidebar (keyboard shortcut: Ctrl+Shift+0).
  2. Click Add Tag to create a new tag.
  3. Give it a name (e.g., “Food”) and an optional description.
  4. For inventory-style tags on variables, enable Consumable and set the consume amount (more on this below).

Adding Properties

Properties define what data each tagged entity carries.

  1. Expand a tag by clicking on it.
  2. Click Add Property.
  3. Set the property name, type (string, number, or boolean), and default value.

When the tag gets assigned to an entity, a variable is automatically created for each property.

Assigning Tags

You can assign tags to variables, NPCs, factions, and characters through their edit modals. Each one has a Tags section where you can click Assign Tag to add a tag. The auto-created property variables show up right there under the tag assignment, so you can set their values.

To remove a tag, click the X button next to it. This also deletes the auto-created property variables.

Dynamic Choices

Normally, if you have 20 food items and want the reader to pick one, you’d have to create 20 separate choices by hand. Dynamic choices solve this.

You pick the Dynamic choice type in the same place where you pick other choice types (continue, back, input, interact, etc.). Then you select a tag (e.g., “Food”) and an entity type (Variables, NPCs, Factions, or Characters). When a reader reaches that scene, every entity with that tag gets added as a choice automatically.

Write the choice text using {name} as a placeholder for each entity’s name. For example, “Eat {name}” becomes “Eat Canned Chicken”, “Eat Energy Bar”, etc.

Setting Up a Dynamic Choice

  1. Add a new choice to a scene.
  2. Change its type to Dynamic using the choice type selector.
  3. Click the green tag icon to configure the tag and entity type.
  4. Write the choice text with {name} as a placeholder (e.g., “Eat {name}”).

Consumable Tags

Tags can be set as consumable, which is useful for inventory items that get used up. When a tag is marked consumable:

  • Selecting a dynamic choice subtracts the consume amount (default 1) from that variable’s value.
  • When a variable’s value reaches 0, its dynamic choice disappears.
  • So if “Canned Chicken” has a quantity of 3, the reader can eat it three times before it’s gone.

This only applies to variable-type entities.

Tag Properties in Effects

Dynamic choices can also reference tag properties in their effects. When you click the fx button on a dynamic choice, you’ll see a Tag Prop setting. This lets you wire up a tag property to another variable.

For example, you could set an effect that adds the “satiety” tag property to a “Hunger” variable. When the reader picks “Eat Canned Chicken”, the engine looks up Canned Chicken’s satiety value and applies it to Hunger. Pick “Eat Energy Bar” instead, and it uses Energy Bar’s satiety value. One effect definition handles all the food items.

Example: Food Inventory

Here’s how to put it all together:

  1. Create variables: “Canned Chicken” (number, default 3), “Energy Bar” (number, default 2), “Hunger” (number, default 50).
  2. Create a “Food” tag with a “satiety” property (number), and mark it consumable.
  3. Assign “Food” to Canned Chicken (set satiety to 10) and Energy Bar (set satiety to 5).
  4. Create a dynamic choice: tag = Food, entity type = Variables, text = “Eat {name}“.
  5. Add an effect using the Tag Prop setting to add satiety to Hunger.

At play time, the reader sees “Eat Canned Chicken” and “Eat Energy Bar”. Clicking “Eat Canned Chicken” adds 10 to Hunger and reduces Canned Chicken’s quantity from 3 to 2. When it reaches 0, the choice disappears.

Tips

  • Tag property variables don’t show up in the main Variables panel. They’re shown under each entity’s tag assignment instead.
  • You can assign multiple tags to the same entity.