> For the complete documentation index, see [llms.txt](https://docs.spicychat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spicychat.ai/product-guides/rulebooks.md).
# Rulebooks
{% hint style="info" %}
**Rulebooks are in Beta.** Things may change as we improve the feature. Tell us what you think on Discord.
{% endhint %}
### Overview
A character's personality describes **who they are**. It stays the same for the whole chat.
A **Rulebook** adds the part that **changes as you chat**: how much a character trusts you, how much gold you've collected, what time it is in the story, or how close you are to winning a game.
A Rulebook is made of two things:
* **Meters**: values that go up and down as you chat, like *Affection*, *Trust*, *HP* or *Coins*.
* **Influence rules**: extra instructions for the AI that switch on when a meter reaches a certain value. For example, *"once Affection is above 60, she's openly flirty."*
Like a [Lorebook](/product-guides/lorebook.md), you build a Rulebook once and attach it. It isn't tied to one character, so the same Rulebook can be used with any character or persona.
**What you can build with Rulebooks:**
* **Relationship arcs**: a slow-burn romance where trust has to be earned before anything happens.
* **Games with a goal**: win someone over before the bar closes at 2 AM, or survive ten dungeon floors.
* **Stats and economies**: HP, gold, XP or reputation that the character actually reacts to.
* **A story clock**: time passes as you chat, and the character behaves differently in the morning than late at night.
### ๐งฉ How it works in a chat
Every time you send a message:
1. **Your message moves the meters.** Keywords and AI evaluation check what just happened and raise or lower each meter.
2. **Influence rules check the new values.** Every rule that matches adds its instruction for the AI.
3. **The character replies**, following those instructions.
{% hint style="info" %}
Users see the **meters**, **what moves them** and the **status line**. They **never** see the instructions written for the AI.
{% endhint %}
**Example:** a barista starts polite and a little reserved. When *Affection* climbs past 60, an influence rule tells the AI she's now openly flirty and remembers your usual order. You see the meter fill and the status line change to *"Warming up to you"*.
### ๐ What you see in chat
When a Rulebook is active, its meters sit at the **top of the chat**: a row of score tiles on desktop and a grid on mobile. Up to **4 meters** can be shown.
* **Short values on each tile.** For example: a bar shows `62`, pips show `3/5`, dice show `14 / d20` and a story clock shows `Tue 18:40`.
* **Moves are highlighted.** When a meter changes, its tile glows and shows the change (for example `+4`), and the reply shows small chips such as **+4 Trust**.
* **The status line** is a short sentence under the meters that tells you how things are going, such as *"Walls up"* or *"She's flirting back"*.
* **Tap the meters** to open the details sheet. You'll see what raises and lowers each meter, the levels the chat has already visited (the others show as **???** until you reach them), a **You're here** marker and the current status line.
**Controls in the details sheet and chat menu:**
* **Interactive features**: turn off to chat with the character normally. The meters freeze where they are.
* **Hide meters**: removes the meters from the screen. They keep updating in the background and still shape the replies.
{% hint style="success" %}
**Regenerating or switching a reply restores the meters** to how they were at that point, so a reroll never "double counts".
{% endhint %}
### ๐ Using a Rulebook
There are three ways to use a Rulebook. In each case, pick from **My Rulebooks** (ones you made) or **Discover** (all Public Rulebooks).
#### On a character (for creators)
1. Open your chatbot in the **Character Editor**.
2. Open the **Advanced** section.
3. Under **Rulebook**, click **Attach Rulebook**, pick one and save the character.
**New chats** with this character use the Rulebook. Chats that already started keep the Rulebook they began with.
#### On a persona
1. Go to **My Personas** and create or edit a persona.
2. Under **Rulebook**, click **Attach Rulebook** and pick one.
Chats where you use this persona follow **the persona's Rulebook instead of the character's**. It's the easiest way to bring your favorite game or relationship tracker to any character.
#### In a single chat
1. In the chat, open the **โฏ** menu and choose **Attach Rulebook**.
2. Pick a Rulebook and click **Attach Rulebook**.
{% hint style="warning" %}
* You can attach a Rulebook at any time, even before your first message.
* The Rulebook **starts with your next message**.
* To try a different Rulebook, choose **Remove Rulebook** from the chat menu, then attach another one. After Remove, the chat uses the persona's or character's Rulebook if there is one. Meter values from the removed Rulebook are not carried over.
{% endhint %}
### โ๏ธ Creating a Rulebook
Go to the main menu and click **Create โ Rulebook**. The editor has three tabs: **Properties**, **Meters** and **Influence rules**.
#### Properties
* **Cover**: upload or **Generate** an image. Required.
* **Name**: up to **60 characters**.
* **Description**: up to **300 characters**. It's shown on the Rulebook card and in the attach picker, so say what the Rulebook does and what the goal is.
* **Tags**: pick at least **2** tags from the list (up to **12**). A Private draft can be saved with fewer, but Public and Unlisted need 2. Type to search, then press **Enter** to add it.
* **Visibility**: see [Private or Public](#private-or-public) below.
{% hint style="info" %}
In descriptions, write *"they"* or *"your character"* instead of `{{char}}`. The placeholders are only filled in during a chat, so on a card they'd show up as raw text.
{% endhint %}
#### Writing `{{user}}` and `{{char}}`
In meter rules and instructions, use **`{{user}}`** for the user and **`{{char}}`** for the character. They're filled in with the real names when the chat runs, so one Rulebook works with any character. Click the **{ }** button in a text field to insert them, or to insert a meter's value or caption.
### ๐ Meters
Open the **Meters** tab and click **+ Add meter**. Pick a type first, because it decides how the meter is edited and how it looks in chat.
| Type | What it is | Good for |
| --------------- | -------------------------------------------------------- | ---------------------------------------- |
| **Bar** | A smooth value between a min and max (for example 0โ100) | Affection, Trust, Interest, Suspicion |
| **Pips** | A small number of steps (up to 10) | HP, lives, strikes, chapters |
| **Number** | An open-ended counter with no maximum | Coins, gold, XP, reputation |
| **Dice** | A random roll every turn (for example a d20) | Luck, combat rolls, "fate" |
| **Story clock** | A date and time that moves forward as you chat | Timed dates, day/night cycles, deadlines |
#### Meter settings
* **Name, icon and color**: how the meter looks in chat.
* **Evaluates**: which messages move it: **All messages**, **User messages** or **Bot messages**.
* **Min / Max / Starts at**: the range and starting value (Bar and Pips).
* **Visibility**: **Shown** or **Hidden**. Up to **4** meters can be shown. Hidden meters still drive influence rules, but users never see their value.
* **What users are told**: one item per line under **Raises it** and **Lowers it** (or **Earned by** for numbers). This is what users see in the "what moves these meters" sheet. For example: *"Making her laugh"* and *"Pushy or crude moves"*.
**Extra settings by type:**
* **Number**: a **Unit** (coins, XP, points) and **Precision**. You can also add a fixed amount **Per message**, and turn on:
* **Show current level in chat**: adds the level name and progress to the next one, such as *"Lv 2 ยท Regular"*.
* **Can be spent**: off means the value only ever grows (XP). On means negative changes spend it, never below 0 (money).
* **Tell the model the value**: lets the character react to it, for example refusing what `{{user}}` can't afford.
* **Dice**: choose the number of **sides**. It rolls on every message, and you use levels to decide what low and high rolls mean.
* **Story clock**: set the **start date and time** and **how many minutes pass per message**. You can also have it **detect time skips** (for example *"we sleep until morning"*) and **tell the model the date and time**. Only one story clock is allowed per Rulebook. The clock can show a **calendar date** (Tue 10 Mar, 18:40) or only count **story days** (Day 3, 18:40). Time per message accepts quarter minutes, so `0.25` is 15 seconds. Time skips are found by the AI only, and the clock **never moves backward**, so typing an earlier time does not undo a skip.
#### How a meter moves
When you send a message, meters move in this order: **keywords** and per-message changes first, then **decay** if nothing else moved the meter, then **triggers**, then **AI evaluation** after the reply (reading your message and the reply together), then triggers again if the AI pushed a meter to a trigger value.
**๐ Keywords**: a fixed change when the user's message contains a word. They're free and predictable.
* Enter comma-separated words and the change, for example `boring, whatever` โ `-5`.
**๐ค AI evaluation**: a small AI model reads the latest exchange and checks each of your rules.
* Each rule has an **impact** (use the **โ** and **+** buttons) and a **condition** written in plain language, for example:
* `+5`: *`{{user}}` makes `{{char}}` genuinely laugh with a witty or playful line*
* `-7`: *`{{user}}` is crude or pushy, or moves faster than `{{char}}` invited*
* Each condition is asked as a **yes/no question about the new messages**. A rule only fires when the AI is confident it clearly happened.
* If several rules match, **the one with the largest impact applies** (on a tie, the negative one wins).
* A Rulebook can ask the AI up to **60 questions per message**, across all meters. The editor shows how many you have left.
* **Can fire** (under Advanced): **Every turn**, **Once**, or **Every N turns**. This is a cooldown that stops a meter from climbing too fast. It doesn't make a rule fire automatically.
{% hint style="warning" %}
Don't write "always true" conditions like *"the user sends a message"*. They're unreliable. For something that should happen every turn, use **Decay** (or **Per message** on a Number).
{% endhint %}
**๐ Decay** (optional): drifts the meter on quiet turns, for example `-1` every `1` quiet turn. It only applies when nothing else moved the meter that turn. It's useful for "keep the energy up or you lose her" mechanics.
### ๐๏ธ Influence rules
The **Influence rules** tab is where meters start changing how the character behaves.
#### Influence by level
Each meter is split into **levels**: ranges on a bar, like *Bored 0โ19*, *Polite 20โ39*, *Curious 40โ59*, *Flirty 60โ79* and *Smitten 80โ100*. Click a level to edit it:
* **Range**: where the level starts and ends. You can **split** a level into two or **delete** one.
* **Instruction for the model**: what the AI should do while the meter is in this level. Users never see this.
* **Status line**: the short line users see while this level is active, such as *"She's checking her phoneโฆ"*.
* **Show in the user's levels list**: turn off to keep a level secret (for example a hidden "Game over" level).
* **Takes over the status line**: makes this level's status line win over the others.
Only the instruction of the **current** level is sent to the AI, so you can write very different behavior for each stage.
**Story clock levels:** the clock is split by **time of day** (by default *Morning*, *Afternoon*, *Evening* and *Night*), and you can also add rules by **story day**. Rename and resize them to fit your story, for example *Early evening*, *Last call* and *Closing time*.
**Dice levels:** split the roll into outcomes like *Fumble (1)*, *Bad luck (2โ7)*, *Steady (8โ13)*, *Good fortune (14โ19)* and *Critical (20)*, each with an instruction for how risky actions turn out.
#### Combined rules
Use **combined rules** for situations that depend on **several meters at once**. A rule applies only when **all** of its conditions are true.
* Numeric meters use comparisons like **Interest โฅ 80**.
* A story clock uses **is** a time of day, for example **Closing Time is Closing time**.
Every matching rule adds its instruction. **The highest matching rule in the list sets the status line**, so put your most important rules (like win and lose endings) at the top. Use the arrows to reorder.
**Example: a win and a lose ending**
| Rule | Conditions | Status line |
| ------------- | --------------------------------------------------- | -------------------------------------- |
| 1 ยท You win | Clock **is** Closing time **and** Interest **โฅ 80** | ๐ You won her over |
| 2 ยท Game over | Clock **is** Closing time **and** Interest **< 80** | Game over: she caught a cab home alone |
### ๐งช Testing before you save
The editor checks your Rulebook as you build it. Look at the bar under the title:
* **Errors** (red) block saving, for example *"Add at least one meter"* or *"Pick at least one tag"*. Click to see the list.
* **Warnings** (amber) point out things like a meter that never moves.
* **Info** checks such as *Largest instruction block* (keep each one under about **1,200 tokens**), *Every meter has a driver* and *All combined rules reachable*.
**What the model sees** shows exactly which instructions are added to the AI's prompt for the current playtest values, plus the status line users would see.
**Playtest** lets you try your rules without starting a chat:
1. Drag the meters to any value to preview levels and combined rules.
2. Write a sample **Bot** message to set up a situation, then a **User** message, and click **Send & evaluate**.
3. See which AI rules fired and how each meter moved. Turn on **Draft a sample bot reply after each evaluation** to see how the character would respond.
4. Click **Reset state** to start over.
### ๐ Private or Public
| Visibility | Who can attach it | When it goes live |
| ------------ | ---------------------------------------------------------------------------------------------- | ------------------------ |
| **Private** | Only you, on your private characters and personas | Right away when you save |
| **Unlisted** | Only you, on your public and private characters and personas. Not listed in the Public library | After moderation review |
| **Public** | Anyone, once approved. It's listed in the Public library | After moderation review |
* **Private** Rulebooks go live as soon as you click **Save**.
* **Public** and **Unlisted** Rulebooks are reviewed by moderation before they go live, and again after each change. The last approved version keeps running in chats meanwhile. If changes are needed, you'll see what to fix in the editor. Fix every flagged item, then submit again.
* Public Rulebooks must follow the [Community Guidelines](https://docs.spicychat.ai/community-guidelines).
{% hint style="info" %}
Whatever you choose, chat users **never** see your instructions or AI rules. They only see visible meters, what moves them and your status lines.
{% endhint %}
### ๐พ Saving, drafts and versions
* Your edits are kept as a **draft** in your browser while you work. The badge shows things like **Draft saved ยท 2 unpublished changes**.
* Click **Save** to publish your changes. For a Private Rulebook they apply right away.
* **Discard draft** throws away unpublished changes and goes back to the saved copy.
* Chats that already started keep running on the Rulebook they began with.
* **Export JSON** downloads your Rulebook as a file, and **Import** (in **My Creations โ Rulebooks**) loads one back in. After importing, add a **cover** and **tags** before you save.
### ๐๏ธ Managing your Rulebooks
All your Rulebooks live in **My Creations โ Rulebooks**.
* Each card shows the cover, name, description, its meters, a visibility badge (**Private**, **Public** or **Draft**) and the number of rules.
* Search by name, description or meter, and sort by **Recently updated**.
* Open the **โฎ** menu on a card to **Edit**, **Clone** or **Remove** a Rulebook.
Removing a Rulebook removes it for everyone and detaches it from characters and personas.
### ๐ Exploring Public Rulebooks
Click **Rulebooks** in the main menu to browse Public Rulebooks made by the community.
* **Search** by keyword and filter by tags.
* Use the **NSFW** toggle to show or hide NSFW Rulebooks.
* **Sort** by **Latest**, **Most Rules**, **Most Attached Characters** or **Most Attached Personas**.
### ๐ก Tips for great Rulebooks
โ
**Start small.** One or two meters with clear levels beat five meters nobody understands.
โ
**Give it a goal.** Win and lose endings (combined rules at the top of the list) turn a chat into a game.
โ
**Write rules about actions, not feelings.** *"`{{user}}` remembers a detail about `{{char}}`"* works better than *"`{{char}}` feels happy"*.
โ
**Mix positives and negatives.** Players should be able to lose ground, not just climb.
โ
**Make the status line fun.** It's the main thing players see. *"She's checking her phoneโฆ"* says more than *"Low interest"*.
โ
**Set the scene in your instructions.** If your Rulebook has a setting (a bar, a wedding, a dungeon), mention it in the level instructions so it works with any character.
โ
**Playtest the edges.** Drag meters to 0 and to max to check every level and ending reads well.
### โFAQ
Do I need a Rulebook to chat?
No. Rulebooks are optional. Characters work exactly as before without one.
Can I see the instructions behind a Rulebook?
No. Users only see the meters, what moves them and the status line. The instructions for the AI stay hidden, for Private and Public Rulebooks alike.
Why didn't my meter move?
AI rules only fire when the AI is confident the condition clearly happened in the latest messages. Try being more explicit in the chat, or reword the rule so it describes a clear action. Keywords always fire when the word appears in your message.
Can I change the Rulebook in a chat?
Not once it's attached. Start a new chat to use a different Rulebook.
What happens if I regenerate a reply?
The meters go back to where they were at that point, so rerolling doesn't stack changes.
Which Rulebook is used if both my persona and the character have one?
The persona's. Chats where you use a persona with a Rulebook follow it instead of the character's.
If I edit my Rulebook, do existing chats update?
New chats use the latest saved version. Chats that already started keep the Rulebook they began with.
Can I hide the meters but keep the game going?
Yes. Use **Hide meters** in the chat menu or the details sheet. The meters keep updating and still shape the replies. To stop them completely, turn off **Interactive features**.
Why is my Public Rulebook not showing in Explore?
Public Rulebooks are reviewed before they go live. If moderation asks for changes, the editor shows what needs fixing. Update every flagged item and submit again.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.spicychat.ai/product-guides/rulebooks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.