How agents should reason, check in, and manage project knowledge when working in this project.
Read the first-layer pages listed on index.page. Give a brief confirmation that you understand the project and stop. Do not dive into board details or hunt for more context unprompted.
Wait for the user to direct next steps.
boards/tasks.page, boards/bugs.page, and boards/backlog.page are not part of the initial read unless the user directs it or a task clearly requires current board state.
After roughly 1 000 tokens of internal reasoning without a clear answer, pause and surface the situation to the user. The user is an expert and can often shortcut a long investigation with domain knowledge or a targeted hint.
Be brief and concrete. Name the specific problem, the hypotheses already ruled out, and what would help most. Offer concrete actions the user can take - open DevTools, check a log, paste an error.
The user has explicitly said so in the current session - e.g. \"just continue\", \"don't interrupt\", \"do the whole thing\". That permission is session-scoped and does not carry into the next conversation.
All persistent knowledge about this project - planned features, decisions made, open improvements, session notes - lives in workspace/ and is version-controlled. Agents must write project knowledge here, not into local agent memory files. The workspace is visible to the user, survives across machines, and is the single source of truth.
guides/actions/Give feedback when tasks become too large for a single session. Cleanups and documentation often need a follow-up session with enough context to do them properly. Communicate this rather than rushing or going silent.
When writing workspace documents, use the hyphen/minus character - instead of the em dash —. This applies to prose, lists, and task descriptions.
The dialogue system is built around composable DialogBlock ScriptableObjects. Each block represents one piece of narrative logic, and the dialogue runtime evaluates blocks sequentially while allowing branches and reusable sub-dialogues.
DialogBlock\n27\t├── DialogLine\n28\t├── PlayerChoice\n29\t├── DialogBranch\n30\t├── DialogList\n31\t├── ReturnBlock\n32\t└── CommentBlockDialogBlockAbstract base class for all dialogue elements.
Blocks can be placed into dialogue sequences and evaluated by the dialogue runtime. Each block can reference other blocks, allowing dialogue to form a graph rather than being limited to a linear sequence.
DialogLineRepresents a spoken dialogue line.
DialogLine\n33\t├── Locale\n34\t└── SpeakerThe Locale provides the localized text, while Speaker identifies the character delivering the line.
Presentation such as portraits, voice, animation, etc. is handled separately through actions/presentation systems.
PlayerChoicePresents the player with multiple dialogue choices.
PlayerChoice\n35\t├── ChoiceLine\n36\t└── Options[]\n37\t ├── Line\n38\t └── Actions[]Each option can execute one or more GameStateActions when selected.
Actions may modify global game state, which can subsequently affect dialogue branching.
DialogBranchConditionally redirects dialogue flow.
DialogBranch\n39\t├── Condition\n40\t└── Branch → DialogBlockThe branch evaluates a GameStateCondition. If the condition is satisfied, dialogue continues from the referenced block.
Conditions can be composed using structures such as ListCondition.
DialogListA reusable collection of dialogue blocks.
DialogList\n41\t└── Blocks[]DialogList is itself a DialogBlock, allowing lists to be nested or referenced from other dialogue structures.
This provides a convenient way to build reusable dialogue sections without requiring every conversation to be a single monolithic graph.
ReturnBlockExplicitly terminates the current dialogue sequence or returns control to the containing dialogue flow.
Useful for ending branches early without requiring special logic in the dialogue runtime.
CommentBlockEditor-only documentation/orientation.
CommentBlock\n42\t└── ContentUsed to annotate complex dialogue structures and help designers understand the intended organization of a conversation.
It has no gameplay effect.
Dialogue blocks themselves remain focused on narrative flow. Game-state manipulation and evaluation are handled through separate abstractions.
GameStateCondition\n43\t├── CompareInt\n44\t├── HasObject\n45\t├── ...\n46\t└── ListCondition\n47\t ├── All\n48\t ├── AtLeastOne\n49\t └── NoneGameStateAction\n50\t├── SetProperty\n51\t├── ModifyProperty\n52\t├── RemoveObject\n53\t├── ...\n54\t└── ActionListThis keeps the dialogue system independent from the specific implementation of game state.
DialogBlock\n55\t │\n56\t ├── Present content\n57\t │\n58\t ├── Evaluate conditions\n59\t │\n60\t ├── Execute GameStateActions\n61\t │\n62\t └── Continue / Branch\n63\t │\n64\t ▼\n65\t another DialogBlockThe result is a data-driven dialogue graph where narrative designers can construct complex conversations without writing code, while the runtime remains responsible primarily for evaluating flow and coordinating the dialogue state.
The important architectural idea is:
\n68\t\n69\t\n71\tSimulation owns truth. Systems transform state. Commands/deltas describe what happened. Unity renders the result.
\n70\t
\n110\t┌─────────────────────────────────────────────┐\n73\t│ Unity Layer │\n74\t│ │\n75\t│ UI / Input / Animations / VFX / Audio │\n76\t│ │ ▲ │\n77\t│ ▼ │ │\n78\t│ Player Commands Commands/Events │\n79\t└──────────┬─────────────────────┬────────────┘\n80\t │ │", "toolId": "toolu_011HShj3Kd4mB5FQFHr4XHuH" }, { "type": "tool_call", "name": "Read", "args": { "file_path": "C:\\Users\\Josef\\.claude\\projects\\C--rokojori-projects-unity-projects-Unity-Roject-Test\\1cf7ca7c-0518-4c67-b7f1-43f30241ab0a\\tool-results\\mcp-roject-get_text_content-1790362520267.txt", "offset": 80, "limit": 200 }, "toolId": "toolu_01BPrwMCCqG5ndpTrhksPRmA" }, { "type": "tool_result", "name": "toolu_01BPrwMCCqG5ndpTrhksPRmA", "result": "80\t │ │\n81\t ▼ │\n82\t┌─────────────────────────────────────────────┐\n83\t│ Simulation Layer │\n84\t│ │\n85\t│ SimulationManager │\n86\t│ │ │\n87\t│ ▼ │\n88\t│ Phase / Turn Controller │\n89\t│ │ │\n90\t│ ▼ │\n91\t│ Systems │\n92\t│ ├── ProductionSystem │\n93\t│ ├── ConsumptionSystem │\n94\t│ ├── AllocationSystem │\n95\t│ ├── PollutionSystem │\n96\t│ ├── CombatSystem │\n97\t│ ├── WinConditionSystem │\n98\t│ └── ... │\n99\t│ │ │\n100\t│ ▼ │\n101\t│ GameState │\n102\t│ │ │\n103\t│ ├── Entities │\n104\t│ ├── Resources │\n105\t│ ├── Technologies │\n106\t│ ├── Effects │\n107\t│ └── Spatial Fields │\n108\t│ │\n109\t└─────────────────────────────────────────────┘
SimulationManagerThis is the conductor, not the place where game rules live.
\n114\t\n125\tpublic class SimulationManager\n115\t{\n116\t public GameState State { get; }\n117\t\n118\t public void ExecuteTurn()\n119\t {\n120\t ExecutePhase(Phase.PreTurn);\n121\t ExecutePhase(Phase.PlayerTurns);\n122\t ExecutePhase(Phase.PostTurn);\n123\t }\n124\t}
Its responsibility is basically:
\n126\tIt shouldn't contain:
\n144\t\n145\tif (city.HasFactory && city.HasTechnology ...)
Those rules belong elsewhere.
\n146\tI'd make the turn structure explicit.
\n149\t\n170\tTURN\n150\t│\n151\t├── PreTurn\n152\t│ ├── UpdateEnvironmentalFields\n153\t│ ├── ApplyGlobalEffects\n154\t│ └── DeterminePlayerOrder\n155\t│\n156\t├── PlayerTurn\n157\t│ ├── Player A\n158\t│ │ └── ProcessPlayerCommands\n159\t│ ├── Player B\n160\t│ │ └── ProcessPlayerCommands\n161\t│ └── ...\n162\t│\n163\t└── PostTurn\n164\t ├── Production\n165\t ├── ResourceAllocation\n166\t ├── Consumption\n167\t ├── UpdateFields\n168\t ├── Effects\n169\t └── WinConditions
The exact phases are game-specific.
\n171\tThe important thing is that the order is explicit and documented.
\n172\tEach system does one conceptual job.
\n175\tFor example:
\n176\t\n187\tProductionSystem\n177\t ↓\n178\treads:\n179\t City\n180\t Factory\n181\t Technology\n182\t PollutionField\n183\t TemporaryEffects\n184\t\n185\twrites:\n186\t ProductionDeltas
Then:
\n188\t\n197\tResourceAllocationSystem\n189\t ↓\n190\treads:\n191\t ResourceState\n192\t ConsumerRequests\n193\t AllocationPolicies\n194\t\n195\twrites:\n196\t AllocationDeltas
Then:
\n198\t\n205\tConsumptionSystem\n199\t ↓\n200\treads:\n201\t Allocations\n202\t\n203\twrites:\n204\t ResourceDeltas
This keeps the simulation understandable.
\n206\tI'd make GameState the authoritative runtime state.
Something roughly like:
\n210\t\n225\tpublic class GameState\n211\t{\n212\t public int Turn;\n213\t public ulong RandomSeed;\n214\t\n215\t public EntityState[] Entities;\n216\t\n217\t public ResourceState Resources;\n218\t\n219\t public TechnologyState Technologies;\n220\t\n221\t public EffectState Effects;\n222\t\n223\t public SpatialState Spatial;\n224\t}
The important distinction is:
\n226\tMostly static:
\n228\t\n234\tResourceDefinition\n229\tFactoryDefinition\n230\tTechnologyDefinition\n231\tBuildingDefinition\n232\tEffectDefinition\n233\tAllocationPolicy
These could be ScriptableObjects.
Changes during the simulation:
\n237\t\n243\tCity has 120 food\n238\tFactory is active\n239\tPlayer owns city\n240\tTechnology researched\n241\tPollution = 37\n242\tTurn = 42
This belongs in the simulation state/save data.
\n244\tYour NumericResource idea fits nicely here.
\n252\tNumericResource\n248\t ├── Food\n249\t ├── Iron\n250\t ├── Gold\n251\t └── Water
Then quantities are runtime values:
\n253\t\n256\tFood = 120\n254\tIron = 35\n255\tGold = 500
Definitions describe what a resource is.
\n257\tState describes how much currently exists.
\n258\tInstead of a huge EconomyManager, factories contain/configure processors.
\n275\tFactory\n262\t │\n263\t └── FactoryProcessor\n264\t │\n265\t ├── Inputs\n266\t │ └── Iron: 10\n267\t │\n268\t ├── Outputs\n269\t │ └── Steel: 5\n270\t │\n271\t └── Conditions\n272\t ├── Active\n273\t ├── NearRiver\n274\t └── TechnologyRequired
Then:
\n276\t\n287\tProductionSystem\n277\t │\n278\t ├── Find producers\n279\t │", "toolId": "toolu_01BPrwMCCqG5ndpTrhksPRmA" }, { "type": "tool_call", "name": "Read", "args": { "file_path": "C:\\Users\\Josef\\.claude\\projects\\C--rokojori-projects-unity-projects-Unity-Roject-Test\\1cf7ca7c-0518-4c67-b7f1-43f30241ab0a\\tool-results\\mcp-roject-get_text_content-1790362520267.txt", "offset": 560, "limit": 33 }, "toolId": "toolu_01AWKUePnbhxzigEP16Eb9pB" }, { "type": "tool_result", "name": "toolu_01AWKUePnbhxzigEP16Eb9pB", "result": "560\tSystem execution order is explicit and deterministic.\n561\t\n562\t\n563\tState mutations go through a controlled mutation/delta mechanism.\n564\t \n565\t\n566\tStatic game definitions are separate from runtime state.\n567\t \n568\t\n569\tSpatial relationships should generally be queried through reusable spatial fields.\n570\t \n571\t\n572\tRandomness is seeded and deterministic.\n573\t \n574\t\n575\tImportant mutations produce inspectable debug information.\n576\t \n577\t\n578\tPlayer actions enter the simulation as commands.\n579\t \n580\t\n581\tRendering reacts to simulation results rather than driving them.\n582\t \n583\t\n584\tEvery major architectural addition should have documentation and a clear ownership boundary.\n585\t \n586\t\n587\tThe nice thing is that this architecture can start much smaller than the diagram suggests. You don't need ECS, multithreading, Barnes–Hut, sophisticated replay, etc. on day one. You can start with
\n588\tSimulationManager → Phases → Systems → GameState, establish the boundaries, and introduce the heavier pieces only when profiling or game complexity actually demands them.\n589\t\n590\t\n591\t Right Column
Something on the right\n592\t", "toolId": "toolu_01AWKUePnbhxzigEP16Eb9pB" }, { "type": "tool_call", "name": "mcp__roject__list_files", "args": { "path": "Assets" }, "toolId": "toolu_01HN2gRKPxqpEwuXSppLHtCU" }, { "type": "tool_result", "name": "toolu_01HN2gRKPxqpEwuXSppLHtCU", "result": "[{\"name\":\"Hello World.asset\",\"type\":\"file\"},{\"name\":\"Hello World.asset.meta\",\"type\":\"file\"},{\"name\":\"Main\",\"type\":\"directory\"},{\"name\":\"Main.meta\",\"type\":\"file\"},{\"name\":\"Scripts\",\"type\":\"directory\"},{\"name\":\"Scripts.meta\",\"type\":\"file\"},{\"name\":\"Settings\",\"type\":\"directory\"},{\"name\":\"Settings.meta\",\"type\":\"file\"},{\"name\":\"UI\",\"type\":\"directory\"},{\"name\":\"UI.meta\",\"type\":\"file\"}]", "toolId": "toolu_01HN2gRKPxqpEwuXSppLHtCU" }, { "type": "tool_call", "name": "mcp__roject__list_files", "args": { "path": "workspace/actions" }, "toolId": "toolu_017fGJsfgjpUyfK4dhiQqpZ4" }, { "type": "tool_result", "name": "toolu_017fGJsfgjpUyfK4dhiQqpZ4", "result": "[{\"name\":\"creating-pages\",\"type\":\"directory\"},{\"name\":\"getting-started\",\"type\":\"directory\"},{\"name\":\"index.page\",\"type\":\"file\"},{\"name\":\"update-history\",\"type\":\"directory\"},{\"name\":\"update-outline\",\"type\":\"directory\"},{\"name\":\"update-tasks\",\"type\":\"directory\"}]", "toolId": "toolu_017fGJsfgjpUyfK4dhiQqpZ4" }, { "type": "tool_call", "name": "mcp__roject__list_files", "args": { "path": "workspace/notes" }, "toolId": "toolu_01GGs8BEsVqshWBvP1NToTVa" }, { "type": "tool_result", "name": "toolu_01GGs8BEsVqshWBvP1NToTVa", "result": "[{\"name\":\"index.page\",\"type\":\"file\"}]", "toolId": "toolu_01GGs8BEsVqshWBvP1NToTVa" }, { "type": "tool_call", "name": "mcp__roject__list_files", "args": { "path": "workspace/boards" }, "toolId": "toolu_01XPTWMTjZiVDpZCCAyy7Mdh" }, { "type": "tool_result", "name": "toolu_01XPTWMTjZiVDpZCCAyy7Mdh", "result": "[{\"name\":\"backlog.page\",\"type\":\"file\"},{\"name\":\"bugs.page\",\"type\":\"file\"},{\"name\":\"index.page\",\"type\":\"file\"},{\"name\":\"tasks.page\",\"type\":\"file\"}]", "toolId": "toolu_01XPTWMTjZiVDpZCCAyy7Mdh" }, { "type": "tool_call", "name": "mcp__roject__list_files", "args": { "path": "Assets/Scripts" }, "toolId": "toolu_015F8N5TdfFvyX9h5oYTid1M" }, { "type": "tool_result", "name": "toolu_015F8N5TdfFvyX9h5oYTid1M", "result": "[{\"name\":\"Project\",\"type\":\"directory\"},{\"name\":\"Project.meta\",\"type\":\"file\"},{\"name\":\"Rokojori\",\"type\":\"directory\"},{\"name\":\"Rokojori.meta\",\"type\":\"file\"}]", "toolId": "toolu_015F8N5TdfFvyX9h5oYTid1M" }, { "type": "tool_call", "name": "mcp__roject__get_text_content", "args": { "path": "workspace/boards/backlog.page" }, "toolId": "toolu_01BEdNvjofcgKzaZetWzBHgb" }, { "type": "tool_result", "name": "toolu_01BEdNvjofcgKzaZetWzBHgb", "result": "\n\n \n Backlog — Unity-Roject-Test \n \n\n\n\n\n \n \n\n\n \n\n Backlog
\n \n\n Ideas & Future Direction
Add longer-horizon ideas, vague features, and things that are too big or unclear for tasks yet.\n\n\n", "toolId": "toolu_01BEdNvjofcgKzaZetWzBHgb" }, { "type": "tool_call", "name": "mcp__roject__get_text_content", "args": { "path": "workspace/boards/bugs.page" }, "toolId": "toolu_018tjSK9C3kh5Dfa5mkYkCry" }, { "type": "tool_result", "name": "toolu_018tjSK9C3kh5Dfa5mkYkCry", "result": "\n\n \n New Page \n \n\n\n\n\n \n \n\n\n \n\n Bugs
\n\n", "toolId": "toolu_018tjSK9C3kh5Dfa5mkYkCry" }, { "type": "tool_call", "name": "mcp__roject__list_files", "args": { "path": "Assets/Scripts/Rokojori" }, "toolId": "toolu_01BCd6nc1ajCRUwAp9kJpv6Z" }, { "type": "tool_result", "name": "toolu_01BCd6nc1ajCRUwAp9kJpv6Z", "result": "[{\"name\":\"Events\",\"type\":\"directory\"},{\"name\":\"Events.meta\",\"type\":\"file\"},{\"name\":\"Extensions\",\"type\":\"directory\"},{\"name\":\"Extensions.meta\",\"type\":\"file\"},{\"name\":\"Locales\",\"type\":\"directory\"},{\"name\":\"Locales.meta\",\"type\":\"file\"},{\"name\":\"Logging\",\"type\":\"directory\"},{\"name\":\"Logging.meta\",\"type\":\"file\"},{\"name\":\"Unique.cs\",\"type\":\"file\"},{\"name\":\"Unique.cs.meta\",\"type\":\"file\"}]", "toolId": "toolu_01BCd6nc1ajCRUwAp9kJpv6Z" }, { "type": "tool_call", "name": "mcp__roject__list_files", "args": { "path": "Assets/Scripts/Project" }, "toolId": "toolu_01DuWCccq1eWujs5oUtFr6zr" }, { "type": "tool_result", "name": "toolu_01DuWCccq1eWujs5oUtFr6zr", "result": "[]", "toolId": "toolu_01DuWCccq1eWujs5oUtFr6zr" }, { "type": "text", "text": "I've read through the orientation layer plus the task-relevant board and tech docs. Here's the picture:\n\n**What's solid**\n- `index.page` → `outline` → `guides` → `agent-conduct` → `boards/tasks.page` → `history` form a clean, consistent onboarding chain. Instructions for agents (session start, check-in cadence, memory rules, writing style) are unambiguous.\n- Code layout matches what the outline claims: `Assets/Scripts/Rokojori` (library code: `Unique.cs`, `Events`, `Extensions`, `Locales`, `Logging`) exists; `Assets/Scripts/Project` is empty, which lines up with \"only the first initial files exist.\"\n- The two active To Do tasks (Game State Management, Dialog Management) match content that's already sketched out in `outline/tech/index.page`.\n\n**Issues found**\n\n1. **`outline/tech/index.page` is bloated with copy-paste cruft.** It's 593 lines / ~92KB - way out of proportion for a project that just started. Most of the size is leftover HTML wrapper markup from a ChatGPT web export (`code-block-viewer`, `cm-editor`, `PDq2pG_selectionAnchorContainer`, etc.) surrounding the actual content. Any agent that opens this page burns a large chunk of context on junk divs. Worth cleaning up - strip the wrapper markup, keep just the text/code content.\n\n2. **The page ends mid-scaffold.** The last block is literally ` Right Column
Something on the right` - unfinished placeholder text that shouldn't be shipped as project documentation.\n\n3. **Two architecture descriptions don't fully reconcile.** The page contains:\n - A lightweight sketch: `GameStateManager` holding a list of `GameStateVariable`s (`GameStateNumberVariable`, `GameStateBoolVariable`) - simple key/value state for dialog conditions.\n - A much heavier design: a `SimulationManager` running `Phase`/`Turn` cycles over systems (`ProductionSystem`, `PollutionSystem`, `CombatSystem`, `WinConditionSystem`, ...) operating on a `GameState` with `Entities`, `Resources`, `Technologies`, `Effects`, `Spatial Fields`.\n \n These look like they came from separate brainstorming passes and aren't clearly related - e.g. is the turn-based `GameState` the same thing the `GameStateManager` reads variables from, or a separate concept? That's not stated anywhere. There's also a stray cut-off sentence (\"There will be also lis\").\n\n**Points that need declaring**\n\n- **Scope of \"simulation.\"** The top-level outline calls this a \"narrative/dialog heavy simulation game,\" but the tech doc's simulation architecture reads like a full turn-based 4X/economy sim (production, allocation, pollution, combat, spatial fields). For a portfolio piece meant to demonstrate narrative-driven systems to a hiring team, that's a lot of surface area. Worth deciding now whether the simulation layer is meant to be that ambitious, or a much smaller state machine that exists mainly to drive dialog branching - the two \"Tech Areas\" tasks (Game State Management, Dialog Management) already on the board suggest the latter, lighter direction.\n- **Relationship between GameState and Dialog systems isn't spelled out** - the dialog doc mentions `GameStateCondition`/`GameStateAction` acting on \"global game state,\" but doesn't say whether that's the `GameStateManager`/`GameStateVariable` model or the heavier `GameState` class.\n- No rojos (individual agents) are defined yet - just fine at this stage, but worth knowing before more agents start working here.\n\n**Suggested next step**: before starting on \"Game State Management\" (next in To Do), I'd clean up `outline/tech/index.page` (strip the HTML cruft, remove/finish the placeholder, and reconcile the two architecture descriptions into one) so the next session has a single source of truth instead of two competing designs. Want me to do that now, or do you want to settle the scope question first?" } ], "tokenTotal": 2270 }, { "role": "user", "timestamp": 1790363079759, "text": "Yes, I would like you toclean up tech/index. \n1. The Right Column thing was just something I did not edit, it is a default Roject Page Block placeholder.\n2. Regarding the different tech areas, yes they were created in different sessions. The two both deeper talks actually cover the scope I want to create. I think the both architecture are in essence 5-10 classes. The task would not be create content as big it was discussed in the brainstrom\n3. Can you normalize all 3? Game State is shorter and that's fine, but I want the other to contain the essence, without bloat. And I want all to look similar in the page editor. Can you rewrite them and use for each a two column layout, that you try to balance out? For the code stuff you can also break up the blocks and put it come some code blocks.\n4. Before you start, can you give me some feedback and how your plan would look like?" }, { "role": "assistant", "timestamp": 1790363162861, "events": [ { "type": "tool_call", "name": "Read", "args": { "file_path": "C:\\Users\\Josef\\.claude\\projects\\C--rokojori-projects-unity-projects-Unity-Roject-Test\\1cf7ca7c-0518-4c67-b7f1-43f30241ab0a\\tool-results\\mcp-roject-get_text_content-1790362520267.txt", "offset": 280, "limit": 280 }, "toolId": "toolu_012BmhPUpPRYZexmKxa6KvJ9" }, { "type": "tool_result", "name": "toolu_012BmhPUpPRYZexmKxa6KvJ9", "result": "280\t ├── Evaluate conditions\n281\t │\n282\t ├── Query environmental fields\n283\t │\n284\t ├── Apply modifiers\n285\t │\n286\t └── Generate production deltas
This was one of the stronger architectural ideas from your answers.
\n290\tInstead of:
\n291\t\n292\tCity -> Factory -> PollutionRelationship -> Plant
use a spatial field.
\n293\t\n300\tPollutionInfluence\n294\t ↓\n295\tPollution Capture System\n296\t ↓\n297\tSpatial structure / quadtree\n298\t ↓\n299\tPollutionField
Then any system can ask:
\n301\t\n302\tfloat pollution = pollutionField.GetValue(city.Position);
So:
\n303\t\n307\tProductionSystem ─────┐\n304\tHealthSystem ─────────┤\n305\tPopulationSystem ─────┤──> PollutionField\n306\tMilitarySystem ───────┘
That's much more reusable than making explicit relationships between every entity.
\n308\tI would make the mutation boundary very explicit.
\n311\tInstead of systems randomly doing:
\n312\t\n313\tcity.Food += 20;
they produce something like:
\n314\t\n321\tResourceDelta\n315\t{\n316\t Entity = city;\n317\t Resource = Food;\n318\t Amount = +20;\n319\t Source = ProductionSystem;\n320\t}
Then a state mutation layer applies it:
\n322\t\n332\tSystem\n323\t │\n324\t ▼\n325\tGenerate Delta\n326\t │\n327\t ▼\n328\tSimulation / State Mutation\n329\t │\n330\t ▼\n331\tGameState changed
This gives you a fantastic debugging trail:
\n333\t\n340\tTurn 47\n334\tCity Berlin\n335\tFood +20\n336\tSource: ProductionSystem\n337\tFactory: Farm_03\n338\tModifier: FertileLand +25%\n339\tPollution: -10%
This becomes its own concern.
\n343\t\n362\tFactories / Units\n344\t │\n345\t ▼\n346\tConsumer Requests\n347\t │\n348\t ▼\n349\tAllocationSystem\n350\t │\n351\t ├── FirstComeFirstServe\n352\t ├── Priority\n353\t ├── RoundRobin\n354\t ├── Random\n355\t └── Cached\n356\t │\n357\t ▼\n358\tAllocation Results\n359\t │\n360\t ▼\n361\tConsumptionSystem
The policy is configuration/data rather than hardcoding every possible factory into the allocation system.
\n363\tFor example:
\n364\t\n370\tpublic interface IAllocationPolicy\n365\t{\n366\t AllocationResult Allocate(\n367\t ResourcePool pool,\n368\t ConsumerRequest[] requests);\n369\t}
Never use uncontrolled Unity randomness inside the simulation.
\n373\tInstead:
\n374\t\n381\tSimulationSeed\n375\t +\n376\tTurn\n377\t +\n378\tDeterministic system ordering\n379\t ↓\n380\t RandomStream
For example:
\n382\t\n385\tRandomStream rng = simulation.GetRandomStream(\n383\t SystemId.ResourceAllocation,\n384\t turn);
Then replaying:
\n386\t\n393\tSeed 12345\n387\tTurn 47\n388\tSame state\n389\tSame system order\n390\tSame commands\n391\t ↓\n392\tSame result
I'd treat this as a first-class system rather than something bolted on later.
\n396\t\n406\tSimulation\n397\t │\n398\t ├── State\n399\t ├── Input Commands\n400\t ├── Random Seed\n401\t ├── System Execution\n402\t └── Deltas\n403\t │\n404\t ▼\n405\t Simulation Log
A debug record might contain:
\n407\t\n419\tTurn: 47\n408\t\n409\tSystem: ProductionSystem\n410\tEntity: City_12\n411\t\n412\tRead:\n413\t Pollution = 14\n414\t FarmCount = 3\n415\t Technology = Irrigation\n416\t\n417\tGenerated:\n418\t Food +23
Then you can answer:
\n420\t\n421\t\n423\t\"Why did this city produce 23 food?\"
\n422\t
without stepping through 500 systems manually.
\n424\tThe Unity side should mostly observe the simulation.
\n427\t\n439\tGameState / Simulation Events\n428\t │\n429\t ▼\n430\t SimulationRenderer\n431\t │\n432\t ┌────┼────┐\n433\t ▼ ▼ ▼\n434\t UI VFX Units\n435\t │ │\n436\t └────┬────┘\n437\t ▼\n438\t Audio
The simulation shouldn't care whether the result is represented by:
\n440\tFor example:
\n458\t\n471\tProductionSystem\n459\t ↓\n460\tFood +23\n461\t ↓\n462\tGameState mutation\n463\t ↓\n464\tSimulationEvent\n465\t ↓\n466\t\"City produced 23 food\"\n467\t ↓\n468\tUnity\n469\t ↓\n470\tFood counter animates 120 → 143
Likewise, input goes into the simulation rather than directly modifying it.
\n474\t\n491\tPlayer clicks \"Build Farm\"\n475\t ↓\n476\tPlayerController\n477\t ↓\n478\tBuildFarmCommand\n479\t ↓\n480\tSimulation command queue\n481\t ↓\n482\tBuildSystem\n483\t ↓\n484\tValidation\n485\t ↓\n486\tState mutation / rejection\n487\t ↓\n488\tSimulationEvent\n489\t ↓\n490\tUI feedback
So Unity never becomes the authority on whether a farm actually exists.
\n492\tThe architecture you were describing essentially becomes:
\n495\t\n544\tUNITY\n496\t │\n497\t ┌────────────┴────────────┐\n498\t │ │\n499\t Player Input Rendering\n500\t │ ▲\n501\t ▼ │\n502\t Simulation Commands Simulation Events\n503\t │ ▲\n504\t └──────────┬──────────────┘\n505\t │\n506\t ▼\n507\t ┌─────────────────────┐\n508\t │ SimulationManager │\n509\t └──────────┬──────────┘\n510\t │\n511\t Phase Manager\n512\t │\n513\t ┌─────────────────┼─────────────────┐\n514\t ▼ ▼ ▼\n515\t PreTurn PlayerTurn PostTurn\n516\t │ │ │\n517\t │ │ ┌──────┴────────┐\n518\t │ │ ▼ ▼\n519\t │ │ Production Consumption\n520\t │ │ │ │\n521\t │ │ ▼ ▼\n522\t │ │ Allocation Effects\n523\t │ │ │ │\n524\t │ │ └──────┬────────┘\n525\t │ │ ▼\n526\t │ │ Win Conditions\n527\t │ │\n528\t └─────────────────┴─────────────────┘\n529\t │\n530\t ▼\n531\t GameState\n532\t │\n533\t ┌───────────┼───────────┐\n534\t ▼ ▼ ▼\n535\t Entities Resources Spatial Fields\n536\t │ │ │\n537\t └───────────┴───────────┘\n538\t │\n539\t ▼\n540\t Delta / Event Log\n541\t │\n542\t ▼\n543\t Debug / Replay
If I were turning this into a real project, I'd put these rules in the team's architecture document:
\n546\tThe dialogue system is built around composable DialogBlock ScriptableObjects. Each block represents one piece of narrative logic, and the dialogue runtime evaluates blocks sequentially while allowing branches and reusable sub-dialogues.
DialogBlock\n27\t├── DialogLine\n28\t├── PlayerChoice\n29\t├── DialogBranch\n30\t├── DialogList",
"toolId": "toolu_01QqkZKGGPoi6fcTaGssaRSs"
},
{
"type": "tool_call",
"name": "mcp__roject__list_files",
"args": {
"path": "Assets/Scripts/Rokojori/Events"
},
"toolId": "toolu_01Cf7i4swKwo9fi72bY2ctwh"
},
{
"type": "tool_result",
"name": "toolu_01Cf7i4swKwo9fi72bY2ctwh",
"result": "[{\"name\":\"EventProperty.cs\",\"type\":\"file\"},{\"name\":\"EventProperty.cs.meta\",\"type\":\"file\"},{\"name\":\"EventSlot.cs\",\"type\":\"file\"},{\"name\":\"EventSlot.cs.meta\",\"type\":\"file\"},{\"name\":\"Null.cs\",\"type\":\"file\"},{\"name\":\"Null.cs.meta\",\"type\":\"file\"}]",
"toolId": "toolu_01Cf7i4swKwo9fi72bY2ctwh"
},
{
"type": "tool_call",
"name": "Write",
"args": {
"file_path": "C:\\rokojori\\projects\\unity-projects\\Unity-Roject-Test\\workspace\\outline\\tech\\index.page",
"content": "\n\n \n New Page \n \n\n\n\n \n Tech Outline
\n\n
\n Project Organization
Code goes into Assets/Scripts.
The main scene is found at: Assets/Main
Unity Settings are in: Assets/Settings
UI will land in: Assets/UIScene Organization
There will be one main scene that manages and contains all singletons as well as UI, camera, player and other globally available scripts.
Only the levels would be loaded additionally in the scene.
In the demo there's no need to load different levels. \n Tech Areas
The prototype should contain the following sections:
- GameState Management- Dialog Management- Simulation Management
Writing Managers/Singletons
Managers exist in the main scene as MonoBehaviours and are accessed via Unique (Assets/Scripts/Rokojori/Unique.cs) when no reference exists.One example is the LocaleManager: Assets/Scripts/Rokojori/Locales/LocaleManager.csIt's not ready yet, but it will later have a function to set the Language Code and iterate all elements that need to be updated.
Writing Code
There are two types of code that can be written and the differ in the way of the usage.
Library Code
Code that is generic goes here. It can't reference any project code. It only is allowed to reference Unity core libraries. it can be found here:
Assets/Scripts/Rokojori
Project Code
Code that is related generic goes here, it can be found here:
Assets/Scripts/Project
\n Game State Management
GameStateManager holds a list of GameStateVariables and builds a lookup dictionary per type on ready.
Reading a value goes through typed getters (GetValue( GameStateNumberVariable ), GetValue( GameStateBoolVariable )), so callers never touch the raw dictionaries.
Changes are broadcast through EventSlots (Assets/Scripts/Rokojori/Events/EventSlot.cs), so other systems - dialog, UI - can react without polling.
The full set of variables can be serialized to and deserialized from JSON, for save/load.\npublic class GameStateManager : MonoBehaviour\n{\n public List<GameStateVariable> variables;\n\n void OnReady()\n {\n // build a per-type value dictionary\n }\n\n public double GetValue( GameStateNumberVariable var ) { }\n public bool GetValue( GameStateBoolVariable var ) { }\n\n public string ToJson() { }\n public void FromJson( string json ) { }\n}\n\npublic abstract class GameStateVariable : ScriptableObject\n{\n public string name;\n}\n\npublic class GameStateNumberVariable : GameStateVariable\n{\n public double initialValue;\n public EventSlot<double> onChanged;\n}\n\npublic class GameStateBoolVariable : GameStateVariable\n{\n public bool initialValue;\n public EventSlot<bool> onChanged;\n}\n \n \n Dialog Management
Built around composable DialogBlock ScriptableObjects. Each block is one piece of narrative logic; the runtime evaluates blocks in sequence while allowing branches and reusable sub-dialogues.
Core Blocks
\nDialogBlock\n├── DialogLine // Locale, Speaker\n├── PlayerChoice // ChoiceLine, Options[]\n├── DialogBranch // Condition, Branch -> DialogBlock\n├── DialogList // Blocks[], itself a DialogBlock\n├── ReturnBlock // ends the sequence\n└── CommentBlock // editor-only, no gameplay effect\n \n
DialogLine pairs a localized Locale with a Speaker; presentation (portrait, voice, animation) is handled separately.PlayerChoice options can each run one or more GameStateActions, which can affect later branching.DialogBranch evaluates a GameStateCondition and redirects flow to another block.Conditions & Actions
Game-state reads/writes stay out of DialogBlock and live in two small hierarchies, so dialogue logic stays independent of how state is implemented:\nGameStateCondition\n├── CompareInt\n├── HasObject\n└── ListCondition // All / AtLeastOne / None\n\nGameStateAction\n├── SetProperty\n├── ModifyProperty\n└── ActionList\n \n
Flow per block: present content → evaluate conditions → execute actions → continue or branch.
This keeps the dialogue graph data-driven - conversations can be built without writing code. \n Simulation Management
SimulationManager
The conductor, not where game rules live. Orchestrates phases each turn; systems do the actual work.\npublic class SimulationManager\n{\n public GameState State { get; }\n\n public void ExecuteTurn()\n {\n ExecutePhase( Phase.PreTurn );\n ExecutePhase( Phase.PlayerTurn );\n ExecutePhase( Phase.PostTurn );\n }\n}\n \n Systems
Each system does one conceptual job: reads a fixed slice of state, writes deltas. Example:\nProductionSystem\n reads: City, Factory, Technology, PollutionField\n writes: ProductionDeltas\n \n
Systems run in a deterministic, explicit order per phase - e.g. Production → Allocation → Consumption → Effects → WinConditions in PostTurn. \n GameState
The authoritative runtime state.\npublic class GameState\n{\n public int Turn;\n public EntityState[] Entities;\n public ResourceState Resources;\n public TechnologyState Technologies;\n public EffectState Effects;\n public SpatialState Spatial;\n}\n \n
Split: Configuration (ResourceDefinition, FactoryDefinition, TechnologyDefinition - ScriptableObjects, mostly static) vs. Runtime State (current quantities, ownership, turn number - what changes and gets saved).Resources & Deltas
NumericResource definitions (Food, Iron, Gold, ...) describe what a resource is; runtime values (Food = 120) describe how much currently exists.
Systems never mutate state directly - they produce a delta, which a mutation step applies. That keeps every change traceable:\nSystem -> Delta -> State Mutation -> GameState changed\n\nResourceDelta { Entity, Resource, Amount, Source }\n \n \n Spatial Fields & Determinism
Instead of wiring explicit relationships between every entity (City -> Factory -> PollutionRelationship -> Plant), systems write into and query a shared spatial field:\nProductionSystem ─┐\nHealthSystem ─────┼──> PollutionField\nMilitarySystem ───┘\n\nfloat p = pollutionField.GetValue( city.Position );\n \n
Randomness is seeded per system and turn (simulation.GetRandomStream( SystemId, turn )), so a given seed and command history always replays to the same result.Unity Boundary
Unity is presentation and input only - never the source of truth.\nPlayer Input -> Command -> Simulation -> Event -> Renderer -> UI / VFX / Audio\n \n
Principles:- Simulation state is authoritative.- SimulationManager orchestrates; systems implement rules.- Systems have narrow responsibilities.- State mutations only happen through deltas.- Static definitions stay separate from runtime state. \n\nUpdate History — Unity-Roject-Test \n5\t \n8\t\n9\t\n10\t\n13\t\n14\t Update History
\n16\t\n17\t When to Run
At the end of every working session, before closing. This is not optional — a missing history entry means lost context for the next session.
Where to Put It
Add a new entry at the top of history/index.page.
For long or complex sessions, create a dedicated .page file inside a dated folder (e.g. history/2026/08-August/04-Tuesday/session-name.page) and link to it from the index.What to Write
What was built or changed — be specific about systems, files, and behaviours. Name the things that changed.
Decisions made and why — include the reasoning behind choices. This is the most valuable part. Future agents will use it to avoid undoing deliberate decisions.
Anything surprising or non-obvious — constraints discovered, bugs encountered, workarounds applied. If it surprised you, it will surprise the next reader too.
What was not done and why — if something was considered and deliberately skipped, note it. Prevents the same ground being covered again.
What to Skip
Do not copy code into history entries — reference files instead. Do not repeat what is already obvious from the code. Do not write step-by-step procedures — those belong in guides. \n20\t \n21\t\n22\tNew Page \n \n\n\n\n \n Tech Outline
\n\n
\n Project Organization
Code goes into Assets/Scripts.
The main scene is found at: Assets/Main
Unity Settings are in: Assets/Settings
UI will land in: Assets/UIScene Organization
There will be one main scene that manages and contains all singletons as well as UI, camera, player and other globally available scripts.
Only the levels would be loaded additionally in the scene.
In the demo there's no need to load different levels. \n Tech Areas
The prototype should contain the following sections:
- GameState Management- Dialog Management- Simulation Management
Writing Managers/Singletons
Managers exist in the main scene as MonoBehaviours and are accessed via Unique (Assets/Scripts/Rokojori/Unique.cs) when no reference exists.One example is the LocaleManager: Assets/Scripts/Rokojori/Locales/LocaleManager.csIt's not ready yet, but it will later have a function to set the Language Code and iterate all elements that need to be updated.
Writing Code
There are two types of code that can be written and the differ in the way of the usage.
Library Code
Code that is generic goes here. It can't reference any project code. It only is allowed to reference Unity core libraries. it can be found here:
Assets/Scripts/Rokojori
Project Code
Code that is related generic goes here, it can be found here:
Assets/Scripts/Project
\n Game State Manager
Shared state layer underneath both the Simulation Manager and the Dialog Manager - both read and write through it, nothing owns its own copy of game data.
GameStateManager holds a list of GameStateVariables and builds a lookup dictionary per type on ready.
Reading a value goes through typed getters (GetValue( GameStateNumberVariable ), GetValue( GameStateBoolVariable )), so callers never touch the raw dictionaries.
Changes are broadcast through EventSlots (Assets/Scripts/Rokojori/Events/EventSlot.cs), so phases and dialog conditions can react without polling. The full set of variables can be serialized to and deserialized from JSON, for save/load.\npublic class GameStateManager : MonoBehaviour\n{\n public List<GameStateVariable> variables;\n\n void OnReady()\n {\n // build a per-type value dictionary\n }\n\n public double GetValue( GameStateNumberVariable var ) { }\n public bool GetValue( GameStateBoolVariable var ) { }\n\n public string ToJson() { }\n public void FromJson( string json ) { }\n}\n\npublic abstract class GameStateVariable : ScriptableObject\n{\n public string name;\n}\n\npublic class GameStateNumberVariable : GameStateVariable\n{\n public double initialValue;\n public EventSlot<double> onChanged;\n}\n\npublic class GameStateBoolVariable : GameStateVariable\n{\n public bool initialValue;\n public EventSlot<bool> onChanged;\n}\n \n \n How It Fits Together
Dialog Manager isn't a separate parallel system - it's one kind of phase the Simulation Manager can run. Everything reads/writes the same GameStateManager.\n GameStateManager\n (shared game state)\n ▲ ▲\n │ │\n SimulationManager │\n │ │\n Intro / PreTurn / PlayerTurn / PostTurn / Outro\n │\n ┌────────────┼──────────────────┐\n ▼ ▼ ▼\n ShowTurnStart SimulateWorld DialogPhase\n Conditions (production, (cursor over\n (dice, ticks) pollution, ...) DialogBlocks)\n │ │ │\n └────────────┴─────commands─────┘\n ▼\n SimulationRenderer\n │\n done ──► next phase\n \n \n Simulation Manager
GamePhase is the atomic unit: a ScriptableObject that runs asynchronously and can read/write GameStateManager. The manager awaits one phase before starting the next.\npublic abstract class GamePhase : ScriptableObject\n{\n public abstract Task Execute(\n GameState state,\n SimulationRenderer renderer );\n\n // set true from inside Execute to end the game early\n public bool gameFinished;\n}\n \n Phase Lists & the Turn Loop
SimulationManager holds five ordered phase lists and runs them like this:\npublic List<GamePhase> intro;\npublic List<GamePhase> preTurn;\npublic List<GamePhase> playerTurn;\npublic List<GamePhase> postTurn;\npublic List<GamePhase> outro;\n\nasync Task Run()\n{\n await RunPhases( intro ); // e.g. set player count\n\n while ( ! anyPhaseFinishedGame )\n {\n await RunPhases( preTurn );\n\n foreach ( var player in players )\n await RunPhases( playerTurn );\n\n await RunPhases( postTurn );\n }\n\n await RunPhases( outro );\n}\n \n
Any phase, in any list, can flag the game as finished. The manager checks this after each phase and jumps straight to outro, skipping whatever was left - it doesn't wait for the current list to finish. \n SimulationManager ↔ SimulationRenderer
A phase doesn't touch Unity directly. It hands commands to the renderer and awaits completion before the manager moves on:\nGamePhase.Execute()\n │\n ▼\nrenderer.Enqueue( command ) // animation, UI, VFX...\n │\n ▼\nSimulationRenderer executes it\n │\n ▼\nrenderer reports done\n │\n ▼\nExecute() completes -> next phase\n \n Example Phases
ShowTurnStartConditions - start of a round: roll dice for events, apply resource ticks, set up the state a turn begins with.
SimulateWorld - where systems like ProductionSystem/AllocationSystem/PollutionSystem run: each reads a slice of state and writes deltas back through GameStateManager, optionally querying a shared spatial field (e.g. a PollutionField) instead of linking entities directly, using a seeded random stream so results are reproducible.
DialogPhase - see Dialog Manager. \n Dialog Manager
Dialog Manager is a phase type: DialogPhase . It starts at a given block - usually a DialogList - and finishes the phase once the dialog concludes, reporting back to the SimulationManager exactly like any other phase.\npublic class DialogPhase : GamePhase\n{\n public DialogBlock start; // usually a DialogList\n\n public override async Task Execute(\n GameState state, SimulationRenderer renderer )\n {\n var current = start;\n\n while ( current != null )\n {\n current = await current.Run( state, renderer );\n }\n }\n}\n \n Execution Model
A cursor sits on the current block. Running a block finishes it and returns the next one. By default that's just \"the next block in sequence\" - but a PlayerChoice or DialogBranch can redirect the cursor to any other block instead, based on the option picked or a GameStateCondition.\nDialogLine: \"Want to buy stuff?\"\nPlayerChoice:\n A) Attacker\n B) Defenders\n C) None\n \n Bigger dialogs work the same way, just with conditions picking the branch - e.g. checking a player's points and whether City A is still standing to decide whether the dialog continues with City A's boss or City B's. \n Dialog Blocks
\nDialogBlock\n├── DialogLine // Locale, Speaker\n├── PlayerChoice // ChoiceLine, Options[]\n├── DialogBranch // Condition, Branch -> DialogBlock\n├── DialogList // Blocks[], itself a DialogBlock\n├── ReturnBlock // ends the phase\n└── CommentBlock // editor-only, no gameplay effect\n \n DialogLine pairs a localized Locale with a Speaker; presentation (portrait, voice, animation) goes through the SimulationRenderer, same as any other phase command.Conditions & Actions
Game-state reads/writes stay out of DialogBlock and live in two small hierarchies on top of GameStateManager:\nGameStateCondition\n├── CompareInt\n├── HasObject\n└── ListCondition // All / AtLeastOne / None\n\nGameStateAction\n├── SetProperty\n├── ModifyProperty\n└── ActionList\n \n This keeps the dialogue graph data-driven - conversations can be built without writing code. \n\nNew Page \n \n\n\n\n \n Tech Outline
\n\n
\n Project Organization
Code goes into Assets/Scripts.
The main scene is found at: Assets/Main
Unity Settings are in: Assets/Settings
UI will land in: Assets/UIScene Organization
There will be one main scene that manages and contains all singletons as well as UI, camera, player and other globally available scripts.
Only the levels would be loaded additionally in the scene.
In the demo there's no need to load different levels. \n Tech Areas
The prototype should contain the following sections:
- GameState Management- Dialog Management- Simulation Management
Writing Managers/Singletons
Managers exist in the main scene as MonoBehaviours and are accessed via Unique (Assets/Scripts/Rokojori/Unique.cs) when no reference exists.One example is the LocaleManager: Assets/Scripts/Rokojori/Locales/LocaleManager.csIt's not ready yet, but it will later have a function to set the Language Code and iterate all elements that need to be updated.
Writing Code
There are two types of code that can be written and the differ in the way of the usage.
Library Code
Code that is generic goes here. It can't reference any project code. It only is allowed to reference Unity core libraries. it can be found here:
Assets/Scripts/Rokojori
Project Code
Code that is related generic goes here, it can be found here:
Assets/Scripts/Project
\n Game State Manager
Shared state layer underneath both the Simulation Manager and the Dialog Manager - both read and write through it, nothing owns its own copy of game data.
GameStateManager holds a list of GameStateVariables and builds a lookup dictionary per type on ready.
Reading a value goes through typed getters (GetValue( GameStateNumberVariable ), GetValue( GameStateBoolVariable )), so callers never touch the raw dictionaries.
Changes are broadcast through EventSlots (Assets/Scripts/Rokojori/Events/EventSlot.cs), so phases and dialog conditions can react without polling. The full set of variables can be serialized to and deserialized from JSON, for save/load.\npublic class GameStateManager : MonoBehaviour\n{\n public List<GameStateVariable> variables;\n\n void OnReady()\n {\n // build a per-type value dictionary\n }\n\n public double GetValue( GameStateNumberVariable var ) { }\n public bool GetValue( GameStateBoolVariable var ) { }\n\n public string ToJson() { }\n public void FromJson( string json ) { }\n}\n\npublic abstract class GameStateVariable : ScriptableObject\n{\n public string name;\n}\n\npublic class GameStateNumberVariable : GameStateVariable\n{\n public double initialValue;\n public EventSlot<double> onChanged;\n}\n\npublic class GameStateBoolVariable : GameStateVariable\n{\n public bool initialValue;\n public EventSlot<bool> onChanged;\n}\n \n \n How It Fits Together
Dialog runs through DialogManager, which any code can call directly. DialogPhase is just a thin wrapper so a dialog can also be one step in the Simulation Manager's turn loop.\n GameStateManager\n (shared game state)\n ▲ ▲\n │ │\n SimulationManager │\n │ │\n Intro / PreTurn / PlayerTurn / PostTurn / Outro\n │\n ┌────────────┼──────────────────┐\n ▼ ▼ ▼\n ShowTurnStart SimulateWorld DialogPhase\n Conditions (production, │\n (dice, ticks) pollution, ...) DialogManager.StartDialog()\n │ │ │\n │ │ DialogProcessor\n │ │ (cursor over DialogBlocks)\n │ │ │\n └────────────┴───────commands─────┘\n ▼\n SimulationRenderer / UI\n │\n done ──► next phase\n\n DialogManager.StartDialog() can also be called directly,\n outside of any phase (menus, cutscenes, etc.)\n \n \n Simulation Manager
GamePhase is the atomic unit: a ScriptableObject that runs asynchronously and can read/write GameStateManager. The manager awaits one phase before starting the next.\npublic abstract class GamePhase : ScriptableObject\n{\n public abstract Task Execute(\n GameState state,\n SimulationRenderer renderer );\n\n // set true from inside Execute to end the game early\n public bool gameFinished;\n}\n \n Phase Lists & the Turn Loop
SimulationManager holds five ordered phase lists and runs them like this:\npublic List<GamePhase> intro;\npublic List<GamePhase> preTurn;\npublic List<GamePhase> playerTurn;\npublic List<GamePhase> postTurn;\npublic List<GamePhase> outro;\n\nasync Task Run()\n{\n await RunPhases( intro ); // e.g. set player count\n\n while ( ! anyPhaseFinishedGame )\n {\n await RunPhases( preTurn );\n\n foreach ( var player in players )\n await RunPhases( playerTurn );\n\n await RunPhases( postTurn );\n }\n\n await RunPhases( outro );\n}\n \n
Any phase, in any list, can flag the game as finished. The manager checks this after each phase and jumps straight to outro, skipping whatever was left - it doesn't wait for the current list to finish. \n SimulationManager ↔ SimulationRenderer
A phase doesn't touch Unity directly. It hands commands to the renderer and awaits completion before the manager moves on:\nGamePhase.Execute()\n │\n ▼\nrenderer.Enqueue( command ) // animation, UI, VFX...\n │\n ▼\nSimulationRenderer executes it\n │\n ▼\nrenderer reports done\n │\n ▼\nExecute() completes -> next phase\n \n Example Phases
ShowTurnStartConditions - start of a round: roll dice for events, apply resource ticks, set up the state a turn begins with.
SimulateWorld - where systems like ProductionSystem/AllocationSystem/PollutionSystem run: each reads a slice of state and writes deltas back through GameStateManager, optionally querying a shared spatial field (e.g. a PollutionField) instead of linking entities directly, using a seeded random stream so results are reproducible.
DialogPhase - a thin GamePhase that awaits DialogManager.instance.StartDialog( start ) and completes. All the real logic lives in DialogManager/DialogProcessor below, so dialog works the same way whether or not it's running inside a phase. \n Dialog Manager
The UI-facing singleton and the only entry point for running a dialog. Owns the actual UI wiring (text, portraits, choice buttons) and can be called directly from anywhere - not just from a DialogPhase.\npublic class DialogManager : MonoBehaviour, IDialogDisplay\n{\n public static DialogManager instance\n => Unique<DialogManager>.instance;\n\n public async Task StartDialog( DialogBlock start )\n {\n var processor = new DialogProcessor( this );\n await processor.Run( start );\n }\n\n // called by DialogProcessor when a block needs to be shown\n public async Task<DialogAnswer> Show( DialogBlock block )\n {\n // update UI (line/portrait, or choice buttons)\n // and wait for the player, e.g. a button click\n }\n}\n \n DialogProcessor
The standalone engine. Owns the cursor, resolves branches/conditions against GameStateManager on its own, and only talks to the outside world through the IDialogDisplay it was given - it has no idea DialogManager exists.\npublic class DialogProcessor\n{\n IDialogDisplay display; // e.g. DialogManager\n\n public DialogProcessor( IDialogDisplay display )\n {\n this.display = display;\n }\n\n public async Task Run( DialogBlock start )\n {\n var current = start;\n\n while ( current != null )\n current = await current.Run( display );\n }\n}\n \n \n Execution Model
Running a block finishes it and returns the next one. By default that's just \"the next block in sequence\" - but a PlayerChoice or DialogBranch can redirect the cursor to any other block instead, based on the option picked or a GameStateCondition.\nDialogLine: \"Want to buy stuff?\"\nPlayerChoice:\n A) Attacker\n B) Defenders\n C) None\n \n Bigger dialogs work the same way, just with conditions picking the branch - e.g. checking a player's points and whether City A is still standing to decide whether the dialog continues with City A's boss or City B's.Dialog Blocks
\nDialogBlock\n├── DialogLine // Locale, Speaker\n├── PlayerChoice // ChoiceLine, Options[]\n├── DialogBranch // Condition, Branch -> DialogBlock\n├── DialogList // Blocks[], itself a DialogBlock\n├── ReturnBlock // ends the dialog\n└── CommentBlock // editor-only, no gameplay effect\n \n DialogLine pairs a localized Locale with a Speaker; presentation (portrait, voice, animation) is handled by whatever implements IDialogDisplay. \n Conditions & Actions
Game-state reads/writes stay out of DialogBlock and live in two small hierarchies on top of GameStateManager:\nGameStateCondition\n├── CompareInt\n├── HasObject\n└── ListCondition // All / AtLeastOne / None\n\nGameStateAction\n├── SetProperty\n├── ModifyProperty\n└── ActionList\n \n This keeps the dialogue graph data-driven - conversations can be built without writing code.Testability
Because DialogProcessor only depends on the IDialogDisplay interface, DialogManager isn't the only thing that can drive it.
A debug/headless display can implement the same interface - auto-answering choices, logging the path taken - to run and check dialogs without the actual UI. \n\nsession-hand-over \n5\t \n8\t\n9\t\n10\t\n13\t\n14\t Session Hand Over
\n16\t\n17\t Outline
A session hand over is used when a session is already quite packed (more than 40%).
It will summarize all things that were changed in the according places, as if the action \"Update History\" (workspace/actions/update-history/index.page)
was used, with the exception that nothing will be done git-wise, so no add/commit/push.
Also a task entry will be placed in \"In Progress\" in tasks.page with a title \"Session Hand-Over: Task Name/Summary\" where the actual task or its summary are used. Shape of Task-Entry
Intro
The task entry has an short intro section, saying what needs to be done (1-2 short phrases).
History
The task entry should also mention the history entry and create a link to that.
Next Steps/Phases/Tasks
This section explains which tasks need to be done next. It can reference also other notes/pages.
Reads
After that it will list the pages/resources/code that new session should read before starting.
Misc
When needed, a section can be added that can hold more details. \n20\t\n21\tHistory — Unity-Roject-Test \n \n\n\n\n\n History
\n\n 25 September 2026
Project created. \n \n\nTasks — Unity-Roject-Test \n \n\n\n\n\n Tasks
\n\n\n\n \n To Do \n \n \n Game State Management
Write the Game State manager and all the needed classes \n \n Dialog Management
Write the Dialog Manager and all the needed classes. Ideally we can test it. \n \n \n In Progress \n \n Get Initial Picture
Give Feeback about Project Orientation and whether more points need to be declared \n \n \n Done \n \n \n\n\n 25 September 2026
Project created. \nIDialogDisplay interface, no knowledge of UI or the simulation loop), StartDialog(), implements IDialogDisplay), and DialogManager.instance.StartDialog()). The IDialogDisplay seam also covers a future debug/headless display for testing, mentioned but not built.