> 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/making-meters-move.md).

# Making meters move

Every turn, the meters move in this order. A normal exchange (your message plus the reply) is one turn, and a Continue reply is a turn of its own:

1. [Keywords](#keywords), the [Number](https://docs.spicychat.ai/product-guides/rulebooks/meters.md#number) meter's Per message change, and the [Story clock](https://docs.spicychat.ai/product-guides/rulebooks/meters.md#story-clock)'s time per message.
2. [Decay](#decay), only on a quiet turn when nothing in step 1 moved the meter.
3. [Triggers](#triggers), when a meter has just reached a trigger value.
4. [AI rules](#ai-rules) and [Detect from messages](https://docs.spicychat.ai/product-guides/rulebooks/meters.md#number), after the reply, reading your message and the reply together (on a Continue turn, just the reply).
5. Triggers again if step 4 pushed a meter to a trigger value.

Dice set to Before the reply roll before step 1. Dice set to After the other meters roll after step 5, so they see this turn's values.

A [Journal](https://docs.spicychat.ai/product-guides/rulebooks/meters.md#journal) has no value to move: its keyword cues record an event the moment their words appear in the chat, and the shared journal question records what the AI saw happen in step 4.

{% hint style="success" %}
**You don't need all of this.** Most Rulebooks use 1 or 2 Bar meters, 2 to 4 AI rules and 3 levels. Everything else on this page is optional. Start with a [Starter](https://docs.spicychat.ai/product-guides/rulebooks/examples-to-clone.md) and come back here when you want more.
{% endhint %}

### Keywords

Changes the meter by an amount, or sets it to a value, when the user's message contains one of the words. Free and instant, no AI. Good for commands and gifts ("give flowers", "pay", "attack"). Up to 20 word groups per meter, 50 words each. Keywords match the user's message only, not the reply. A Set keyword wins over the other keywords on that meter for this turn, and AI rules that change by an amount are then ignored. An AI rule with Set to can still override it.

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FVReGyRZMbZP59MTfCnQs%2Frulebooks-editor-keywords-decay-fit.png?alt=media" alt="Keywords and Decay" width="390"><figcaption><p>Keywords and Decay</p></figcaption></figure>

### AI rules

A small model reads the latest user message and the reply and answers one yes/no question per rule: "Did this clearly happen in the new message?" A rule fires when the model is confident (about 70 percent or more).

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FMyDUfmAu3PLl8yYt5Ujw%2Frulebooks-ai-rules-v470.png?alt=media" alt="AI evaluation rules: an impact rule, a Set to rule, and Only when" width="390"><figcaption><p>AI evaluation rules: an impact rule, a Set to rule, and Only when</p></figcaption></figure>

How to write a condition:

* Describe an action in the new message, not a state. "`{{user}}` apologises to `{{char}}`" works. "`{{user}}` is sorry" is weak.
* One event per rule. Split "compliments or helps" into two rules.
* Name who does it. "`{{char}}` refuses" and "`{{user}}` refuses" are different rules.
* On a group bot, `{{char}}` is the member who wrote the latest reply, and something said to the whole group counts for each member. To follow one member, write the member's name in the rule ("Mira thanks `{{user}}`" only fires for Mira), but only in a Rulebook made for that specific group.
* Avoid conditions that are always true ("the conversation continues"). The editor warns about them. For a change every turn, use Decay or Per message instead.
* Meter tokens in a condition are replaced by the bare current value before the AI reads it: {{meters.gold}} becomes "30", not "Gold 30". Write the token into the sentence so it still reads well: "`{{user}}` offers more than {{meters.gold}} coins". The Caption token becomes the status line of the current level. Values are this turn's values after keywords and decay.
* Don't use a meter value as an on/off switch for the rule ("while {{meters.affection}} is 20 or lower"): the AI reads "while 30 is 20 or lower". Use Only when instead (Affection <= 20). To change how `{{char}}` reacts at different values, write it in the level instructions.

| Weak                   | Better                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `{{char}}` feels happy | `{{user}}` does something that makes `{{char}}` laugh                                                                    |
| the date goes well     | `{{user}}` gives `{{char}}` a sincere compliment (a second rule: `{{user}}` asks about something `{{char}}` just shared) |
| `{{user}}` is rude     | `{{user}}` insults `{{char}}` (a second rule: `{{user}}` ignores a question `{{char}}` asked)                            |
| time passes            | (use [Decay](#decay) or the Story clock)                                                                                 |

Effect: ± changes the meter by an amount when the rule fires, Set sets it to a value (kept inside the meter's range).

Priority order: rules are checked from the top of the list. When several rules on one meter match in the same turn, only the highest one counts. Drag the number or use the arrows to reorder them.

Only when: meter conditions with All or Any, the same as triggers. The AI only checks the rule while they are true, so a rule that does not apply takes no question from the budget. Example: "`{{user}}` apologises" Only when Anger >= 50. Only when can also use the Story clock, for example "the shop is open" Only when time of day is Morning or Afternoon. It reads the clock from before the message, so a rule limited to Monday is asked from the first message on Monday.

Can fire: Every turn, Once (one-off story beats: the first kiss, the reveal), or Every N turns (a reward that should not repeat every message).

Budget: a Rulebook can ask up to 60 questions per message across all meters, including the Story clock's skip question. The editor shows how many you have left.

Referring back to an old event does not fire the rule again. "Remember when you lied to me?" is not a new lie.

### Journal

A [Journal](https://docs.spicychat.ai/product-guides/rulebooks/meters.md#journal) records events instead of changing a value. An event is recorded when one of its keyword cues appears in the chat, or when the shared journal question sees it happen. Each event records at most once per turn, even events that can happen again.

Timing conditions read the newest record of one event: "turns at least" or "story days at most" count how long ago it was recorded. They work in [triggers](#triggers), [combined rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md#combined-rules) and [Only when](#ai-rules). The story days form needs a [Story clock](https://docs.spicychat.ai/product-guides/rulebooks/meters.md#story-clock) with a date; without a dated clock only turns can be counted.

### Decay

Drifts the meter on quiet turns: an amount, every N quiet turns, only when nothing else moved the meter. Use it for things that fade: Heat cools, Suspicion settles, Hunger rises.

### Triggers

When a watched meter or the clock matches a condition, change this meter, with no AI. Set them on the meter that should change. Example: "When Trust >= 80, set Key to 1" or "When HP <= 0, Change Lives by -1 and Set HP to 5".

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FpTsrB9jVsBoDgQ4Dz8KB%2Frulebooks-480-triggers.png?alt=media" alt="Triggers: Keep between while a clock condition holds, and a meter condition that fires every turn" width="390"><figcaption><p>Triggers: Keep between while a clock condition holds, and a meter condition that fires every turn</p></figcaption></figure>

* Conditions can watch any other meter, never the trigger's own meter: Bar, Pips, Number or Dice meters with at least (>=), at most (<=), above (>), below (<) or equals (=), and Pick one or Collection meters (is, isn't, has at least, doesn't have). Match All or Any.
* Conditions can also read the Story clock: time of day is, day >=, day <=, day is, date is and weekday is. "Date is" takes a month and a day, with an optional year (a wedding anniversary, a deadline); it works on a day-count clock too, because the clock keeps its start date. "Weekday is" needs a clock with a calendar date. Example: a Number meter "Weeks" with "weekday is Monday, each time it becomes true, Change by +1", and the same trigger on Wallet with -50 for the rent. A time skip of exactly 7 days goes from Monday to Monday, so "each time it becomes true" does not fire.
* Effect: Change by an amount, Set to a value, or Keep between (Bar and Number only). Keep between holds the meter inside a min and max for as long as the conditions are true: for example "day <= 5, Keep between 30 and 40" stops Affection from leaving that range until day 6.
* Fire: Each time it becomes true (resets when it stops being true), Every turn while true, Every N turns while true, or Once per chat.
* A change made by a trigger never fires another trigger. Up to 10 triggers per meter. Users see a plain "Trigger" chip and never the rule.

***

**Up next:** Make the character act differently at each level.

{% content-ref url="/pages/LObg0ThDjJHPMV1GdhZz" %}
[Influence rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md)
{% endcontent-ref %}


---

# 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/making-meters-move.md?ask=<question>&goal=<user_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.
