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

# Meters

Choose the type first; it decides which settings you get.

{% 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 %}

| You want to track                                                              | Use         | Why                                                                 |
| ------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------- |
| A feeling or relationship with a floor and a ceiling (Trust, Suspicion, Heat)  | Bar         | Smooth value between Min and Max, good with levels                  |
| A few steps (HP 0 to 5, lives, strikes, chapters)                              | Pips        | Up to 10 steps shown as dots                                        |
| An open-ended amount (coins, XP, reputation, debt)                             | Number      | No maximum, units and decimals, can read amounts from the text      |
| Luck or risk the user cannot control                                           | Dice        | A random roll every turn, every few turns or when something happens |
| Story time (deadlines, day and night, a date that must end by midnight)        | Story clock | Date and time that move forward; one per Rulebook                   |
| Where the story is, or one current state (Harbor, Tavern, Forest; Calm, Angry) | Pick one    | One item of a list is selected at a time                            |
| What someone carries or has found (rope x2, the key, clues)                    | Collection  | Items that are held or counted, like an inventory                   |
| Story events the character should remember (the day they met, promises, clues) | Journal     | A dated list of events recorded as they happen                      |

[Limits](https://docs.spicychat.ai/product-guides/rulebooks/troubleshooting-faq-and-limits.md): 15 meters per Rulebook, 8 visible in the chat strip, 1 Story clock. The chat shows the first 4 visible meters in one row; "+N more" shows the rest.

**Settings every meter has**

* Name, icon and color. The icon picker has a search and groups (Feelings, People, Places, Items, Combat, Time & stats). Icons and colors already used by another meter are dimmed, so each meter stays easy to tell apart.
* Visibility: **Shown**, **Panel only** or **Hidden**. Shown meters take one of the 8 slots in the chat strip. Panel only meters stay out of the strip and do not count toward the 8, but they still show in the [explanation sheet](https://docs.spicychat.ai/product-guides/rulebooks/using-a-rulebook-in-chat.md) and in move notes. Hidden meters are never seen by the user at all. Panel only and Hidden meters still drive [influence rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md). Use Panel only for values users should look up but not watch every turn (a debt they check now and then), and Hidden for things the character knows and the user should guess (Suspicion, Secret agenda).
* Players can change this value: lets the user set the meter themselves [from the chat](https://docs.spicychat.ai/product-guides/rulebooks/using-a-rulebook-in-chat.md). Bar, Pips, Number and Story clock only, off by default, and only for meters the user can see (Shown or Panel only; a Hidden meter turns it off). Use it for values players need to correct, like the story time or a wallet after an off-screen purchase.
* What users are told: one item per line, shown in the [explanation sheet](https://docs.spicychat.ai/product-guides/rulebooks/using-a-rulebook-in-chat.md) as "what moves this meter". Write it as hints, not as the full rule.
* Tell the model the value: adds the current value to the character's context every turn, for Bar, Pips and Number meters (the Dice and Story clock have their own version). Off by default. Turn it on when the character should react to the number (refuse what the user can't afford, mention the time). Leave it off for feelings the character should show, not state.

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FbRs9yGqs2pYGhvml52oh%2Frulebooks-480-meter-editor.png?alt=media" alt="The Visibility setting: Shown, Panel only or Hidden" width="390"><figcaption><p>The Visibility setting: Shown, Panel only or Hidden</p></figcaption></figure>

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FOUwr131GrmBr8W9oXgpN%2Frulebooks-d470-icon-picker.png?alt=media" alt="The icon picker: search, groups, dimmed icons are already used" width="390"><figcaption><p>The icon picker: search, groups, dimmed icons are already used</p></figcaption></figure>

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FQ1S7sA9962giknXRgyup%2Frulebooks-d470-color-picker.png?alt=media" alt="The color picker: dimmed colors are used by another meter" width="390"><figcaption><p>The color picker: dimmed colors are used by another meter</p></figcaption></figure>

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FJkmXFCQXghKNgGYXccOI%2Frulebooks-480-meters-tab.png?alt=media" alt="The Meters tab: each row shows the meter&#x27;s Visibility; drag or use the arrows to reorder" width="390"><figcaption><p>The Meters tab: each row shows the meter's Visibility; drag or use the arrows to reorder</p></figcaption></figure>

### Bar and Pips

Min, Max and Starts at. Levels split the range ([Influence rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md)). Pips has at most 10 steps; the steps are whole numbers.

Tell the model the value adds one line to the prompt every turn: a Bar writes "Trust: 40/100.", a Pips writes "Hearts: 3 of 5.".

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FKhxFE11YvepREgNXPAX9%2Frulebooks-480-bar-tell-model.png?alt=media" alt="A Bar meter with Tell the model the value on" width="390"><figcaption><p>A Bar meter with Tell the model the value on</p></figcaption></figure>

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2F3r14jsgKVxicKaQ4SxdQ%2Frulebooks-480-pips-tell-model.png?alt=media" alt="A Pips meter with Tell the model the value on" width="390"><figcaption><p>A Pips meter with Tell the model the value on</p></figcaption></figure>

### Pick one and Collection

Both are lists of up to 20 items, with a name of up to 40 characters each. Each turn, AI detection reads the messages the meter evaluates (the user, the character or both) and updates the list. Write What to detect to tell it what the list follows, for example "Where `{{user}}` is in the harbor town" or "Things `{{user}}` carries". Each item can have a Hint for the AI to tell similar items apart. Users never see the hint.

* Pick one: one item is selected at a time. Choose the item it starts on. AI detection moves to the item the story moves to, or keeps the current one.
* Collection: each item is Counted (rope x2) or Held (has the key). Set a Starting count or Held at start, and an optional Max (empty means no max). AI detection adds, removes or recounts items.
* Hidden until first reached: the item shows as ??? until the chat first selects or holds it. Use it for secret places or clues.
* Rules: Pick one has one rule per item. While the item is selected, its instruction goes to the model and its caption shows as the status line. Collection rules have a condition (has at least, holds at least, doesn't have, holds nothing). While it matches, its instruction goes to the model.
* Pick one and Collection conditions also work in [combined rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md#combined-rules), [triggers](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#triggers), [Only when](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#ai-rules) and dice.

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2F8c4DSANIczqgZRGbrAX4%2Frulebooks-pick-one-v470.png?alt=media" alt="A Pick one meter: where the story is" width="390"><figcaption><p>A Pick one meter: where the story is</p></figcaption></figure>

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FfbLmExb4JyQfaY4YrP8w%2Frulebooks-collection-v470.png?alt=media" alt="A Collection meter: counted and held items" width="390"><figcaption><p>A Collection meter: counted and held items</p></figcaption></figure>

### Number

* Unit (coins, XP, HP) and Precision (no decimals, 1 or 2).
* Per message: a fixed change every message (+1 XP a turn, -2 HP a turn in a poison scene).
* Can decrease: off means the value only grows (XP). On means [keywords](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#keywords), [AI rules](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#ai-rules) and [triggers](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#triggers) can lower it, never below 0. A change that would go below 0 is refused and the user sees "Not enough".
* How the model changes it:
  * Rules: AI rules with fixed impacts, like other meters ("+50 when `{{user}}` finishes a job").
  * Detect from messages: the AI reads the amount from the text. Write What to detect, for example "How much money `{{user}}` has after paying or being paid". It lists each change it finds, as quantity times unit price: "three potions at 20 gold each" is minus 60, "she hands you 200 gold" is plus 200. The changes are applied in order, and the meter never goes below 0 at any step. A total stated in words ("you now have 340 gold") is used only when the messages list no change. If the messages mention no amount, the meter does not change.
  * Use Rules for fixed rewards and penalties. Use Detect for shops, wages, gambling, anything where the text names the amount.

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FwsVlsfr8yiDEj3tRydKx%2Frulebooks-editor-number-v470.png?alt=media" alt="A Number meter with Detect from messages" width="390"><figcaption><p>A Number meter with Detect from messages</p></figcaption></figure>

### Dice

Dice size: d4 to d100 or a custom number of sides (2 to 1000). Use [levels](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md#levels) to react to the roll (1 to 3: "Fumble: something goes wrong"; 18 to 20: "Critical: it goes better than hoped"). Dice have no keyword changes, AI rules or decay: only a new roll changes their value.

**Rolls when**

* Every turn: a new roll on every message. This is the default.
* Every N turns: for example every 3 turns.
* When something happens: the die rolls when any of these is true:
  * Keywords: a message contains one of the words, for example "next stop, brake".
  * When a meter goes up: a meter you tick went up this turn, for example roll once each time Stops goes up.
  * When the AI sees it happen: a short event the AI judges, for example "the bus stops". Needs Roll timing set to After the other meters, because the AI reads the reply.
  * When meters reach values: meter conditions with All or Any, and the same Fires choices as triggers (Each time it becomes true, Every turn while true, Every N turns while true, Once per chat).

With When something happens, Evaluates appears: it decides which messages the keywords and AI conditions read. A die that only reads the Bot's messages and rolls Before the reply can't match anything, because the reply isn't written yet. The editor shows a warning on it.

With two or more options set, an **All or any** choice appears: **Any** rolls when at least one of them matches (the default), **All** rolls only when every set option matches on the same turn, for example roll when the AI sees a new event AND Suspicion is above 60.

**Cooldown** sits under it, off by default: after a roll, the die waits at least that many turns (1 to 999) before it can roll again. A turn the cooldown skips does not use up a "Once per chat" or "Every N turns" window. A die with no options set still rolls every turn.

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FLCwVGFapeiHywxA5VVyl%2Frulebooks-480-dice-gating.png?alt=media" alt="Dice: Rolls when, All or any and Cooldown" width="390"><figcaption><p>Dice: Rolls when, All or any and Cooldown</p></figcaption></figure>

**Roll timing**

* Before the reply: the roll shapes this reply. Its conditions see the meters as they were after the last turn.
* After the other meters: the die rolls after the AI, keywords and triggers have updated this turn, so its conditions see fresh values (for example "roll for loot when Enemy HP reaches 0"). The result shows in chat now and shapes the next reply.

**Effect lasts a few replies**

Off: the result stays until the next roll. On: it clears after that many replies, for example a "Loud group boards" event that lasts 3 replies and then goes away.

**Tell the model the value**

Adds one line with the exact roll to the prompt, on the reply right after a roll, for example "Stop event: rolled 19 on d20 (Sharp brake)". It is not repeated while the result holds.

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FECHZrDKpesaq2Wp0n2qt%2Frulebooks-editor-dice-timing.png?alt=media" alt="Dice: Roll timing, Effect lasts a few replies, Tell the model the value" width="390"><figcaption><p>Dice: Roll timing, Effect lasts a few replies, Tell the model the value</p></figcaption></figure>

Keep roll-based instructions short, because a die that rolls every turn changes them every turn.

### Story clock

* Tracks: Date & time keeps a calendar-style date with a time; Date only counts days and drops the time of day. Pick Date & time when the hour matters (a midnight deadline), Date only when only the day matters ("on day 7 the ship arrives").
* Use a calendar date: on shows weekdays and dates (Tue 10 Mar, 18:40); off counts story days (Day 3, 18:40). Pick on when the real date matters (a deadline, a holiday), off when it does not. Dates and times follow the device language and time format (18:40 or 6:40 PM).
* Story starts on and at: the opening date and time. A day-count clock still keeps a start date, so [date is](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#triggers) conditions can be used on it.
* Advance with each message: how much time one message takes. 0.25 is 15 seconds. Typical values: 1 to 2 minutes for real-time dialogue, 5 to 10 for a normal scene, 30 to 60 for a travel or montage story.
* Detect time skips: the AI reads time words in the messages. "Two hours later" moves 2 hours, "Good morning" in the evening jumps to the next morning, a scene cut or travel to a new place counts as a skip. When it sees a skip but no exact time, it uses a rough amount (hours, next morning, days). Only the messages since the last check are read, so time that was already counted is not counted again. One skip can move the clock up to about 10 years. On a Days only clock, only a move to a later day counts (the next morning, waking up, three days later), and the "one day every N messages" step counts again from the last day change.
* Tell the model the date and time: one line in the context every turn, so the character knows it is 2 a.m.

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FIT7Hcz3hLMZRan66ifdm%2Frulebooks-480-clock-fields.png?alt=media" alt="Story clock settings" width="390"><figcaption><p>Story clock settings</p></figcaption></figure>

<figure><img src="https://3060264960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZHNBN3T5KDxoXWSU7L3d%2Fuploads%2FF2dhVQN7nef6p8hu7odn%2Frulebooks-480-clock-levels.png?alt=media" alt="Time of day and Story day levels in Influence rules" width="390"><figcaption><p>Time of day and Story day levels in Influence rules</p></figcaption></figure>

Rules to know:

* The clock moves forward, with one exception: when the story text states the exact time it is now and that time is earlier the same day ("it's 5:44 PM"), the clock is set back to it. It never goes back to an earlier day or before the story start, and a move back of less than one hour is ignored. A vague time ("that evening") always moves forward.
* Stage directions in brackets, like "\[8:00 PM]", are read as narrator notes, not as the story's time. Write the time in the story text: "By eight that evening...".
* Levels for the clock are set in [Influence rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md) by dimension: Time of day (morning, evening, night) and Story day (Day 1 to 2, "the first weekend"). At least one dimension stays on. A Date only clock only gets Story day controls; the time-of-day settings stay off.
* Clock conditions in [triggers](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#triggers), [combined rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md#combined-rules) and Only when read the time of day, the day, the weekday or an exact date ("date is" Dec 25). "Weekday is" and "date is" need the clock to know its date; "date is" still works on a day-count clock, because the start date stays set. While a clock condition holds, a [Keep between](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#triggers) trigger can pin a meter inside a range (for example keep Stress between 40 and 60 while it is night).

### Journal

A Journal keeps a dated list of story events: "Met her", "Shared a secret", "Found the logbook". When an event happens in the chat it is recorded with its date, and the character remembers it as something that already happened. Up to 30 events.

* Events: a name (up to 40 characters) and an optional icon each. "What counts as this event" is the hint the AI uses to record it; users never see the hint.
* Keyword cues: up to 8 words or phrases per event. A message that contains one records the event right away, without AI.
* When the AI sees it happen: for events a cue did not catch, one shared detection question watches the chat for all journal meters together. Reads: User, Bot or All picks whose messages are read, and What to detect is an extra sentence for it. A Journal counts once against the [AI question budget](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#ai-rules), however many events it has.
* Can happen again: on, the event can be recorded again later, at most once per turn, and the sheet shows "x3" with the earlier dates. Off, it happens once: the first kiss.
* At start: the event is already recorded when the chat begins. Use it for backstory the user did not play, like "they already know each other".
* Tell the model the recorded events: on by default. The character gets a line with the newest recorded events every turn (at most 10). Turn it off for a tracker the character should not talk about.
* Visibility: Shown or Hidden. A Journal has no Panel only option.

[Journal rules](https://docs.spicychat.ai/product-guides/rulebooks/influence-rules.md#journal-rules) send an instruction while the journal matches ("the case is solved"), and [Journal timing](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md#journal-timing) conditions read how long ago an event was recorded.

Dates come from the [Story clock](#story-clock). With a dated clock the sheet shows "Day 3, 15:42"; without one it shows "Turn 5" and "At start". Story-day timing conditions need a dated clock.

**Names with tokens:** a meter name can contain `{{char}}` or `{{user}}`, for example "`{{char}}`'s trust". In the chat it shows the real names.

***

**Up next:** Decide what makes your meters go up and down.

{% content-ref url="/pages/wD4BWvJvVeamQs0CcGUx" %}
[Making meters move](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.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/meters.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.
