Guide
The Loom Engine
Make your stories feel authored, reactive, and alive — without writing a single line of code.
The Loom Engine is a behind-the-scenes scripting system built into every world. It lets you set up rules that silently guide the AI's writing during live gameplay. Think of it as a stage director that the audience never sees — shaping plot twists, tracking choices, introducing characters, and reacting to everything the player does.
Invisible
Players never see threads running. They just experience a story that reacts to them in surprising, intentional ways.
No Code
Everything is configured through a visual editor. Pick conditions from dropdowns, type your narrative text, and hit save.
Powerful
Dice rolls, stat meters, quests, inventory, branching choices, timed reveals, hidden plot logic — all possible.
The core concept
Every rule in the Loom Engine follows a simple pattern: IF something is true about the current moment in the story, THEN do something about it. These rules are called Threads. They run silently every time the AI writes a response.
IF
The player mentions "the sword"
THEN
Tell the AI: "The sword begins to glow with ancient runes"
Fundamentals
Threads
Each thread is one rule. Name it, give it conditions, give it actions, and let it run.
A thread is the building block of the Loom Engine. You create threads in the Loom Editor — a dedicated full-screen workspace you open from your world's Settings page.
Each thread has a name (so you can identify it), an enabled toggle (to turn it on or off), and a color (for visual organization). Threads are listed in a sidebar, and you click one to edit its details.
Thread settings
Priority
A number from 0 to 100. Higher-priority threads fire first. If two threads fire on the same message, the one with higher priority takes precedence. Default is 5.
Condition Logic
Choose AND (every condition must pass) or OR (any one condition passing is enough). This controls how multiple conditions on the same thread work together.
Fire Once
When enabled, the thread fires at most one time per playthrough. Perfect for one-shot story beats like a villain reveal or a plot twist that should only happen once.
Max Fires
Limits how many times a thread can fire per playthrough. Set it to 3, and after the third firing the thread stops. Leave empty for unlimited.
Cooldown
After firing, the thread waits at least N messages before it can fire again. Great for recurring events you don't want to spam — like a weather system that changes every 5 messages.
Tags
Freeform labels you attach to threads (like "act_1" or "combat"). Use them to filter threads in the sidebar, and to enable or disable entire groups of threads at once with a single action.
The IF side
Conditions
Conditions decide when a thread fires. Pick from over 50 condition types across 9 categories.
Every condition answers a yes-or-no question about the current moment: "Did the player say a keyword?", "Is a flag set?", "Has a lore card been triggered?" You can stack multiple conditions on one thread and choose whether all must pass (AND) or just any one (OR).
Message contains any keyword
Fires if the player's message includes any word from a list you define. Great for reacting to specific topics.
Message contains all keywords
Fires only if every keyword in your list appears. Use this for very specific triggers like "attack the dragon".
Message excludes keywords
Fires only when none of your listed words appear. Useful for "do this unless the player mentions X".
Message starts with
Fires when the message begins with a specific phrase, like "/roll" or "I cast".
Input mode is
Fires when the player is using a specific input mode — Do, Say, Story, or See.
Is continue action
Fires when the player clicks Continue (letting the AI write without input).
Action count ≥ / ≤ / = / in range
Check how many messages have been sent in this playthrough. "Action count ≥ 10" fires from message 10 onward.
Every Nth action
Fires on a repeating cycle. "Every 5th action" fires at messages 5, 10, 15, 20... Great for periodic events.
Is first message
Fires only on the very first player message of the playthrough. Perfect for opening scenes.
Flag equals / not equals
Check if a flag you've set has a specific value. "quest_stage equals 2" fires when you're in act 2.
Flag exists / not set
Check whether a flag has been created at all, regardless of its value.
Flag is truthy / falsy
Treats flag values as true/false. "false", "no", "0", and empty are falsy — everything else is truthy.
Counter ≥ / ≤ / = / in range
Compare a numeric flag against a threshold. "reputation ≥ 10" fires when the player's reputation reaches 10.
Flags with prefix ≥ N
Counts how many flags start with a prefix. "collected_item_ ≥ 3" means the player has collected 3+ items.
All/Any flags equal
Check multiple flags at once. "All flags in [quest_a, quest_b, quest_c] equal done" fires when all three quests are complete.
Lore card triggered / not triggered
Fires when a specific lore card was (or wasn't) included in the current AI prompt based on keyword matching.
Any / All lore triggered
Check sets of lore cards — did any of them trigger, or did all of them?
Triggered lore count ≥ N
Fires when a certain number of lore cards triggered in this prompt.
Lore card is active / inactive
Check whether a lore card's "Active for Prompt" toggle is currently on or off.
Lore ever / never triggered
Check if a lore card has triggered at any point during this playthrough — not just this message.
Thread has fired / has not fired
Check whether another thread has fired at any point this playthrough.
Thread fire count ≥ N
Has another thread fired at least N times?
Thread fired recently
Did another thread fire within the last N messages?
All / None / Sequence
Check sets of threads: have they all fired? None fired? Fired in a specific order?
Actions since thread
Have at least N messages passed since another thread last fired?
Player has item
Fires when the player is carrying a specific item — optionally at least N of it. "Has Iron Key" can gate a locked-door scene; "Has 3 Gold Coins" can gate a purchase.
Player lacks item
Fires when the player does not have an item. Great for "the merchant won't trade until you find the token" style gates.
Random chance
Fires with a percentage chance you set. "30% chance" means roughly 1 in 3 messages will trigger this.
Scaling random chance
Starts at a base chance and increases each message. "Start at 5%, increase 5% per message, max 50%" — tension that builds over time.
Dice check (DC)
Roll dice using standard notation (1d20, 2d6+3) against a difficulty number. The thread fires if the roll meets or beats the target. Results are shown to the player as an animated notification.
NOT (invert)
Wraps another condition and flips its result. "NOT message contains help" fires when the word "help" is absent.
AND / OR (nested)
Group conditions inside a single condition. Lets you build complex logic like "(A AND B) OR C".
N of M
Fires when at least N out of M sub-conditions are true. "2 of 3" means any two out of three must pass.
React when the player asks about the prophecy
A simple keyword trigger that adds flavor when a specific topic comes up in conversation.
Message contains any keyword: "prophecy", "foretold", "chosen one"
Inject narrative: "The air grows cold. The old man's eyes widen — he grips the player's arm. 'You've heard the words, then. The prophecy is no myth.'"
Thread: Prophecy Mention
The THEN side
Actions
Actions are what happens when a thread fires. You get over 50 action types across 8 categories.
Every action does something concrete — inject text into the AI's instructions, set a flag, activate a lore card, show a notification, roll dice, or control other threads. Actions execute in the order you list them, so you can chain multiple effects.
Narrative Injection
The most important action type. You write a piece of creative direction, and the AI weaves it into its response. The player never sees your instruction — they just experience the result.
Inject narrative
Tell the AI to work a specific event, detail, or plot point into its response. The most flexible and commonly used action.
Inject dialogue
Force a named character to say specific words. "Innkeeper says: You're not welcome here anymore."
Inject environment
Describe a change in the surroundings. "A thick fog rolls in from the river. Visibility drops to ten feet."
Scene transition
Force the story to a new location or time. "Cut to three days later. The party arrives at the mountain pass."
Flashback & Foreshadowing
Weave in memories of the past or plant seeds for the future. Subtle, atmospheric storytelling tools.
Present choices (text)
End the AI's response with a numbered list of options. For real tappable choice buttons, see Interactive Choices in the Feedback section.
Inject into character profile
Automatically add text to the player's character profile for this session. Great for persistent character evolution based on story events.
The innkeeper recognizes a wanted criminal
When the player enters a tavern with a bounty on their head, the innkeeper reacts.
Message contains any keyword: "tavern", "inn", "bar"
Flag equals: wanted = true
Inject dialogue: The innkeeper's face drains of color. She drops a glass. "You... you're the one from the posters."
Set flag: innkeeper_alerted = true
Thread: Bounty Recognition
World State & Flags
Track anything across your story with named variables. Choices remembered. Progress tracked. Consequences earned.
World state is a set of named values (called flags) that persist for the entire playthrough. Think of them as sticky notes the Loom Engine can write and read.
A flag has a name (like quest_stage) and a value (like 2). You set flags with actions and check them with conditions.
What you can do with flags
Set a value
Set act to 2 — now any thread can check which act you're in.
Toggle a boolean
Flip door_locked between true and false each time the player interacts.
Increment a counter
Add 1 to reputation each time the player does something honorable.
Decrement with a floor
Subtract from health but never go below 0.
Random value
Set weather to a random choice from "sunny", "rainy", "stormy".
Batch set
Set multiple flags at once when initializing a new scene or quest.
Three-act story progression
Use a simple flag to transition the story through three acts.
Action count ≥ 15
Flag equals: act = 1
Set flag: act = 2
Inject narrative: "The ground trembles. A tower of black glass rises from the earth."
Activate lore card: The Obsidian Spire
Thread: Begin Act 2
The RPG layer
Meters, Quests & Inventory
Give players a living HUD — stat bars, quest logs, and a real inventory the story reacts to.
Beyond invisible logic, the Loom Engine can surface visible RPG systems. They appear in the Adventure HUD — a compact, collapsible panel that floats at the top-left of the story and stays out of the way. Everything here is built from the same flags and counters you already know, and it all updates live as you play.
Meters & stat bars
A meter is a labeled progress bar — Health, Sanity, Reputation, Affection — bound to a counter flag. Change the counter, fire Show meter, and the bar updates instantly in the HUD. You choose its label, max value, and color.
A health bar that drains on injury
Bind a meter to an hp counter, drop it when the player is hurt, and refresh the bar.
Message contains any keyword: "hurt", "wounded", "struck"
Decrement counter: hp by 15 (floor 0)
Show meter: "Health" → bound to hp, max 100, red
Thread: Take Damage
Quest tracker
Start a quest with a list of objectives, then tick them off as the player progresses. Quests appear in the HUD with a status — active, complete, or failed. Starting a quest and completing objectives also tell the AI, so the story acknowledges the player's goals.
Start / set quest
Open a quest in the tracker with a title and a list of objectives. Each quest has a stable ID you reference later.
Update quest
Mark an objective complete, or set the whole quest to complete or failed. The change is reflected in the HUD and described in the story.
A multi-objective main quest
Open the quest on the first turn, then complete an objective when the player finds the map.
Is first message
Start quest: "The Lost Heir" → Find the old map · Reach the ruined keep · Recover the signet
Thread: Start Main Quest
Inventory
Inventory items are first-class — defined once, then referenced everywhere. Give item defines an item (name, quantity, optional description). Remove item and Use / consume item let you pick from items the player actually has. Items stack with quantities and show in the HUD, and the Player has item condition gates content on what they carry.
Give item
Add an item to the player's inventory with a quantity and description. This defines the item so other actions and the “has item” condition can reference it.
Remove item
Remove an item the player owns — picked from a dropdown of items your Give-item actions defined, so you never retype a name.
Use / consume item
Consume an owned item and tell the AI to show its effect in the scene — perfect for potions, keys, and consumables.
A key that unlocks a door — and is spent
Gate the door on owning the key, then consume it as the lock turns.
Message contains any keyword: "door", "gate", "unlock"
Player has item: Iron Key
Use item: Iron Key
Inject narrative: "The iron key fits the lock and turns with a heavy click — the way is open."
Thread: Unlock the Door
The Adventure HUD
Players see a small floating pill with glanceable mini-bars. Tapping it expands a full panel with every meter, quest, and item (a bottom sheet on mobile). It persists for the whole playthrough and updates live as threads fire.
The Manage panel
In the editor, the Manage button opens tabs for Flags, Items, and Quests — a registry of everything you've defined across the world, with usage counts.
Dice Rolls
Add tabletop-style randomness. Roll dice, check against targets, and branch the story based on outcomes.
The Loom Engine supports standard dice notation — the same kind used in tabletop games. Write 1d20 for one twenty-sided die, 2d6+3 for two six-sided dice plus 3, or 4d6kH3 to roll four dice and keep the highest three.
When dice roll, players see an animated notification showing the result, the target number, and whether they succeeded or failed.
As a condition: Dice Check
Roll dice and compare against a target number (DC). If the roll meets or beats the DC, the condition passes and the thread fires.
Example: "Roll 1d20 vs DC 15 — if they pass, they successfully pick the lock."
As an action: Roll + Branch
Roll dice and inject different narrative text based on the outcome — success, failure, critical success, or critical failure.
Example: "Roll 1d20+5 vs DC 12 — on success the bridge holds, on failure it collapses."
Combat encounter with dice
When the player attacks, roll for success. The story branches based on the outcome.
Message contains any keyword: "attack", "strike", "swing"
Roll dice + check: 1d20+3 vs DC 13
On success: "Your blade finds its mark. The creature howls and staggers."
On failure: "Your swing goes wide. The creature lunges."
Store result in flag: last_attack_roll
Thread: Attack Roll
Lore Card Control
Threads can activate, deactivate, pin, and even rewrite your lore cards on the fly.
Lore cards define what the AI knows about your world. The Loom Engine lets you dynamically control which lore cards are active, ensuring the AI only knows what it should at any given point.
Activate / Deactivate
Turn a lore card on or off. "Deactivate the Village card and activate the Ruins card" — the AI now knows about the ruins, not the village.
Pin / Unpin
Pinned cards are always included in the AI's context, regardless of keyword matching. Pin critical characters during their scenes.
Temporary pin
Pin a card for exactly N messages, then it auto-unpins. Perfect for introducing a character that's important for a scene but not the whole story.
Swap description
Rewrite a lore card's description mid-story. The "Village" card starts peaceful, then changes to describe a burning ruin after an attack.
Change importance
Boost or lower a card's priority. Make a character more prominent as they become important to the plot.
Reveal a hidden villain
When the player discovers the truth, swap out the friendly NPC's lore card for the villain version.
Flag equals: clues_found = 3
Thread has not fired: Villain Reveal
Swap lore description: "Aldric" → villain version
Pin lore card: Aldric the Merchant
Inject narrative: "Something in Aldric's smile changes. His eyes are cold now."
Show achievement: "Truth Unveiled"
Thread: Villain Reveal
Player Feedback & Choices
Show notifications, achievements, hints, and notes — and offer tappable choices that branch the story.
Sometimes you want to communicate directly with the player outside the story. Feedback actions display visual messages the player sees but the AI does not — and interactive choices let the player steer the next turn with a tap.
Notifications
Brief pop-up banners in four styles: info, success, warning, and lore. Use them for quest updates, story hints, or atmospheric messages.
Achievements
A special notification styled like a video game achievement unlock. Reward players for discoveries, milestones, or hidden interactions.
Hints
A subtle text hint near the input field. Guide the player without breaking immersion: "Try looking behind the painting."
Narrator Notes
A styled message that appears in the chat timeline. Visible to the player but never sent to the AI.
Interactive Choices
Tappable choice buttons that appear above the input. The player taps one and it is submitted as their next action — branching the story with a single click. (The text-only "Present choices" action lists options in the prose instead.)
Thread Control
Threads can enable, disable, reset, and force-fire other threads — enabling multi-phase storylines.
This is where the Loom Engine becomes truly powerful. Threads don't just react to the story — they can control each other.
Enable / Disable thread
Turn another thread on or off at runtime. "When Act 1 ends, enable all Act 2 threads."
Reset thread
Reset a thread's fire count and cooldown, as if it had never fired. Useful for repeating story beats.
Force fire thread
Immediately trigger another thread, skipping its conditions. Chain reactions of narrative events.
Schedule thread
Set a thread to enable itself after N messages. "Schedule the ambush in 5 messages" — delayed events.
Enable / Disable group
Control all threads with a specific tag at once. Tag your Act 1 threads as "act_1", then disable the entire group with one action.
Multi-act story orchestration
Thread control enables seamless act transitions.
Flag equals: quest_complete = true
Action count ≥ 20
Disable thread group: act_1
Enable thread group: act_2
Set flag: act = 2
Inject narrative: "The quest is complete — but the real story is just beginning."
Show notification: "Act 2: The Reckoning"
Thread: Transition to Act 2
Get started fast
Templates & the Editor
One-click starter packs and a guided editor take you from idea to working thread in seconds.
The Loom Editor's Templates button installs ready-made, fully-wired threads in a single click — the fastest way to learn by example and to drop in common systems instantly. There are dozens spanning many genres — fantasy & RPG, horror, sci-fi, romance, intimacy, mystery, survival, action, 1-on-1 character chats, and director tools — with a search bar to find the right one fast. Open one, see how it's built, and tweak it to taste. A taste:
Health System
A live HP bar that drains on injury and triggers a defeat beat at zero.
Romance Meter
An affection bar that warms and cools with tender or cold moments.
Branching Choices
Offers tappable choices every few turns to steer the story.
Quest Tracker
A multi-objective quest that ticks off objectives as you play.
Loot Drops
Chance-based item rewards when the player searches containers.
Three-Act Pacing
Escalates the story at turn milestones to keep a three-act shape.
Sanity Meter
A horror sanity bar that frays and warps the narration when low.
Reputation
A standing that rises and falls with heroic or villainous deeds.
Coin Purse
A gold currency meter you earn from loot and a starting purse.
Companion Bond
A loyalty meter with a payoff when a companion fully trusts you.
Skill Checks
Rolls a d20 check on risky-action phrases and shapes the outcome.
Inventory & Keys
Carry items, drink potions, and spend a key to unlock a door.
The editor helps as you build
Plain-English preview
Every thread shows a readable summary of what it does — “When HP ≤ 0 → show a defeat note” — so you always know what you're building.
Tooltips everywhere
Every condition, action, and setting has a hint explaining what it does, so the full toolset is approachable from day one.
Import & export
Export your threads to a file and import them into another world — share systems or back up your work.
Publishing & Hidden Threads
Share your worlds with the community — and protect your secret narrative logic.
When you publish a world, all your Loom threads come with it. Players who download your world experience all the reactive storytelling you built.
But sometimes you want to protect your creative work. That's where hidden threads come in.
Hidden Threads
Mark any thread as "Hidden" in its settings. In your world, it works normally. But when someone downloads your world, hidden threads become completely invisible — they can't see, edit, or delete them.
They still fire and shape the AI's responses. The player experiences the effects without knowing how they work.
Loom Visibility
A world-level setting with two modes. Exposed (default): threads keep their individual hidden/visible status. Hidden: ALL threads are forced to hidden in downloaded copies.
Downloaders see a banner: "N hidden scripts active — Locked narrative logic from the world creator."
Tips & Patterns
Proven patterns from experienced world creators.
Start simple, layer complexity
Begin with 2-3 threads that inject narrative on keyword triggers. Once you see them working, add world state flags, then thread control for multi-phase stories.
Use tags to organize
Tag threads by story act (act_1, act_2), by system (combat, weather), or by character. Then use "Enable group" and "Disable group" to manage them in bulk.
Write specific, vivid directives
Instead of "make it dramatic", write "The innkeeper slams her fist on the bar, sending mugs crashing to the floor." The more specific, the better.
Use Fire Once for big moments
Plot twists, character reveals, and major transitions should use Fire Once. You don't want the villain to reveal themselves repeatedly.
Cooldowns prevent spam
For atmospheric threads (weather, ambient descriptions), set a cooldown of 3-5 messages. Keeps the world alive without repetition.
Test by playing
The best way to test threads is to play your own world. Type messages that should trigger your conditions and check the Context Inspector to verify.
Ready to build?
Open the Loom Editor in any world and create your first thread. Start with a simple keyword trigger — you'll be amazed at how much it changes the experience.