> 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/troubleshooting-faq-and-limits.md).

# Troubleshooting, FAQ and limits

## Why did...

### My meter did not move

The condition describes a state, not an action; or the model was not confident; or the rule is on cooldown or fired Once already; or its Only when conditions were not true; or the meter cannot decrease.

Rewrite the condition as an action, check the [trace](https://docs.spicychat.ai/product-guides/rulebooks/playtest-and-checks.md), change Can fire, or turn on Can decrease.

### It moved less than expected

Two rules matched and only the highest in the list counts; or the change was clamped at Min or Max. Merge the rules or raise the impact.

### It moved when nothing happened

An always-true condition, or a reference to a past event. Make the condition specific to a new event.

### Detect read the wrong amount

The hint does not say whose amount, or the text had several amounts. Say "money `{{user}}` has after...", and state totals in the text.

### The clock jumped too far

A time word or scene cut was read as a skip, and no exact time was found. Write exact times in the story text and use skips less. To fix the time of day, write the exact time it is now in the story text ("it's 9 PM"): a time earlier the same day sets the clock back.

### The clock ignores the time I typed

It was in brackets, it was less than one hour earlier than the clock, or it would go back to an earlier day or before the story start. Write it in the story text as the time it is now ("it's 5:44 PM"). A vague time ("that evening") always moves the clock forward.

### The status line is not the one I expected

A combined rule above it matched, or a level with Takes over the status line. Reorder the rules and check the preview in [Playtest](https://docs.spicychat.ai/product-guides/rulebooks/playtest-and-checks.md).

### A combined rule never matches

A value outside a meter's range, or two conditions on one meter that cannot both be true. Open the [checks list](https://docs.spicychat.ai/product-guides/rulebooks/playtest-and-checks.md) under the Save button.

### A trigger did not fire

Its source meter was moved by another trigger. Move the source with a keyword, AI rule or decay.

### My character chat has no meters

The chat was created before the Rulebook; it is a group chat on an app older than 4.9.0; a persona Rulebook is active; Interactive features is off; or Hide meters is on. Start a new chat, check the persona, and check the [sheet settings](https://docs.spicychat.ai/product-guides/rulebooks/using-a-rulebook-in-chat.md).

### My character or group cannot go public

Check the Rulebook attached to it: a public character or group needs an approved Rulebook (Unlisted or Public). Submit the Rulebook for review first, or detach it. See [Visibility, review and versions](https://docs.spicychat.ai/product-guides/rulebooks/visibility-review-and-versions.md).

### My public Rulebook is not in Explore

It is still in review, or it is Unlisted. Check the [status](https://docs.spicychat.ai/product-guides/rulebooks/visibility-review-and-versions.md) on My Rulebooks.

## Questions people ask first

### Does a Rulebook slow down replies or cost more?

A Rulebook adds one short check per turn, after the character's reply. A Continue reply counts as a turn and gets the same check. Replies take a moment longer while the meters update. It does not cost extra messages or tokens on your plan.

### Can players see my rules and instructions?

No. In the chat, players see the meters, the status line, the change chips and the explanation sheet. They never see your instructions, AI rules, keywords, triggers or hidden meter values. Other creators can read a Public Rulebook's meters and rules on its page when it shows **Rules visible**.

### What does ??? mean on a meter or in the explanation sheet?

The value is masked, not missing: levels and list items the chat has not reached yet, and anything the creator keeps hidden, show as `???`.

### Does it work in the mobile app?

Yes. Chats with a Rulebook show the meters, the status line and the explanation sheet in the app, and you can attach a Rulebook there. The Editor is on the website: open **My Rulebooks** in the app and tap **Edit** to continue on the web. Editing a persona's Rulebook field is also on the website for now; in the app you can attach a Rulebook to a persona from the Rulebook's page but not remove it.

### Can one Rulebook go on several characters?

Yes. Attach the same Rulebook to as many of your characters and personas as you like. Each chat keeps its own meter values.

### If I start a new chat or restart one, do the meters reset?

Yes. Every chat keeps its own meter values, and a new chat starts from the Rulebook's starting values. Regenerating or switching to another reply restores the values saved at that point.

### Who reviews my Rulebook?

Automated checks read every submission first, then a moderator decides. Approval publishes the version; Needs changes sends it back with the flagged fields and the reason in the editor. Fix them and submit again. See Save for testing and Submit for review.

### Does a Rulebook work in group chats?

Yes. Attach the Rulebook to the group itself: in the Rulebook's attach picker, your groups are listed with your characters. The members' own Rulebooks are not used inside the group; they keep working in each character's own chats. A persona Rulebook still wins over the group's. On older app versions, group chats ignore Rulebooks.

In a group chat, `{{char}}` is the member who wrote the latest reply. In group story mode, `{{char}}` is the group's name. To track one member, write that member's name in the rule, for example "Mia is warm to `{{user}}`". Something said to the whole group ("you all", "everyone") counts for each member.

The AI can still count what one member describes another doing, for example Leo writing "Mia takes your hand" can move a rule about Mia. Rules about one member work best when that member acts in their own reply.

### Why does Playtest behave differently from the real chat?

Playtest runs the same checks as a real chat, but you write both sides of the conversation. In a real chat the character's reply comes from the model, so a rule that reads `{{char}}`'s behaviour may fire differently. Cooldowns and quiet turns are kept between evaluations, like in a chat.

### What happens to chats when I edit my Rulebook?

A Private Rulebook applies to every chat that uses it from the next message. A Public or Unlisted change goes live after [review](https://docs.spicychat.ai/product-guides/rulebooks/visibility-review-and-versions.md); until then chats keep the last approved version. See [Edits to a Rulebook](https://docs.spicychat.ai/product-guides/rulebooks/using-a-rulebook-in-chat.md).

**Limits**

| Item                     | Limit                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------- |
| Meters                   | 15, 8 visible in the chat strip, 1 Story clock                                          |
| Pips steps               | 10                                                                                      |
| Dice sides               | 2 to 1000                                                                               |
| Levels per meter         | 12                                                                                      |
| AI questions per message | 60                                                                                      |
| Keyword groups per meter | 20, 50 words each, 64 characters per word                                               |
| Triggers per meter       | 10                                                                                      |
| Pick one / Collection    | 20 items, 40 characters per item name, Collection count up to 9999, 20 Collection rules |
| Combined rules           | 30, 6 conditions each                                                                   |
| Condition length         | 300 characters                                                                          |
| Instruction              | 600 characters per instruction, about 1200 tokens total (1800 hard limit)               |
| Status line              | 120 characters shown, warning above 48                                                  |
| Name, description        | 60, 800 characters; meter and level names 40                                            |
| Tags                     | 0 to 6; Public needs at least 2, with one Focus tag                                     |
| Number range             | -20,000,000 to 20,000,000                                                               |
| Clock step               | 0.25 minutes to 1 year                                                                  |

## Glossary

| Word                                                                                            | Meaning                                                                         |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Meter](https://docs.spicychat.ai/product-guides/rulebooks/meters.md)                           | A value the Rulebook keeps score of, like Trust or Coins                        |
| [Driver](https://docs.spicychat.ai/product-guides/rulebooks/making-meters-move.md)              | What moves a meter: keyword, AI rule, decay, per message change or trigger      |
| AI rule                                                                                         | A yes or no question about the last exchange, with an impact on a meter         |
| Level                                                                                           | A range of a meter with its own status line and instruction                     |
| Status line                                                                                     | The short text players see under the meters                                     |
| Instruction                                                                                     | Text the model gets while a level or combined rule applies, hidden from players |
| Combined rule                                                                                   | A rule across several meters, with its own status line and instruction          |
| Trigger                                                                                         | A meter-to-meter change without AI                                              |
| Can fire                                                                                        | How often an AI rule can fire: every turn, once, or every N turns               |
| Quiet turn                                                                                      | A turn where nothing moved the meter; decay counts these                        |
| [Starter](https://docs.spicychat.ai/product-guides/rulebooks/examples-to-clone.md)              | A small Rulebook that comes with the app, to copy and change                    |
| [Version](https://docs.spicychat.ai/product-guides/rulebooks/visibility-review-and-versions.md) | Each approved Public or Unlisted change gets a new number                       |

***

You have reached the end of the guide. [Go back to the start of the Rulebooks guide](https://docs.spicychat.ai/product-guides/rulebooks).


---

# 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/troubleshooting-faq-and-limits.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.
