SOLESIDO began as a childhood experiment in Microsoft Paint and became a native Windows city-builder and living-world simulation. This guide explains the complete development journey: what I asked the AI to build, what worked, what repeatedly failed, how I detected false confidence and hallucinations, how the architecture was repaired, and how another first-time creator can use AI more safely and effectively.

This is not a story in which every AI answer was correct. The useful lessons came from both the successes and the failures.

Prepared from the complete SOLESIDO development session, July 2026.

Read This First#

The shortest version of the lesson is:

[CORE LESSON] AI can write an extraordinary amount of game code, art integration, tests and documentation, but it does not automatically preserve your intent. Your most important job is to control scope, define authority, demand evidence and stop unverified changes from becoming the new baseline.

If you remember only ten rules, remember these:

1. Write the game contract before asking for large implementations.
2. Use source control from the first day.
3. Separate gameplay values from compiled code.
4. Never let the AI silently choose game-design logic that belongs to you.
5. Require a reproduction and a test before accepting a bug fix.
6. Preserve known-good builds and never overwrite the last playable release.
7. Treat visuals, simulation, persistence, performance and user experience as separate verification tracks.
8. Do not confuse a passing unit test with a fun, visible, playable game.
9. Budget disk space, build folders, session records and audio assets from the beginning.
10. When the AI says “fixed,” ask: which build, which test, which save, which measured result and which screenshot?

Contents#

• Part I - The idea and the project that emerged
• Part II - The full development journey
• Part III - What the AI got wrong
• Part IV - The architecture that finally worked
• Part V - A safer AI collaboration workflow
• Part VI - Testing, balancing and performance
• Part VII - Visual assets, animation and user interface
• Part VIII - Save systems, releases and storage hygiene
• Part IX - Copyable prompts and checklists
• Part X - A practical roadmap for your first AI-assisted game

Part I - The Idea and the Project#

1. The childhood prototype#

My original “game” required only Microsoft Paint.

I opened a 1440 x 900 image and filled it with green. In my imagination, every 5 x 5 pixels represented a rainforest tree. I painted random blue rivers through the green field. Then I used the eraser as a deforestation tool. A small eraser represented careful clearing; a 256 x 256 eraser could remove a huge area. The erased region became brown soil.

There was no source code, pathfinding or economy. The play came from changing a map and imagining the consequences. I spent hours watching the rainforest shrink.

Years later I returned to one question: what if the forest actually mattered?

That question created the design foundation:

• rainforest coverage should affect oxygen, habitat and wildlife;
• cities and industries should create demand and pollution;
• timber should connect forest clearing to construction and modern life;
• people should have homes, work, food, families and destinations;
• the player should be able to build freely, but every choice should have visible consequences;
• there should be no abrupt game over; the world should continue reacting;
• the player’s real challenge should be finding a balance between nature and modern life.

The childhood Paint interaction was not discarded. It became one of the game’s two identities: a freeform Paint view and a detailed isometric simulation view.

2. The intended experience#

SOLESIDO was never meant to be a hardcore engineering simulator. The goal was an easy, relaxing game with genuine causal systems.

The inspiration was not a modern billion-euro production. It was the clarity and charm of older games such as Transport Tycoon Deluxe and Beasts and Bumpkins: compact rules, readable sprites, persistent little people, visible vehicles, funny moments and long play sessions.

The desired player fantasy was:

• paint or shape a rainforest;
• build roads, towns, farms, shops, industries and services;
• observe individual people and vehicles;
• watch trees become Roundwood, Roundwood become Timber and Timber become buildings;
• see families form and children grow;
• trade with surrounding regions;
• experience protests, policing, humor and social consequences;
• understand why something works or fails;
• keep playing without the simulation becoming a punishment.

3. What the finished project became#

The project evolved into a native C++20 Windows application with:

• an isometric renderer and a Paint view;
• deterministic simulation records;
• roads, cities, farms, commerce, industry, mines, utilities and warehouses;
• individual residents, families, life stages and purpose-driven trips;
• passenger cars, buses, freight, logging vehicles and regional TIR trucks;
• Food, Consumer Goods, Roundwood, Timber and industrial material chains;
• ecology, pollution, forest coverage, habitat and fauna;
• Save/Load, autosave recovery, Undo/Redo and validation;
• a data-driven gameplay rules directory;
• a regional economy with four surrounding partners;
• a Gazette, statistics, civic pressure, protest and public-safety systems;
• a large generated art library and replacement audio banks;
• automated regression, persistence, performance and asset tests.

The important point is not the feature count. The important point is that the project reached this state only after its development process was repeatedly corrected.

Part II - The Full Development Journey#

4. Phase 1 - Turning a memory into a specification#

The first useful act was describing the childhood Paint experiment in concrete terms:

• 1440 x 900 canvas;
• green rainforest;
• 5 x 5 pixel tree abstraction;
• blue rivers;
• deforestation brush from approximately 20 x 20 to 256 x 256;
• cleared soil displayed in brown;
• statistics for deforestation, oxygen and pollution;
• cities, roads and industries that affect soil, water and vegetation.

This mattered because AI performs much better when an emotional idea also contains measurable rules.

The request quickly expanded. I asked for zooming, isometric Transport Tycoon-like terrain, farms, bridges, traffic, people, family life, economy, audio, wildlife and regional trade. That expansion was creatively productive, but it created the first major risk: the scope became larger faster than the architecture.

[LESSON] Ideas can expand quickly; architecture must expand deliberately. Every new system should first be added to the design contract with its dependencies, acceptance test and non-goals.

5. Phase 2 - The visual prototype#

The early version used web-style rendering. It was valuable because it made the concept visible quickly:

• rainforest tiles;
• rivers;
• brush sizes;
• roads and city placement;
• generated isometric buildings;
• zoom and edge scrolling;
• basic cars and statistics.

This prototype proved that the idea was fun. It also exposed visual rules that prose alone could not reveal:

• isometric roads need compatible corners and junctions;
• bridges must share the same projected width as roads;
• buildings require a consistent ground anchor;
• tall sprites cannot be sorted only by their top tile;
• cars need directional artwork and lane centers;
• people should walk around buildings, not through them;
• close zoom makes every placement error obvious.

Screenshots became essential evidence. Instead of saying “the building looks wrong,” I circled the exact roof, road overlap, floating base, sideways car or placeholder.

6. Phase 3 - Moving to a native Windows game#

I rejected an HTML-only final product because I wanted a proper Windows executable and better performance. The project moved to native C++20.

That decision brought advantages:

• predictable executable packaging;
• direct Direct2D/Windows rendering;
• precise control of memory, timing and persistence;
• native file dialogs and input;
• the ability to optimize simulation and rendering separately.

It also raised the engineering burden. Native code made memory safety, thread safety, save compatibility, build configuration and rendering order much more important.

A better decision would have been to establish the native architecture before implementing dozens of gameplay features. Instead, much of the early work was translated while design requirements were still changing.

7. Phase 4 - Isometric roads, bridges and grounded buildings#

Roads were one of the longest-running visual problems.

Early road rendering used segments that did not align. Junctions looked patched together. Angles were inconsistent. Roads over water were treated as special bridges with ramps and pillars, but their width and perspective did not match the ordinary road.

The eventual simplification was correct: use the exact normal road surface over water. A bridge could be a road with restrained decoration, not a completely different geometric system.

Buildings had related problems:

• sprites were centered incorrectly;
• some were sorted behind their own ground parcels;
• large buildings occupied multiple tiles but were rendered from the wrong tile;
• pedestrians and roads could appear over building bodies;
• some sprites showed only a roof, as if buried underground;
• industrial assets appeared to float over empty parcels or water.

The robust solution required explicit asset metadata:

• logical footprint width and height;
• visual anchor cell;
• baseline offset;
• sprite bounds;
• layer and sort owner;
• road frontage;
• construction-stage asset;
• optional operating animation attachment point.

The Trade Warehouse exposed why this matters. It had a 3 x 5 footprint but its large visual body was initially owned by the far/top parcel cell. Later isometric cells painted through it. The correction did not change the simulation footprint; it changed which cell owned the sprite for depth sorting.

[TECHNICAL LESSON] In an isometric game, a sprite’s simulation footprint and its rendering owner are related but not identical. Store both explicitly.

8. Phase 5 - Traffic and purpose-driven agents#

The first cars moved too fast, occupied both lanes, turned sideways, overlapped buildings and sometimes spawned without a real trip. Those errors looked small in code but destroyed the illusion of a living city.

The design contract became stricter:

• every passenger car belongs to a resident;
• the resident has a real origin, destination and trip purpose;
• cars spawn from homes and disappear at destinations;
• vehicles have a front and must face the direction of travel;
• opposite directions use opposite lanes;
• cars keep headway and cannot overlap;
• resource trucks use their correct truck artwork;
• buses retain their own model;
• freight can receive priority without being visually merged into passenger traffic;
• parking and road access matter.

Pedestrians received similar rules:

• they have homes, work, shopping, food, leisure and return trips;
• they may cross each other;
• they can walk over ordinary ground or rainforest when no path exists;
• they prefer roadsides and pedestrian paths when available;
• if a car cannot reach the exact job, it may park nearby and the person walks the remainder;
• pedestrians should not remain permanently stuck at crossings.

Several attempted “fixes” made matters worse. Reducing the simulation to one visible movement update per second improved CPU time but made cars and people visibly stop every second. The real solution was to separate low-frequency decisions from high-frequency visual interpolation.

9. Phase 6 - Forestry as a visible causal chain#

Forestry was central to the original concept.

The final intended chain was:

1. The player deforests a 1 x 1 tile.
2. That tile creates one finite pile worth 100 Roundwood.
3. A local forestry truck collects five harvested tiles, or 500 Roundwood.
4. The collected piles disappear and do not respawn.
5. The truck delivers Roundwood to a Sawmill.
6. The Sawmill converts Roundwood to usable Timber.
7. Local Timber vehicles deliver material to construction or a player warehouse.
8. Upkeep can consume stored Timber internally without spawning visual delivery spam.
9. Reforesting is the deliberate way to create new trees and future harvest.

At several points this chain was broken:

• cut logs visually reappeared;
• passenger car sprites were used for timber cargo;
• brown lines or pixels stood in for delivered wood;
• import trucks dominated local wood even when the player had harvested forest;
• hundreds of truck orders accumulated;
• the same unit was described as “wood,” “Roundwood” and “Timber” without a clear conversion.

The correction was to define authoritative product units and enforce conservation tests. One 1 x 1 harvested tile became 100 Roundwood. Sawmill conversion produced 70 usable Timber from that input under the approved model. Each transfer recorded its source, quantity, destination and physical or internal mode.

10. Phase 7 - Food, commerce and utilities#

Food was the most persistent gameplay blocker. For many builds the statistics displayed Food at zero regardless of the number of farms. Farms could hold millions of units while grocery inventory remained frozen. In other builds one shop created a fleet of yellow vans because each load was too small for the six-month reserve target.

The lessons were:

• production is not supply;
• inventory is not household consumption;
• a delivery order is not a completed delivery;
• a displayed percentage must be derived from the same authoritative records that gameplay uses;
• a casual game needs continuity protection when the player cannot yet diagnose the full chain.

The working causal path became:

Farm production -> persistent Food order -> yellow commercial freight vehicle -> Grocery inventory -> household purchase -> Food statistic.

Food became the only essential product allowed to import automatically when critically low. Other products became manual trade decisions. The local Grocery load was ultimately set to 7,200 Food points to avoid excessive delivery vehicles while preserving visible logistics.

Utilities caused a different design question: should service require roads, invisible networks or citywide coverage? I did not want to invent a new underground grid without first designing it. The temporary casual rule kept existing utility behavior and regional fallback, while documenting a future utilities-view requirement.

This was an important example of restraint: a missing explanation did not justify silently creating a new simulation dependency.

11. Phase 8 - Families, children and life#

I wanted people to feel alive, not to be decorative particles.

The family design included:

• adults form couples;
• couples decide to have children;
• pregnancy lasts according to approved timing distributions;
• newborns appear in strollers;
• little children walk with a caregiver;
• children and teenagers use distinct life stages;
• caregivers may stay home while children are very young;
• teenagers grow into adults, find jobs and seek housing;
• parents age, retire, receive pensions and eventually die;
• some pregnancies produce twins;
• foreign workers may settle permanently, form couples and have children.

The AI sometimes claimed these systems were “already working” when I had never seen them in the actual game. That distinction became a release rule:

[EVIDENCE RULE] A family state existing in a data structure is not the same as a visible family feature. Acceptance requires the right records, the right trip behavior and the right directional artwork on screen.

The 2,000-person coupled regression eventually measured 394 births by month 67 and kept couples, babies and caregiver outings Save-valid. Visual testing still mattered because twin heads, overlapping family sprites and momentary couple separation were presentation defects that state validation could not catch.

12. Phase 9 - Economy, society and regional trade#

The economy grew from simple statistics into a causal model:

• jobs and wages;
• household spending;
• commercial revenue;
• business payroll and debt;
• welfare and pensions;
• municipal taxes and services;
• construction costs;
• resource imports and exports;
• civic pressure, protests, policing and recovery.

The player is the city. City construction and trade settle through the player treasury. If the treasury is empty, construction waits and the player is told why. The player can earn large amounts by exporting valuable harvested wood or deliberately borrow money.

Four surrounding regions were added as lightweight aggregate maps. They do not run thousands of hidden citizens. They maintain inventories, forest condition, prosperity, relationships, offers and gateway traffic. This preserves the idea that the player’s resource demand affects other places without multiplying CPU cost.

Trade rules were ultimately made explicit:

• Food imports automatically only when critically low;
• Timber and Roundwood are manual import/export;
• Consumer Goods, Ore, Industrial Goods, Recovered Wood and Residue Fuel are manual import/export;
• no product is automatically exported;
• imported cargo cannot be immediately re-exported;
• surplus is consolidated into a player warehouse and shown as export-ready;
• manual confirmation shows quantity, truck count, price, inventories, ETA and consequences;
• every confirmed order creates real full TIR trucks;
• Utility service is never truck cargo.

The first implementation auto-created thousands of orders and flooded streets. The better model used full 50,000-unit TIRs for regional trade and kept small local delivery vehicles for local distribution.

13. Phase 10 - Sound, music and atmosphere#

Audio began as a very large collection of WAV files. The initial bank exceeded 600 MB and many clips sounded like undifferentiated noise. Some files were duplicated or unreachable. First-use decoding could stall the game.

The audio work produced several lessons:

• ambience needs layers, not one loud mixed recording;
• city, people, engines, horns, farms, industry and nature need separate causal triggers;
• loops require clean boundaries and controlled density;
• audio should follow camera position and activity;
• “more sound” does not mean “more alive”;
• the game should preload essential audio and stream or cache secondary material deliberately;
• replacement prompts should specify duration, loop behavior, forbidden sounds, peak level, spectral density and file format.

City and nature replacement prompt documents were created, new packs were supplied, and the game was prepared to use them. For distribution, audio was kept separate from no-audio source packages.

14. Phase 11 - Branding and player-facing structure#

The game was renamed SOLESIDO and received a dedicated logo.

A proper front end was added:

• Continue Autosave;
• New Blank Rainforest;
• Load Game;
• How to Play;
• Settings;
• About SOLESIDO;
• Creator & Credits;
• Exit.

The main game UI went through several revisions because icons were hidden, stretched, poorly centered or labeled with developer abbreviations such as “Svc.” Important actions such as roads, demolish, pan, buses, parks, landmarks and trade needed direct icons rather than deep menus.

The rule became simple:

• the main dock contains frequent player actions;
• a category opens specific visual choices;
• tooltips explain every icon;
• the bottom bar reports current tool and brush size;
• the Gazette occupies a restrained bottom area instead of blocking the map;
• statistics use player language, not internal variable names.

15. Phase 12 - Data-driven gameplay rules#

One of the most important late corrections was extracting gameplay logic into JSON.

Initially, many values lived inside C++:

• capacities;
• wages;
• pregnancy timing;
• protest thresholds;
• vehicle payloads;
• construction requirements;
• trade prices;
• upkeep transfer modes;
• spawn rules;
• economy multipliers.

Every balancing change required recompilation and risked unrelated code. Worse, the same value could exist in more than one file.

The final project created one authoritative gameplay-rules package with domain files. The loader validates them before game construction and provides an immutable runtime snapshot.

Rules were separated by domain rather than placed in one giant file. Examples included:

• buildings;
• delivery;
• transport;
• economy;
• population;
• families;
• civic behavior;
• regional trade;
• ecology;
• presentation;
• audio;
• upkeep.

This made tuning safer, but only after strict ownership rules were established:

• every tunable has one owner;
• units appear in the key name or documentation;
• enums use readable values such as physical and internal;
• invalid combinations fail at startup;
• defaults in C++ exist only as startup fallback or invariant, not a second source of truth;
• staged JSON beside the executable must match source JSON by hash.

16. Phase 13 - Final tuning and verification#

The final casual balance pass did not merely inspect source.

It ran:

• 41 native test executables;
• a coupled town beyond 2,000 people;
• real Food production and household consumption;
• farms, shops, industry, utilities and construction;
• passenger traffic, buses and freight;
• regional visitors and workers;
• couples, babies and caregiver outings;
• Save/Load and validation;
• manual trade and anti-re-export protection.

The measured acceptance state reached:

• 2,532 people present;
• 2,094 permanent residents;
• 394 births;
• 398 completed freight movements;
• 22 passenger cars;
• 483 bus boardings;
• 33 operating Groceries;
• Food at 100%;
• a valid persistent state.

The executable was packaged with source, tests, JSON rules and documentation, without audio. The archive was extracted, hashes were compared and the extracted executable was launched.

Part III - What the AI Got Wrong#

17. The recurring failure patterns#

The same classes of error happened more than once. Recognizing these patterns is more useful than memorizing any individual bug.

18. Mistake: assuming design authority#

The AI repeatedly chose rules that had not been approved:

• making construction borrow automatically;
• changing utility connectivity;
• deciding when imports or exports occur;
• changing vehicle speed to reduce congestion or CPU usage;
• inventing caps;
• choosing hidden aggregate behavior when I asked to see every person;
• adding premade cities to a new blank game.

These were not harmless implementation details. They changed the game.

The correct boundary is:

• the player decides game-design outcomes;
• the AI may choose safe implementation details;
• if a choice affects difficulty, causality, visibility, money, time, population or player control, it must be recorded and approved.

19. Mistake: claiming completion without evidence#

Several times the AI said that timber trucks, families, traffic lanes, Food, Save/Load or police systems were working. When I opened the game, they were absent, invisible or broken.

This happened because the AI confused one of the following with completion:

• code compiled;
• a function existed;
• a unit test exercised a helper;
• an asset file existed;
• a state record could be serialized;
• a previous build had once worked.

The correction was an evidence ladder:

1. Source compiles.
2. Focused test proves the causal rule.
3. Integrated test proves connected systems.
4. fresh-world run proves initialization.
5. Save/Load proves persistence.
6. live visual inspection proves presentation.
7. extracted-package launch proves delivery.

No single level replaces the others.

20. Mistake: changing too much at once#

Broad requests such as “continue with the blueprint” sometimes caused simultaneous edits to traffic, families, audio, UI, economy and rendering. When the result broke, it was difficult to identify the cause.

The user’s correction was to demand sections:

• finish one bounded part;
• test it;
• update the blueprint;
• create a checkpoint;
• then proceed.

This is also how to survive context compression. A long AI conversation may be summarized. If the project state exists only in chat, the next continuation can forget crucial decisions.

21. Mistake: fixing performance by damaging motion#

When 4,000 people caused severe lag, the simulation frequency was reduced to 1 Hz. CPU load fell, but cars and pedestrians moved once per second and visibly paused.

The correct model was not “everything at 60 Hz” or “everything at 1 Hz.” It was:

• state decisions at appropriate low frequencies;
• movement integration at a stable simulation cadence;
• visual interpolation every render frame;
• event-driven updates for changes;
• staggered resident needs;
• spatial and visibility filtering for rendering.

Performance work must preserve behavior and feel. Never accept lower CPU time without a visual and causal comparison.

22. Mistake: using the wrong asset as a fallback#

When a specific sprite was missing or misrouted, the AI sometimes used:

• passenger cars as timber trucks;
• yellow vans as generic cargo;
• brown pixels or lines as Timber;
• concrete pallet piles as construction;
• procedural symbols as mine yards;
• floating activity components over unrelated buildings.

Fallbacks are dangerous because they allow tests to pass while presentation deteriorates.

A better asset rule is:

[ASSET RULE] A missing gameplay-critical sprite should fail an asset-integrity test or show a clearly marked developer diagnostic. It should not silently masquerade as another vehicle or building.

23. Mistake: treating visual defects as simulation defects#

Some problems looked causal but were only presentation:

• cut logs appeared to respawn because the visual source was not cleared;
• a bridge looked disconnected because two asset halves had a gap;
• a warehouse appeared to overlap buildings because its sort owner was wrong;
• couples seemed to separate because their render interpolation used different snapshots;
• old people appeared to move at adult speed because animation and state cadence were conflated.

Other problems were genuinely causal:

• Food existed at farms but never entered Groceries;
• construction workers could not reach unfinished destinations;
• save validation rejected a foreign-worker phase;
• imports created too many orders;
• local production credit did not distinguish imported stock.

The first diagnostic question should always be: is the authoritative state wrong, or is the renderer showing the state incorrectly?

24. Mistake: overengineering before the player could play#

The project sometimes spent effort on advanced systems while basic play was blocked:

• family biography inspection before family visibility;
• complex bridge ramps before ordinary road-over-water alignment;
• ecology penalties before the player could see pollution;
• deep utility networks before the player understood current service;
• more audio layers before core audio was audible;
• elaborate regional logic while Food was still zero.

The better priority order is:

1. The player can start.
2. The player understands the next action.
3. The action works.
4. The result is visible.
5. The result persists.
6. The system remains fun over time.
7. Only then add depth or polish.

25. Mistake: stale documentation and context loss#

The blueprint grew to hundreds of kilobytes. Some sections described old behavior. Later messages corrected earlier messages, but both remained in the document.

At one point the system drive reached zero free bytes during a write and a blueprint was truncated. It had to be reconstructed from checkpoints and logs.

Documentation is not useful merely because it is long. It needs:

• a current-state summary at the top;
• superseded sections clearly labeled;
• one decision ledger;
• one assumption register;
• one release checklist;
• dated evidence;
• exact paths and hashes;
• a short continuation handoff.

26. Mistake: uncontrolled temporary data#

The project accumulated:

• many CMake build directories;
• extracted verification packages;
• packaging stages;
• duplicated asset banks;
• large WAV libraries;
• object files and logs;
• Codex conversation/session records.

Codex session records alone occupied approximately 362 GB on the C: drive during this project. They were not game source or assets. The session store was moved to E:\CodexData\sessions.

The larger lesson is that AI-assisted development produces far more intermediate data than a normal manual workflow. Storage must be designed, not treated as cleanup after the disk is full.

Part IV - The Architecture That Finally Worked#

27. Establish five separate authorities#

A robust simulation project should define five authorities.

27.1 Design authority#

The approved game contract and decision ledger define what the game should do.

27.2 Rules authority#

Validated JSON defines tunable values and dependency modes.

27.3 Simulation authority#

Persistent C++ records define what actually exists: residents, sites, inventories, orders, trips, families and events.

27.4 Presentation authority#

The renderer consumes immutable views of simulation state. It never invents gameplay outcomes.

27.5 Evidence authority#

Tests, captured metrics, screenshots, Save/Load round-trips and package hashes prove the release.

If two layers both own the same fact, bugs multiply. For example, if both renderer and simulation decide whether a delivery exists, the screen and save file can disagree.

28. Separate the systems#

The project became safer when it separated:

• world/terrain;
• buildings and parcels;
• products and storage;
• economy;
• society and families;
• movement demand;
• traffic;
• pedestrian presentation;
• freight;
• forestry;
• regional world;
• ecology;
• civic events;
• audio;
• UI;
• persistence.

Each subsystem needs:

• inputs;
• outputs;
• authoritative records;
• invariants;
• cadence;
• Save/Load ownership;
• tests;
• player-facing explanation.

29. Make gameplay rules data-driven#

A good rules file is readable by a player and strict enough for a program.

Bad:

{
  "x": 7200,
  "mode": 1
}

Better:

{
  "local_grocery_food_load_points": 7200,
  "timber_upkeep_transfer_mode": "internal",
  "regional_food_import": "automatic_when_critical",
  "regional_timber_import": "manual",
  "regional_timber_export": "manual"
}

The loader should reject:

• unknown fields;
• missing required fields;
• invalid enum strings;
• negative capacities;
• contradictory automatic and manual modes;
• Utility configured as truck cargo;
• percentages outside range;
• products without units.

The active rules snapshot should be immutable during a running world unless the game explicitly supports hot reload.

30. Preserve determinism#

Determinism made failures reproducible.

The same:

• seed;
• rules;
• input sequence;
• elapsed simulation time;

should produce the same:

• residents;
• jobs;
• vehicle assignments;
• families;
• inventories;
• events;
• save bytes or logically equivalent state.

Determinism is especially useful for:

• traffic regressions;
• family timing;
• economy balancing;
• regional offers;
• visual atlas selection;
• Save/Load.

Randomness should use owned, seeded streams. Do not use unrelated wall-clock randomness throughout the code.

31. Use explicit product conservation#

Every physical product chain should be auditable.

For a conversion:

input stock = output stock + residue + recorded loss.

For a transfer:

source before - loaded quantity = source after.

destination before + unloaded quantity = destination after.

For regional settlement:

player money change + partner money change + fees = zero, within the defined model.

For exported local goods:

exported quantity must be backed by local-production credit.

These equations should be tests, not comments.

32. Treat Save/Load as part of every feature#

Every persistent feature needs an answer to:

• What is saved?
• What is derived and rebuilt?
• What version owns the schema?
• What validation protects it?
• What happens if the primary file is corrupt?
• What happens if autosave is writing while a new world starts?

The SOLESIDO save system eventually used:

• immutable captured payloads;
• validation before commit;
• write-through temporary output;
• atomic replacement;
• a previous valid backup;
• session authority so an old autosave cannot overwrite a new world;
• exact post-load reconstruction of derived transport.

The foreign-worker save failure showed why validation should not be bypassed. The correct fix repaired the lifecycle transition that created inconsistent state.

33. Design rendering metadata, not exceptions#

For every authored isometric asset, record:

• atlas and cell;
• logical footprint;
• anchor;
• draw offset;
• depth owner;
• shadow/base policy;
• direction variants;
• animation attachment;
• collision/display bounds;
• fallback policy.

Avoid code such as “if this is the water plant, move it seven pixels.” Those exceptions become unmaintainable.

34. Keep regional simulation cheap#

The four surrounding regions demonstrate a scalable pattern.

They do not simulate every hidden person. They keep aggregate state:

• population stage;
• prosperity;
• forest coverage;
• product inventory;
• relationship;
• offers;
• gateway demand.

Only entities entering the player’s visible world become full agents or vehicles.

This provides visible consequences without multiplying the main simulation by five.

Part V - A Safer AI Collaboration Workflow#

35. Start with a project constitution#

Before code, write one page containing:

• player fantasy;
• core loop;
• non-negotiable behaviors;
• excluded features;
• target platform;
• performance target;
• visual language;
• save policy;
• evidence required for “done.”

For SOLESIDO, non-negotiable examples were:

• blank New World, not a premade city;
• visible causal trips;
• no fake passenger cars;
• the rainforest is mechanically important;
• the player controls game-design logic;
• casual continuity without hidden punishment;
• native Windows executable;
• high-quality isometric art;
• Paint and isometric views both remain available.

36. Use a decision ledger#

Every decision that changes player experience should record:

• date;
• question;
• options;
• player decision;
• exact values;
• affected files;
• test;
• superseded rule.

Example:

Decision: Regional Timber trade
Import: manual
Export: manual
Truck capacity: 50,000 units
Imported cargo re-export: forbidden
Settlement: player treasury
Visibility: real TIR vehicles
Acceptance: quote + confirmation + physical trip + Save/Load

This prevents the AI from rediscovering or reinterpreting the rule after context compression.

37. Maintain an assumption register#

When the AI must proceed while you are unavailable, require it to write every unapproved choice into an assumption register.

Each assumption should include:

• what was unknown;
• what value was chosen;
• why;
• risk;
• how to change it;
• whether code or JSON owns it;
• whether it was tested.

An assumption is not approval. The next review should accept, replace or reject it.

38. Make every task bounded#

Bad request:

Continue the whole blueprint and finish the game.

Better:

Change only the local Grocery Food payload from 3,600 to 7,200.
Do not change vehicle speed, reserve targets, spawn logic or any other value.
Update the authoritative JSON and its startup fallback.
Add or update the focused regression.
Build Release and report the exact test result.
Do not package until I approve.

Large goals are still useful, but each implementation turn should have one bounded change set and explicit non-goals.

39. Use the verify-before-change rule#

For a bug:

1. Reproduce it.
2. Identify the authoritative wrong state.
3. State the root cause.
4. State the smallest correction.
5. State what will not change.
6. Add a failing regression.
7. Apply the fix.
8. Re-run the focused test.
9. Re-run integration tests.
10. Inspect live presentation if the bug is visual.

Do not accept “I found a likely issue” followed immediately by edits.

40. Require a no-regression contract#

Before a change, list protected behavior.

Example for increasing freight payload:

• vehicle speed unchanged;
• vehicle artwork unchanged;
• lane placement unchanged;
• order remains physical;
• Save schema unchanged;
• destination logic unchanged;
• no hard vehicle cap added;
• only payload and resulting natural order count may change.

The test should assert protected behavior as well as the new behavior.

41. Use checkpoints designed for context compression#

A useful checkpoint is short enough to reread and specific enough to resume.

It should contain:

• current working build path;
• current source root;
• last known-good archive;
• changes completed;
• tests passed;
• live visual checks passed;
• open blockers;
• exact next step;
• prohibited changes;
• unapproved assumptions.

Do not rely on the chat transcript as project memory.

42. Ask the AI to report evidence, not confidence#

Replace:

Is it fixed?

with:

Show the failing state before the fix, the exact causal record after the fix,
the focused regression name, the full integration result, the executable path,
and what remains unverified visually.

Confidence language is cheap. Evidence is useful.

Part VI - Testing, Balancing and Performance#

43. Test the game at several levels#

One of the most expensive mistakes in the SOLESIDO project was treating one kind of evidence as proof of everything. A compiler proves syntax and linkage. A unit test proves one coded contract. Neither proves that a player can understand the feature, see it on screen, save it, load it and enjoy it for two hours.

Use this evidence ladder:

1. Static inspection. Confirm that the intended code and asset path are actually present in the source tree.
2. Build verification. Compile the exact Release configuration that will be packaged.
3. Focused regression. Reproduce the original failure with the smallest deterministic test.
4. System integration. Exercise every producer, queue, carrier, consumer and statistic involved in the feature.
5. Fresh-world simulation. Start without an old save and run the real new-game path.
6. Persistence test. Save during an active transition, load, and prove that the transition completes only once.
7. Live visual test. Open the actual executable and inspect scale, anchoring, direction, overlap, readability and animation.
8. Extracted-package test. Unzip the release elsewhere and launch the copy, not the build-tree executable.
9. Long soak. Run a dense city long enough to reveal queue growth, drift, memory leaks, starvation and demographic imbalance.

A feature is complete only when it passes every relevant rung.

44. Fresh games and old saves answer different questions#

An old save is essential for backward-compatibility testing, but it is a poor default for judging new-game balance. It may contain stale queues, older rule versions or already-invalid state.

The SOLESIDO workflow eventually separated the tests:

• Fresh game: proves current defaults, starter capital, starter timber, population arrival, first construction and first deliveries.
• Migrated save: proves version compatibility and derived-state rebuilding.
• Adversarial save: begins inside a dangerous transition such as a foreign worker arriving, timber in transit, a pregnancy due, construction funded or an autosave occurring.
• Dense save: stresses rendering, routing, freight, warehouses, families and the dashboard at the same time.

Never repair an old save by weakening a core invariant unless that migration is explicit, versioned and tested.

45. The 2,000-person acceptance city#

The user repeatedly asked for a city large enough to expose real problems. That was correct. A 500-person starter town can conceal missing families, weak food flow, unused buses, warehouse floods and pathfinding costs.

A useful acceptance scenario for SOLESIDO contains:

• 2,000 or more residents;
• housing of several sizes;
• farms, groceries, commerce and multiple industries;
• local forestry, a sawmill and construction demand;
• at least one trade warehouse and active regional trade;
• utility buildings;
• connected and disconnected destinations;
• walking, cars, buses and freight at the same time;
• families, pregnancies, births, children, teenagers and retirees;
• sufficient social pressure to exercise police, protests or civic events;
• a Save and Load while freight and family transitions are active.

The important output is not only “the test passed.” Record population, jobs, births, deaths, food security, utility reliability, queued orders, delivered orders, vehicle counts, warehouse stock, treasury, debt, route failures and frame timing.

46. Read statistics as a causal story#

The dashboard must answer four questions:

1. What is wrong?
2. Why is it wrong?
3. What can the player do?
4. How long should recovery take?

For example, “Food 0%” is not enough. A useful diagnosis is:

Farms produced food. Two grocery orders are waiting. No stocked grocery is serving households because its reserve gate is incorrectly blocking sales while a replenishment van is in transit.

That sentence identifies the producer, queue, carrier, consumer and broken rule. It also distinguishes a true shortage from a delivery bug.

The same pattern applies to timber, workers, utilities, construction, crime and regional trade.

47. Use authoritative cadence tiers#

SOLESIDO became unplayable when too much work happened at display frequency. It also looked broken when all movement was reduced to one update per second.

The correct answer was not “everything at 60 Hz” or “everything at 1 Hz.” It was to separate simulation decisions from visual motion.

The renderer may run at the monitor frame rate, but it should interpolate between the last two simulation states. A resident does not need to reconsider work, food and family sixty times each second for the sprite to walk smoothly.

48. Stagger expensive decisions#

If 200,000 residents all evaluate needs on the same frame, the result is a periodic freeze even when the average CPU load looks low.

Instead:

• divide agents into deterministic batches;
• give each batch a stable phase offset;
• process only the due batch;
• retain event-driven wakeups for urgent changes;
• use a bounded work budget;
• expose backlog and worst-frame time in diagnostics.

This preserves individual persistent agents. It does not replace people with a fake population number.

49. Separate routing from movement#

A vehicle route may be recalculated at one or two hertz or when an edge becomes invalid. Its physical position should still be interpolated every render frame.

The vehicle loop should conceptually be:

decision: choose origin, destination, mode and route
simulation: advance along route, reserve space and obey headway
presentation: interpolate position and choose directional sprite

When these concerns were mixed, SOLESIDO produced sideways cars, lane jumps, overlap, stop-start motion and expensive repeated route scans.

50. Measure the correct performance numbers#

Overall CPU percentage can be misleading. A game using 4.5% of a fourteen-core CPU may still be limited by one serial thread and have visible frame spikes.

Record:

• frame-time median, 95th and 99th percentile;
• simulation-tick duration;
• route calculations per second;
• agents evaluated per tick;
• active and visible vehicles;
• queued freight orders;
• render draw calls or sprite batches;
• memory growth;
• save serialization time;
• audio decode time;
• time spent while fully zoomed out.

Use a release build and the same camera position for comparisons. Do not optimize from intuition alone.

51. Optimize the actual hot path#

The most useful SOLESIDO performance discoveries came from tracing the real scheduler. An outer 20 Hz loop still hid passenger-traffic subdivision that performed sixty scans per second. Changing the outer constant alone therefore did not solve the lag.

The safe optimization process is:

1. profile;
2. name the hot function and caller;
3. define behavior that must not change;
4. change one layer;
5. compare deterministic simulation results;
6. compare visible motion;
7. benchmark before and after;
8. revert if the improvement is not demonstrated.

52. Balance in data, not in arguments#

Once the rules were externalized, tuning became safer. A balance pass should:

• lock the code and change only rule data;
• use a fixed set of seeds and scenarios;
• change one related group of values at a time;
• record the before and after metrics;
• include scarcity, abundance and recovery scenarios;
• preserve the user’s design decisions in a decision ledger;
• package the exact rules used by the executable.

A casual default is not the same as “resources can never fall.” A useful casual game lets the player see pressure, understand the cause, and recover without needing to reverse-engineer the simulation.

53. Tune logistics as a flow network#

For every physical resource, write the chain explicitly:

source -> source stock -> order -> carrier -> destination stock -> consumer

Then define:

• unit;
• production batch;
• carrier capacity;
• dispatch threshold;
• reserve target;
• reorder threshold;
• consumption;
• ownership of payment;
• visible or internal transfer;
• cancellation and retry;
• Save/Load state.

The SOLESIDO food-van flood occurred because a grocery’s six-month target could require many 600-unit vans. Increasing capacity was a valid balance change; an arbitrary hard cap of four vans would have concealed shortages and broken larger stores.

54. Test balance with recovery, not only equilibrium#

Players make mistakes. A good test deliberately removes a farm, road, worker, warehouse or utility, waits for failure, then restores it.

The system should:

• explain the failure;
• stop generating duplicate impossible orders;
• retain recoverable state;
• resume without a restart;
• clear stale warnings;
• normalize queues and traffic after recovery.

This is where many “working” simulations reveal deadlocks.

Part VII - Visual Assets, Animation and User Interface#

55. Treat every sprite as production data#

An isometric asset needs more than a PNG filename. It needs a contract:

• semantic role;
• footprint in tiles;
• visual bounds;
• ground-contact point;
• baseline and sort owner;
• allowed rotations;
• directional variants;
• collision and road-access point;
• transparent-margin policy;
• construction stages;
• animation attachment points;
• close-zoom and far-zoom behavior.

Without this metadata, a beautiful image can still float over a road, hide behind the wrong building or reveal only its roof.

56. Use a consistent isometric art specification#

SOLESIDO’s strongest art shared these traits:

• a consistent camera angle;
• a readable tile diamond;
• detailed but controlled pixel-art texture;
• a grounded base or shadow;
• clear front-facing entrances;
• transparent background;
• no baked neighboring terrain;
• sufficient empty margin for tall elements;
• a palette that belongs to the rainforest world.

Art prompts should specify the exact footprint and ground-contact line. “Create a cute isometric warehouse” is not enough.

57. A reusable asset prompt#

Create one original high-detail isometric pixel-art asset for SOLESIDO.
Subject: [asset].
Gameplay role: [role].
Footprint: exactly [W] x [H] isometric tiles.
Camera and lighting: match the supplied SOLESIDO reference atlas exactly.
The complete foundation must sit on the tile plane; nothing may float.
Keep the entrance and road-access edge on [direction].
Transparent background. No labels, UI, neighboring buildings, terrain fill,
cut-off roof, perspective mismatch, orthographic front view or duplicate object.
Include a subtle contact shadow contained inside the footprint.
Deliver one clean sprite at native scale with enough transparent margin for
sorting, plus [directions/stages] if requested.

After generation, verify it in the game at minimum, normal and maximum zoom.

58. Construction needs authored stages#

Procedural brown beams and repeated pallet piles looked like placeholders because they were placeholders. A polished building should have a short sequence such as:

1. cleared and surveyed ground;
2. delivered resources and foundations;
3. partial frame or first walls;
4. roof and exterior work;
5. finished building.

The simulation can retain the same progress value. The renderer chooses the authored stage. This improves presentation without inventing new construction logic.

59. Ground assets on their footprint#

Centering by PNG dimensions is often wrong because transparent margins and tall roofs distort the geometric center.

Use the authored ground-contact anchor. For multi-tile assets:

• compute the tile-footprint diamond;
• align the asset’s ground-contact point to its center or authored frontage;
• assign exactly one render owner;
• suppress all covered tile owners;
• sort from the footprint’s back-to-front baseline;
• test adjacent roads, pedestrians, water and tall neighbors.

This is the correct fix for warehouses and large utilities, not repeated pixel nudges.

60. Keep animations attached to machinery#

Several early activity effects appeared as floating water, sprinklers or machinery because their offsets were global guesses.

Every effect needs:

• an owning building instance;
• a named local attachment point;
• a small frame sequence or transform;
• visibility rules;
• a z-order relative to the building;
• a fallback of “do not draw” when metadata is missing.

If an effect cannot be attached correctly, disable that effect. A static, beautiful building is better than a floating “WOW” animation.

61. Water and environmental motion should be cheap#

Moving water does not require a full simulation. A restrained solution is:

• a small seamless tile sequence or UV offset;
• deterministic phase variation;
• only animate visible water chunks;
• share frames across tiles;
• reduce update frequency when zoomed out;
• keep riverbank geometry static;
• avoid per-tile allocation.

The same approach works for chimney smoke, fans, signs and crop shimmer.

62. Build riverbanks from adjacency#

The improved riverbanks were a visual-only system:

• inspect neighboring land and water;
• select edge, corner, inlet or isolated-bank art;
• keep the water tile and gameplay unchanged;
• render a deeper soil/rock lip and a thin vegetation transition;
• batch or cache the resulting surface.

This gives rivers depth without introducing terrain-height simulation.

63. Distinguish intact, damaged and restored ground#

The project learned this requirement through several reversions:

• untouched terrain keeps the approved base appearance;
• deforestation or demolition reveals a seamless damaged-soil surface;
• the damaged surface must appear only on affected tiles;
• the player can later use a “Restore Grass” tool;
• restoring grass changes the surface, not the forest;
• reforestation is a separate action.

This rule should be covered by a screenshot regression because a one-line condition can accidentally apply the damaged texture to the whole map.

64. Visual quality can still be CPU-cheap#

Thousands of individually drawn detailed ground tiles caused zoomed-out lag. The approved visual did not need to be discarded. It needed a cheaper representation:

• precompose or cache static ground chunks;
• invalidate only changed chunks;
• use simpler mip or lower-detail texture when far away;
• batch tiles sharing a texture;
• cull outside the camera;
• avoid re-creating brushes and bitmaps every frame.

Preserve the player’s approved appearance while optimizing its delivery.

65. Give the interface a game hierarchy#

The player should not have to guess where a core tool is hidden.

SOLESIDO’s interface should expose:

• global menu, Save, Load, Statistics and map mode;
• primary build categories on the left;
• direct icons for Roads, Demolish, Pan and Public Transport;
• direct categories for Parks, Landmarks and Trade;
• the selected category’s assets immediately beside or within that panel;
• size controls in one stable bottom-left location;
• contextual explanation and status;
• bottom-corner Gazette notifications that do not cover play.

Icons must be centered, consistent and paired with hover tooltips.

66. Write interface text for a player#

Avoid internal abbreviations such as “Svc.” Avoid a dashboard that reads like an AI report.

Good labels tell the player what the action does:

• “Build Road”
• “Restore Grass”
• “Regional Trade”
• “Town & Families”
• “Why construction is waiting”

When text does not fit, revise the hierarchy or layout. Do not shrink it until it is unreadable.

67. Inspect at every supported resolution#

The logo, welcome guide, statistics tabs, treasury text and tool icons each failed at some point because only one layout was considered.

The visual matrix should include:

• 1024 x 768;
• 1280 x 720;
• 1440 x 900;
• 1920 x 1080;
• 100%, 125% and 150% DPI where supported;
• windowed and fullscreen;
• smallest and largest UI scale;
• every major tab;
• long translated or diagnostic strings.

Capture deterministic screenshots and compare them against approved references.

68. Use generated art responsibly#

AI image generation was extremely useful for SOLESIDO’s buildings, farms, vehicles, icons and branding. It was not automatically production-ready.

The finishing pipeline still needs:

1. reference selection;
2. generation with exact constraints;
3. transparent-background cleanup;
4. cropping and padding normalization;
5. scale and palette matching;
6. directional or stage slicing;
7. anchor metadata;
8. asset-integrity test;
9. live placement test;
10. license and provenance record.

Do not silently copy the supplied reference. Use it for composition, scale and quality direction while generating original art.

Part VIII - Save Systems, Releases and Storage Hygiene#

69. Use source control from the first file#

The greatest missing safety net in the early SOLESIDO work was disciplined version control. Copies of build folders are not a substitute for Git.

A minimal workflow is:

main           last verified playable state
feature/...    one bounded change
fix/...        one reproduced defect
release/...    frozen release candidate

Commit before a risky change. Commit after the focused tests pass. Tag packaged releases. Never place generated build output, WAV archives or temporary renders in the source repository.

Useful commit messages describe behavior:

fix(food): allow stocked groceries to sell while refill is inbound
fix(save): normalize foreign-worker gateway phase before serialization
perf(render): cache static damaged-ground chunks
ui(toolbar): expose road, pan and demolish tools

If a change fails, revert that commit instead of manually remembering every file the AI touched.

70. Define a release checkpoint#

Each checkpoint should record:

• source commit or content hash;
• rules hash;
• Release executable hash;
• package hash;
• compiler and configuration;
• required asset and audio packages;
• tests and their results;
• fresh-world seed;
• live visual evidence;
• known issues;
• saves created with the build.

“Latest executable” is not a reliable identifier.

71. Save an immutable game-state snapshot#

The simulation should not serialize a moving object graph while another thread changes it.

A safe pattern is:

1. request a save at a simulation boundary;
2. produce one immutable snapshot;
3. validate cross-record invariants;
4. serialize to a temporary file;
5. flush and close it;
6. atomically replace the target;
7. retain a .bak of the previous valid save;
8. write the version and rules hash.

Load into temporary state, validate it, rebuild derived caches and only then replace the live world.

72. Validate transitions, not only records#

The foreign-worker Save failure was useful because the validator detected a real contradiction: the worker’s phase did not match the job and gateway-trip lifecycle.

The wrong fix would have been to hide or remove the validation. The correct fix was to repair the state transition and add cases for:

• arrival;
• job assignment;
• temporary employment;
• departure;
• settlement;
• conversion into a permanent resident;
• Save and Load during each phase.

The same strategy applies to construction, births, deliveries and demolition.

73. Give autosave one session authority#

An old simulation session must not finish an autosave after a new world has replaced it.

Every save request should carry:

• session or world identifier;
• monotonic generation;
• intended slot;
• captured rules hash;
• captured snapshot version.

Before committing the file, verify that the session is still authoritative. This prevents an old autosave from overwriting a new game.

74. Package the game from a clean source state#

A trustworthy release process is:

1. clean or create a dedicated release build directory;
2. compile Release;
3. run focused and full tests;
4. stage the exact executable, DLLs, rules and assets;
5. exclude development logs, object files and private material;
6. create the ZIP;
7. extract it into a new directory;
8. launch the extracted copy;
9. start a new world;
10. Save, Load and exit;
11. hash the executable and ZIP;
12. archive the previous release separately.

SOLESIDO sometimes had a newer loose executable than the packaged ZIP. This procedure prevents the wrong binary from being delivered.

75. Separate source, game and audio packages#

The user often needed a compact build without audio for review by another AI. That is a legitimate product configuration.

Maintain:

• Game package: executable, rules, required visual assets, minimal runtime and player documentation.
• Audio package: production audio in its expected folder structure.
• Source package: full source, tests, JSON schemas/rules, build instructions, documentation and a matching executable, but no bulky audio unless requested.
• Debug evidence: logs, traces, screenshots and special QA worlds, kept out of public packages.

Each package should state what it deliberately excludes.

76. Audio needs an asset budget#

Uncompressed WAV grows quickly. Duration × sample rate × channels × bit depth determines size. Hundreds of long stereo files can easily exceed 600 MB.

For city and nature ambience:

• use mono for point sources;
• use stereo only for beds that need width;
• trim silence;
• use sensible sample rates;
• loop short, clean beds;
• layer independent sounds at runtime;
• compress distribution audio with a codec supported by the game;
• retain lossless masters outside the shipping package;
• decode or preload according to an explicit memory budget.

MIDI cannot replace recorded jungle, traffic, engines, crowds or animal calls. It is suitable for music and synthetic instruments, not environmental recordings.

77. Know what consumes disk space#

The SOLESIDO work accumulated several distinct kinds of data:

The surprising discovery was approximately 362 GB of Codex session and tool history on the system drive. Those files were not SOLESIDO source or assets, but they still competed for the same SSD space.

The user moved the session folder to:

E:\CodexData\sessions

That experience produced an important rule: AI-assisted development needs a storage plan just as much as the game does.

78. A practical drive layout#

For a PC with a small system SSD and a larger data drive:

C:\Users\<you>\Documents\<project>\src       active source and small docs
E:\GameDev\SOLESIDO\build                    disposable build trees
E:\GameDev\SOLESIDO\packages                 release ZIPs
E:\GameDev\SOLESIDO\audio-masters            large source audio
E:\GameDev\SOLESIDO\qa                       screenshots, traces, test worlds
E:\CodexData\sessions                        Codex session history

Do not move a live application’s internal folder blindly. Close the application, verify its supported configuration, copy first, validate the new location, and keep a rollback path. The application may use absolute paths, locks or a database.

79. Establish storage thresholds#

Use simple operational limits:

• stop large builds below 20 GB free on the system drive;
• warn below 40 GB;
• keep one current and one previous verified release locally;
• archive older releases with hashes;
• delete only reproducible build output;
• never delete the only source tree, rules package, save or verification record;
• monitor session, compiler-cache and audio directories separately.

Running the system drive to zero caused a failed documentation write to truncate the SOLESIDO blueprint. Disk exhaustion is therefore a correctness risk, not only an inconvenience.

80. Audit disk use without deleting#

Before cleanup, list and measure. A PowerShell audit can be read-only:

Get-ChildItem -LiteralPath 'C:\path' -Directory -Force |
  ForEach-Object {
    $bytes = (Get-ChildItem -LiteralPath $_.FullName -File -Recurse -Force `
      -ErrorAction SilentlyContinue | Measure-Object Length -Sum).Sum
    [pscustomobject]@{ Path = $_.FullName; GB = [math]::Round($bytes / 1GB, 2) }
  } | Sort-Object GB -Descending

The user should review the list. A cleanup operation should state whether each directory is source, generated, cached, archived or unknown.

81. Treat AI session history as project evidence#

A long development task can contain valuable design decisions, reproduced bugs and user approvals. But the raw transcript is too large and fragile to be the only memory.

Extract durable records into the repository:

• GAME_CONTRACT.md
• DEVELOPMENT_BLUEPRINT.md
• DECISION_LEDGER.md
• ASSUMPTION_REGISTER.md
• RELEASE_EVIDENCE.md
• KNOWN_ISSUES.md
• versioned JSON rules and schemas.

This keeps the project understandable even if session history is moved, archived or unavailable.

Part IX - Copyable Prompts and Checklists#

82. Project kickoff prompt#

You are helping me build a game, but I retain authority over game design.
First inspect the repository and write a concise game contract containing:
player fantasy, core loop, causal systems, non-goals, supported platform,
performance target, persistence requirements and definition of done.

Do not implement yet. List every design decision that the current request leaves
ambiguous. Distinguish safe implementation details from choices that affect
difficulty, money, time, population, visibility, causality or player control.
Do not choose the latter for me.

83. Bounded feature prompt#

Implement only: [feature].
Protected behavior: [list].
Authoritative design decisions: [list].
Source files likely in scope: [list if known].
Do not redesign adjacent systems, alter vehicle speeds, change existing art or
rebalance unrelated values.

Before editing:
1. reproduce or inspect the current behavior;
2. identify the exact data flow and invariants;
3. state the smallest safe implementation boundary.

After editing:
1. add a focused regression;
2. run related and full tests;
3. start a fresh game if balance is involved;
4. state what remains visually unverified;
5. update the decision and release ledgers.

84. Diagnose-only prompt#

Diagnose this issue. Do not implement a fix.

Observed by the player:
[symptoms, screenshot, save and build].

Trace producer -> queue -> carrier -> consumer -> statistic.
Show the first state that becomes invalid, the owner of that state, and why.
Separate confirmed facts from hypotheses. Tell me which existing tests fail and
which new focused test would reproduce it. Do not infer permission to change
gameplay rules.

85. Approved-fix prompt#

I approve this exact behavior:
[decision].

Implement the smallest causal repair. Preserve:
[protected behavior].

Do not bypass validation, hide the warning, grant free resources, delete queues
or introduce a hard cap unless explicitly stated above. Add a test that fails on
the original bug and passes after the repair. Report exact files changed and
evidence.

86. Visual-asset replacement prompt#

Replace only the demonstrated low-quality asset:
[asset and screenshot].

First search the existing asset library for an approved matching sprite. Reuse
it if suitable. Generate new art only if no suitable asset exists.

Do not change simulation logic. Preserve footprint, road access, construction
stage and z-order contract. Verify transparent bounds, anchor, ground contact,
close zoom, neighboring buildings and far-zoom performance.

87. Performance prompt#

Profile this reproducible scenario:
[save/new-game steps, population, camera and speed].

Do not change behavior yet. Report median/p95/p99 frame time, simulation tick
time, the hottest callers and work counts. Separate visual interpolation from
simulation decisions.

Then propose the cheapest change that preserves:
real persistent agents, purpose-driven trips, vehicle speeds, route behavior,
family logic, deliveries and visual smoothness. No aggregation or hidden fake
population without my approval.

88. JSON-rules extraction prompt#

Inventory every tunable gameplay value in the source tree. Classify it by
domain, unit, owner, default, valid range, dependencies and Save compatibility.

Create one authoritative typed rules package. Do not merely duplicate constants
into JSON; the runtime must read the JSON value and the old compiled authority
must be removed. Reject unknown, missing or contradictory values. Add schema,
loader tests, a rules hash and human-readable comments or companion
documentation.

List every value that remains compiled and why.

89. Balance prompt#

Balance only through the approved rules package.
Goal: casual, understandable, recoverable play—not infinite free resources.

Run fixed scenarios for starter town, 2,000 residents, scarcity, recovery and
long soak. Record production, stocks, orders, deliveries, consumption, jobs,
families, treasury, traffic and performance. Change one domain at a time.

Do not alter logic. Put every suggested design assumption in
ASSUMPTION_REGISTER.md for my review.

90. Adversarial audit prompt#

Act as a release auditor. Do not praise the build and do not fix anything yet.

Audit fresh game, Save/Load, construction, Food, utilities, forestry, trade,
warehouses, passenger traffic, buses, freight, families, twins, foreign workers,
police/protests, UI, assets, audio and performance.

For every finding provide:
severity, player-visible symptom, exact reproduction, evidence, causal owner,
affected builds/saves, safest proposed repair and protected behavior.

Mark untested claims as unverified. Passing code inspection is not live proof.

91. Compaction handoff prompt#

Before context compression, update the durable project checkpoint.
Include:
exact source root;
working executable;
last known-good package;
commit/hashes;
completed changes;
tests;
live checks;
open blockers;
unapproved assumptions;
prohibited changes;
next exact step.

Do not mark a feature complete unless the checkpoint names its evidence.

92. Packaging prompt#

Create a clean source-and-executable ZIP without audio.
Include source, headers, tests, assets required to run, JSON rules and schemas,
build instructions, documentation and the matching Release executable.
Exclude object files, old builds, private session records, temporary QA data and
audio.

After creating the ZIP, extract it to a new folder, verify hashes, launch the
extracted executable, start a new game, Save and Load. Report the final absolute
path and exclusions.

93. “Do not guess” prompt#

For this task, do not make unapproved game-design decisions.
You may choose reversible implementation details that do not affect the player.
If a choice changes price, capacity, timing, difficulty, visibility, causality,
population, vehicle behavior, failure or reward, stop and show me:
the confirmed current behavior, two or three bounded options, their consequences,
and your recommendation. Record my answer in the decision ledger.

94. Live playtest checklist#

• Start the exact candidate executable.
• Start a fresh world, not an old autosave.
• Confirm starter capital and starter construction freedom.
• Connect roads before diagnosing transport.
• Build housing, farms, groceries, industry, utilities and warehouse.
• Watch at least one complete Food delivery.
• Watch a deforested tile become Roundwood, get collected and disappear.
• Watch the sawmill produce Timber and a construction receive it.
• Confirm local resources are preferred according to the approved rules.
• Open trade and execute one import and one export.
• Observe cars, buses, local freight and TIRs without sprite substitution.
• Inspect lane centering, headway and overlap.
• Observe a couple, pregnancy, birth, stroller, child and teenager.
• Trigger or load a controlled civic-pressure scenario.
• Save during active trips and deliveries.
• Load and confirm no duplication, loss or invalid state.
• Open every main UI page and hover every icon.
• Zoom fully in and out and pan at screen edges.
• Record performance and outstanding visual seams.

95. Release checklist#

• Game contract and decision ledger current.
• No unreviewed assumptions.
• Rules schema and hash match the executable.
• All focused regressions pass.
• Full deterministic suite passes.
• Fresh 2,000-person acceptance run passes.
• Save/Load active-transition suite passes.
• Visual matrix inspected.
• Audio package tested separately.
• Release build contains no development fallbacks.
• ZIP extracted and launch-tested.
• Exact executable and package hashes recorded.
• Previous verified release retained.
• Known issues written in player language.

Part X - A Practical Roadmap for Your First AI-Assisted Game#

96. Start with one toy that is already fun#

SOLESIDO began with a compelling toy: erase a rainforest and watch the map change. That interaction was fun before families, finance or freight existed.

For a first milestone, implement:

• one map;
• one primary tool;
• one visible consequence;
• Undo/Redo;
• Save/Load;
• one performance target;
• one short player explanation.

If this small loop is not enjoyable, additional simulation will not rescue it.

97. Write the causal graph before the feature list#

A feature list says “farms, shops, people, trucks.” A causal graph says:

farm workers -> food production -> farm stock -> grocery order
-> delivery van -> grocery stock -> household purchase
-> hunger/wellbeing -> labor and family outcomes

The graph exposes missing ownership and statistics before code is written.

For every arrow, decide whether it is:

• physical and visible;
• internal and immediate;
• scheduled;
• paid;
• capacity-limited;
• optional;
• persistent;
• explained to the player.

98. Build vertical slices#

Do not build every producer before any consumer works. Finish one complete slice:

1. one farm;
2. one grocery;
3. one household;
4. one visible van;
5. one stock change;
6. one dashboard explanation;
7. Save/Load.

Only then add farm varieties, regional imports, warehouses or price dynamics.

99. Preserve the first working release#

The moment the first slice works:

• tag it;
• package it;
• extract and test it;
• save a deterministic world;
• capture screenshots;
• record its metrics.

All later work should be compared against that baseline.

100. Move configuration out early#

Before the second major system, create the typed rule layer. It is much cheaper than extracting hundreds of values after the code has grown.

Start with:

• time and cadence;
• construction;
• production and consumption;
• vehicle capacities;
• prices and wages;
• population and families;
• civic thresholds;
• performance budgets.

Keep structural invariants in code. Put design-tunable values in validated data.

101. Introduce one system at a time#

A practical order for a game like SOLESIDO is:

1. map and terrain editing;
2. roads and placement;
3. one building type;
4. one resource chain;
5. persistent residents and one trip;
6. construction;
7. Food and shops;
8. other industries;
9. families;
10. freight and warehouses;
11. regional trade;
12. civic systems and humor;
13. richer animation and audio;
14. deep balance and long soak.

This order produces a playable game at every milestone.

102. Use a three-document control system#

Large blueprints become stale. Keep three short authorities:

Game contract#

What the game is, what the player controls, what must never change silently and what the game is not.

Decision ledger#

Approved design choices with date, reason and superseded alternatives.

Release evidence#

What exact build has proved what exact behavior.

Long research and ideas can live elsewhere. These three documents govern the work.

103. Make the AI stop at design boundaries#

The AI should continue autonomously through safe implementation details, but it must stop when a choice affects the game’s meaning.

Examples requiring the creator:

• whether cities may borrow automatically;
• whether imported timber is cheaper than exported timber;
• whether utility service is global or road-connected;
• whether a building can construct without workers;
• whether freight is visible or internal;
• how frequently couples have children;
• whether pedestrians block cars;
• whether regional trade is automatic or manual.

Record the answer once so it is not re-guessed after context compression.

104. Let the AI challenge, not replace, your judgment#

The AI can calculate implications and present alternatives:

A 600-unit van requires up to 24 trips to fill this grocery’s reserve. Increasing the load to 7,200 reduces traffic while preserving physical deliveries. A hard cap would leave larger stores permanently understocked.

That is useful technical counsel. The user still decides the gameplay rule.

105. Budget time for repair#

AI-generated code is not free code. It creates review, testing, integration and maintenance work.

A realistic milestone allocates time to:

• implementation;
• focused testing;
• integration;
• live visual review;
• balance;
• documentation;
• packaging;
• repair after player testing.

If every available token and hour is spent adding features, no budget remains to make the game reliable.

106. Prefer reversible progress#

The safest changes are:

• isolated;
• behind a data value or feature flag;
• covered by a regression;
• committed separately;
• compatible with the current save version;
• easy to disable;
• visually inspectable.

Broad rewrites should require stronger evidence than local repairs.

107. Finish with a player, not a checklist#

A system can meet its technical contract and still feel bad. The final pass asks:

• Can a new player understand the first ten minutes?
• Does every main tool have an obvious home?
• When something fails, is the remedy clear?
• Are vehicles and people visibly purposeful?
• Are shortages pressure or confusion?
• Can the city recover?
• Is the map still beautiful after play changes it?
• Does the world produce charming, surprising moments?
• Can the player play for hours without lag or constant interruption?

Those questions define the product.

108. The central lesson#

The creator’s role is not reduced by AI. It becomes more important.

AI accelerated SOLESIDO’s code, art, tests and documentation. It also introduced false claims, accidental design choices, performance regressions, visual placeholders, stale documents and repeated damage to known-good behavior.

The project improved when the collaboration became disciplined:

• the user’s intent became explicit authority;
• logic moved into validated data;
• every system acquired invariants;
• evidence replaced confidence;
• work was divided into bounded sections;
• live playtesting complemented automated tests;
• releases were checkpointed;
• disk and session history were treated as infrastructure.

The goal is not to prevent every error. It is to make errors small, visible, reversible and educational.

Appendix A - SOLESIDO Development Timeline#

Appendix B - AI Failure and Recovery Matrix#

Appendix C - Definition of Done#

A SOLESIDO feature is done only when all applicable statements are true:

• The player-facing behavior is approved.
• Current behavior was reproduced or inspected before editing.
• The causal owner and invariants are documented.
• Gameplay values are in the authoritative rules package where appropriate.
• The source contains no second authority for the same value.
• The focused regression fails on the original defect.
• The regression and related suite pass after the change.
• A fresh world exercises the feature.
• Save/Load works during active transitions.
• The feature has correct assets, anchors and directional presentation.
• The dashboard explains failure and recovery.
• Performance is measured in a representative dense city.
• The exact Release executable is visually checked.
• The extracted ZIP is launch-tested.
• Documentation, decisions, assumptions and known issues are current.
• The last known-good package remains recoverable.

Appendix D - Compact Handoff Template#

PROJECT:
SOURCE ROOT:
ACTIVE BRANCH / COMMIT:
RULES HASH:
WORKING EXECUTABLE:
LAST KNOWN-GOOD ZIP:

COMPLETED THIS SECTION:
-

FOCUSED TESTS:
-

FULL / INTEGRATION TESTS:
-

LIVE VISUAL CHECKS:
-

OPEN BLOCKERS:
-

UNAPPROVED ASSUMPTIONS:
-

PROTECTED BEHAVIOR:
-

NEXT EXACT STEP:
-

Appendix E - Glossary#

Authoritative rule The single value or policy the runtime actually uses.

Causal integrity The guarantee that visible outcomes follow the approved chain rather than hidden grants, duplicated goods or decorative agents.

Derived state Data rebuilt from persistent records, such as route caches or render lists.

Deterministic test A test with controlled seed and inputs that produces repeatable results.

Event-driven update Work performed when state changes instead of on every frame.

Fresh-world test A test using the current New Game path and no old save.

Invariant A condition that must always be true, such as conserved goods or a worker phase matching its trip.

Known-good build A specific hashed executable and package that passed named evidence.

Live visual gate Human inspection of the real executable for presentation and usability.

Persistent agent An individual person or vehicle with identity and state that survives Save/Load.

Render owner The tile or entity responsible for drawing a multi-tile object once.

Rules hash A digest identifying the exact gameplay configuration loaded by the executable.

Vertical slice A complete narrow path from input to visible, persistent player outcome.

Closing Perspective#

SOLESIDO started with green pixels, blue rivers and an eraser. That simple childhood experiment contained the essential game long before there was C++, traffic, trade, JSON or audio: the joy of changing a living-looking world and imagining what the change meant.

AI made it possible for one creator to pursue an unusually ambitious version of that memory. The accomplishment is real. So are the difficulties.

The best outcome is not a myth that AI “made the whole game perfectly.” The honest and more useful outcome is that a determined creator learned to direct a powerful but fallible collaborator. He rejected features he did not ask for, insisted on visible residents and physical freight, caught false completion claims, supplied screenshots, demanded causal explanations, moved gameplay rules out of spaghetti-like constants, protected the original Paint idea and kept returning to one sentence:

Find the balance between nature and modern life.

For another person beginning an AI-assisted game, the advice is equally simple: begin with the part you love, write down what must remain true, make one complete loop work, preserve it, and demand proof before adding the next one.

That is how an idea survives the speed of AI.

Creator: Michal Contact: 118michal@gmail.com Prepared from the complete SOLESIDO development session, July 2026.