> For the complete documentation index, see [llms.txt](https://cardstock-studio.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cardstock-studio.gitbook.io/docs/test/playtest-flow-overview.md). # Playtest Flow Overview ***Playtest*** turns your written rules into a working model of your game, then has bots play that model over and over — hundreds or thousands of seeded games — so balance problems show up on a chart instead of at a table. {% hint style="success" %} **This will not replace human playtesting, and it isn't trying to.** {% endhint %} What it's good at is the part human testers hate: playing the same setup five hundred times so you can see whether going first wins too often, whether that one card is basically dead weight, or whether the economy stalls out around turn nine. Your friends can then spend their evenings on the stuff bots can't judge — whether the game is actually *fun*. {% hint style="warning" %} Games built around resources, economies, and engines model really well. Games that lean on bluffing, table talk, dexterity, or "the group decides" moments model less well. Most games land somewhere in between, and you'll find out quickly. {% endhint %} The flow runs in order, and each stage unlocks the next. ## 1. Define Rules You'll paste or upload your written rules (or point at a rulebook you've built in [**Books**](/docs/design/books.md)), list the physical components, and link each deck so the AI reads your real card data. During the refinement flow, your AI will ask questions about the rules. Each answer you provide becomes a numbered ruling that's kept permanently alongside your rules. The end result is a short structured brief of the game, which boils down the rules into a structure that both humans and AIs can quickly consume. {% hint style="success" %} Even if you do not plan to run simulations, the **Rules** flow may help you spot holes in your instructions, or areas where humans may be confused or make inaccurate assumptions. {% endhint %} ## 2. Add Measurements Here you will state what you wish to learn from the simulations. "Does first player win too much?" "Is the resource economy too generous?" These are the concrete metrics the simulations will track. While this step is optional, you may get much more from the simulations by adding measurements to track. ## 3. Build Playtest Game In this step you will compile your rules into a runnable game. This step uses AI heavily, as it requires the AI to literally write the code for the game to run on the custom Cardstock Studio simulation engine. ## 4. Define Personas & Goals Bots that just optimize all play the same way, and that tells you very little. Personas give each seat a personality — aggression, patience, risk appetite, all visible dials — so a run can show you which *strategy* wins rather than who got lucky. Goals point the bots at your game's actual payoffs so they plan toward something instead of drifting. The AI drafts these from your rules; you can edit every value. ## 5. Set up A/B Variations This is the house-rule laboratory. Every tunable number in your built game becomes a variable, and a variation is just a named column where you override the handful you want to test — starting gold at 4 instead of 5, for example. When two variations run head to head, the only differences are the ones you typed, so the comparison can help illuminate actual differences based on the changes. ## 6. Run Simulations & Analyze Results Pick which bot sits at each seat, set the number of games, and run. Runs are seeded, so a result you find can be reproduced exactly. Every run is saved, and the analysis tools work through them: win rates by seat and persona, your metrics from earlier, card analytics that flag cards nobody ever plays, loop detection for games that circle forever, and a plain-English writeup of what happened. {% hint style="info" %} **Simulations are not run by AI.** They are run by your system and are "free". In most cases, 1,000 games can be simulated in less than 20 minutes, and we find that running more simulations tends to provide results that begin to show the true averages. {% endhint %} {% hint style="success" %} You can also choose to watch an entire game turn by turn, steping forward and back. This is a very useful tool to better understand how your bot personas are "thinking" about the decisions and actions they make, which can help you refined the simulation. If you find something off here — perhaps bots are doing something that no reasonable human would ever do — go back to the **Build** phase and prompt the AI to fix the issue. Please expect a few rounds of this type of refinement, as edge cases are discovered. {% endhint %} ## A few things worth knowing ### **🤖 This flow uses AI** It would be nearly impossible for a human to set up the simulations. During this flow, you will be given .md files to upload into your preferred AI such as Clause or ChatGPT. These files include everything the AI needs, along with instructions on how to reply. You will then import the reply into the system, to make updates. Expect a few laps through the loop — rules, build, simulate, find edge cases and unexpected bot behavior, adjust — before the model really matches your intent. That loop is fast, it's cheap, and will get you to where you can start finding real actionable insights. {% hint style="success" %} We set up this flow to export instructions and import responses because it's less expensive than using AI credits through the API — in most cases at least. Subscriptions currently include more total usable credits, and will save money over using an API key. {% endhint %} ### Helps with Unity Export If you plan on exporting your game to [Unity](/docs/ship/unity.md), the rules, personas, and other data from this flow can be exported as well, allowing any AI assistant to utilize the defined values in your digital version as well. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cardstock-studio.gitbook.io/docs/test/playtest-flow-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.