Dekiro: Sanctuary of Shadows · Dev Blog

Mastery Past the Cap: Ten Grandmaster Ranks, a Hidden Rank, and the Soul Jade

2026-10-19T12:00:00Z

The bosses in dungeons should also drop cores and skill books, or even better: let's add Grandmaster skill levels up to 10. With level 10 it can flip to a level above Grandmaster that is not visible in the skill overview yet. [...] Bosses should have a chance to drop an item that can be studied to eventually level up any one skill (no specific item per skill).

— the developer

Where the ladder used to end #

A skill in Dekiro has always been a single number, its rank. The first fourteen ranks come from skill points, one per character level. The fifteenth turns the skill into its Mastery version, M1, and from there only skillbooks raise it: Shadows drop them, reading one is a gamble between 70% and 35%, and the tenth successful read makes the skill Grandmaster. That is the ladder of a popular Korean MMO that this game grew out of, and until this week it ended there. A Grandmaster skill was finished.¹

The request above arrived the evening of the first playtest (post 18), as one message that started small (bosses should drop Shadow Cores and books) and grew a new layer on top of the skill ladder. The coordinator offered names for the two new things; the developer picked Peerless for the hidden rank and Soul Jade for the item, and added two rules before the agent started: "of course the item should not be dropped every time from bosses, but with a chance", and "skill books can also drop".

Ten more rungs #

Grandmaster became ten ranks, G1 to G10. Old characters needed no migration: their Grandmaster was stored as rank 25, which is now simply G1.

The scaling keeps the shape the lower ranks already had. Every rank adds 7% of the skill's base damage and 3% of its heal or buff strength. Heals and buffs grow slower on purpose: after the playtest, a permanently held Iron Skin at the old numbers would have given a Grandmaster 86% damage reduction, and ten more ranks of that would break the game rather than reward it.

Rank	Skill damage (x base)	Raised by
Lv 14	1.91	skill points
M1	1.98	the 15th point
M10	2.61	skillbooks
G1	2.68	the 10th successful read
G10	3.31	Soul Jades
Peerless	3.63	a Soul Jade at G10

So the ten new ranks are worth about as much as the ten Mastery ranks before them: a quarter more damage over many hours, not a doubling. None of the monster numbers from the balance passes (posts 15 and 22) had to move, because no character gets there before the level cap.

One jade for every skill #

The most interesting decision in the request is in its last sentence: "no specific item per skill". The skillbooks are the opposite: a book teaches one skill, and since the drop picks the skill, many books are useless to the player who finds them. The book system needs a whole support structure for that. Drops are weighted three to one toward skills you've already mastered, books of other schools can be traded or sold, and since the playtest your own grandmaster swaps a foreign book for a random one of yours, once an hour.

A Soul Jade has none of that problem. In the item's own words, it is "a sliver of the Sanctuary Stone's jade that drank a fallen master's last insight". The player decides which Grandmaster skill studies it: right-click it in the bag, press Study in the skill window, or drag the jade onto the skill. A small dialog lists every skill of the school with its rank, the chance and where it leads.

The Soul Jade

The skill window and the study dialog: Whirlwind at G5 (32% to G6), Cleave at G10 (4% to "???"), Charge at G1, and the skills that aren't Grandmaster yet greyed out

Three things come out of that choice:

Every drop is good news. A jade is never the wrong item. That makes it safe to keep it rare, because rarity only hurts when the rare thing might be useless.
The player builds the character. Push one skill to the top or spread the jades over five; both are valid, and the dialog shows what each choice costs.
One stack in the bag, not twenty-four. The study item has one icon, one tooltip, one place in the inventory, and one sell price for the players who'd rather have the gold.

The jade is also tradeable like any material. A friend who has finished their skills can hand theirs over.

The odds, and why a failure still counts #

Studying is a gamble, like reading. The chance falls from 45% at G1 to 18% at G9, and the step from G10 to Peerless is 4%. The jade is used up either way. What softens it is the bad-luck protection the books already had: every failure in a row on the same skill adds 4 points to its next chance (1 point at G10), and a success resets the streak.²

The protection matters more than the base numbers suggest. Worked out over the whole ladder:

Step	Base chance	Jades needed on average
G1 -> G2	45%	2.1
G5 -> G6	32%	2.7
G9 -> G10	18%	3.8
G1 -> G10, all nine steps		about 25
G10 -> Peerless	4%	about 10 (median 9)

On the early steps the streak bonus hardly matters: G1 to G2 would take 2.2 jades without it instead of 2.1. On the long shots it decides everything. Without it, Peerless would average 25 jades, and one player in ten would still be trying after 56. With it, the average is about 10, and the chance reaches 100% at the 97th try at the very worst. Nobody will get there, but the ceiling exists. That is what bad-luck protection is for: the lucky and the typical player barely notice it, and the unlucky tail is cut off.

This seems to break a rule from the Fullmoon post (17), "gamble on progress, never on rare rewards". It doesn't, because of what is gambled. The Shard of the Sanctuary Stone drops once at the end of the final raid and can't be gambled away. A Soul Jade is a repeatable drop from every dungeon boss past level 25. Losing one costs you a dungeon run, not the best moment of the game.

Rest for the mind #

Between two studies, the mind needs five minutes of play to rest. The study dialog counts the wait down, and the refusal says what helps: "Your mind needs rest: 4:12 (destroying Shadows clears it faster)". Each Shadow you destroy takes a minute off.

The cooldown exists so that a stack of jades isn't one click session: twenty jades saved over a week of dungeons would otherwise go in twenty seconds, failure on top of failure. Spread over play, each study is its own small moment.

Why Shadows? They are the game's core loop. The Shadow stones are what the hunting grounds are built around, they drop the skillbooks, and reading a book already requires one destroyed Shadow between two reads. The jade's rest follows the same idea: progress on your skills comes from going out and fighting, not from waiting in town. A player who hunts Shadows between dungeon runs will rarely see the cooldown at all; a player who logs in only to study waits five minutes. The timer counts play time, not wall-clock time, so logging out doesn't skip it either.

Bosses drop it, by chance #

Soul Jades come only from dungeon bosses, and never every time. The chance grows with the boss's level, so the late dungeons pay better:

Who	Soul Jade	Skillbook	Shadow Cores
A dungeon's final boss	4% + 0.18% per boss level (max 20%): about 9% at level 25, 18% at 80	35%	60%, 1-2
The same, in the Demon Tower and the Chamber of Seals	a second roll at 15%	35%	60%
A boss within a dungeon	2% + 0.12% per level (max 12%)	20%	60%
A mini-boss	1% + 0.05% per level (max 5%)	15%	30%
The First Shadow (final raid)	25%	always, 1-2	always, 3-5

Jades start at boss level 25, because nobody has a Grandmaster skill that early. Chests and Elites in the wild drop neither jades nor books: those entries are marked as boss-only in the loot tables.³

The skillbooks from bosses answer the first half of the request. Unlike a Shadow's book, a boss's book can be from any school, with your own school's skills twice as likely (on top of the three-to-one weight toward skills you've already mastered). Books from other schools aren't wasted: they can be traded, sold, or swapped at your grandmaster.

A test rolls a level 80 final boss 400 times and checks the result lands in a window: a jade now and then, never one per kill, and a skillbook more often. It rolls a chest and a wild Elite the same number of times and expects zero of either.

Peerless: the rank nobody tells you about #

The part of the request that needed the most care was "not visible in the skill overview yet". A hidden rank is easy to hide and easy to spoil. Every place in the UI that talks about the next step had to agree.

Up to G9, the tooltip shows the next rank's numbers ("At G6: Damage 485% of your attack"). At G10 it shows only this: "Next: ??? (a Soul Jade may show the way)". The study dialog says "Chance 4% -> ???". The jade's description ends with a rumour, "Some say there is a step beyond the tenth." Nothing else names it. Once one of the character's skills is Peerless, the word appears everywhere at once: the other G10 skills show "-> Peerless" and the real numbers. A test walks through exactly these states and checks every string.⁴

Before and after the first Peerless. Above, Cleave at G10 only promises "???". Below, Whirlwind has become Peerless ("without equal") and Cleave's tooltip now shows what its own Peerless would do

The name comes from the wuxia vocabulary the game's lore already uses. Peerless translates 无双, "without equal", the word for a martial artist nobody can match. The skill window gives it a line of its own, "Peerless: without equal", in jade.

A clear step, not a bigger number #

A hidden rank that feels like G11 would be a letdown. So Peerless is built to be noticed:

More damage and support: +25% of the skill's base damage and +15% of its heal or buff strength on top of the rank scaling. Against G10 that is about a tenth more damage (Whirlwind's hit goes from 1,282 to 1,406 in the screenshots).
A bigger area: every radius, length and width grows by a fifth. Whirlwind reaches 4.6 m instead of 3.8, enough to catch the stragglers at the edge of a pack.
Its own look. The effect tiers had been normal, Master and Grandmaster, with Grandmaster adding a golden second shockwave, sparks and a pillar of light. Peerless is a fourth tier: the same, a bit bigger, with a jade ring further out, jade sparks and a jade pillar, and a jade crown on buffs.

Whirlwind at G10 and at Peerless on the test map's dummies: the wider swing, the jade ring inside the gold, and the bigger numbers

A skill's data can also replace the Peerless step with something of its own (an extra hit, a longer dash), the same way skills already change shape at M1 and G1.⁵ None does yet. That's a natural next pass once players have Peerless skills and can say which ones feel flat.

How long it takes #

The balance model from post 15 got a new phase for this. Its characters still play from level 1 to 90 (now in about 21 hours, after the playtest halved the target), and then keep going: 60% of the time re-running the dungeons that still drop jades at level 90, the rest hunting Shadows. They study every jade on the highest Grandmaster skill first, so one skill goes to G10 and Peerless before the next one starts.

The first finding was that nobody reaches G1 before level 90. Skill points spread over several damage skills, and the best skill at the cap is about M5. The four jades a character finds while levelling just wait in the bag. That's deliberate: the jade ladder is the long tail after the story, not a race inside it, and it doesn't move any of the levelling numbers.

After 90, the median of 60 simulated Blade characters looks like this:

Hours after level 90	G levels gained	Skills at G10	Peerless skills	Characters with a Peerless skill
at 90	0	0	0	0%
+25 h	9	0	0	0%
+50 h	13	0	0	10%
+100 h	19	1	1	78%
+200 h	30	2	2	100%

The endgame in the model: Grandmaster levels gained over all skills (left) and the share of characters with a skill at G10 or Peerless (right), at the model's checkpoints

The median character's first skill reaches G10 about 53 hours after the cap, about 74 hours into the game in total, and its first Peerless skill arrives about 74 hours after the cap. At 200 hours there are two Peerless skills and about thirty Grandmaster levels: a long way from all six skills at the top. The ladder has no wall at any point. Every hour adds a little, and at no point does the next step need something you can't get.⁶

What we're not sure about #

The pace is a model. "0.66 jades per dungeon hour" assumes clears as fast as the bots manage. Real runs with puzzles, walking and loot breaks will be slower, and the hours above longer.
Focus versus spread. The model pushes one skill. A player who spreads jades sees more G levels and later Peerless; whether that feels better or worse is a playtest question.
The cooldown. Five minutes, a minute per Shadow, is a guess at a rhythm. If jades pile up anyway, it's in the way; if players never see it, it does nothing. Either answer is one number.
The secret. A hidden rank lasts until the first player posts about it, and this post doesn't help.

Takeaways #

Extend the ladder you have. Ten more ranks with the same per-rank scaling fit everything that was balanced before; a new system on top would have had to be balanced from scratch.
Make the rare item useful to everyone. One study item for every skill means no drop is ever wasted, so it can be rare without feeling cruel.
Cut off the bad-luck tail, keep the gamble. A few points per failure barely touch the easy steps, cut the cost of the long shot by more than half, and make the worst case finite.
Tie the pacing to the core loop. A cooldown that Shadows shorten rewards playing, not waiting.
Hide the top consistently. A secret rank only works if every tooltip, dialog and item text agrees on what it doesn't say, so a test checks all of them.

What's next #

The skills now have somewhere to go after level 90. The next question is the same one the Fullmoon weapons raised: whether a hundred hours of dungeons stay interesting, and what to add to them so they do.

The ladder lives in one pure script, scripts/skills/skill_rules.gd. Ranks 1-14 are Lv 1-14, 15-24 are M1-M10, 25-34 are now G1-G10 and 35 is the new top rank. ↩
The failure streaks are per skill and saved with the character, together with the study cooldown. A forged save file can't skip either: loading clamps the cooldown to five minutes and drops junk. ↩
data/items.json, the loot tables dungeon_boss, boss, elite and first_shadow. A material entry can scale with the victim's level (chance_per_level, max_chance), and an item id of @skillbook drops a skillbook picked for whoever made the kill. ↩
test_peerless_stays_hidden_until_reached in tests/run_tests.gd, against the skill tooltips (SkillTips) and the study dialog (SoulJadeDialog). A tooltip drawn without a character keeps the secret too. ↩
A "peerless" block in a skill's entry in data/skills.json, applied after the bigger area (SkillData.params_for_rank). The effect tier is in scripts/skills/skill_fx.gd. ↩
tools/balance/progression.py, the endgame() phase, about 0.66 jades per hour of dungeon running. The numbers are in docs/balance/model.json under skills; the design doc keeps the summary. ↩

A Dev Blog in the Game's Style

2026-10-19T12:00:00Z

Build a website for the blog articles we have in a style fitting the game

— the developer

Drafts in the repository #

These articles started as Markdown files in docs/blog/ of the game's repository, written from the git history, the docs and the code, with screenshots from the development review folders. They sat there as drafts for three days. When the human asked for a website, two constraints shaped it:

The drafts stay the source. Articles keep being added and corrected next to the code they describe. The site has to be rebuilt from them at any time, never edited by hand.
It should look like the game. The game's UI is lacquer panels, gold double frames, crimson title bars and pixel fonts. A generic blog theme would have been faster and wrong.

The result is one script, tools/blog/build_site.py, about 830 lines, and a 400-line stylesheet. It writes plain HTML and CSS with a little JavaScript into website/, and it is now online at dekiro.d12r.io.

The home page: a golden-hour screenshot of the Vale's town square in a gold frame, the seal and title in the game's pixel font, and the first windows of the article list

One script, no framework #

A static site generator would have worked. The choice of a single script came from how the rest of the project works: every generated thing (maps, dungeons, monster models, music, sound effects, the minimap pictures) is a rerunnable Python tool in tools/, whose output is never edited by hand. The blog follows the same rule. The dependencies are small and ordinary: markdown-it-py for Markdown, Pygments for code highlighting, Pillow for images, fontTools for fonts.

python tools/blog/build_site.py            # incremental, ~2 s; first run or --clean ~30 s
python tools/blog/check_site.py            # link check
python tools/blog/check_site.py --shots review/website   # + screenshots at 1440x900 and 390x844

Everything the site knows comes from files that already existed or are short:

Output	Source
Articles, their order, teasers, the 8-post route	`docs/blog/NN-*.md` and the table in `docs/blog/README.md`
Title and subtitle	the `# Title` line and the italic paragraph under it
Image captions	the Markdown alt text
About page	`tools/blog/about.md`
Address, title, tagline, author, dates, hero image	`tools/blog/site.json`
Look	`site.css` + `site.js`, the game's `assets/ui` textures and `assets/fonts`

An article that isn't in the README's table isn't published; the build warns. That makes the README the editorial switch: drafts can live in the folder until they're listed.

The build is incremental (images and fonts are only re-encoded when their source is newer) and deterministic: building twice gives byte-identical output, so the site's diff in git shows only what really changed.

The game's UI, in CSS #

The game draws its windows from 9-slice textures: small pixel-art images whose corners stay fixed while the edges and middle stretch. The window panel is a 40 x 40 pixel PNG with 14-pixel corners; the crimson title bar is 32 x 18.¹

CSS has the same idea built in: border-image. So the site doesn't imitate the game's frames; it uses the same files, copied from assets/ui, drawn at 2x with nearest-neighbour scaling:

.panel {
	border-style: solid; border-width: 28px;
	border-image: url(ui/panel.png) 14 fill / 28px round;
	image-rendering: pixelated;
}

14 fill slices the panel at 14 pixels and keeps the middle as the background; / 28px draws the corners at twice their size; round repeats the edges in whole tiles, so the gold fretwork never squashes; image-rendering: pixelated keeps the pixels square. The title bars, the tabs in the header, the jade and red buttons (with their hover and pressed states), the dividers and the tooltip frame all work the same way, from 22 textures that weigh 30 KB together. The page background is a 48-pixel tile of lacquer noise, generated deterministically by the build.

The window panel (40 x 40) and the title bar (32 x 18) from the game, at 8x with their slice lines, and the panel stretched to a window the way border-image draws it at 2x

Fonts: 2 MB down to 6 KB #

The game uses three free (OFL) pixel fonts: DotGothic16 for headings, Pixelify Sans for UI text and Silkscreen for the tiny labels. On the web, a font file is a download on every first visit, and DotGothic16 is large because it covers Japanese: its TTF is 2 MB.

The site needs only Latin and a few symbols, so the build subsets each font with fontTools to a fixed list of Unicode ranges and saves it as WOFF2:

Font	TTF	WOFF2 subset
DotGothic16	2,069 KB	6 KB
Pixelify Sans	79 KB	10 KB
Silkscreen	32 KB	8 KB

One detail sits in a code comment: Pixelify Sans has a "fi" ligature that, at blog sizes, reads like an "A". The subset keeps kerning and drops ligatures. The licences are copied next to the fonts.

Pixel fonts are made for short text. The articles are long, so the body text is set in a system serif at 19 pixels with lines of about 690 pixels; the pixel fonts are for titles, headings, navigation and labels.

An article page on a desktop: a sticky table of contents in the game's window style, the crimson title bar with the part number, and the body in a readable serif

Images: WebP with fallbacks #

The articles carry over a hundred screenshots, many of them 4K captures cut down to 1600 pixels. For each one the build writes:

a WebP at up to 1600 pixels, plus an 800-pixel WebP for phones;
a JPG or PNG fallback for browsers without WebP;
a <picture> element with srcset, loading="lazy" and the width and height set, so the page doesn't jump while images load.

Pixel art and UI shots need different treatment from photos. The build counts an image's colours on a thumbnail: few colours means pixel art, a chart or UI, which is saved lossless and scaled with nearest neighbour; everything else is lossy at quality 80. Thumbnails for the home page are 480 x 270 crops.

All formats together are 33 MB on disk, most of it images. A visitor downloads only one variant of each, and only the ones they scroll to.

A link to an article shared on Discord or a social network shows a preview image. The build draws one per article, 1200 x 630: the article's first picture, darkened towards the bottom, the game's gold double frame, the 影 seal, a crimson label with the part number, and the title in DotGothic16. The seal comes from the same file as the iOS app icon.

A generated social card for the post about HD-2D sprites: the article's first screenshot behind an ink gradient, the seal, the part label and the title in the game's heading font

The rest is the list that makes a site a site: an Atom feed with full articles, sitemap.xml, robots.txt, a 404 page, a favicon in four sizes, canonical links, .nojekyll for GitHub Pages, and a .gdignore.²

Most of the site works without knowing where it lives: every link between pages, images and styles is relative, so website/index.html opens straight from disk. Only the feed, the sitemap and the social cards need absolute addresses. When the human said "The domain will be dekiro.d12r.io", the change was one line in site.json:

"base_url": "https://dekiro.d12r.io/",

and a rebuild.

No tracking #

The footer says "No cookies, no tracking", and the build makes it true by construction: no analytics, no web fonts from a CDN, no embedded players, no external requests at all. Everything a page loads is in website/.

Checked by a robot #

check_site.py serves website/ on localhost, fetches every page and everything each page links to, and reports broken links, missing images or fonts, #anchor links to headings that don't exist, and images without alt text or size. It exits with an error if anything is broken, so it can gate a deploy.

With --shots, it also drives a headless browser (Playwright, using the Edge already installed on the machine, so no browser download) and saves screenshots at 1440 x 900 and at 390 x 844, a phone. Those screenshots were the design review. The first round found three things: the text in the crimson title bars sat on the top edge instead of the middle, an empty column next to the article title on desktop, and body text that looked huge on phones. That last one turned out to be the 2x screenshot, not the page; the phone layout got narrower window frames anyway, which left more room per line.

A Tufte-inspired layout #

Wide screens leave room beside a 690-pixel text column, and a second pass on the site uses it the way Edward Tufte's books do: side facts sit next to the line that needs them, not at the bottom of the page. All of it still comes from plain Markdown, and an article that uses none of it renders as before.

Sidenotes. Cross-references, file paths and small facts are ordinary Markdown footnotes in the drafts ([^1], with markdown-it's footnote plugin). The build turns each one into a numbered note in the margin beside its paragraph. A label starting with m- makes an unnumbered margin note instead. On narrow screens a note collapses behind its number and opens on a tap, done with a checkbox and a label, no JavaScript. The Atom feed, where there is no margin, gets them as numbered endnotes.
Margin and full-width figures. The image title picks the kind: ![caption](x.png "margin") puts a small image (an icon, a sprite, a phone screenshot) in the margin, "full" lets a panorama, a before/after pair or a chart span the text column and the margin. The srcset sizes follow, so a margin figure doesn't download its 1600-pixel version. An unknown title stops the build.
Epigraphs. A blockquote whose last line starts with an em dash becomes an epigraph with that line as its attribution. Most of the newer posts open with the developer's request that started the work.
Small-caps openings. The first few words after each section heading are set in small caps, cut at the first punctuation mark so a phrase is never split oddly.
Booktabs tables, in the spirit of the LaTeX package: a few horizontal rules instead of a grid, and columns whose cells are all numbers are right-aligned automatically.

The phone screenshot below is a margin figure: on a wide screen it sits in the margin, not in the text column.

The same article on a 390-pixel phone screen: the title window, the folded table of contents, and the body text

What it took #

The website was one request and one agent run, with one round of fixes after the screenshots, and the domain a week later. The home page's hero image and the About page's gallery are Steam store screenshots, which live in a git-ignored folder; so that the site stays rebuildable from a fresh clone, those seven shots were copied into tools/blog/media/ as JPGs (1.5 MB).

Takeaways #

Keep the drafts as the source, next to the code, and generate the site from them. Corrections stay in one place.
Reuse the game's art as-is. 9-slice textures map directly onto CSS border-image; pixel art needs image-rendering: pixelated and whole-number scales.
Subset fonts. A CJK pixel font went from 2 MB to 6 KB for Latin-only use.
Make links relative and keep the absolute address in one setting.
Check the built site, not the source, and take screenshots at phone size: that's where layouts break.

What's next #

Back to the game. The next posts return to what players will actually do in Dekiro.

The UI textures are generated too: tools/ui/gen_ui_textures.js draws every 9-slice, ornament and icon at 1x, and the game's theme sets the slice margins in code. ↩
website/ sits inside the Godot project folder. Without a .gdignore, the editor would import every website image and font as a game asset. ↩

Baking the Minimap: Top-Down Renders of the Real World

2026-10-19T12:00:00Z

The minimap (and map) do not take trees or buildings into consideration for the top down view - hard to orient with that.

— the developer

"Hard to orient with that" #

The minimap is older than most of the world. It came on day two: a corner disc and a big map on M, drawn from the map's JSON. Zones were coloured by level, the town was a stone-coloured circle, roads were lines, water was blue, and portals, NPCs, party members and nearby monsters were dots on top. It rendered on a background thread, once per map, and it was cheap.

The world it described kept growing after that. The maps became generated, 1.2 to 1.5 km across, each with one walled town of East Asian buildings,¹ forests of tens of thousands of trees, lakes, ruins, camps and landmarks. The minimap still showed a beige disc where the town was and an even green where the forest was.

In the first playtest, the human summed it up in the line at the top of this post: hard to orient.

That's the whole point of a minimap. You glance at it to find the gap in the treeline, the road out of town, the building with the smith. A map that only shows the data behind the world can't do that, because the data is "a hunting ground of level 5-9 here", not "a dense pine wood with a clearing in the middle".

The corner minimap on three maps, before (left: drawn from the map data) and after (right: the baked picture). Sanctuary Vale's town, Duskmoor's grey village grid, the Ember Wastes' ash plain

Draw it, or photograph it? #

There were two ways to fix it.

Draw more from the data. Every tree, house and road is in the map JSON, so the old renderer could paint trees as dots and buildings as rectangles. That's a lot of drawing code, and it would still be a diagram: it can't know that a forest's crowns overlap, that a roof is red, or what the Shadow Marsh's water actually looks like.

Photograph it. The game can already render each map. Put an orthographic camera straight above it, render it once, and the picture shows exactly what stands in the world, because it is the world. The cost moves from runtime to a bake step, and the picture has to be kept in sync with the map.

The second won, for a reason that runs through this project: the maps are generated by Python scripts and rebuilt often.² Anything derived from them has to be rerunnable, so the bake became a tool next to the generators, with a --stale flag for "only what changed".

Step 1: Godot renders the map from above #

tests/bake_map_images.gd is a script that starts the real game on a map, waits until the map has finished building, and takes over the camera:

An orthographic camera looks straight down, north up, at noon. No fog, no clouds, no weather, no night, no sun glint on the water.
Everything that moves is hidden: monsters, NPCs, townsfolk, animals, the caravan, loot, particles and your own character. So is the grass, which from above is just noise. What remains is the ground, flora, clutter, buildings, mountains and water.
The sea isn't drawn at all. It stays transparent, and the next step paints it flat, so the picture has a clean coastline instead of sun reflections.
The map is rendered in 1024 px tiles at 2 pixels per meter and stitched together. A 1.5 km map is about 3,000 x 3,700 pixels at this stage.

It also renders two extra passes as masks. Trees are moved to their own render layer, and so are structures: houses, halls, walls, palisades, towers, tents, bridges, ships. A structure is recognised by matching each prop's position to its entry in the map JSON, so the map code itself didn't change for the bake. The three images go to build/map_bake/:

<id>_color.png       the lit picture (alpha 0 = sea)
<id>_trees.png       alpha = tree crowns
<id>_structures.png  alpha = buildings, walls, bridges, towers, tents...
<id>_raw.json        {"map", "ppm", "size": [w, h] px, "rect": [x, z, w, h] map-local meters}

This step needs a real window. Headless Godot doesn't render (and doesn't compile shaders), so the baker opens one for each map, about 15 to 40 seconds each.

Step 2: Python makes it look like a map #

A raw top-down render is a photograph: busy, dark on the moody maps, and every tree a little cluster of leaf cards. tools/mapgen/bake_map_images.py (numpy, scipy, Pillow) turns it into something that reads at the size of a minimap and sits in the game's lacquer-and-gold UI:

Brighten dark maps. Duskmoor and the three realms are dark by design. A gamma per map lifts the land's median brightness to a fixed grey, never darker than it was.
Flatten. A 3x3 median filter removes speckle, saturation drops a little, and the colours are posterised to steps of 14 per channel. That gives the flat, few-colour look of the UI, and it keeps rare hues like a lake's blue that a palette reduction would lose.
Trees become blobs. The tree mask is cleaned up (closed, then opened) and painted in a darker green, lit from the top left with a bright rim, shaded on the bottom right, with a soft shadow. A forest reads as a forest, and a clearing as a clearing.
Roads are redrawn from the data, on top of the trees: a road under a canopy disappears in the photo, and roads are what you navigate by.
Buildings get an ink outline and a drop shadow, and their rendered roofs are made a little brighter. Bridges and piers count too, even over water.
The sea is flat, lighter in the shallows, with a pale line along the coast.
A touch of the UI's warmth over everything, so the picture doesn't look cold inside the gold frame.

The Vale's town square as rendered from above (left) and after the stylise step (right, 1 pixel per meter shown at 2x): flatter colours, roads redrawn from the map data, and every building outlined in ink with a drop shadow

The result is saved at 1 pixel per meter, at most 2048 pixels on a side. The Vale (1468 x 1856 m) fits at full resolution; five larger maps are capped at 1.1 to 1.34 meters per pixel. Each picture is imported VRAM-compressed with mipmaps, so it shrinks cleanly in the big map window. The script writes assets/maps/<id>_map.png and one index, data/map_images.json:

"sanctuary_vale": {
	"image": "res://assets/maps/sanctuary_vale_map.png",
	"rect": [-820.0, -928.0, 1468.0, 1856.0],
	"size": [1468, 1856],
	"source_md5": "1be9034db171f8dce1161926b02781f4"
}

rect is the part of the map, in map-local meters, that the picture covers. It is the land's coastline plus 40 m of sea, not the map's declared size. That distinction found a bug in the old minimap: on some maps the land sits off-centre within the declared size. The Ember Wastes' coast runs from z -1347 to 370 while its size says plus or minus 900, so the old data drawing had been cutting part of the map off.

source_md5 is the hash of the map's JSON when the picture was baked. That's what --stale compares:

python tools/mapgen/bake_map_images.py            # every world map (~4 min for all nine)
python tools/mapgen/bake_map_images.py --stale    # only maps whose JSON changed since their picture
python tools/mapgen/bake_map_images.py --restyle  # reuse the renders, rerun only step 2 (tuning the look)

--restyle made the look cheap to iterate: the expensive render runs once, and the stylise step takes seconds. A render that fails³ is retried three times, 20 seconds apart, before that map is skipped.

Step 3: the game draws it #

On the game side, a small static class reads the index:

class_name MapImage
## Baked top-down pictures of the world maps [...]. Minimap and WorldMapWindow draw it under
## their markers; a map without one (dungeons, a new map not baked yet) keeps Minimap.render's data drawing.

It holds one texture at a time, the map you're on, about 4 MB in video memory, and does the math between map-local meters and the picture's UV coordinates (to_uv, from_uv). The minimap's background() now asks MapImage first and only falls back to the old data drawing when there's no picture. A new background_rect(map) tells the corner disc and the big map which part of the world the picture covers, because it is no longer the map's declared size.

Everything drawn on top stayed as it was: the markers, the labels, the party dots, the arrow for you and the world map's fog of war over areas you haven't explored. Only the background changed.

The world map (M) of Sanctuary Vale before and after: the same markers and labels over coloured zone discs, then over the baked picture with the forest, the walled town, the roads, the lakes and the mountain border

Checking that it lines up #

A picture that is off by twenty meters is worse than no picture: you walk to the bridge on the map and find water. So the check was about alignment, not looks:

A test checks the world-to-picture math, that every picture covers its map's coast at the right aspect ratio, that dungeons, unknown maps and map instances (<dungeon>@<n>) get no picture, and that the data drawing still works as the fallback.
In the screenshots, a fake party member placed on a portal landed on the torii at the end of its road, our arrow sat on the town square, and the waystones, lakes and roads matched the old drawing.

Dungeons have no picture, on purpose. Down there the minimap shows "No map down here", and the dungeon generator's own overview images⁴ stay a development tool.

What it costs #

Repository: the nine PNG sources are about 9 MB.
Exports: each imported picture is 2.7 to 5.4 MB, about 33 MB per platform (desktop and mobile each get their own compressed copy).
Memory: one picture at a time, about 4 MB.
Upkeep: a stale picture still lines up, because the rect doesn't move. It just shows last week's trees and buildings. So the rule in the project's notes is: after any map generator or dressing change, run --stale.

All nine world maps after baking, from the grey Duskmoor and the red Hellmouth Rift to the snow of Frostpeak and the green Vale

What isn't perfect #

The dark realms (Ember Wastes, Hellmouth Rift, Shadowlands) are readable but low in contrast: their roads are faint, and the Hellmouth comes out strongly red after brightening.
The minimap uses the project's default nearest filtering. At 1 meter per pixel that looks fine standing still; if the ground shimmers while walking, the minimap's disc may need its own linear filter.
The bake is a build step, so it can be forgotten. The source_md5 makes forgetting visible, but nothing fails when a picture is stale.

Takeaways #

If the game can render it, bake it. A top-down photo of the real world beats any amount of drawing code that guesses at it.
Stylise for the UI, not for realism. Posterised colours, blob trees and outlined buildings read at minimap size; a raw render doesn't.
Redraw what you navigate by from data. Roads under trees vanish in a photo.
Store the covered rect with the picture, and hash the source, so a stale picture stays aligned and knows it's stale.
Split slow and fast steps. A --restyle that skips the render makes tuning the look a matter of seconds.

What's next #

One more tool that turns project data into something for people to look at: the website this blog lives on, generated from the Markdown in the repository and styled with the game's own UI textures.

Post 6: from an open world to torii portals, and nine maps with one town each. ↩
Every world map has its generator in tools/mapgen/maps/<id>.py plus a _dressing.py for the clutter, and the JSON it writes is never edited by hand. ↩
It happens: several agents work in the same repository at once (post 11), and the game can be briefly uncompilable while one of them is mid-edit. ↩
Post 13: the dungeon generator writes an overview PNG next to every dungeon it builds. ↩

Every Platform from One Windows PC

2026-10-19T12:00:00Z

How do I get an exported version of that game now?

— the developer

Seven presets #

Dekiro is developed on one Windows PC. The human doesn't own a Mac, a Linux desktop or a test phone farm, and the first build question, the one above, came on day two. Two weeks later the project has seven export presets in export_presets.cfg:

Preset	Output	Size (packed)
Windows (Game)	`Dekiro.exe` + `Dekiro.pck` + Steam DLLs	155 MB zip
Linux (Game)	`Dekiro.x86_64` + `.pck` + Steam `.so`	146 MB tar.gz
macOS (Game)	a universal `.app` (Intel + Apple Silicon), ad-hoc signed	178 MB zip
Android (Game)	a debug-signed arm64 APK	147 MB
iOS (Game)	an Xcode project	486 MB folder
Windows (Dedicated Server)	`DekiroServer.exe` + `.pck`
Linux (Dedicated Server)	`DekiroServer.x86_64` + `.pck`

Every one of them is a single command from a shell:

godot --headless --path . --export-release "Windows (Game)" build/game/Dekiro.exe
godot --headless --path . --export-release "Linux (Game)" build/game-linux/Dekiro.x86_64
godot --headless --path . --export-release "macOS (Game)" build/game-mac/Dekiro.zip
godot --headless --path . --export-debug   "Android (Game)" build/game-android/Dekiro.apk
godot --headless --path . --export-release "iOS (Game)" build/game-ios/Dekiro.ipa   # writes an Xcode project

The sizes tell their own story. The first Windows zip, on day two, was 38 MB. The sprite characters,¹ 177 monster models, 20 dungeons and 30 music tracks brought it to 155 MB.

Export templates, once #

Godot exports by copying a prebuilt engine binary (an export template) and appending the game's data pack. The templates weren't installed when the first build was asked for. The AI downloaded the official 4.7.2 package (1.28 GB) from Godot's GitHub releases, checked it against the published checksum, and unpacked it to %APPDATA%\Godot\export_templates\4.7.2.stable. That one package holds the templates for Windows, Linux, macOS, Android, iOS and the web, so every later platform needed no further download from Godot, only the platform's own tools.

The JSON that didn't ship #

Godot exports resources: scenes, scripts, imported textures and sounds. A plain .json file isn't a resource, so an export leaves it out unless the preset's include filter names it. Dekiro is data-driven:² skills, items, monsters, maps, quests and NPCs are all JSON. So the very first presets had:

include_filter="data/*.json,data/maps/*.json"
exclude_filter="tests/*,tools/*,docs/*"

The rule went into the project's rulebook ("add *.json to the export preset's non-resource include filter, or data/*.json won't ship") and it worked for four days. Then the sprite characters arrived, and each body's sprites came with an atlas.json: where every frame sits on the packed pages, where the feet and hands are, which frame the blow lands on. It lived in assets/sprites/, not data/. Nothing failed: no test ran an exported build, and the game code falls back to the old capsule when a sprite sheet can't be loaded, which is exactly what it should do headless. An exported build would have shown every player and NPC as a capsule.

It was caught before shipping, but only because a build request ("Get me new builds for Windows and Linux") was preceded by a check of the filters against what the game loads. The fix was one line in every preset:

include_filter="data/*.json,data/maps/*.json,assets/sprites/*.json"

and checking that the data files are inside the pack became part of every build since. The lesson is general. A fallback that keeps the game running also hides what's missing; for a build, a missing data file should be a loud error, or at least something a check looks for.

Windows #

The simplest target, and the one everything else is measured against. The export folder holds the exe, the .pck, and GodotSteam's two DLLs (the GDExtension and Valve's steam_api64.dll). Zip the folder, send it. Two notes for friends that went into the instructions:

The exe isn't code-signed, so Windows SmartScreen says "Windows protected your PC". More info, Run anyway. Signing comes with a real release.
During development the game uses Steam's test app 480,³ so Steam shows everyone as playing "Spacewar".

One practical trap: the developer plays from the unpacked build/share/Dekiro-Windows folder, and a running game locks its exe and DLLs. Later builds zip straight from the export folder instead of copying over the one in use.

Linux, checked in WSL #

A Linux build needs no Linux machine to export, but it does need one to run. WSL 2 with Ubuntu is the Linux box here, with its own Godot 4.7.2 Linux binary. Two rules came out of using it:

Never point a Linux Godot at the Windows project folder. It would rewrite .godot/, the import cache, with Linux paths. The project is copied with rsync (excluding .godot and .git) to ~/dekiro and run there.
Wrap every run in timeout. A headless server that doesn't exit blocks the session; Ubuntu 26.04's timeout needs -- before the command.

The first Linux run found a real bug that Windows never showed. The exported Linux dedicated server logged 261 errors on shutdown, all "disconnect a nonexistent connection", because the multiplayer spawner was freed before the entities it had spawned. World.shutdown now frees entities first, on every quit path. The second found another: a blocked read on stdin deadlocks process exit on Linux, so the server console got a --no-console flag for services and a watchdog. The full suite, a passworded dedicated server, Linux client bots joining it, the console commands and all three ways to stop the server were verified on Ubuntu under WSL.

The packaging detail that matters for Linux: a .tar.gz, not a zip, because tar keeps the executable flag and a friend can run ./Dekiro.x86_64 straight away.

The human's next question was whether the Linux build runs on a Steam Machine. In principle yes: SteamOS is Linux on x86-64 with an AMD GPU, and a non-Steam game can be added to the library from Desktop Mode. In practice the game was keyboard and mouse only at the time, which made gamepad support the real follow-up.

macOS: universal, ad-hoc signed, and Steam #

";Can I get a Mac OS build?" took a couple of minutes of work and one project setting. The macOS preset exports a universal app (one binary with both Intel x86_64 and Apple Silicon arm64 code). Apple Silicon's GPU reads ETC2/ASTC compressed textures, not the BC formats desktop PCs use, so the importer has to write both:

[rendering]
textures/vram_compression/import_etc2_astc=true

That reimported every texture once and adds nothing to the Windows or Linux downloads, which only ship their own format.

Signing is the Mac's real hurdle. A proper release needs an Apple Developer account for a signing certificate and notarization. Without one, the preset uses ad-hoc signing (codesign/codesign=1, notarization off): the app is signed, but by nobody Apple knows. macOS blocks it on first launch, and the instructions for testers are:

right-click the app, Open, then Open again; after that it starts normally;
if macOS says the app is "damaged", run xattr -cr on it in Terminal, which removes the quarantine flag the download added.

The first Mac build also logged one error at start: the GodotSteam plugin's config pointed at addons/godotsteam/osx/, a folder that had never been added, because Steam was set up for Windows and Linux only. The game runs fine without Steam (single player, hosting and joining by address), but Mac players would have had no Steam lobbies, invites or friends list. The human asked "What's the steam on Mac thing?", got the explanation, and answered "Yea. Fix it". The fix was the matching GodotSteam 4.23.1 release's two universal .dylib files (the extension and Valve's libsteam_api.dylib), the same version the other platforms use. The export then embedded them in the app bundle with no error.

One thing nobody can check from Windows is whether it actually works on a Mac. As of this post, nobody has reported opening it on one; the first Mac player is the test.

Android and iOS #

The phone builds have their own post (19), so briefly:

Android builds completely on Windows, given a JDK 17 (Godot 4.7 wants 17 even though newer ones exist), the Android SDK's command-line tools with platform-tools, build-tools 35 and android-35, and a debug keystore. All three were installed into the user's folder without admin rights. The same ETC2/ASTC setting covers the textures. The result is a sideloadable APK.
iOS exports an Xcode project from Windows, but building, signing and installing need Xcode on a Mac. Godot won't export without an App Store Team ID in the preset, and GodotSteam (which has no iOS library) is excluded so the app doesn't try to load it. Steam is also switched off in code on both phone platforms.

Phones exclude more than the desktop builds: addons/godotsteam/* on both, and the iOS icon art on Android. Everything else uses the same include filter, which is the point: one list of data files that must ship, repeated in seven places, and checked.

The iOS icon and launch screen, drawn by a script from the game's UI art: a crimson seal with the kanji for "shadow" on the window lacquer, and the start menu's title row

Dedicated servers #

The dedicated server is the same project exported with Godot's dedicated_server feature tag, and the game checks for it (or a --server flag) to skip the menu, read server.cfg, and run with no local player. There are Windows and Linux presets. For Linux, docs/HOSTING.md includes a systemd unit whose stop command touches a STOP file in the save folder: the server notices it within a second, saves the world and exits, which is the clean way to stop a process that may have nothing attached to stdin.

During development there's a third way that needs no export at all: tools/run_dedicated_server.bat starts the server straight from the project folder with the Godot console binary.

Testing a build you can't click through #

An export that finishes without errors says little. The checks that run after one:

Is the data in the pack? List the .pck and look for data/*.json, the maps and the sprite atlases.
Does the exported pack run the game? Release templates refuse a scene path on the command line (you can't tell Dekiro.exe to open main.tscn directly). The editor's binary can, though, and it can load any pack:
```
godot --main-pack build/game/Dekiro.pck res://scenes/main.tscn --quit-after 400
godot --main-pack build/game/Dekiro.pck res://scenes/main.tscn -- --join=127.0.0.1:24680
```
That runs exactly the exported data with the same engine version, smoke-tests a session, and with --join makes a client of the exported pack join a server. The exported exe itself only writes a log with --log-file.
Linux in WSL, headless: the real Dekiro.x86_64 starts, and the Linux pack joins a Linux server.
Mac, Android and iOS: export without errors, check the bundle's contents, and say plainly that nobody has run it yet.

A bug from the first real multiplayer session with a friend is a good reminder of where these checks stop. Joined players and their dropped loot appeared sunk into the ground on hills. The exported pack placed items correctly in single player, which pointed the search at the network code: the host stored a joined player's height as zero.⁴ No export check would have found it; only two people on two PCs did.

Shipping it #

The builds go into build/share/ as one file per platform: Dekiro-Windows.zip, Dekiro-Linux.tar.gz (executable flag intact), Dekiro-macOS.zip, Dekiro-Android.apk. When the human asked "Are the builds now containing all changes?", the answer came from facts, not memory: the working tree is clean, no game file is newer than the exported packs, and the last commit before the export is named.

Saves never live next to the game. Godot's user:// maps to %APPDATA%\Godot\app_userdata\Dekiro- Sanctuary of Shadows\ on Windows and ~/.local/share/godot/app_userdata/... on Linux, so unpacking a new build over an old one never touches a character. (The odd "Dekiro-" comes from the project name with the colon removed, which no file system accepts.)

Takeaways #

One machine can export every platform; running them is the hard part. Use what you have: WSL for Linux, --main-pack for the exported data, phone-shaped windows for the touch UI.
Non-resource files need include filters, and a graceful fallback can hide a missing one. Check the pack, not the export log.
ETC2/ASTC is one setting that Apple Silicon Macs and phones both need.
Ad-hoc signing gets a Mac build to testers without an Apple account; tell them about right-click Open and xattr -cr.
Native plugins are per platform. A GDExtension with a missing .dylib or no iOS library has to be added or excluded per preset.
Answer "is it current?" from timestamps and git, not from what you remember building.

What's next #

The builds were heading to a friend's PC and a first playtest. One of its notes was about the minimap: it didn't show what the world actually looked like. The next post is about baking it.

Post 12: every player and NPC is a stack of palette-indexed sprite sheets rendered from 3D characters, eight directions per clip. ↩
Post 2: skills, items and loot tables as data, with almost nothing hard-coded. ↩
Valve's public test app id. A game uses it until it has its own Steam app id, which comes with a store page. ↩
Post 20, on the multiplayer bugs only a friend can find, tells that story. ↩

A Tavern, Named Hens and Cats: The Small Stuff

2026-10-19T12:00:00Z

I would also like to name the chickens: Stefan, Gerrit, Mars, Daria, Gitti, Mike and Nici.

— the developer

"Everything is happening in the center" #

The living-world post¹ ended with 66 townsfolk on routines: Old Marta sweeping the square, two gossips at the well, children chasing a dog. It worked, and the first playtest found its weak spot within minutes:

Non-player-relevant NPCs should be scattered a bit out on the roads to the north, east, west and south. Right now everything is happening in the center.

True. Every town had a lively square and four empty streets leading out of it. You walked out through the gate past nobody, which is the opposite of how a town works: the square is where people meet, but the roads are where they come from.

The Vale's north gate: a guard pair now stands at every gate of every town

Out onto the roads #

One agent took every town, the Vale first, then the other five, and lightly the three gate camps. Some existing people moved out (Joss to the north gate, Brann to fish from the pond bridges, Xiao the courier to a loop through all four gates), and 88 new people moved in:

Town	Townsfolk before	After
Sanctuary Vale	17	41
Marsh Camp	8	20
Ranger Outpost	8	21
Pilgrim's Rest	8	22
Oasis Town	8	22
Pass Hut	8	19
Forge Camp, Warden's Watch, Last Lantern	3 each	4 to 5

That's 88 in the six towns, plus five at the camps: data/townsfolk.json went from 66 people to 159. Every town now has a guard pair at each gate, and one pair per town has something to say to each other. In Duskmoor:

"How many tonight?" "Twelve strokes. Then one more." "There is no thirteenth hour." "Tell that to whoever's ringing." "...Light the gate lantern. Both wicks."

In the desert, a guard has noticed that the big dune by the cairn was left of the cairn this morning and is right of it now. Nobody goes north today.

Between the gates there are carters with things to carry: Gerd pulls a cart through the Vale, Sun the Porter pushes a wheelbarrow, Dirk hauls peat in the Marsh, Torvald drags a sled of firewood through Frostpeak, and Grom brings ore to the forge camp ("Ore for Kael!"). Carts are a new routine option, a clutter model the person pulls behind or pushes ahead. They were invisible at first: the person walked along the street holding nothing, miming a cart, until a one-line fix.² There are also sweepers, travellers walking in and out, pilgrims and beggars by the gates, farmers working the field edge just outside them, recruits jogging laps, an herbalist shouting the name of a plant ("Feverfew!"), and pairs of children on the ring roads playing tag and freeze ("Freeze!" "Didn't move!").

A carter heading out of the Vale's north gate, past the guard pair

Each one has a name in the game's European and wuxia mix, a few lines when you talk to them, barks when you pass, and a look in their region's palette.³ Townsfolk animate only near the camera, so 88 more of them cost very little.

A checker that walks the routes #

A routine is a loop of stops, and a person walks in a straight line from one stop to the next. Townsfolk have no collision: they're presentation, and nothing may depend on where they stand. That makes them cheap, and it means nothing in the game stops a baker from walking through the bakery's back wall to reach the square.

tools/mapgen/town_life.py already checked that every stop stood somewhere sensible: not inside a building, a prop, clutter or water, and inside the town's sanctuary. For the roads it got stricter. It now also walks every leg of every routine in 0.75 m steps and complains if the line passes through a building, a wall, clutter with a collider, or water off a bridge, and it checks that each stop lasts long enough to cover the walk there at the person's speed:

  ! carter_gerd 3->4 walks through house at (41.2, -18.5)
  ! sweeper_bao stop 2: 12 s is too short for the 19 s walk there

Two typical complaints, made up for this post.⁴

The first run of the stricter checker over the existing routines, before any new person was added, found about 120 problems. People had been walking through walls for over a week, and nobody noticed, because on screen a person passing through a house corner for half a second looks like a person walking past it. All of them are fixed now. The generators route walks around buildings themselves through extra "walk" stops, a stop can say how long to stay instead of how long it takes in total (the walk is worked out), and the dresser keeps clutter off people's walking lines.

Two limits remain, and the agent wrote them down rather than working around them. People can't stand further out than the sanctuary's edge, so "just outside the gate" means at most about 6 m outside. And routines can't depend on the time of day yet, which matters for exactly one person, introduced below.

The Bierlinger Tribe #

The next request came in the same playtest, between a bug report and the chickens:

I would also love to have a "bar" style of house that contains NPCs of the "Bierlinger Tribe", who have the names Stefan, Sebastian, Alexander, George, Bernhard and Dominik (plus a title that fits the theme).

Buildings in Dekiro have no interiors, so a bar has to be a place where the party happens outside. The tavern is a new building type from the Blender pipeline: a two-storey izakaya with red lanterns along the eaves, a long noren curtain, stacked straw-wrapped kegs, a cedar ball over the door, a balcony and a tall sign. It replaced the first house down the Vale's east street. The beer garden in front uses two new clutter pieces, a long table with benches and a keg rack, plus banner poles and barrels. Like every building, it comes in regional variants (desert, snow, swamp, ember), for whenever another town gets thirsty.

The Bierlinger tavern on the Vale's east street, with the tribe in the beer garden

The tribe got the titles, all six distinct and all short enough for a name tag:

Name	Title
Stefan	Bierlinger Brewmaster
Sebastian	Bierlinger Hop-Sage
Alexander	Bierlinger Toastmaster
George	Bierlinger Barrel-Keeper
Bernhard	Keeper of the Tap
Dominik	Last to Leave

They share an amber trim in their outfits, and the writing stays in the game's voice: no real-world brands, and the lore leaks in. Stefan claims the tribe brewed in the Vale "since before the walls. We were here first. The walls came for the beer." Sebastian grows his hops "on the north side of the wall, where the shard's song is faint. They come up bitter and proud." George counts kegs: "Twelve. Should be thirteen. Somebody's been brave in the night." They have two timed conversations. Stefan and Sebastian argue about hops:

"It needs more hops, Stefan." "It needs fewer opinions." "A brew without bite is just wet bread." "And yours is a bite without bread. Drink." "...It is good, though." "Of course it is. I made it."

and Alexander toasts, with Bernhard keeping count:

"To the Sanctuary Stone, that keeps the night outside!" "That's your third toast to the stone." "It's a very good stone." "Then let it drink water. Here." "To water! ...No. To the tribe!"

At level 15 Stefan offers your character a cup "on the tribe, for the hero". Nobody actually gives you a drink. It's a tavern without an inside.

Dominik is the time-of-day problem. The brief said one of them should stumble home along a street at night. Routines can't depend on the clock's hour yet, so Dominik walks home on a loop, at 0.8 times normal speed, day and night, and comes back for one more. His lines cover it: "Home is up the street. The street is longer at night. I've measured."

The same tavern at night: lanterns lit, the tribe still at it

Seven hens with names #

The same message asked for the names at the top of this post: Stefan, Gerrit, Mars, Daria, Gitti, Mike and Nici, for the chickens.

Dekiro's animals are presentation like townsfolk: built from map data on every machine, run from the wall clock, no network traffic. Named animals get a name tag; the Vale already had Mochi the cat, Lady Plum, Old Bao and Tofu. So this was a list in the Vale's generator:

# The named hens (the user's): two in the town's yard behind the tea house, five at the farmstead nearest the town.
HEN_NAMES = ["Stefan", "Gerrit", "Mars", "Daria", "Gitti", "Mike", "Nici"]

Stefan and Gerrit live in a yard behind the tea house, among the market stalls. Mars, Daria, Gitti, Mike and Nici live at the farmstead nearest the town, out in the Whispering Fields.

Gerrit and Stefan in the town yard

Yes, there is now a Stefan the hen and a Stefan the Brewmaster. The name check that keeps people's names unique covers NPCs, townsfolk and companions, not animals, and the brief said the overlap was intended. The brewer knows. One of his barks:

"Someone named a hen after me. I'm honoured. I think."

Mars, Daria, Mike, Gitti and Nici at the farmstead

Petting, briefly #

The living-world post covered petting: press F next to a cat or a dog, your character kneels, a heart pops up, and you get Content, 2% movement speed for five minutes, once per animal per world day. It's the one piece of animal life the server checks, loosely, against where the animal's schedule says it should be.

Hens are not on that list, named or not. In data/animals.json, cats and dogs belong to a pettable group and hens have a scatter rule instead: run through them and they bolt 2.4 m at 3.4 m/s for about a second, with a sound, then go back to pecking. So you can visit Gitti, but you can't pet her. That's not an oversight: it's what hens do.

Still no network traffic #

All of it, 88 people, carts, two conversations at the tavern, seven hens, is computed on every machine from map data, the clock and a seeded hash. A friend joining your game sees Dominik at the same point of his walk home and Gerrit by the same stall, without a packet. The one thing that had to be fixed for that:⁵ a friend's PC clock that's a few minutes off would put Dominik somewhere else, so clients now take the server's clock when they join.

Takeaways #

Life belongs on the roads, not just the square. People coming and going between the gates make a town read as part of a world; a busy centre with empty streets reads as a stage.
Check the walks, not just the stops. The stop checker was clean; the walk checker found about 120 people passing through walls. Presentation without collision needs a tool that pretends it has some.
Write the limits down. "Can't stand more than 6 m outside the gate" and "can't depend on the hour" are now known, and Dominik's lines make the second one a joke instead of a bug.
The cheapest features carry the most personality. A list of seven names and one bark ("I'm honoured. I think.") cost minutes and give a town more character than a new building.

What's next #

The same playtest produced three dozen other notes, from potion numbers to a chat. The playtest post goes through every one of them and what it became.

"Making a Generated World Feel Lived In" (16): clutter by rules, houses, cats you can pet, and the first townsfolk. ↩
In scripts/world/ambient_npc.gd. A townsperson's cart (data/townsfolk.json) is one of cart, wheelbarrow or sled, a clutter model pulled behind or pushed ahead. ↩
From data/npc_looks.json: a seeded archetype plus a regional palette, so the same person looks the same on every machine. The HD-2D post (12) has the sprite side. ↩
The real output, python tools/mapgen/town_life.py, is one line per map, and now every one of them says "0 problems". ↩
"Multiplayer Bugs Only a Friend Can Find" has the story: WorldClock.server_skew, sent in the server's welcome message. ↩

Weather That Fights Back

2026-10-19T12:00:00Z

A map should play differently, not just look different #

By day six the game had nine world maps, each with its own monsters, music, sky and town. But a level 55 fight on Frostpeak played exactly like a level 35 fight on Duskmoor with different colours. The world plan had always listed a mechanic per map, one line each:

Duskmoor: "rituals: cult priests start rituals at circles on the moor; if not stopped in time..."
Sunscar Desert: "heat away from shade; oases reset it."
Frostpeak: "cold (standing still in the open slows you), campfires; ice patches; avalanche lines."
Hellmouth Rift: "demon portals open now and then and pour out waves until closed."
Shadowlands: "corruption that builds away from Sanctuary Shards; destroying Shadows cleanses it."

When the AI listed what was still open, "map mechanics from the world plan" was item seven of nine. The developer picked "1-7 and 9", and on the morning of day six one agent built all six in a single run.

The brief had a tone as well as a list, and it ended up written at the top of the data file where every later change will see it:

"_doc": "World-map mechanics (MapMechanics, scripts/world/mechanics/): the rules here, the placement in
each map's \"map_mechanics\" block (written by the map generators' MECHANICS blocks). Everything runs on
the server; clients get the state (telegraphs, HUD) from MapMechanics. [...] Keep it modest: flavour and
reward, not frustration."

A grind game is played for hours at a time. A mechanic that's exciting the first time and a chore the fiftieth is worse than none. So every one of these is either mild and constant, or rare and rewarding.

One node, two halves #

Every map that has mechanics gets a child node, MapMechanics, built on every machine from the map's data. The split of work follows the project's network rules:¹

The server runs everything: it steps the meters, rolls the timers, deals the damage, spawns the monsters and hands out the rewards.
Clients only show it: each part has a state() the server sends to peers on that map when it changes and every two seconds anyway, and one-off telegraphs ("a drake is about to land here") go out through broadcast() to everyone on the map.

Where things go is split the same way. The rules live in data/mechanics.json: rates, timers, damage as shares of max HP, rewards. The placement lives in each map's "map_mechanics" block: where the shade is, where the avalanche chutes run, where the ritual circles stand. That block is written by the map's generator, in a marked MECHANICS section, so regenerating a map keeps its mechanics in step with its buildings and roads.

Five of the mechanics are event-like and share a small base class, MechanicPart: a server tick, a state for clients, a way to show one-off events, lines for the quest tracker, and an optional bar on the HUD. The meters are different enough to get their own code.

Heat and Cold: one meter, two personalities #

Heat (the Sunscar Desert) and Cold (Frostpeak) are the same thing: a number from 0 to 100 on the player, Actor.exposure, that builds out in the open and falls in shelter. The rules are pure functions in Exposure, unit tested, and the two maps differ only in their data:

	Heat (Sunscar)	Cold (Frostpeak)
Builds	0.55 / s in the open, standing or moving	2 / s standing still in the open
Falls	7 / s in shade, 25 / s in water	4 / s while moving, 15 / s near warmth
Shelter	78 spots: tents, ruins, palms, oases; safe zones	57 spots: 21 roadside campfires, buildings; safe zones
Penalty starts at	60	35
At 100	x0.88 move and attack speed, 1.2% max mana lost a second	x0.8 move, x0.85 attack speed
Counter	Water Skin (120 gold): no heat for 3 minutes	keep moving

The interesting part is that they reward opposite behaviour. Heat is about where you stand: it takes about three minutes in the sun to fill, so a long fight in the open dunes slowly costs you, and a run to the nearest palm or pool fixes it. Cold is about whether you move: walking warms you, standing still in the snow chills you in under a minute, so a fight on Frostpeak pushes you to stay mobile or to fight near a campfire.

Heat in the Pale Sands: the bar under the health bar fills in the open (left) and falls in the shade of a tent at Palm Hollow, with the hint line "In the shade: cooling off" (right)

The server steps the meters once a second, and the value replicates with the player's other synced state (the network protocol version was bumped for it). The penalties are computed on every machine from the replicated number, which matters for movement: your own client moves your character, so it needs to know how slow you are without asking. Heat is reset when you change maps or die, and every safe zone counts as shelter, so no one ever respawns into a full meter.

Cold on Frostpeak: a roadside campfire warms you ("By the fire: warming up"), with an Elite snow wolf pack close by

The cold meter also turned out to be reusable. The Frost Monastery dungeon, built the same day by a different agent, switched it on inside: every brazier is a warm spot, and the watchers' sight cones make standing still a bad idea for two reasons at once.

The event mechanics #

Duskmoor: the Lightless Rite #

The moor's mechanic is a world event with a map, the same kind as the desert's sandstorm.² Every 40 to 70 minutes the server may start "The Lightless Rite": the moor's sky turns purple for six minutes, and one or two of its four ritual circles (the Ritual Circle, Nine Widows, Witch-light Hollow, the Hanging Tree) light up, each with three priests and two guards.

Kill a circle's priests before the event ends and it breaks: everyone within 55 m gets 4% of their level bar in XP, 700 gold and a roll on the Elite loot table, reserved for them. Leave it burning and a Ritual Shadow rises at the circle, and up to eight monsters within 45 m turn Elite until someone breaks it. Breaking every circle ends the event early. It's a choice the map offers rather than forces: race to the circles for a reward, or ignore them and accept a tougher moor for a while.

A circle the cult finished: the Ritual Shadow has risen in the purple light, and an acolyte nearby has turned Elite

Frostpeak: avalanches #

Nine chutes run down Frostpeak's crags, each marked by a pale strip of snow and red-tipped poles, so you can learn where they are. Every 110 to 220 seconds, but only while a player is within 70 m, one of them rumbles: a red warning strip lies along it for 3.5 seconds, then the snow comes down. Caught in it, you take 14% of your max HP, get pushed downhill and gain 25 Cold.

An avalanche chute on Frostpeak: the warning strip lies on the slope for 3.5 seconds (left), then the snow slides down it (right)

Ember Wastes: lava that moves, and drakes that dive #

Eight lava pools on the Ember Wastes have three shapes each and switch to the next one every 170 to 260 seconds. Twenty seconds before a shift, glowing cracks (a new shader) appear on the ground where the lava is about to run, players within 70 m are told, and the quest tracker counts down. The map generator keeps the ground flat and free of trees under every shape a pool can take, so the lava never flows through a tree or up a hill.

Lava shifting on the Ember Wastes: glowing cracks warn of the new flow 20 seconds ahead (left), then the lava has moved (right)

In the Lava Fields and the Caldera, Fire Drakes also dive at players every 35 to 60 seconds: a 2.4 second red circle with the drake's shadow sweeping in, then a fiery impact for 10% of max HP and a knockback. Nothing kills you on its own; it keeps you looking at the ground.

Hellmouth Rift: demon portals #

The rift's mechanic is the one players act on most. Nine spots across its three hunting bands can open a demon portal, at most two at a time: the first 40 to 90 seconds after players arrive, then every 150 to 300 seconds, announced on the map. While a player is within 90 m, an open portal sends out a wave of its zone's own monster packs every 22 seconds, with at most eight alive.

You close it by standing in it for eight seconds without being hit. Any damage interrupts the channel, so it's a team play (someone holds the monsters off, someone channels) or a solo puzzle (clear the wave, then channel in the gap). Everyone within 30 m shares the reward: 5% of the level bar, 1,500 gold, and an Elite loot roll each. A portal nobody closes collapses after twelve minutes, with nothing.

Closing a demon portal on the Hellmouth Rift: the channel bar ("Sealing the demon portal") fills while you stand in it unhurt

Shadowlands: the shade #

The last map is the prison of the First Shadow, and its mechanic is the one the final raid already had: corruption, the Shade bar. Out in the open it builds at 0.35 a second (about five minutes to full). Near a Sanctuary Shard (18 new jade shards along the roads, plus the safe zones and the waystones) it falls at 12 a second, and breaking a Shadow stone takes 45 off everyone within 35 m. A Fullmoon weapon in hand halves the build-up, which makes the endgame weapon do something the stat sheet doesn't show.³

The damage is gentle on purpose: up to 1.2% of max HP a second while the bar is high, a 12% burst when it fills, then it settles back to 65. Rather than copy the Citadel boss's logic, the agent moved it into one shared function in Corruption and made the boss call it, so the map and the raid can't drift apart.

The Shadowlands' shade: the bar fills out in the open ("The shade grows: break Shadows or find a Sanctuary Shard", left) and lifts in a shard's light (right)

The ground isn't flat #

The most useful finding of the run was a side note in the agent's report:

Existing skill effects (SkillFx) are drawn at a fixed y=0.06, so on hilly maps the terrain hides them. I added telegraphs that follow the ground. Boss warnings and skill effects on the overworld probably have the same problem; that is outside this task.

The game's combat is 2D: everything happens on the X/Z plane, and characters snap to the terrain's height after they move. Skill effects and boss warnings had been designed in flat dungeons and on the flat test map, so they were flat quads at a fixed height just above zero. On a map with terrain, a 3.5 m avalanche warning on a slope would be partly underground, and a drake's circle on a hillside would show as a sliver. For a telegraph that's the worst possible bug: the warning exists, the player just can't see it.

So MechanicPart got its own ground shapes. ground_disc() builds a disc as rings of triangles (one ring every 1.5 m, 32 segments), and ground_strip() a strip as a grid of about 2 m cells. Every vertex samples the map's height and sits 14 cm above it:

var at := func(r: float, a: float) -> Vector3:
	var p := center + Vector3(cos(a), 0.0, sin(a)) * r
	return Vector3(p.x, map().height_at_local(p) + lift, p.z)

The mesh drapes over the hill like a cloth. It costs a few hundred triangles per telegraph, built once when the warning appears, which is nothing next to what's on screen. Every map mechanic's warning (the avalanche strip, the drake circle, the ritual ring, the portal's channel ring) uses these.

The note about skill effects was correct, and it came back eight days later from the other direction. In the first playtest⁴ the developer reported:

Skills in the city seem to be "under" the texture of the street.

Town streets and paved squares lie slightly above the terrain, and the skill effects, still at their fixed height, vanished underneath. The fix took the same idea further: ground effects now take their height from the terrain under them and lean with the slope over their size (a big glyph tilts with the hill instead of cutting into it), and enemy and boss warnings got the same treatment. The flaw had been written down the first time it was seen; it only became urgent when a human tripped over it.

Testing weather #

Headless unit tests cover the rules: the exposure math, the corruption steps, ritual outcomes, portal channelling, lava shape schedules, about 150 checks in ten tests. But "is the warning visible on the slope?" is a question for a picture, so there's a scenario, tests/scenario_mechanics.gd, that visits each mechanic on its real map, forces it to happen in front of the camera, and saves a screenshot: heat in the sun and in the shade, cold in the open and at a fire, the avalanche warning and the slide, lava cracks before and after a shift, a drake dive, a portal open and channelling, a ritual burning and risen, the shade in the open and by a shard. Every image in this post comes from one run of it.

What none of these tests can answer is whether the numbers are right. Is three minutes the right time for the sun to get to you? Is eight seconds of channelling tense or tedious? Does a 14% avalanche every few minutes add to a hunt or interrupt it? The agent's report ended where all of these reports end: "All rates, penalties and timings are first guesses and need a playtest." They're one data file, so changing them is cheap; knowing what to change needs players.

Takeaways #

Give each map a verb, not just a palette. Seek shade, keep moving, break the circles, close the portal, find the shards: each map asks something different of the same combat.
Mild and constant, or rare and rewarding. A grind game is played for hours; nothing here kills you on its own, and the risky ones pay.
Rules in one data file, placement in the map generator. A map rebuild keeps its mechanics in the right places, and a balance change never touches code.
The server decides, clients draw. One node built on every machine, state on change, one-off events by broadcast, and penalties computed from replicated values where movement needs them.
A telegraph you can't see is worse than none. Drape warnings over the terrain; and when an agent writes "probably the same problem elsewhere" in a report, put it on the list.

The multiplayer post explains the server-authoritative model and the "single player is a local server" rule this relies on. ↩
The desert post (21) explains how world events grew a "map", a "look" and an "aftermath" for the sandstorm. ↩
The Fullmoon weapons post (17) is about those weapons and their upgrade track. ↩
The first-playtest post (18) has a before-and-after picture of the street fix. ↩

Bots That Play for Balance

2026-10-19T12:00:00Z

Would you want to do a balancing exercise first before I playtest?

— the developer

Why a simulation, and why bots #

By day six the game had 177 monster types, 20 dungeons with their bosses, four schools of six skills each, and gear from level 1 to 90. Every number had been picked when its feature was built, by whoever built it. Nobody had ever checked whether a level 44 Blade in level 44 gear kills a level 44 boss in one minute or in one second.

The balancing pass had two halves, run by two agents in parallel. One was a Python model of a whole career: how many hours to level 90, where the gold goes, when gear arrives.¹ This post is about the other half, the one that answers a narrower question with much more fidelity: what actually happens in a fight?

A spreadsheet can multiply attack by skill coefficients. It can't tell you that a boss's slam is undodgeable when three of its adds are body-blocking you, that a mirror boss copying your skills one-shots your whole party, or that a warded goblin king makes players hit an invulnerable target for four minutes. Those come from the game's own code: its AI, its telegraphs, its dungeon scripts. So the simulation runs the game itself.

The rule that made it cheap #

tests/sim_combat.gd is a SceneTree script of about 1,000 lines. It builds the real World, real Actors, real dungeon instances with their beams and wards and phases, and runs them headless with --fixed-fps 30, as fast as the CPU allows: about 70 times real time.

The bots needed almost no new game code because of an architecture rule from day one: controllers drive actors only through command_* methods. The player's controller, the monster AI, the companions' AI and network input all go through the same small interface (command_move, command_attack, command_use_skill, command_use_potion, command_sprint). A bot is just one more controller. It can't cheat, because there's nothing to cheat with: it moves at the speed the actor moves, swings at the speed the combo allows, and casts only what's off cooldown and affordable.

The one change to the game was a hook. Telegraphs (the red circles and strips that warn of a boss's slam or an archer's shot) are drawn by SkillFx, which had no reason to tell anyone they exist. Now it has a static Callable, SkillFx.warning_watch, which is empty in the game and set by the sim. Every warning the player could see, the bots see too: a circle or a line, where, and when it goes off.

What the bots read: the Sunken Pharaoh's sun lance (the red strip) about to fire along the floor, and a lit light beam across it. The bots get the same warning a player sees, and step out after 0.3 seconds

A bot that plays like a careful player #

Each bot is built for one school and one level, the way a reasonable player would have it:

Gear: for every slot, the best normal (not rare) item up to its level, Common rarity, upgraded +0 to +6 by level (one step per ten levels). School weapon from level 5.
Attributes: all points spent by a school's weights, e.g. Blade 50% STR, 30% VIT, 20% DEX; Sanctum 60% INT. Capped at 90 per attribute like the game.
Skills: one point in each skill, then the four damage skills in turn to Master; from level 47 one more Mastery rank every seven levels, as if books dropped.
Potions: below 50% HP it drinks the potion tier the game drops at its level; mana below 30%.

In a fight, the bot thinks four times a second. It picks a target (a Shadow stone or a boss is its focus, because area skills catch the adds around it anyway), casts the first skill that would hit (heals below 55% HP, buffs when a fight is close), and otherwise walks into range and swings its combo.

And it dodges. Every physics frame it asks the Danger tracker which warnings cover its position and go off within 2.5 seconds, but only those it has seen for at least 0.3 seconds: a human's reaction time. If there's one, it searches rings of 16 points at 1.5 to 13 m around itself for the closest spot that is safe, on the floor, and not in a lit beam, and sprints there. What still hits it is, by construction, what a careful player couldn't avoid either.

A few lines decide which target to hit, and one of them is an admission:

# a warded boss (Gorrak's shamans: a big "defense" buff) can wait: its guards first, like a player would
if _valid(focus) and _hittable(focus as Actor) and not ((focus as Actor).buff_total("defense") >= 0.5 and best != null):

The first runs had the bots beating on Gorrak the Goblin King for 150 to 230 seconds while his shamans kept his ward up. Nothing was wrong with the data; the bots simply didn't know to kill the shamans first. They had to be told, which raised the real question for the playtest: will players see it? He does shout "Shamans! Shield your king!" when the ward goes up; whether that's enough is on the playtest list.

Three configurations, four suites #

The sim runs any of four suites, each over any subset of schools and configurations:

Suite	What fights	Configurations
`zones`	every hunting zone at its middle level: each pack group, one Elite of each monster type, the zone's Shadow	solo, per school
`bosses`	every boss, mini-boss and rare boss at its level, in its own room of a fresh dungeon instance	solo per school, Blade + 2 companions, a party of the four schools
`rooms`	every dungeon's trash rooms	solo Blade, party of four
`curve`	a reference swing at every level	(the yardstick for the HP targets below)

The zone suite takes about a minute, the boss suite about twelve. A dead bot comes back after 15 seconds (respawn plus the walk back), and the death is counted.

The brief asked for "solo with three companions"; the game caps a party at two, so the sim used two and said so. That kind of small, explicit correction turned out to be a pattern in this pass.

Every fight produces a row: time to kill, damage taken as a share of max HP, potions, deaths, the biggest single hit, and what dealt the damage. Damage is matched to the telegraph that went off ("crypt_lord: slam"), or labelled melee or "environment" (beams, traps, lava). tools/balance/sim_report.py turns the JSON into the markdown tables of docs/BALANCE_COMBAT.md: per band, per school, per zone, per boss, and the top damage sources for every boss.

What it found #

The headline was that the game was too easy in a way no single fight shows. Player power grows about 45 times from level 1 to 90 (attack, weapon times upgrade, STR, skill ranks times Mastery), monster HP only about 20 times, and the last map's monsters still had early-game stat lines. Packs died to the opening skill burst in about a second. Article 15 has that story; here's the shape of it in the sim's numbers.

Medians over the four schools by level band, before (orange) and after (blue) the combat pass: seconds to kill a pack from aggro, seconds to break a Shadow stone solo, and basic hits per monster. The green bands are the brief's targets

Some findings only a fight could produce:

Your Shadow (a level 85 boss that copies your skills and swing speed) had a damage multiplier of 0.6 of yours. Against a party of four that meant four copies of each school's burst at once: it one-shot the party, and the party killed it in 0.4 seconds. It now has 600 times your HP and 0.07 of your damage.
Ranged telegraphs too short to dodge in a crowd: some shots warned for 0.5 seconds, some bursts for 1.0 with a 3 m radius, and with wave monsters body-blocking, about half the bots' dodges failed. Shots now warn at least 0.65 s, bursts at least 1.1 s with a radius of at most 2.6 m, and a test (test_ranged_telegraphs_can_be_dodged) checks every ranged monster's data against those floors.
Iron Fist was 1.5 times slower than the other schools: weaker fist weapons, two of six skills defensive, no damage buff. Four skill multipliers more than doubled and Iron Skin gained a damage bonus. Packs are now 0.92 to 1.15 times the mean for every school up to level 60.
Companions had no gear. In boss fights they died every 20 to 60 seconds and got back up eight seconds later. A follow-up gave them their level's armor; companion deaths per boss dropped to 0 to 2, and in the final raid from 70 to 3.
Flat potions: with one 250 HP potion for everything past level 15, every Shadow from level 50 on killed a careful bot about once. That one went to the economy agent, who made four potion tiers.

The boss numbers were the most dramatic. Bosses were sized with a target in mind (about a minute for a party of four, about two minutes solo with two companions) and the sim measured the fit:

Party-of-four kill times for every dungeon boss, before and after, on a log scale. The final raid's target was four to six minutes. The Crypt Lord's "before" had no party run

The "what hurt" table was the other surprise. For almost every boss, 60 to 97% of the damage a solo bot took came from plain melee, and the telegraphed slams were 2 to 13%. That's what dodging bots should produce: the big hits are avoidable, the steady ones aren't. The biggest single hit on any bot after the pass was 5 to 15% of max HP (before: up to 82%, on unarmored companions). No unavoidable one-shots.

It also confirmed a design choice from the desert²: on the empty dunes, an Elite King Scorpion takes a level 42 Blade 53 basic hits, against 14 for the same monster on the islands.

The targets that had to move #

The brief had numbers: a normal monster dies in 2 to 4 hits, a pack in 8 to 15 seconds, Shadows in 30 to 60 seconds solo. The sim showed that the first two can't both hold once skills scale. At level 40, a Blade's first second (Cleave, Whirlwind, Earthsplitter, Blade Storm) is worth about 14 basic hits on everything in range. If a monster dies in four basic hits, the pack is gone before the second skill lands.

So the agent kept the pack time and the time to kill a lone monster (about 2 to 3 seconds), and let basic hits per monster grow with level: 4 at the start, then 7, 9, 11. Monster HP was rebuilt from that rule, using the curve suite as the yardstick: HP equals the target number of hits times the average combo hit of the physical schools at that level. Damage became "5% of the player's max HP after armor per hit for the zone's typical monster", easing to 4% at level 90.

Two other targets turned out not to be measurable: "a dungeon run of 15 to 30 minutes" is mostly puzzles and walking, which bots can't do (they walk in straight lines, so rooms behind a maze, a rail line or deep water end "stuck"). The sim reports fighting time only (2 to 5 minutes with companions) and says the rest needs a stopwatch.

The sim as a measuring stick #

Once the combat numbers settled, the sim became the reference for the career model. The model had been estimating solo boss fights at 12 to 40 minutes; the sim said 3 to 4. A calibration factor (solo Blade kills take about 0.87 times the model's HP-over-DPS estimate) replaced the model's guess, dungeons dropped from 8.3 to 5.9 of the 40 hours, and the XP data was refit around the result. That's the order that worked: the fight first, measured; the career built on top.

Playtest 1: half the hours, and feeling powerful #

About a week later the developer played the game for the first time, at length, and came back with a long list.³ Two items rewrote the balance:

EXP progression can feel a bit faster. Let's scale to 20 hours.

I don't feel so powerful, especially on the lower levels. Can you adjust the health slightly?

The first went to the career model: its fit mode searched for an XP curve exponent and quest XP that hit a target of half the hours at every level. The XP bar dropped from 80 x level^2.58 to 80 x level^2.37 (about 250,000 XP at level 30 instead of 520,000), quest XP followed the bar, and drop rates for the rare things (Fullmoon weapons, Sunstone, key fragments) doubled so that the shorter career still finds them. Out-of-combat regeneration (back to full in about 25 seconds) and stronger potions came from the same list.

Hours to reach each level after playtest 1: the median of 60 simulated characters (blue, with the spread) against the 20-hour target points (green). It lands at 20.7 hours

The second item was ambiguous, and the AI said so. "Health" could mean the player's or the monsters'. It took it to mean the monsters' (the combat pass had raised low-level monster HP 2.7 times, so you needed noticeably more hits than in the version the developer remembered), acted on that, and added: "If you meant your own character's health, tell me and I'll raise that too."

The change is one new key in monsters.json: a monster HP factor by level, applied on top of the normal scaling. Points [15, 0.65], [30, 0.85], [40, 1.0]: 35% less HP up to level 15, tapering to none from 40. It applies to packs, Elites and Shadows. The sim then reran the zones, before and after:

The new HP factor by level (left), and what the sim measured: basic hits for a Blade to kill a typical pack monster, before and after (right)

Level	Pack kill time	Shadow, solo
3	3.0 s -> 2.1 s	47 s -> 31 s
12	2.6 s -> 1.7 s	30 s -> 19 s
20	2.7 s -> 2.0 s
24		34 s -> 26 s
28	4.7 s -> 3.1 s

Two details show why the sim matters even for a one-line change:

Bosses are exempt ("hp_by_level_bosses": false). With the factor on bosses too, the sim had the Crypt Lord, the Leech Matriarch and Old Mother Gloam, the first three dungeon bosses, falling in 38 to 43 seconds with two companions. They'd have melted. Without it they stay around a minute.
XP doesn't move. Monster XP is tied to base HP ("XP follows HP" was a rule of the first pass), and the factor sits on top of it, so lighter monsters die faster but pay the same. That's exactly the "powerful" feeling: more kills per minute at the same reward, and the 20-hour timeline unchanged.

What bots can't tell you #

The sim's report ends with a list of things it can't know, and they're worth repeating:

It's a careful player. Perfect potion timing, 0.3 second reactions, no greed. Real players take more from telegraphs and less from standing in crowds. Nobody simulated kiting or pulling three packs at once.
It walks in straight lines. Mazes, minecart rails and deep water stop it; dungeon run times are fighting only.
It has no opinion. Whether 9 to 11 basic hits on a monster feels spongy while your skills are on cooldown, whether a two-minute boss with companions is fun, whether a 45-second Shadow is 45 seconds well spent: those went on a "needs a human" list, and the first item to come back from the human was exactly that kind of thing.

Takeaways #

Run the real code. A bot driving the same command_* interface as the player found the one-shots, the undodgeable shots and the warded king that no spreadsheet would.
Give the bots human limits. A reaction time and a "seen the warning" rule turn "damage taken" into "damage a careful player can't avoid", which is the number you actually want.
Attribute every point of damage. "60 to 97% plain melee" tells you more about a boss than its total.
Let targets fail in the open. "2 to 4 hits" and "8 to 15 s a pack" couldn't both hold; the sim said so and the brief changed.
Measure the fight, then model the career. The sim calibrated the career model, not the other way round.
A playtest beats both. One sentence ("I don't feel so powerful") changed the low levels more than a day of simulation, and the sim's job became checking that the fix didn't break the bosses.

What's next #

The bots dodge telegraphs on flat dungeon floors. Out in the world, some telegraphs belong to the weather itself, and the ground isn't flat. That's the next post.

The balancing post (15) covers that model, the 40-hour target and the economy fixes in depth. This post stays with the combat side. ↩
The desert post (21) explains the "less but stronger" wanderers. ↩
The first-playtest post (18) covers the rest of that list. ↩

Making an Empty Desert Worth Crossing

2026-10-19T12:00:00Z

The desert I feel like should be larger and feel somewhat empty. What are rewards we can have there to still make it valuable for players to go there? Even though it should feel somewhat empty?

— the developer

The problem with empty #

Sunscar Desert is the level 40 to 50 map, the fifth of nine. On day five it was about 1.3 by 1.2 km of walkable sand with roughly 1,100 monster packs spread evenly, about 35 m apart, the same density as every other map. It played like a hunting ground that happened to be yellow.

A desert should feel like a desert: wide, quiet, a little hostile. But in a grind game, empty space is dead time. Every minute spent walking across dunes is a minute not spent killing things, and players notice. So the question had two halves: make it emptier, and give people a reason to cross the emptiness anyway.

Seven ideas, six kept #

The AI's answer started with the layout: grow the map to about 2 by 2 km, keep roughly the same number of monsters, and gather them into "islands of life" (oases, canyons, ruins, a raider camp) with nearly empty dunes in between. Then it listed seven rewards that fit an empty map:

Buried treasure: glinting sand mounds you dig up with a Shovel, plus Treasure Maps dropped by raiders that mark one dig spot on your world map.
A Sandstorm world event: low visibility, storm elementals, and half-buried chests uncovered when it passes.
A desert-only material needed for the top upgrade steps.
A wandering caravan merchant on a schedule, selling things nobody else sells.
Rare desert bosses with long respawns.
Key fragments for the Sun Tomb, a dungeon already in the world plan.
Lore tablets at hidden landmarks, with a small permanent bonus for reading all of them, in the spirit of the biologist quests in a popular Korean MMO.

The AI recommended building the shovel first, because it "makes the empty sand the reward itself". The developer disagreed:

I do like 2-7. Not so much of a fan of the shovel thing, to be honest. Let's go.

That was the whole design meeting. The shovel was dropped entirely (no item, no dig spots, no treasure maps), and four agents started on the other six in parallel: one for the map, one for the storm, Sunstone and bosses, one for the caravan and tablets, one for the Sun Tomb.¹

A minute later, a follow-up on monster count:

I guess a few less would also make sense. Maybe less but stronger? Not sure. What do you think?

The AI's answer was a split rather than a yes. In a grind game, levels 40 to 50 run on kills per hour; if every monster gets tougher, the whole map is just slower. So the islands keep the normal density and strength (they're the grinding spots), and the dunes get only a few wanderers that are much stronger and pay much better. About 30% fewer packs overall, nearly all of the cut taken out of the empty sand.

The map: islands and dunes #

The map generator² lays the desert out inside a ring of sandstone mesas. Oasis Town sits in the south; levels rise to the north. The numbers on the current map:

	Area	Packs	Shadows	Spacing
9 islands (oases, ruins, canyons, camp, glass dunes, temple, crater)	0.93 km²	758	66	~35 m
3 dune bands (Pale Sands, Red Dunes, Deep Dunes)	2.76 km²	25	6	~330 m

Three quarters of the land holds 3% of the packs. That's the emptiness, by construction.

The Sunscar Desert's top-down overview before (left, about 1.3 x 1.2 km) and after (right, about 2 x 2 km). Each picture is fitted to its frame, so the new map is drawn at a smaller scale: the town in the south is the same size in both

The dune packs use three keys the storm agent added to the pack data for exactly this: "elite": true makes a group spawn as Elites, "level_bonus" lifts it a few levels above the zone, and "loot" swaps in a different drop table. A dune wanderer is either a lone Elite (weight 3) or a pair three levels above the zone (weight 2), both on the desert_wanderer table.

One more knob turned out to matter. The game spawns roaming packs near players every 15 to 25 seconds, up to three around each of them, so that a cleared area doesn't stay dead. On the dunes that would have quietly refilled the emptiness. The map agent added a per-zone "roam_chance", and the dunes use 0.12: about one roaming pack for every eight elsewhere.

How much stronger are the wanderers? The combat simulation (the next post) measured it: a Blade at level 42 needs about 14 basic hits for a King Scorpion on the islands, and 53 for the Elite version out on the Pale Sands. That's "less but stronger", in numbers.

Sunstone: the reason to come back #

Rewards for a visit are nice; a reason to come back is better. Upgrades already had a currency (Shadow Shards), and the top three blacksmith steps are where a game in the style of that MMO gets its long tail. So the desert got its own material, Sunstone ("glass the Sun King's mirror-light fused out of the desert"), and the steps +6 to +7, +7 to +8 and +8 to +9 need 1, 2 and 3 of it. The Fullmoon weapons' own track needs more.³

Where it comes from, today:

Source	Sunstone	Sun Tomb Key Fragment
Island monsters	6%	0.8%
Dune wanderers	30%	2.4%
Desert Elites	60%, 1-2	8%
Storm Cache	60%, 1-2	24%
Rare bosses	always, 3-6	40%
The caravan	6,000 gold, 2 per stop	30,000 gold, 1 per stop
Level 55+ Shadows anywhere	30%	-

The last row came later. The balance model noticed that the level-gap rule (monsters seven or more levels below you stop dropping things) cut characters past level 57 off from the desert's Sunstone, and weapons stalled at +6 or +7. The developer's call was that it "should also drop from Shadows after 55+". Those rates were doubled again when the game was retuned from 40 to 20 hours, so the desert band still yields about ten Sunstone an hour.

The Sandstorm #

World events already existed: a server picks one every 40 to 70 minutes (Shadow Surge, Harvest Moon, Gilded Night). The Sandstorm is the first one tied to a single map, and the event system grew a few keys for it, all data in events.json:

"map": it only happens on the Sunscar Desert, but the start is announced to everyone, so players on other maps can decide to travel there.
"look": for its 12 minutes, the map's sky, fog and weather are overlaid with ochre fog, wind-blown grit at eye height and big soft dust veils. The overlay fades in over five seconds, and the veils fade out near the camera so your own character stays readable.
"roamers": Storm Elementals (a sandy figure on a spinning funnel of sand bands) rise out of the ground 12 to 18 m from a player every 12 to 22 seconds, one to three at a time, at most six around each player. They vanish when the storm ends.
"aftermath": when it passes, 6 to 10 Storm Caches appear at random spots from a list of 34 candidates spread over the map, mostly out in the dunes, for 10 minutes.

A sandstorm in the Red Dunes: the ochre overlay, grit in the air, a Storm Elemental and scorpions. The quest tracker counts the storm down

The caches are the payoff, and one choice there is worth explaining. The storm agent made each cache openable once per player, not first-come: "Friends who ride out the storm together each get their own share instead of racing each other to the chest. The 10-minute clock and the spread-out spots are still the challenge." The server checks that you're standing at it and rolls the storm_cache table for you alone: gold (a base of 900, times 0.8 to 1.6), gear at a 60% chance with much better rarity odds than monsters, and the materials in the table above.

A Storm Cache after the storm: a half-buried chest with a light beam (left) and opened (right). Each player opens it once

The storm also changes how the empty dunes feel. For 12 minutes they're the most dangerous place on the map, and then for 10 minutes they're the most valuable.

Two rare bosses #

RareSpawns is a small server-only node: for each entry in a map's "rare_spawns", at most one boss is alive, roaming its area instead of pacing a lair, and the next one comes respawn_minutes after it dies. Everyone on the map hears when one appears. The desert has two:

The Sand Wyrm (level 50) roams 190 m around the Bones of the Sand Wyrm and respawns after 45 minutes. It burrows: it goes under the sand where nothing can hit it, chases its target as a moving mound at 1.7 times its speed, and comes up under it after a 1.3 second telegraph.
The Raider Warlord (level 48) holds the raider camp, respawns after 30 minutes, and calls three raiders at 95%, 60% and 30% of his health.

The Sand Wyrm under the sand, a mound in the ground (left), and surfaced (right)

They're tuned like mini-bosses (about a minute and a half solo, under 25 seconds for a party of four), and their table is the best outside a dungeon: three gear rolls at Rare or better, 3 to 6 Sunstone, Shadow Shards and Cores, a 40% key fragment, and a 3% chance at each of the four Fullmoon weapons. Timers live only for the server session, so a restart spawns both fresh.

A caravan that needs no network #

The caravan was the most interesting one to build, because of a rule the project already had: townsfolk are presentation, built on every machine from map data and moved by the wall clock, with no spawn and no sync.⁴ A merchant who walks a 2.9 km loop with two camels and two guards could work the same way.

CaravanRoute is a pure timetable. The map gives it a looped road (22 points) and which points are stops (five: Oasis Town, Palm Hollow, Mirage Springs, The Last Well, The Oasis Ruins). It walks at 2.2 m/s and halts 240 seconds at each stop. From those numbers it computes, for any clock time, where the caravan is and what it's doing:

## A wandering caravan's timetable (map data "caravan": {route: [[x, z], ...], stops: [route indices],
## speed?, halt?, offset?, npc?}): a looped road it walks at `speed`, halting `halt` seconds at each
## stop. Pure: where it is follows from a clock time alone (AmbientNpc.clock(): the wall clock), so
## every machine (server, clients, the world map) agrees without any network traffic.

On the desert that makes a 42-minute loop: 22 minutes of walking, 20 of trading. Every client computes the same position from the same clock, the server's copy stands exactly where the clients see it, and the world map can draw the caravan's live position with no extra message.

Zarah, the Thousand-Li Merchant, leaving Oasis Town with her camels and guards. The banner appears when the caravan comes within 60 m

The caravan agent made one design call of its own: it trades only while halted. "This makes the stops places worth knowing, and a moving merchant would otherwise walk out of range and close its own shop window." Talk to Zarah on the road and she tells you where she camps next and in how many minutes. A banner says "A caravan is near" within 60 m, the world map always shows the road as a dotted line, and it shows her live position if you've seen her in the last 15 minutes.

Her shop sells things no town does: the rare Green and Purple potions, the Scroll of Renewal, two pieces of desert gear (Sandstriders, shoes with 7% move speed; the Oasis Charm), and the two items that make the trip worth timing: Sunstone and a Sun Tomb Key Fragment. Those carry a "limit": two Sunstone and one fragment per character per halt, counted on the server. Five stops per loop means the caravan is a steady but slow source, never a replacement for hunting.

The caravan's shop window, with the per-stop limits on Sunstone and the key fragment

Lore tablets #

Eight tablets stand at the desert's remote landmarks: the Sand Ship, the Sunken Colossus, the Buried Gate, the Lone Obelisk and the rest. Each tells part of the Sun King's story, and they're numbered I to VIII, but placed so that reading them in order means crossing the whole map. Press F at one and its text opens with "Lore 3 / 8". The server records the read only if you're actually standing at that tablet.

Reading all eight gives a permanent bonus that counts like gear you can't take off: 3% move speed and 150 max HP for the desert. Small on purpose, like the classic's biologist rewards. The system was built for the desert and has since spread to every map, 58 tablets in all, each map telling one chapter.⁵

The Sun Tomb #

The last piece turns the desert's drops into a destination. Three Sun Tomb Key Fragments combine (right-click in the bag) into a Sun Tomb Key, and the key opens a portal at the Temple of the Sun, in the level 46 to 50 north. Entering uses one key; your party follows you in for free.

Inside is an instanced dungeon for levels 46 to 52 built around the Sun King's mirrors: light beams. The developer's first question after seeing the screenshots was "What are the light beams?", and the answer is the dungeon in one sentence. Fixed, sweeping, rotating and pulsing bands of light cross the halls, each with a red-orange warning strip before it lights. A lit beam burns players for a share of their max HP, then leaves them alone for 0.8 seconds so it never wipes anyone in one frame.

The beams also solve the tomb's monsters. Mummies are "undying": killing one only knocks it down, and it stands up seven seconds later at 60% HP, unless a beam touches it, or it dies within four seconds of being touched. So you fight next to the light and use the hazard against them. Pressure plates hold doors open while someone stands on them and for a few seconds after (six in one room, nine in another): a party just stands on both, a solo player runs between them. At the end, the Sunken Pharaoh lights extra beams and raises mummies at 70% and 40% of his health.

The Hall of Rays on day five: a sweeping beam crosses the hall, with a scarab and mummies. The walls were 3.2 m then; they are 6 m now, with a cutaway near the camera

The developer's other reaction to these screenshots was about the walls: "The walls of the dungeons need to be higher. Otherwise people will just look over." They had been kept at 3.2 m so the camera could see over them. The fix was taller walls (6 m) that get out of the camera's way instead: wall pieces between the camera and your character dissolve, Diablo-style. That went into the dungeon generator, which was being built the same afternoon, so every later dungeon has it too.⁶

Heat, a day later #

The next day the desert got one more layer: Heat, a meter that builds while you're out in the open and falls in shade, in water, and in safe zones. The generator wrote 78 shade spots (tents, ruins, palms, oases) into the map. It builds slowly (about three minutes to full), and above 60% it starts to cost a little move and attack speed and some mana. A Water Skin from the oasis supplier (120 gold) stops it for three minutes. It's deliberately mild: the point is to make the empty dunes feel hot and to make an oasis feel like relief, not to punish the crossing. It shares its machinery with the other maps' weather, which is the subject of a later post.

What it adds up to #

None of the six features is big on its own. Together they give the empty part of the map a rhythm:

Routine: grind the islands for XP and a trickle of Sunstone.
Detours: a dune wanderer on the way pays several times what an island pack does.
Appointments: the caravan's stops, the rare bosses' respawn timers.
Events: a sandstorm announced on every map pulls people into the dunes, and its caches keep them there for ten more minutes.
A goal: three fragments, from any of those sources, open the Sun Tomb.

The balance model put a number on the last one: at the current rates, a key takes about two and a half hours of desert hunting. All of these rates, timers and the heat itself are still first guesses; the first playtest so far changed drop rates (doubled, along with the shorter game) but not the structure.

Takeaways #

Emptiness is a design choice you build, not one you leave. Three quarters of the land with 3% of the monsters, plus a switch that stops roaming packs from filling it back in.
Make the empty space pay, briefly. Strong wanderers and timed caches make the dunes worth crossing without turning them into another grinding spot.
A unique material is the long tail. Sunstone gave level 40 to 50 a reason to come back, and then the model showed it also needed a late source.
A timetable is cheaper than a network message. If everyone shares a clock, a pure function of time is a replicated entity for free.
A one-line "no" saves a feature's worth of work. The shovel was the AI's top recommendation; it never got built, and nothing is missing.

What's next #

The sim mentioned above (bots that fight every zone, every Elite and every boss) is the next post: how it works, what it found in this desert and elsewhere, and how the first playtest changed it again.

The coordinator-and-subagents post has the details of how parallel agents share one repository, and what went wrong when two of them ran the network test on the same port at the same time (it happened here too). ↩
tools/mapgen/maps/sunscar_desert.py, a rerunnable Python script like every map generator. The dunes are listed after the islands because the first zone that contains a point wins. ↩
The Fullmoon weapons post covers that track, its Moon Seals and the 1000-fragment forge. ↩
The "lived-in world" post explains the townsfolk routines this borrows from. ↩
The story post covers what the tablets say and how the main quest line uses them, without spoilers. ↩
The dungeon generator post tells that story, including how the beams became a reusable device for other dungeons. ↩

Multiplayer Bugs Only a Friend Can Find

2026-10-19T12:00:00Z

On the Windows build it seems that items as well as other players are all below the actual surface, so on the Y axis 0. What could that be?

— the developer

Why the bots didn't find them #

The multiplayer post described the setup: single player is a local server, every actor has a network role, and tests/net_test.sh starts a host, a client and a dedicated server with bots that walk, fight, trade, die and come back. It runs after every network change and reports engine errors. It's good at what it was built for: race conditions, missing spawns, RPCs to peers that can't see an entity yet.

What it can't do is notice that something looks wrong, and it only goes where it's told. Most of the bugs below lived in exactly those two gaps. Three came from the developer's evening with a friend on the Windows build, one from playing alone, and two were caught by thinking about what a friend's machine would do differently. This post follows on from the multiplayer post,¹ and the order is roughly from "embarrassing" to "subtle".

A friend at y = 0 #

The report came in one sentence (the epigraph above), then a second:

Can't seem to pick up any items and so on.

The first suspicion was the items. A dropped item takes its height from the ground like everything else, so the first checks measured that: in the editor, on a hill, items landed exactly on the ground. In the exported game, in single player, too. So it wasn't export-specific and it wasn't items. It was something only a joining player sees, and reproducing it with two game instances was slow, so the investigation went to the code that receives a client's position instead. On the host:²

net_pos = Vector3(pos.x, 0.0, pos.z)

When a client sends its position, the host keeps x and z and sets the height to zero. That line was written on day two, in the commit that added multiplayer, when every map was flat and zero was the ground. Rolling hills arrived the next day. Characters don't collide with the terrain in this game: an actor snaps its y to map.height_at() after moving. But a joined player's copy on the host (a PROXY, in the post's terms) doesn't move itself; it takes the client's samples. So for eleven days, every joined player stood at height zero on the host, which is inside any hill.

That one line caused all three symptoms:

Players sank into the ground. The host sends its copy's position to everyone else, so every other player saw the friend at height zero, which on a hill means buried.
No pickups. Loot is collected on the server when your character's body overlaps the pickup's area. The host had the friend's body under the hill, so on any slope it never touched anything.
"Items under the surface" was the same effect seen from the other side: the friend stood at the right height on their own screen, the items were where they should be, and the host disagreed.

On the host, a joined player's copy stood at y = 0, inside the hill, under the loot's pickup area. The fix: the host puts them on its own ground

Why didn't the bots find it? Because towns are flat. The terrain generator flattens the ground at safe zones, coasts, portals and buildings, and the network test's bots spend their time in town. On flat ground zero is correct, so everything worked. The bug needed someone to walk out into the hills and try to pick something up.

The fix³ takes the height from the host's own ground, not from the client:

func apply_owner_state(pos: Vector3, dir: Vector3, sent_msec: int) -> void:
	if Vector2(pos.x - net_pos.x, pos.z - net_pos.z).length() > MAX_OWNER_STEP:  # ground distance: hills don't count
		_rpc_teleport.rpc_id(owner_peer, net_pos)  # too far: put them back
		return
	net_pos = Vector3(pos.x, map.height_at(Vector3(pos.x, 0.0, pos.z)) if is_instance_valid(map) else pos.y, pos.z)

Trusting the client's height would have been the quick fix, and the wrong one in a server-authoritative game: a client could then float. The second change fixes a related bug: the "you moved too far, back you go" check measured in 3D, so on a steep hill the difference in height alone could look like a cheat. It now measures distance along the ground only. The receiving code moved out of the RPC into its own function so a test can feed it.

The test, test_joined_players_stand_on_the_ground_on_the_server, finds a hill on the test map, sends a sample with height zero, then one with a fake height 30 m up, and checks the player stands on the ground both times.

Four characters on a forest slope (a staged shot from the Steam screenshot set): the kind of ground where joined players used to disappear

"ConnectToGlobalUser failed" #

The same evening started with a different report: "It seems there's a Steam bug." Then the error text: "ConnectToGlobalUser failed." Steam's own message for "this program can't talk to your Steam account" is not self-explanatory, and the logs on the machine showed nothing. The coordinator guessed Family View, Steam's PIN-locked parental mode, which blocks exactly this connection. A few minutes later the developer confirmed it:

Ah, never mind, this is me: the family guard was active in Steam.

Not a game bug, then. But other players will run into the same wall, and they won't have an AI to guess for them. So the start menu now translates the error.⁴ For ConnectToGlobalUser it says: make sure Steam is running and signed in, not in offline mode, with Family View unlocked; that the game and Steam run as the same user, neither "as administrator"; and on Linux, that a Flatpak or Snap Steam can't see games started outside it. It ends with ". Playing without Steam (join by address still works)", and keeps Steam's own text in brackets for anyone searching for it.

The second half of the fix matters more: the start menu now tries to connect to Steam again every 5 seconds. Before, Steam was initialized once at launch, so unlocking Family View or starting Steam after the game meant restarting the game. Now the Steam row just lights up. The test is small: test_steam_init_errors_are_explained checks the text names what to check and keeps Steam's message.

The host that froze #

";It lags a bit for other players if someone uses a portal." This is the playtest note that sounds smallest and was the most work.

The network agent measured before touching anything. A new test, tests/net_portal_test.sh, starts a host and two clients: a "mover" who travels through five maps nobody is on yet and two dungeon instances, and a "watcher" who stands in the Vale. The host logs its worst frame around each trip; the watcher logs the biggest gap between updates of another player. The first run on the development PC:

Trip	Host's worst frame
Shadow Marsh (first load)	6,260 ms
Frostpeak	1,102 ms
Sunscar Desert	557 ms
Sun Tomb (dungeon)	79 ms
Crypt of Whispers (dungeon)	77 ms
back to the Vale (already loaded)	13 ms

Six seconds. "Lags a bit" was generous. The cause was the one everybody suspected: when someone travels to a map that isn't loaded, the host builds the whole map, terrain, tens of thousands of plants, clutter batches, buildings, NPCs and monsters, inside a single frame. In single player that's a loading screen and nobody cares. On a host, everyone else's game stops with it: their characters freeze, their monsters freeze, and then the world catches up in a jump.

The fix is to build maps in steps. GameMap now queues its build as a list of resumable steps, and the World drives them a slice per frame: 6 ms on a host with a screen, 12 ms on a headless server. Loops that place plants or clutter remember where they stopped and continue next frame; the terrain bake and the ground mesh run on a worker thread. The travelling player sees a short "Travelling..." screen and stays where they are until the map is ready, then arrives. Maps that are already loaded are instant. Single player still builds at once, because there's nobody else to stall.

Two tests guard it: test_map_built_in_steps_matches_built_at_once builds the test map and a dungeon both ways and compares a signature of every placed thing, line by line, because a step that resumes in the wrong place would quietly shift every plant after it; and test_travel_waits_for_a_map_built_in_steps checks the traveller waits and then arrives.

The host's worst frame when one player first travels to each place, before and after building maps in slices (headless host, an intermediate run while the work was going on)

The last stragglers were found the same way. Frostpeak kept one 550 ms frame until the scatter step learned to look up marsh pools and lakes in a grid instead of testing every plant against every pool, and dungeons cost 6 to 10 seconds on a host with a screen because merging the kit pieces read each tile's mesh back from the GPU; caching the pieces as plain arrays took the Crypt from 9.6 s to 0.3 s. Monster packs near the arriving player now appear one per slice, nearest first, instead of all in one frame.

The final run, same trips:

	Before	After
Headless host, worst frame	5.8 s (Marsh; 22 s when its terrain cache was missing), desert 7.5 s, Frostpeak 6.2 s	30 ms; nothing over 33 ms
Host with a screen, worst frame	up to 7.2 s	72 ms
The watcher's longest gap between updates	28 s headless, 10.9 s with a screen	55 ms / 90 ms
The traveller's wait	none (everyone else waited instead)	0.1-0.9 s for a dungeon, 2.4-6.4 s for a big map

The traveller now waits a few seconds on a "Travelling..." screen for a fresh map, which is the price of nobody else noticing.

A clock that disagreed #

This one was found without a friend, by imagining one. Townsfolk, animals, the desert caravan and the time of day don't go over the network. Every machine computes them from the wall clock: a 36-minute day, a routine at a time of the clock, a caravan stop at a time of the clock. So every player sees the caravan at the same well without a packet.

That works if every PC agrees on the time. The caravan agent wrote that its merchant trades "only while halted (plus 5 s slack for machines whose clocks differ a little)". A little is the normal case. But a friend's PC with a clock five minutes off would see the caravan at a different stop than the host, walk up to it, and be refused by the server, which thinks the caravan left long ago. The same friend would see a different time of day, and townsfolk in different places.

The fix is small. On join, the server's welcome message carries its wall clock, and the client keeps the difference:

WorldClock.server_skew = float(rules["clock"]) - Time.get_unix_time_from_system()

WorldClock.now() is the local time plus that skew, and everything timed by the wall clock reads it. The server resets its own skew to zero, so a host that was a client earlier in the session doesn't inherit someone else's offset. test_clients_take_the_wall_clock_from_the_server feeds a welcome two minutes ahead and checks that the clock, the townsfolk and the caravan follow.

Dashing out of the world #

The developer found this one alone, but it's a multiplayer bug in spirit:

With some of the skills like dash, one can move over boundaries such as the ocean's invisible wall or into mountains. Any way to fix this? I guess this would also work and break dungeons.

Dash and Charge simply teleported the character 6 to 8 m to the end point. Nothing in between was checked: not the coast's wall, not a mountain, not a dungeon wall or a locked door. In a single-player game that's an exploit. In a server-authoritative game it's worse, because the server itself was doing the teleport, so no amount of client checking would stop it, and a party member could dash past a puzzle door everyone else had to solve.

Actor.dash_end now walks the path in 0.4 m steps with a 0.35 m sphere and stops just before the first static body, the edge of the map's land, or the start of a mountain. Monsters don't block it, so Charge still goes through the enemies it hits. Knockback, pulls and the attack lunge already moved through normal physics and needed nothing. test_dash_stops_at_walls_and_the_edge_of_the_map covers four cases: an open dash goes the full distance, a monster in the way doesn't stop it, a wall stops it just in front, and a dash across the edge ends on land. The test itself had a bug of its own.⁵

The build that would have shown capsules #

The last one never reached a friend, which is the point. Asked for new Windows and Linux builds, the coordinator checked the export settings first and found the sprite atlases missing. Godot exports resources it knows about; plain .json files have to be listed in an export preset's include filter, and the filter had data/*.json and data/maps/*.json but not assets/sprites/*.json. Every sprite sheet's atlas, the file that says where each frame of each direction lives, would have been left out, and the game falls back to the capsule when a sheet has no atlas. The exported game would have run without a single error and shown every player and NPC as a coloured capsule.

What an export without the atlases would have looked like: the capsule fallback next to the sprite (from the HD-2D post)

Commit 21dd86c adds the path to every preset. It's also why the project's rulebook has a line about it:⁶ "add *.json to the export preset's non-resource include filter, or data/*.json won't ship." Headless tests run from the project folder, where every file exists, so no test could see this. The check now is to look inside the built package before handing it over.

What they have in common #

Six bugs, and none of them was a race condition or a desync, the things network code is usually afraid of. They were all assumptions that held on the developer's machine:

The ground is at zero (true on day two, and in every town).
The person reading the error knows Steam's internals.
Building a map takes a moment (true when only you are waiting).
Every PC's clock agrees.
A short teleport can't leave the map.
The files in the project folder are the files in the build.

Takeaways #

Bots test what you point them at. The network bots stayed in flat towns, so the y = 0 bug was invisible to them for eleven days. Send at least one bot somewhere inconvenient.
Never take the client's height, and don't fix a bug by trusting the client. The server owns the ground; the fix put the player on it rather than believing them.
Measure the lag before fixing it. "Lags a bit" was a six-second freeze, and the numbers per map showed which maps mattered.
Presentation from a clock needs one agreed clock. One number sent on join keeps every machine's townsfolk, sun and caravan together.
Translate the platform's errors. "ConnectToGlobalUser failed" means nothing to a player; a list of four things to check does. And retry, so fixing the cause doesn't need a restart.
Look inside the package. A build that runs without errors can still be missing half its look.

What's next #

The friend's evening was also the first real playtest, and most of its notes weren't bugs but wishes. The playtest post goes through all of them, from potion numbers to a chat that was once "not needed".

"Server-Authoritative Multiplayer in Godot, Single Player Included" (03) has the roles, the spawn function and the network bot. ↩
Line 1909 of scripts/actors/actor.gd, in _rpc_owner_state, unchanged since the multiplayer commit be14886 of day two. Hills came with 21a6b5b the next afternoon. ↩
Commit 4feeb21: 11 lines in actor.gd, 24 in the tests. ↩
SteamService.explain() in scripts/autoload/steam_service.gd, commit a2db5ce; the start menu's Steam row calls SteamService.start() again every 5 seconds until it works. ↩
It passed alone and failed after other tests, because maps that earlier tests left behind sat at the same spot. It now runs 41 km away from everything (maps sit 5 km apart). ↩
CLAUDE.md, the file every Claude session reads first; the first post explains it. ↩

Taking a PC ARPG to iPhone and Android

2026-10-19T12:00:00Z

Mobile controls would be nice as we want to play it on iPhone and Android. Not sure how the server stuff will work though.

— the developer

One sentence, two agents #

Dekiro was a PC game for six days. Its windows were drawn for 960 x 540 UI pixels, every tooltip opened on mouse hover, splitting a stack of potions was Shift + drag, and the hotbar answered to the number keys. Then the human asked for phones, with the worry quoted above.

The server worry turned out to be the small part. The game is server-authoritative even in single player:¹ a phone runs its own local server exactly as a PC does, and a phone joining a friend is just another ENet client. Two things don't carry over. Steam doesn't exist on phones, so phones join by address, and hosting on a phone (battery, mobile networks, carrier NAT) is labelled "experimental" in the menu with a tooltip that recommends a PC host or a dedicated server. Characters stay on the device; one character across PC and phone would need a cloud save, which is a later step.

The real work was the interface. After a short plan, the human's reply was one line: "Spawn two agents. Android and iPhone." The split that made them able to work in parallel² was by layer, not by platform:

The Android agent built what both platforms share in the world: the on-screen controls, a mobile renderer and quality profile, and the Android export.
The iPhone agent built what both share in the windows: screen density, the notch, touch-friendly windows, and the iOS export.

They met in one small static class, Mobile, that the iPhone agent published as an API on its first pass so the other one could size its buttons with it.

The touch HUD on a simulated iPhone 15 Pro: a floating stick on the left, the attack button with six skills on two rings and two potions on the right, the menu row as icon tiles left of the minimap, and the notch and home bar drawn over the screenshot

Sizes in millimetres #

The PC UI scales by whole numbers: 960 x 540 UI pixels times 2 on a 1080p monitor, times 4 on 4K. That rule means nothing on a phone. An iPhone 15 Pro in landscape is 2556 x 1179 pixels but only about 65 mm tall, and what matters is how big a button is under a thumb, not how many pixels it has.

So on touch screens the scale comes from the screen's density:

## The UI scale on touch screens: one UI pixel is about UI_PX_MM millimetres (a 10 px body font is then
## ~1.7 mm, iOS's smallest comfortable text), never fewer than TOUCH_MIN_HEIGHT UI pixels high (the
## windows were drawn for 540) and snapped to quarter steps.
const UI_PX_MM := 0.17
const TOUCH_MIN_HEIGHT := 360.0

An iPhone 15 Pro (460 dpi) gets 3x, which makes its screen 852 x 393 UI pixels. A 2400 x 1080 Android phone gets 2.5x, an iPad 1.75x. The player's "Interface size" option still multiplies the result.

Everything that has to be touched is specified in millimetres too, through Mobile.target_px(viewport, mm). The brief asked for buttons of about 10 mm, which is what platform guidelines recommend. The agent pushed back with arithmetic: a landscape phone is only about 65 mm tall, so 10 mm buttons (or even Apple's 7 mm) would leave room for about five rows, and a 9-wide bag would no longer fit. Its rule, from the code:

const TARGET_MM := 6.0
const SLOT_MM := 5.5
const SNAP_MM := 3.0

That is the fat-finger snap: buttons look 6 mm, but a tap that hits nothing pressable goes to the nearest button within 3 mm. Visually the windows keep their density; functionally each button is as wide as a fingertip wherever it has no close neighbour. Item slots are 5.5 mm so the bag stays 9 wide. The close X keeps its drawn size and gets a 6 mm hit area.

The notch #

SafeArea is the second piece. Phones have a notch or Dynamic Island, a camera hole, rounded corners and a home indicator, and none of the HUD may sit under them. SafeArea attaches to a CanvasLayer and moves each child's offsets in by the safe-area insets, keeping its anchors. The full-screen HUD layers (player frame, hotbar, quest box, banners) shrink to the safe rectangle; anchored windows stay inside it; dragged windows are clamped to it by the window dragger. Things drawn over world positions (health plates, name tags, the fishing bobber's "!") opt out, because they belong to the 3D world, not the screen.

On a PC, without a phone in reach, the same code runs against a simulated device:

godot --path . -- --touch                  # touch mode + a simulated iPhone 15 Pro notch and home bar
godot --path . -- --touch --notch=android --dpi=420   # a punch-hole Android phone at its density

--touch turns on every touch rule (the mouse becomes one finger), --notch picks the outline, --dpi the density. The notch, rounded corners and home bar are drawn over the screenshot, so every image in this post shows exactly what would be hidden on the real device. Without the flags a PC gets the desktop UI unchanged; one agent checked that with a pixel diff of the inventory window before and after its changes.

Controls: a stick, a big button, and things that appear #

The on-screen controls follow the shape most mobile ARPGs (that popular Korean MMO's own mobile version included) settled on:

Left: a floating stick that appears where the thumb lands. Pushing it past 1.3 times its rim sprints.
Right: a 15 mm attack button (hold it and the combo keeps going), the six skill slots on two rings around it with cooldown sweeps, seconds left, a mana tint and their rank, and the two potion slots beside them.
Context buttons appear only when there is something to do, and name it: Talk, Pet, Open, Read, Travel, or the dungeon devices' verbs (Pull a lever, Light a candle, Turn a valve). A Take button appears when loot is in reach.
Camera: one finger on empty screen rotates, two fingers pinch to zoom.
Menu row: Bag, Skills, Hero, Map, Party, Menu, top right.

Every finger belongs to whatever it first touched, so the stick, the attack button and the camera work at the same time. The project's first architecture rule paid off here: controllers drive actors only through command_* methods.³ Touch input is a new source in PlayerController, next to the keyboard and the gamepad, and nothing on the actor side changed. Touch skills aim like the gamepad's (in the direction you face), and a touch attack while standing still turns toward the nearest enemy within 4.5 m, because there is no mouse cursor to aim with.

A test feeds the layout four screen shapes (an iPhone, an Android phone with a camera hole, a small phone and an iPad) and checks that no two controls overlap and none is smaller than its minimum size. It caught one real problem: the top button of the outer skill ring sat on the minimap's clock. The ring now leans left.

School selection on an Android-shaped screen: before, the "School of Blade" popup floats over the character; after, it is a banner under the menu row. The green Talk button only appears next to an NPC

A crowded top edge #

The first screenshot of the touch HUD worked and looked busy. The menu was six big round buttons that covered the zone banner and touched the minimap, and the NPC name tags of the town piled up behind them. A cleanup pass the same evening changed four things, all only on touch:

The menu row became a tight row of 7 mm square tiles with pixel icons, left of the minimap.
A banner band hangs under the row. The zone name shows there, and so do achievements, "New quest" and "Quest complete", queued behind each other, instead of floating over the fight. A later pass sent the other big popups over your own character there too: "LEVEL N!" (several level-ups in the queue merge into one banner), "School of X", and any popup at least 1.4 times the normal size that isn't a number. Damage numbers (crits are 1.35) and small messages stay in the world.
Name tags dodge the HUD. Every HUD part reports its rectangles through a hud_rects() method; a tag that collides with another tag or a HUD part drops the NPC's title first, and if it is still under the HUD it dims to 22 percent. The placement became a pure function, so it has its own test.
The hotbar moves beside an open window, whole, or hides when there is no room. On touch it is only shown while a window is open, as the drop target for skills and potions dragged out of it.

The same fight before and after the cleanup: the round menu buttons and the zone banner competing for the top edge, then a row of icon tiles with the banner band under it, here showing an achievement

Windows taller than the screen #

Every window was designed for 540 UI pixels of height. An iPhone's safe area at 3x is 372. A new fit shot in the mobile scenario opens every window one by one and prints its rectangle against the safe area, "OK" or "CUT". Three windows were cut: the inventory, the skill window and the shop.

FitScroll is the general tool: a container that grows up to a height and then scrolls. Wrapping a whole window in it works, but it scrolls the buttons away too, and a shop whose Sell button is off screen is broken. So windows can now mark their middle as the body (TouchUi.mark_body), and on touch only that part scrolls: the skill list, the NPC window's quests and goods, the storage pages. The title, the gold line, Sell and Goodbye stay where they are. Windows that mark nothing still scroll as a whole.

The inventory got its own compact layout instead: the equipment moves into two columns beside the Bag, Skillbooks and Runes pages. That makes it 332 UI pixels tall, and it fits without scrolling, with every slot still 5.5 mm.

The inventory on an iPhone, before and after: equipment above the bag with the gold row cut off by the home bar, then equipment in two columns beside it, with gold, Split and the bin in view

Touch has no hover and no right button #

TouchUi is the layer that makes Godot's ordinary Controls behave on a touch screen without rewriting each window. It walks the UI as windows open and applies a set of rules:

Long-press tooltips. Hover doesn't exist, so a finger held still for 0.45 s shows the tooltip, placed above, below or beside the finger so the finger doesn't cover it. It stays until the next tap, and the release that ended the long press doesn't count as a click.
Double-tap is right-click. Equip, use and read are right-click on a PC. Every hint and tooltip text that mentions right-click says "double-tap" on touch (Mobile.touch_text).
Drag to scroll, with a fling, on every ScrollContainer, list and rich text. A press that moves more than 2.5 mm becomes a scroll and cancels the button under it, except on drag sources: item slots and skills keep drag and drop.
Splitting a stack was Shift + drag. There is no Shift on a phone, so the inventory has a Split toggle next to the bin. Turn it on, drag a stack onto an empty square, and the amount comes from a slider instead of a number field, so no keyboard opens. The toggle turns itself off after one use.
Text fields open the right on-screen keyboard (a number pad for the port, a URL keyboard for the join address, a password keyboard for passwords). The screen slides up so the focused field stays above the keyboard, and a tap elsewhere puts the keyboard away.

A long press on a sword in the bag: the tooltip with the comparison to the equipped sword opens beside the finger and ends with "Double-tap to equip"

The second finger #

One problem needed a piece of engine knowledge. Godot turns touches into mouse events so that every Control works on a touch screen, but only for one finger: the first one down, until it lifts. With a thumb on the stick, a tap of another finger on a window's button reached nothing, because buttons only listen to the mouse.

TouchRouter fills that gap. TouchUi feeds it every touch. A finger that isn't the mouse finger and lands on a window or on anything pressable becomes a tap: when it lifts, still on the same control, the router pushes a left press and release at that point into the viewport. It stays deliberately small. Drag and drop, long-press tooltips and scrolling remain with the first finger, and nothing is routed while the first finger is itself on the UI, because it holds the interface's mouse focus and a second press would steal it mid-drag.

This is the one feature here that is covered by a unit test only. The PC simulation has one mouse, so one finger. It is on the list for a real phone.

The mobile renderer #

The desktop build uses Godot's Forward+ renderer with volumetric fog, SSAO, glow and dense grass. Phones get the Mobile renderer (set per platform in project.godot, so the PC keeps Forward+) and a "Mobile" quality profile that phones start on:

# phones: plants / clutter drawn ~60% as far (the fog hides the edge), half the weather, short 2-split shadows
"mobile": {"view": 0.6, "particles": 0.45, "shadow_distance": 45.0, "shadow_splits": 2, "camera_far": 190.0},

On top of that: grass at a quarter of its density, fading out at 26 to 38 m; a 2048 shadow map with hard filtering; no SSAO or volumetric fog (the Mobile renderer has neither); 75 percent render resolution and 30 fps by default. A new Upscaling option offers FSR, but Godot 4.7 only has FSR in Forward+, so on the Mobile renderer it falls back to bilinear by itself.

Shaders were the risk. Every custom shader in the game (the sprite characters, the skill effects, the foliage, the dungeon cutaway) was written against Forward+, and headless tests never compile shaders.⁴ The agent took windowed screenshots with --rendering-method mobile of the Vale, every room of a dungeon, every Blade skill and the sprites, and compared them with Forward+. No shader needed a change. The visible difference is the missing ambient occlusion. One limit to watch on a device: the Mobile renderer draws at most 8 point and 8 spot lights per object, and the towns have many flickering lanterns.

The Vale's town square at night with the desktop renderer and with the Mobile renderer: the same sprites, shaders and lights, minus ambient occlusion

Android: an APK from a Windows PC #

The Android preset is plain: arm64 only, package io.dekiro.game, landscape following the phone's rotation, immersive mode, internet and Wi-Fi state permissions, the Steam addon excluded. The same include filters as every other preset.⁵

The first export stopped at missing tools. Building an APK from Godot needs:

A Java JDK 17. Not the newest JDK: Godot 4.7's Android export wants 17, so that's what went in, as a portable zip in the user's folder, since no installer for it runs without admin rights.
The Android SDK command-line tools with platform-tools, build-tools 35 and the android-35 platform, licences accepted. The AI asked the developer before accepting those on their behalf.
A debug keystore for signing, one keytool command.
ETC2/ASTC textures. Desktop GPUs read BC-compressed textures; phones (and Apple Silicon Macs) need ETC2 or ASTC. One project setting, import_etc2_astc=true, makes the importer write both. It had already been switched on a day earlier for the macOS build.

Both tool paths go into Godot's editor settings, and from then on an APK is one command:

godot --headless --path . --export-debug "Android (Game)" build/game-android/Dekiro.apk

The result is a 147 MB debug-signed APK that installs from a file, after allowing "install unknown apps" for whatever app opened it.

iOS: an Xcode project, not an app #

An iPhone build can't be finished on Windows, and the iPhone agent didn't pretend otherwise. Godot can export an iOS Xcode project from any platform: Dekiro.xcodeproj, an Info.plist with every icon size, the launch storyboard, the 120 MB game pack, the Godot engine as an xcframework and MoltenVK (Vulkan on Metal). Building, signing and installing it needs Xcode, which only runs on macOS. Godot says as much: ".ipa can only be built on macOS".

Two smaller lessons from the export:

Godot refuses to export at all with an empty App Store Team ID, even for a project-only export. The agent tested with a dummy ID and set it back to empty; the real one goes in on the Mac.
GodotSteam has no iOS library. The preset excludes addons/godotsteam/*, and the export then leaves out the extension list as well, so nothing tries to load a library that isn't there.

The app icon and the launch screen are drawn by a script from the game's own UI art: a crimson seal with 影 ("shadow") on the window lacquer, and the start menu's title row. docs/MOBILE.md has the Mac steps: Xcode 16 or newer, an Apple ID (a free one runs on your own phone by cable for 7 days; TestFlight needs the paid program), automatic signing, Developer Mode on the iPhone, and a local network permission text for joining friends on the same Wi-Fi.

Testing on a PC #

Everything in this post was built and checked without a phone in the room. Unit tests cover the pure parts: the size math, the safe-area insets, long-press timing, the stick's dead zone, the HUD layout on four screen shapes, name tags against the HUD, the second-finger router and the iOS preset's filters. tests/scenario_mobile_ui.gd opens a phone-shaped window with --touch, takes shots of every window, and checks behaviour on the way: a drag scrolls a list, a tap beside a button snaps to it, an item dragged by "finger" lands in its slot. tests/scenario_touch.gd sends real touch events through the engine in town and in a fight. The monitor can't show a 2556 x 1179 window at full size, so many shots ran at half size (--size=1278x590 --dpi=230), which gives the same layout.

What a PC can't tell you #

As of this post, no phone has run the game while anyone watched. The open questions are the honest ones:

Frame rate. A desktop GPU says nothing about a phone's. The mobile profile is an educated guess.
Feel. Stick radius, camera drag speed (1.6 times the mouse's), and how much the 4.5 m auto-aim helps or annoys.
The second finger on real hardware.
Lights in lantern-heavy towns under the Mobile renderer's per-object limit.

Takeaways #

Size touch UI in millimetres, from the screen's density, not in pixels.
Small visible targets plus a snap radius fit more on a 65 mm screen than big buttons, and still answer to a fingertip.
Pin the header and footer, scroll the middle. A window whose action buttons scroll away is broken on a phone.
Know your engine's touch emulation. Godot's mouse comes from one finger; anything a second finger should do needs its own path.
Simulate the device, and draw its notch over your screenshots, so a PC can catch most layout bugs.
Keep input behind one interface. Touch was a new input source for PlayerController, not a change to the game.

What's next #

Phones and PCs can now play in the same world. The next post is about the bugs that only showed up once a friend actually joined one.

Post 3 explains the four network roles and why single player is a local server. ↩
Post 11 has the rules for running agents side by side in one repository, most of them learned from file collisions. ↩
From the project's rulebook (post 1): PlayerController, the AI and network input must be interchangeable, so none of them may touch an actor's velocity or combat internals. ↩
Post 4 tells the story of a uniform name that turned every sprite into a white wall, which no headless test could see. Since then every shader change gets a windowed screenshot. ↩
Post 25 tells how the sprite atlases once went missing from every export because a JSON file isn't a resource. ↩

The First Playtest: Forty Notes and What Each One Became

2026-10-19T12:00:00Z

I don't feel so powerful, especially on the lower levels. Can you adjust the health slightly?

— the developer

The list #

Until this week, almost every number in Dekiro came from a model. The balance post describes a Monte Carlo career and a combat simulation with bots, and it says plainly that none of it had met a human. Then the human sat down with the Windows build, played for an evening, part of it with a friend,¹ and sent one long message. It starts like this:

Items in shops don't show stats, so there is no way of knowing if they are better or not. HP regeneration out of combat is way too low, let's adjust that to be higher. The potions also heal too little. EXP progression can feel a bit faster, let's scale to 20 hours. I want to have an option to "restart here" or "restart in town" instead of restarting in the city.

It goes on for nineteen points: buff skills that run out too fast, dropped items that vanish, lag when someone uses a portal, switching schools, upgrade materials, a white outline for loot, a more readable font, skills that stay behind when you move, a classic item from a popular Korean MMO, which the developer knew by its German name (Tapferkeitsumhang), Shadow minions, an XP potion, mouse capture, the camera, and trading skillbooks.

Over the next ninety minutes more notes followed, one or two lines each: a ten-slot hotbar, party members on the big map, tooltips, skills hidden under the street, grandmasters staring at their own buildings, a sprint toggle, Game Master tools, townsfolk out on the roads, a minimap without trees, an easter egg, wrong quest markers, named chickens, a tavern, a chat, a skill rank above Grandmaster, and one question: "Do bosses have HP recovery?"

About forty notes in all. This post goes through what each one became.

From a list to ten agents #

The coordinator workflow from the subagents post was built for exactly this. Within two minutes of the first message, four agents were running, each with its own slice of the list and its own files:

Agent	Took	Owned
UI	shop tooltips, respawn choice, mouse capture, camera drag, loot outline, font comparison	the windows, the HUD, the camera rig
Gameplay and balance	regen, potions, the 20-hour pace, drop lifetime, upgrade materials, Cape of Valour, XP potion, Shadow rules, school switching, book exchange	data tables, the balance model
Skills	4-minute buffs, buff particles, skills that follow the caster	skills.json, the skill effects
Network	portal lag	map loading

Every later note went either to the agent already working in that area (the UI agent ended up with eight extra tasks, from the hotbar to the XP tooltip) or to a new agent when it was its own thing: GM tools, townsfolk on the roads, baked map pictures, the easter egg, the chat, and the Grandmaster ranks. Ten agents in total. The coordinator did two small ones itself between reports: the grandmasters' facing and the boss recovery.

The brief they all shared was one file,² with the rules from the subagents post: own your files, edit shared ones only with exact-match edits and re-read first, don't fix other people's half-finished work, run the full tests, look at your screenshots, don't commit. Those rules were tested hard this time. The agents' reports are full of lines like "the compile broke twice because of that same unfinished skills work" and "the earlier potion-heal failure no longer shows". The test suite went from 15,085 checks before the list to 17,695 at the end of the evening, and at most moments some of them were failing because somebody else was mid-edit.

The one-line changes #

A surprising share of the list was numbers. Because content lives in data, these were edits to a JSON file or a constant, plus a test and a rerun of the balance model to see what else moved.

Regeneration. Out of combat (no damage dealt or taken for 5 seconds) players and companions now regenerate 4% of their HP and mana per second, so an empty bar is full again in about 25 seconds. Three constants in attributes.gd. In a fight nothing changed.

Potions. Each tier heals about 1.6 to 1.9 times as much, and costs about a quarter more:

Potion	Heal before	Heal after
Red Potion (S)	80	150
Red Potion (L)	250	450
Greater Red Potion	700	1,100
Superior Red Potion	1,300	2,000

One small code change came with it: the potion key used to drink the weakest potion in the bag. It now drinks the smallest one that fills what's missing. With the new regen on top, the model's character drinks 30 to 190 potions an hour instead of 175 to 430.

Twenty hours to level 90. This one was a number too, but it needed the model. The XP curve's exponent went from 2.58 to 2.37, which makes the bar at level 90 about 3.4 million XP instead of 8.7 million, and every quest's XP followed the bar. The model now reaches level 90 in 20.7 hours (it was 38.6). Everything that was paced against the old 40 hours had to move with it: monster gold up a third, Fullmoon weapons twice as likely from Shadows and bosses, Sunstone more common in the desert, Sun Tomb key fragments doubled.

Lighter low levels. "I don't feel so powerful" was the vaguest note on the list. The coordinator read it as monster health (the combat pass had raised low-level monster HP about 2.7 times) and asked back in case it meant the player's own health. The fix is a level factor in monsters.json: x0.65 up to level 15, tapering to x0.85 at 30 and none from 40. A level 3 monster now takes 2.1 hits instead of 3.2. Bosses were first included and then exempted, because the Crypt Lord fell in 40 seconds with two companions, which is not a boss fight.

Upgrade materials. "Shadow Shards should only be required from +5 and then go up as they do right now from +1." Taken literally: +1 to +4 now need no shards at all, the attempt to +5 needs what +1 needed (one shard), +6 what +2 needed, and so on. "Shadow Cores only with items on level 30+" became a new key on a material, "min_item_level": 30, which the upgrade window and the server both read. That's the whole change: nine lines of upgrades.json and one check.

Shadows. Three notes landed in one small block of data:

"shadow_waves": { "engaged_for": 9.0, "calm_after": 60.0 },
"shadow_break": { "heal_share": 0.25, "heal_radius": 25.0, "minions_die": true }

A Shadow now spawns nothing until someone hits it, keeps spawning while it was hit in the last 9 seconds, and goes back to sleep after 60 seconds alone. When it breaks, its monsters die with it (you still get their XP, but not their loot: otherwise piling them up and breaking the stone would be free loot), and everyone within 25 m heals 25% of their max HP. The coordinator decided companions get the heal too, and said so.

Two new items. The Cape of Valour (that MMO's Tapferkeitsumhang) drops from monsters level 10 and up at 1% (3% from Elites). Swing it and every monster on the map comes running at you for 40 seconds; bosses and Shadows ignore it, and it doesn't work in safe zones. The Potion of Insight doubles XP for 15 minutes at the requested 0.1% drop chance; another one adds 15 minutes, up to an hour, and death doesn't wash it out. Both are a few lines in items.json plus an icon and a model from the Blender pipeline. The cape needed one new effect, a map-wide taunt.

Schools and books. Switching schools is allowed while no skill has reached Master and the character is below level 30, where the school's own questline starts. Skill points come back one to one. Trading a skillbook of another school for a random book of your own works at your own grandmaster, then waits an hour of real time. Both rules are two numbers in a new data/schools.json.

Buffs. War Cry, Iron Skin, Haste and Blessing now last 4 minutes with a 60-second cooldown, so you can keep them up the way the classic does. Two values went down: held up permanently, the old numbers would have given a Grandmaster 86% damage reduction from Iron Skin, or double running speed from Haste.

The ones that were real work #

Other notes sounded just as small and weren't.

"Restart here" or "restart in town". The game had one respawn: back to the map's spawn. The new death window offers both. In town is available after 3 seconds, at full health, in the town or gate camp the character last stood in, which the character now remembers and saves.³ Here waits 10 seconds and gives 50% health and 5 seconds of protection that your own first hit ends, so it can't be used to hit a boss for free. In a dungeon, "town" means the entrance, so the party's run isn't thrown away.

The new death window: restart in town after 3 s, or here after 10 s with half health

Shop tooltips. The shop rows simply had no tooltip. They now show the bag's tooltip, compared with what you wear.

A shop tooltip comparing an Iron Sword with the equipped one, and a Sell box tooltip on the left

Buff effects. "For all the passive skills I would like to have a particle effect on the character or weapon." Every active buff now has its own small emitter: embers from the weapon hand for War Cry, steel flakes round the waist for Iron Skin, wisps at the feet for Haste, motes from a halo for Blessing. Other players see them, which meant a new synced value on the player (buff_look, for example "war_cry:2,iron_skin:1"). The coordinator's own verdict on the screenshots was that they read as "sparse specks", not yet as an aura, and offered a denser pass.

Each buff's particles, standing and running

Skills that follow you. Spins, Blade Storm, Consecration and the self buffs now move with the caster, both their effects and their damage area, on the server. Aimed and thrown skills (Charge, Light Lance, Night Blades) stay where they land. The rule is in data: circle, arc and self skills follow unless a skill's "fx" says otherwise.

Skills under the street. The developer's first guess was a masking problem: "It seems a masking issue of the skill, tower buildings and NPCs somehow?" The sprite outline does use a stencil mask, so it was a good guess, and the skills agent checked it first. The real cause was draw order. Roads and paved squares have soft edges, so they are transparent materials, and transparent things are drawn in priority order. Floors were at priority 0, skill effects at -2, so the floor was drawn after the effects and covered them. Consecration was completely invisible on the Vale's square. The fix is one constant, FLOOR_PRIORITY = -20, plus ground effects that now follow the terrain's height and tilt with slopes instead of sitting at a fixed 6 cm.

The Vale square before (top: only the boss telegraph shows) and after (the skill glyphs draw over the paving)

Quest markers. "Some NPCs have ! on top even when there is no quest action possible; some NPCs that have quests don't." The audit found the "!" wasn't connected to quests at all. It was a fixed label for NPCs whose role was "quest", and only Elder Mira had that role. So Mira always showed it and every other quest giver never did. Markers are now computed from the character's own quest state with the same conditions the NPC window uses: a yellow "!" for a quest you can take, a light blue "?" for something to hand in. A test checks every NPC on every map for two characters.

Portal lag. "It lags a bit for other players if someone uses a portal." The host was building the whole target map in a single frame, which on the Shadow Marsh took over six seconds, frozen for everyone. Maps now build in slices of a few milliseconds per frame.⁴

Game Master tools. The developer asked for GM controls on their own Steam account: give a Fullmoon sword, add gold, change levels and points. The panel was the easy part. The hard part is who counts as a GM. The answer is that only the server decides, from identities it can verify: its own Steam login, or Steam's authenticated mapping from a lobby peer to an account. A client that joins by IP address is never a GM, and an ID sent in a message is ignored.⁵ Every GM action goes through the normal character systems, so a reload's sanitizing keeps it, and there is no "gm" flag in the save, because a client could write one into its own file.

The chat that wasn't needed #

On day two the developer had ruled chat out: "Chat is not needed. Most will be in Discord anyway." It sat in the backlog as "not planned". The playtest changed that in one sentence:

There is no way for me to understand what my quest rewards were that I have just received. It might be time to add a chat, so we can have system messages where these rewards can be dropped into, and players can also write things in.

and a follow-up four minutes later: "every popup that appears on screen should then be shown in that chat to the one player that triggered that message, so a user can always scroll back if the message disappeared too fast."

The second sentence decided the design. Instead of adding chat lines in forty places, the chat agent hooked the one function every popup over your own character goes through (DamageNumber.spawn_text), so popups added later land in the chat automatically. Damage numbers and other players' popups are skipped, repeats merge into "(x2)", pickups merge into one line, kill XP is summed every 4 seconds. Player chat is server-authoritative like everything else: the server stamps the sender's name from its own copy of the player, strips markup so nobody can fake a system line, caps messages at 200 characters and 5 per 5 seconds, and routes say, party, whisper and shout only to the right peers.

The chat: a quest's rewards listed in full, merged pickups, summed XP, a refusal popup (x2), and player lines. "[b]not bold[/b]" stays plain text

What got asked back #

An agent working from a one-line note has to fill in details. The rule from the subagents post is to decide sensibly and say so, and to ask where it's a matter of taste. After this round the open questions were:

Respawn values. 10 seconds and 50% health for "here", 3 seconds for town, 5 seconds of protection, town after 3 minutes without a choice. All guesses; the developer will feel them.
The font. The developer asked for "a bit more readable" and "any suggestions?". The answer was a comparison sheet rather than a switch: the same HUD, tooltip, shop and quest tracker in four candidates. Jersey 10 (current) crowds its letters; Fusion Pixel 12 stays pixel art, is clearly spaced and also covers Chinese and Japanese, at about 20% more width; m6x11plus is very readable, but its licence couldn't be confirmed; Noto Sans is the most readable and breaks the pixel look. The recommendation is Fusion Pixel 12. Swapping is one path in UiTheme. The developer hasn't picked yet.
"2 minutes". "Dropped items can stay a bit longer, let's say 2 minutes." It turned out that items monsters drop never disappeared at all. Only items you drop from your own bag expired, after 20 seconds. That's now 120 seconds, and the question went back: did you mean something else?
The Cape's reach: the whole map, as asked, or a radius like in the classic? It's one number.
"!" and "?": two symbols, WoW-style, or a single "!" as before?
Buff strength and cooldown: should Iron Skin and Haste be higher after all, and is 60 seconds right?
The loot outline: 2 pixels at 1080p, white, unshaded so it reads the same at night. Enough?

The font comparison sheet, first two of four: Jersey 10 (current) and Fusion Pixel 12

One misunderstanding went the other way. "Skills should also be accessible with the shortcut V," then a minute later "ah sorry, F not V", then, asked whether F should open skills instead of talking to NPCs, "don't adopt this", and finally "V as an additional shortcut (next to K) for skills would be great." The result: K and V both open the skill window, F stays the interact key, and players who saved key settings before still get V, unless they've bound it to something else.

The small ones, and one question #

Some notes took a few minutes. The four grandmasters stood facing their school halls; the map generator now turns them to the square (one atan2 each), and every NPC turns toward whoever talks to them. The oversized colour picker was Godot's full editor dialog at two to three times UI scale; it's now a square, a hue strip and a hex field. Alt names gold and items on the ground. The hotbar has ten slots (touch keeps eight, because ten wouldn't fit at finger size).

A few notes were bigger than they sounded and have their own posts: townsfolk spread out onto the roads, a tavern for the "Bierlinger Tribe" and seven named hens;⁶ minimap pictures with trees and buildings, baked from top-down renders;⁷ and Grandmaster ranks G1 to G10 with a hidden rank above them and a study item that drops from bosses by chance, which gets its own post once it's finished. There is also an easter egg for a friend, which stays a secret.

And the question. "Do bosses have HP recovery?" They didn't: you could wear a boss down, die, run back from the entrance and continue where you left off. The coordinator suggested the classic MMO's rule, and the developer set the numbers:

The suggestion makes sense: if no player hits for 20 seconds, 2% per second is OK.

That's BossAI.recover(): a boss nobody has hurt for 20 seconds heals 2% of its max HP a second, so it's full again within a minute. Phase triggers (summons at 66% and 33%, the enrage) still fire only once per fight, so healing back over a threshold doesn't replay them.

By the numbers #

About 40 notes, from 19 in the first message to a question at the end.
10 agents plus the coordinator, the first four briefed within two minutes.
15,085 → 17,695 test checks over the evening.
38.6 → 20.7 hours to level 90 in the model.
6,260 → 18 ms: the host's worst frame when someone first travelled to the Shadow Marsh.
2 of the notes turned out to be misunderstandings worth asking about; 0 were declined.

None of it has been playtested a second time yet. At the time of writing it's in the working tree, waiting for the last agents and the full check before the commit.

Takeaways #

Playtest notes are mostly data, if your content is. Potions, regen, XP pace, upgrade materials and Shadow rules were numbers. The balance model is what made changing them safe in minutes rather than days.
The vague notes need a reading and a question. "I don't feel powerful" could mean two things; the agent picked one, said which, and offered the other.
Ask about taste, decide about mechanics, and say which is which. The font, respawn timings and marker symbols went back to the developer; loot-free Shadow minions and boss phases that don't replay were decided and explained.
Hook the funnel, not the callers. One hook in the popup function put every message into the chat, including the ones nobody has written yet.
A good guess still needs checking. "A masking issue" was a sensible hypothesis and wrong; the cause was one priority number.

What's next #

Several of these notes came from playing with a friend, and some of the bugs behind them can only be found that way: players sunk into hills, a clock that disagreed, and a host that froze when someone took a portal. That's the next multiplayer post.

The bugs that only showed up with a second player are in the post "Multiplayer Bugs Only a Friend Can Find". ↩
playtest_brief.md in the coordinator's scratchpad; each agent's own prompt only added its tasks, in the developer's words. ↩
On load the remembered town is kept only if it's a real, non-dungeon map whose safe zones that character has visited: a server can't trust a client's save file. ↩
The measurements and the stepped map build are in "Multiplayer Bugs Only a Friend Can Find". ↩
tests/net_bot.gd sends exactly that: a client joined by IP claiming the developer's account. The server logs the refusal. ↩
"A Tavern, Named Hens and Cats: The Small Stuff". ↩
The minimap post (26) covers the baker: a top-down render of each map in Godot, then a stylising step in Python. ↩

The Fullmoon Weapons: an Old-School +9 Gamble, and Three Steps That Never Fail

2026-10-11T12:00:00Z

The weapon everyone remembers #

Anyone who played a certain popular Korean MMO remembers the Full Moon Sword: a mid-level weapon that players kept upgrading long after they could have replaced it. Dekiro's version is the Fullmoon set, one sacred weapon per school: the Fullmoon Sword (Blade), Fists (Iron Fist), Daggers (Shadowstep) and Staff (Sanctum). The lore makes them the heirs of the four weapons the founding disciples forged under a full moon to seal the First Shadow, and the game treats them accordingly:

They're the only items of Unique rarity, with 5 to 6 random bonuses, and never come from normal rolls.¹
They don't drop like normal gear. A level 28+ Shadow has a 0.3% chance per weapon; a boss 2%. When one drops, the game announces a "Special weapon" and it stands in a beam of light.
All four drop for everyone, and only their school can equip them. The rest can be traded or sold, so luck for one player can be a gift for a friend.

In the balance model, 98% of characters find their own school's Fullmoon weapon by level 90, at a median of about 13 hours of play (around level 45). That's late enough to feel like an event and early enough to carry you through half the game.

Problem: a level 30 weapon at level 90 #

A level 30 item that outclasses later drops has an obvious problem: either it stops mattering at 50, or it's so strong that nothing else matters. The design answer is to make the Fullmoon weapon a project rather than an item. Its power comes from upgrading it, on its own track, with its own currency.

Its own upgrade track #

Normal gear gets +12% base stats per upgrade level, with chances from 100% down to 20% and downgrades on failure from +5. The Fullmoon track is steeper on both sides:

+36% attack, armor, HP and mana per level (percentage stats +6%), so a +9 Fullmoon weapon is about a +9 level 60 weapon. That's the calibration target written into the data.
Chances fall from 95% to 15% at the last step, and failures from +5 drop a level.
Every step costs Shadow Shards and Cores, and the last three add Sunstone (2, 3, then 5), the desert glass that the top of every upgrade track needs.
Every step also needs the school's Moon Seal.

The seals are the interesting part. They come from a questline: finding your own school's Fullmoon weapon starts "The Sacred Weapon" (show it to your grandmaster), then nine seal quests unlock at levels 30, 30, 30, 35, 40, 45, 50, 55 and 60, one seal each. A seal is used up on success. On a failure, an early version destroyed it; a later design change made it kinder: "a failed Fullmoon upgrade keeps the Moon Seal but drains it." To recharge it you destroy Shadows, 5 for the first step up to 25 for the last:

"recharge_shadows": [5, 6, 8, 10, 12, 15, 18, 22, 25],

So a failure costs materials and gold and sends you back out to hunt, but never your progress through the questline. The model estimates what a full +9 takes on this track: about 270 attempts, 1,100 Shadow Cores, 230 Sunstone and all nine seals. That's over 100 hours of play, well past the 40-hour story. +9 Fullmoon is endgame by design. In a first playthrough the median character ends at about +6 or +7.

+7, +8 and +9: from a full glow to a few pixel sparks, after the human pointed out that in that MMO "you can see the sparkling"

Sparks, not glow #

In the old MMO a +7, +8 or +9 weapon is visible from across the map. Ours first glowed red, green and gold; the human corrected it: "shouldn't glow but have particular sparks around the weapon, not too many." Now a few pixel sparkles run along the blade in the step's colour, and at +9 a shine travels up the edge. Because weapons in hand are live 3D models on the sprites' hand anchors,² the sparkles are real and every player sees them.

The slow, certain road #

A 0.3% drop is a lottery, and some players never win lotteries. The human asked how the weapons can be found and with what chance, and decided on a second road with no luck in it, but no shortcut either:

We do the moonsteel fragments only. But it would be 1000 for sure. Shadows also don't drop these by default, also random.

Moonsteel Fragments drop from level 28+ Shadows (30% of the time, 1 to 3). With 1,000 of them and 300,000 gold, Forgemaster Kael at the forge camp in the Ember Wastes forges your own school's Fullmoon weapon. There is no bad-luck protection on the drop itself; the fragments are the protection. The balance pass sized the drop rate for the real speed of Shadow fights (one to three minutes each, after the combat retune), which comes to about 1,700 Shadows: 55 to 60 hours of Shadow hunting. The design doc calls it "the slow, certain road next to the 0.3% drop", and that's exactly its job: a guarantee for the unlucky that no one takes by choice.

Awakening: past +9, and why it never fails #

The human wanted more: "I guess I want them to scale up even further to end game." A +9 Fullmoon weapon is about a +9 level 60 weapon. By level 90 it would be outclassed. So after +9, the weapon can wake three times at a blacksmith:

Stage	Level	Needs	Base stats
Moon Awakening I	60	a quest at your grandmaster, 60 Moonsteel Ore, 10 Shadow Cores, 250,000 gold	x1.1
Moon Awakening II	75	the next quest, 50 Demon-Forged Essence, 30 ore, 15 cores, 600,000 gold	x1.45
True Fullmoon	90	the last quest, a Shard of the Sanctuary Stone, 30 essence, 20 cores, 1,500,000 gold	x1.72

A blacksmith's window for Moon Awakening II: the stats before and after, the quest, gold and materials (screenshot from before the balance pass raised the gold cost to 600,000)

Each stage keeps the weapon at +9 and multiplies its base stats on top of the upgrade scaling. The multipliers are calibrated against the normal weapons: stage I is about 14% over a +9 level 60 weapon, II about 13% over a +9 level 75 one, and the True Fullmoon about 7 to 15% over a +9 level 90 weapon and about 20% over the +9 level 86 raid weapons. That margin is the "Fullmoon premium": the reason to keep it.

And here's the design decision this post is named for: awakening always succeeds. The data's own comment says why: "the quest and the materials are the gate, a raid-only shard is never gambled." The Shard of the Sanctuary Stone drops only from the First Shadow at the end of the final raid. Putting that on a 15% roll would turn the best moment of the game into the worst one. The upgrade track is where the gambling lives; the awakening is where effort is rewarded with certainty. Two different feelings, on purpose, on the same weapon.

The awakening stages are school-bound (only the weapon's school can do the quests), and each one sends you somewhere: the first to Forgemaster Kael and the Cinder Shadows of the Ember Wastes, the second to the Hellmouth Rift, the third to the Shadowlands. The costs are the game's biggest gold sinks; the balance model's median character reaches level 90 with about enough gold for the first two.

How it looks #

Each stage shows: at I the moonsteel shines, at II it glows with a breathing light and moonlight motes, at III a full-moon halo stands behind it. Icons get a brighter tint, a glow or a moon ring, and the numeral. The name becomes "True Fullmoon Sword". It's the one place where the game breaks its "sparks, not glow" rule, because by then you've earned it.

The Fullmoon Sword at +9 asleep, then at Awakening I, II and III, at night

All four True Fullmoon weapons, one per school

And the raid needs one #

The Fullmoon weapons also tie into the story's end. The Shadow Citadel, the final raid, only lets you in with a Fullmoon weapon in your bag or in hand, any school's (companions follow without one). It's not used up. The questline calls this step the Moonsteel Gate. In play it means everyone at the final boss has held one of the four weapons at least once, even if it came through a trade. The raid's boss drops the Shard for the True Fullmoon (always), and his own Sovereign weapons at 6% each.

What we're not sure about #

The drop chance. 0.3% per weapon per Shadow, with 15 to 30 Shadows an hour in the model, gives a median of 13 hours. Players will feel the variance more than the median. The fragments are the answer, but 55 hours is a long answer.
The seal drain. Draining instead of destroying is gentler, but 25 Shadows to recharge the last seal after a 15% roll may still feel bad in practice. It's a data change if it does.
Gold. The awakening costs were raised during the balance pass to soak up late gold. If the economy moves after the playtest, these move with it.

All of these are numbers in data/upgrades.json and data/items.json, which is the point of keeping them there.

Takeaways #

Make a signature item a project. A weapon that grows with you for 60 levels is worth more than ten that replace each other.
Gamble on progress, never on rare rewards. Upgrade rolls can fail; a raid-only material must not be rolled away.
Give the unlucky a certain road. A long fixed path next to a lottery keeps the lottery exciting and fair.
Calibrate against the alternatives. "About a +9 level 60 weapon" and "20% over the raid weapon" are written into the data, so the premium survives the next balance pass.

What's next #

That's the end of the series so far. What's next for the game is the part no agent can do: the human's playtest, and the notes on how all of it actually feels.

Or from an edited save file: loading clamps them. ↩
The HD-2D post explains how. ↩

Making a Generated World Feel Lived In: Clutter, Houses, Cats and Townsfolk

2026-10-11T12:00:00Z

"Mostly low poly flat boxes" #

By day five every map had a town, roads, landmarks and monsters. Walking through them, the human put the problem plainly:

Can we add some more stuff, clutter like boxes and so on, to make the world more populated and lively. Right now buildings are mostly low poly flat boxes. No character.

— the developer

Generators are good at placing the important things: roads, houses, NPCs, spawns. They're bad at the unimportant things that make a place look used: the crate by the back door, the cart nobody unloaded, the laundry line. Those are exactly the things a level designer adds by hand in the last weeks. We had a generator and a day. The answer came in four parts, each its own agent: a building detail pass, a clutter kit with automatic dressing, ambient animals, and later more and better townsfolk, drawn as sprites.

A Vale street before and after the dressing pass

Houses with character #

The houses came from the Blender pipeline as clean low-poly shapes. The detail pass rebuilt them with what the eye looks for in East Asian architecture: tiled roofs with visible courses, timber frames on the walls, eaves, porches, window lattices, and trade signs on shops. Weathering (darker roof edges, grime at the foot of walls) is painted into vertex colours rather than textures, so every building in the game still shares one material. That matters for the GPU budget,¹ and it means a new house style costs nothing at runtime.

The kit now has five house styles plus a tall house, a teahouse, a shop, a storehouse, a granary, a farmhouse and a guard tower, and each comes in regional variants: desert, snow, swamp and ember. The map data still just says "a house, 7 x 6 m, here", and the game scales the model to the footprint.

Part of the building kit after the detail pass: tiled roofs, timber frames, porches, signs

Clutter by rules, not by hand #

The clutter kit is 53 models (crates, barrels, sacks, carts, market stalls, racks, nets, laundry, benches, planters, a noodle stand) from the same kind of Blender script. Placing them is the interesting part. tools/mapgen/dressing.py is called by every map generator, and its central idea is in its docstring:

How it reads as lived in, not scattered: every placement is a VIGNETTE (a small hand-made group: a crate stack with a sack against it, two barrels and a bucket, a woodpile, a bench with a planter...) set against a wall or a road edge, turned to it, with a little jitter. Each building ROLE has its own vignettes per wall: a smithy gets coal, racks and firewood; a farm hay, a cart, a trough and a fenced plot with a scarecrow; a dock fish racks and nets.

Random scatter looks random. Small authored groups, placed by rules, look like someone put them there. The rules are checked for every item as an oriented box: never on a road's walkable width, in water, inside a building or on a mountain, never in front of a door or in a gatehouse passage, never near a portal. If the first item of a group breaks a rule, the whole group is dropped, so you never get half a woodpile.

The dresser has a small vocabulary: dress a building by its role, a street edge, a market lane (two rows of stalls on an arc round a square), a food court (a noodle stand, tea tables under parasols), a camp (cook fire, bedrolls, crates, a banner), and the space behind an NPC (a stall behind a merchant, keeping their talk spot clear). The result is 2,129 placements across the maps, 918 of them in the Vale. They're drawn in batches per model and 48 m chunk with one shared material, so a dressed town costs about as much as an empty one.

Animals, and petting them #

Animals came next: cats, dogs (huskies in Frostpeak), chickens, goats, oxen, donkeys, a camel in the desert, frogs and herons by the water, and flocks of birds, gulls, crows, butterflies and fish. The Vale alone has 115 animal and flock entries. They're driven by small schedules with personality in the data: cats sit, groom and nap in sun spots and on doorsteps; dogs sniff about, lie by doors and trot after a nearby player for a few steps; chickens peck and scatter when you run through them; birds take off when you get close and land on roofs and fences.

Cats and dogs can be petted (press F). Your character kneels (a pet clip was rendered for the sprites), the animal reacts, a heart pops up, and you get a small buff called Content: 2% movement speed for five minutes. Two achievements count it, "Friend of Cats" and "Good Dog!". Every town has named pets: Mochi, Lady Plum, Old Bao and Tofu in the Vale, Kuma and Snowball the huskies in Frostpeak, Cinder and Bellows at the forge camp, Wick, alone in the Shadowlands. It's the cheapest feature in the game and possibly the most liked.

Petting a cat in the Sanctuary

Townsfolk with routines #

The Vale started with a few static NPCs and some townsfolk. A towns pass and a later NPC pass brought the count to 43 NPCs (merchants, the blacksmith, the four grandmasters, quest givers, Gate Keepers) and 66 townsfolk across the maps. Townsfolk aren't quest machines; they're there to make a town feel inhabited. Each one has a routine, a loop of stops with an activity and a duration: idle, work, sweep, farm, sit, chat, play, music, look. Old Marta sweeps the square. Two people meet by the well and have a conversation: lines alternate every 4.5 seconds once both have arrived.

"Did you hear? Old Marta saw a Shadow by the well last night." "Marta sees Shadows in her porridge."

They also have lines when you talk to them and barks when you pass, which can depend on your level, your school, or how far you are in the main story. Old Marta, before the finale: "Mud. Always mud." After it: "The shard sang all night. My knees stopped aching. Don't tell anyone."²

Three maps were deliberately left without a town. The Ember Wastes, the Hellmouth Rift and the Shadowlands keep only a gate camp with a few people, a fire and a dog or a cat. A lived-in world also needs places that aren't.

The busy-square benchmark: the Vale's NPCs and townsfolk plus 60 extra passers-by with seeded looks

From capsules to people #

For five days the NPCs were coloured capsules. The human had grown fond of them ("Not sure why I like the capsules so much. Somehow they grew on me. But I guess we have to replace them right?") and asked for "NPCs with different sizes, clothing and colour". They became sprites, rendered from the same character sheets as the player with seven NPC outfits and five hats. Named NPCs have fixed looks; townsfolk pick theirs from a regional palette with a random seeded by their id, so the same person always looks the same on every machine, and the desert's people dress differently from the Marsh's. Sizes and builds vary: a stocky or slender stretch of the card, and heights from 0.86 (an apprentice) to 1.14 (the Iron Fist grandmaster). The HD-2D post has the pipeline; a video memory test keeps a busy square (the Vale's 33 NPCs and townsfolk plus 30 passers-by) at 92.7 MB of sheets, inside a 128 MB budget.

The Vale square with capsule NPCs, and with the same people as sprites

None of it goes over the network #

All of this is presentation. Townsfolk, animals and flocks are built on every machine from the map data and run from the wall clock (the same 36-minute day as the sky) and a seeded hash, so every player sees the cat on about the same doorstep without any synchronization. There's no spawn, no sync and no collision. The architecture rule from CLAUDE.md is strict about it: "nothing may depend on where they stand."

There is one exception, and it's small: petting is a real action, so the server checks it, loosely, against where the animal's schedule says it should be (an 18 m "leash"), and relays the reaction to other players. Reactions that only concern you (a dog following you, chickens scattering) happen on your machine only, and then the animal walks back to where its schedule says.

Takeaways #

Place vignettes, not items. Small authored groups placed by rules read as lived in; scattered single props read as noise.
Make rules that drop whole groups. Half a woodpile is worse than none.
Detail in vertex colours, one material. Character without a draw-call or descriptor cost.
Presentation can be deterministic. A clock and a seed let every machine agree on where the cat is without a packet.
Give the cheap features names. A named cat you can pet costs almost nothing and makes a town somebody's home.

What's next #

The last post is about the weapons at the end of the road: the Fullmoon weapons, the +9 upgrade gamble, and why their final steps never fail.

The performance post has the story of why. ↩
The story post covers progress-gated dialogue. ↩

Balancing a 40-Hour Grind Before Anyone Plays It

2026-10-11T12:00:00Z

The target #

By day six the game had nine maps, 20 dungeons, 177 monster types and a story from level 1 to 88. It had never been balanced as a whole. Every system had sensible numbers on its own, picked when it was built. Before playtesting, the AI asked whether to do a balancing pass first, and the human answered with a target:

I would like to have about 40 hours of actual gameplay minimum potential. You don't need to test for that amount of time but estimate if level, gear and so on progression fits that timeline.

— the developer

Forty hours to level 90 and the end of the main story, with level, gear and upgrades moving along the whole way. The endgame (the Fullmoon weapons' awakening, a 1000-fragment forge, the weekly Demon Tower) may run longer.

Nobody can playtest 40 hours in an afternoon, so two agents worked in parallel on two halves of the question, and a third did the follow-ups:

The progression model: how long does a level take, where do the hours go, and does gear keep up?
The combat simulation: how long does a fight take, and how much does it hurt?

The two depend on each other (fight times feed the model), which is why the numbers below moved more than once.

Half one: a career in five-minute steps #

tools/balance/progression.py is plain Python. It reads the game's own data files and the constants of the GDScript rules (damage formulas, the combo chain, weapon types, skill multipliers and cooldowns, upgrade scaling, drop tables) and plays a character from level 1 to 90 in five-minute steps, sixty times over with different random rolls:

A hunting loop per zone: walk to the next Shadow (spacing from the zone's real area and Shadow count), kill the packs met on the way, break the Shadow while its waves come, move on. Mana limits skill use; incoming damage turns into potions and, if a fight outlasts what HP and potions hold, deaths.
Zone choice: the zone with the most XP per hour net of deaths, at most two levels below its monsters, with a small bonus for the zone the story points you to.
Dungeons once each at their entry level, quests with realistic overhead ("kill quests cost 35% of their grind time on top, talk quests 4-6 minutes"), daily bounties, world events.
Loot and upgrades: every drop rolled, gear worn if better, the rest sold; every blacksmith attempt rolled, failures and downgrades included, while gold and materials last.

The behaviour assumptions sit in one block at the top, each documented: efficiency 78% (time actually fighting), 4 seconds to engage a pack, 45% of enemy hits landing. They're the knobs a playtest should calibrate, so the model also prints how sensitive the result is to them:

Change	Hours to 30	to 60	to 90
as tuned	7.4	22.0	39.7
efficiency 65% (more downtime)	8.0	24.4	44.7
efficiency 90% (a focused grinder)	7.0	20.6	36.8
30% of hits land (better dodging)	7.4	21.8	39.9
6 s per pack to engage	7.6	22.6	41.4
dungeons slower (150 s rooms, boss 3x)	8.6	24.8	43.7

So "40 hours" really means "about 37 to 45 hours for reasonable play styles". That's the honest version of the number.

Half two: bots that fight #

tests/sim_combat.gd runs the real game code headless at about 70 times real time.¹ Bot players of a given level and school, wearing the gear a player of that level would have, fight every hunting zone, every boss and mini-boss in its own dungeon room, and every dungeon's trash rooms: solo per school, with two AI companions, and as a party of four. They step out of every telegraph after a 0.3 second reaction time, so what still hits them is what a careful player can't avoid.

The first run was sobering. From the report:

Nothing could hurt you, and nothing lived. Packs died in 0.5-1.5 s (the opening skill burst), normal monsters in 0.8-2 basic hits, Elites as fast as packs, a pack cost 0-5% HP. Player power grows ~x45 from level 1 to 90 [...], monster HP only x20, and the level 76-90 monsters were early-game stat lines.

Bosses died in 1 to 15 seconds solo. A party killed "Your Shadow" in 0.4 seconds and the First Shadow, the final raid boss, in 3.4. Iron Fist was about 1.5 times slower than the other schools. Some ranged attacks gave half a second of warning, which in a crowd meant about half the dodges failed. And every Shadow from level 50 on killed a careful solo bot about once, because the only healing potion past level 15 healed a flat 250 HP against health bars of 2,000 to 4,000.

What changed #

Monsters got their HP and damage fitted per level and band, boss HP sized for a fight of about one minute in a party and one to two minutes with companions, ranged telegraphs got minimum warning times,² and Iron Fist and Sanctum got skill buffs. After:

	Before	After
A pack, from aggro	0.5-1.5 s	4-7 s (plus walking and looting: 8-15 s a pack)
An Elite	as fast as a pack	6-8 s
A Shadow, solo	9-22 s	29-45 s
A boss, solo + 2 companions	1-23 s	78-136 s
A boss, party of four	under 1-33 s	44-61 s
The biggest single hit	up to 82% of max HP (on companions)	5-15% of max HP
Schools, pack kill time	up to 1.5x apart	0.9-1.15x of the mean up to level 60

One target from the brief had to give. "A normal monster dies in 2-4 hits" and "a pack dies in 8-15 seconds" can't both hold once skills scale: at level 40 a Blade's first second of skills is worth about 14 basic hits on everything in it. The sim kept the pack time and the time to kill a lone monster, so basic hits per monster now grow with level (4, then 7, 9, 11).

XP was the other half. With tougher monsters the old curve gave 25 hours to 90, not 40. The model's --fit mode searches for the data that hits a target curve, and the result was simpler than expected:

The XP curve became one power law, 80 x level^2.58 (from 80 x level^1.6 x (1 + 0.05 (level - 10))). The first level still costs 80, so the opening stays quick.
Monster XP follows monster HP: 0.1 x base HP for pack monsters, 0.11 x for Shadows. The combat pass had raised HP between 2x (early beasts) and 15x (the last map's shades) while XP stayed, so a Shade paid 12 XP for 831 HP. Tying XP to HP means XP per hour follows your damage everywhere, and no zone is a trap or a jackpot.
Quest XP is a share of the level bar at the quest's level: task quests 70%, travel and talk quests 25%, the final boss 150%.

Hours to reach each level: before (dashed), after the combat retune only (dotted), and after (solid, with the spread of 60 runs), against the target points

The economy, which the model caught #

Once the hours were right, the model's gold and gear charts showed problems no single fight would.

Gold piled up. Gold was "the monster's XP reward times a table factor", and XP now grew much faster with level than prices did. The median character ended the run with about 16 million unspent gold out of 18.5 million earned. The fix moved gold onto the monster's level (1.2 x (level + 2) times the table's factor), the same shape as item prices. Now the median character earns about 4.9 million, spends about 3.5 million (potions 2.25M, upgrades 1.1M), and reaches 90 with about 1.3 million: roughly the price of the first two Fullmoon awakenings, which became the late game's gold sinks. Income stays ahead of spending in every band; the tightest is the desert at 40-50, where Sunstone upgrades and stronger potions cost the most.

Gold over time for the median character: earned, spent and held

A 56-level armor gap. Body armor stopped at level 30, helmets at 26, shields at 20, until the level 86 raid set. The model's deaths clustered in the 66-85 zones, where under-armoured characters met the new monster damage. 41 new pieces in six sets (with models and icons from the Blender pipeline) now give every slot a tier at least every ten levels, and a test checks that.

Too many potions. With flat potions, the model drank 1,000 to 1,300 an hour from level 15 on, one every three seconds. Affordable, but "a lot of clicking". Red potions now come in four tiers that track max HP (80, 250, 700, 1,300 HP), monsters drop the tier of your level, and the model drinks 175 to 430 an hour: about one per pack.

Sunstone dried up. The top three upgrade steps need Sunstone from the desert, and the level-gap rule stops drops from monsters seven levels below you, so from level 57 the caravan was the only source and weapons stalled at +6/+7. The human's call: Sunstone "should also drop from Shadows after 55+". At 18% per Shadow, characters who stay on a normal weapon reach +9 at a median of level 69.

Gear over time for one median character: the weapon jumps to the Fullmoon weapon (a level 30 item that outclasses later drops) and back to new tiers, armor follows the level

The result #

Sixty simulated Blade characters reach level 90 in a median of 39.5 hours (the middle 80% between 37.9 and 40.9). The other schools land at 38.7 (Iron Fist), 40.6 (Shadowstep) and 39.0 (Sanctum). The shape is the one the human wanted from a popular Korean MMO: the first ten levels in about an hour and a half (quests carry the first five), then 15 to 30 minutes a level through the 20s, 25 to 35 minutes through the middle, and 35 to 55 minutes from 60 to 90. Every level from 1 to 90 has a hunting zone in its band, and each map is used for the levels it was built for.

Where the hours go, for the median character: about 26 hours of grinding, about 6 hours in dungeons (one clear each), about 5.5 hours of quests and 1.5 hours of daily bounties.

Where each level is spent: map by map, with dungeon runs in orange

Some numbers from the rare-item table, because a grind game is also a waiting game:

Item	Time to get (median)
Your own school's Fullmoon weapon (0.3% per Shadow, 2% per boss)	about 13 hours of play; 98% of characters by 90
1000 Moonsteel Fragments for the forge	about 57 hours of Shadow hunting: the slow, certain road
A +9 Fullmoon weapon on its own track	100+ hours: endgame

What a model can't tell you #

The report ends with its own list of risks, and the last one is the most important: "The model is a model." Efficiency, engage time, hit rate and potion use are guesses until a human plays. Party play, trading and other schools' Fullmoon weapons aren't modelled at all. Dungeon times are fighting time only, because the bots can't solve puzzles or walk mazes. And no simulation can say whether a 45-second Shadow feels like 45 seconds well spent.

What the model and the sim do give is a calibrated starting point. After the human's first playtest, the PLAY block gets their real numbers (how much of their time they actually fight, how many hits they take), the model reruns in a minute, and the data moves with it.

Takeaways #

Simulate the whole career, not a fight. The worst problems (16 million spare gold, a 56-level armor gap, Sunstone running out) only show up over 90 levels.
Tie rewards to the thing that costs time. XP from monster HP and gold from monster level keep zones honest when the combat numbers change.
Use the real code for combat. Bots that drive the same commands as players find the one-shots and the invincible phases that a spreadsheet can't.
Publish your sensitivity, not just your number. "40 hours" is really "37 to 45, depending on how you play".
The model is a model. Plan the playtest that calibrates it.

What's next #

Forty hours is a long time to spend in a world, so it should feel alive. Next: clutter, buildings, animals you can pet, and townsfolk who keep their own schedules.

The testing post has the setup. ↩
A shot's line at least 0.65 s, a burst's circle at least 1.1 s; a test now checks every ranged monster. ↩

A Story That Unfolds with Your Level: Murim Lore for a Grind Game

2026-10-11T12:00:00Z

The brief #

Grind games are not known for their stories, and players of the old MMO skip quest text faster than anyone. On day five the human asked for a lore anyway, with two conditions: "Come up with a lore that works with Chinese martial arts murim style and shadows. Make room for potentially adding some form of 'solo leveling' type of portals/rifts that we might want to build in the future." Five hours later came the question that turned the lore into a design: "Is the lore already built into quests? So that as we get closer to the level cap we discover more and more?"

That second question is the whole idea of this post. In a game where the main activity is killing the same kind of monster for 40 hours, the story can't compete with the grind. It can ride it: every ten levels you reach a new map, and every new map should know a little more than the last.

A lore that explains the game #

The first rule was that the lore must explain what the game already does, rather than add things the game would then need. The result, in short:¹

Three hundred years ago the greatest martial artist who ever lived, Yan Wuying, called the Shadowless, tried to become immortal by eating his own shadow. It worked, almost. He became the First Shadow. Four of his own disciples turned on him; they couldn't kill him, so they sealed him away behind a great jade stone that sang with their four arts. The seal is breaking.

Everything the player does maps onto that:

In the game	In the lore
Shadows, the stones you break	splinters of the First Shadow that fall through the cracks of the seal and corrupt what's around them
Four schools	the four disciples' arts: Blade, Iron Fist, Shadowstep, Sanctum
Safe zones, one town per map	every town is built around a shard of the broken Sanctuary Stone; shade can't cross its song
Portal shrines and waystones	gates and steles cut from the Stone, holding a sliver of shard
Levelling	breaking a Shadow releases shade; a disciple marked by the Stone refines it into strength
Skillbooks dropping from Shadows	techniques of masters who fell in the war, swallowed with their shadows, released when a splinter breaks
+7 to +9 sparks	moonsteel waking up
The player	a Wanderer who woke beside a broken Shadow with a silver crescent on their palm: a Moon Mark

The "one town per map" rule from the map rework suddenly had a reason, and so did the maps without a town: in the Ember Wastes, the Hellmouth Rift and the Shadowlands no shard was big enough, and the last people there camp inside a portal shrine. The Fullmoon weapons, the game's sacred late-game weapons, became the heirs of the four weapons the disciples forged under a full moon. The world is the Jianghu, the murim's "rivers and lakes", or rather one corner of it at the edge of the western kingdoms. That edge is also why the names are a mix: about half the people carry European names (Mira, Varek, Haro, Maud, Nyra) and half wuxia-style ones (Fang, Shen, Bai Yun, Ming), which the human asked for: "A fair mix of European names and maybe titles in Wuxia style". People of note carry an epithet under their name: Varek the Unbroken Edge, Haro the Hundred-Fold Hammer, Kael, Tender of the Undying Fire. A test checks that every name of every NPC, townsperson and companion is used only once.

The Cracked Seal: one questline, nine provinces #

The main questline, The Cracked Seal, has 25 quests from level 1 to 88, out of 87 quests in the game. It starts the moment you load in:

You woke in the Whispering Fields beside a broken black stone, with no memory of the night. A silver crescent burns on your palm and will not wash off. Show it to Elder Mira in the Sanctuary.

Each province adds one piece. The Marsh is a battlefield of the old war, drowned by a broken dam. The orc clans of Orc Valley were mountain tribes until a splinter in their sacred totem made them warlike, and their warlord thinks the shade is a god's gift. Duskmoor holds what's left of the cult that served the First Shadow. The Sunscar Desert was green until a king tried to burn every shadow away with a temple of mirrors and burned the land instead. Frostpeak's monks froze their own masters to keep a Shadow from waking in them. The quest text stays short and in-world, and it moves you on:

The Sun King failed because one light alone can't hold the dark; the seal was made from four arts. Iron Abbot Bao's order kept its last monastery on Frostpeak, and it stopped answering a year ago. Brother Ming waits at the Pass Hut.

Dungeons carry the local story. The Bog Witch's Hollow isn't "the swamp dungeon"; it's where the fen's old hedge-witch found a splinter first and put it in her pot, and has been brewing herself younger on its shade ever since. That's why the dungeon's puzzle is brewing her potion.

A lore tablet in the Shadow Woods: one chapter of the Vale's set, with its permanent bonus

People who remember what you did #

The cheapest way to make a world feel like it notices you is to let people change what they say. NPC data has a lines_after block: lines keyed by a story quest, used once you've completed it, the last one winning. Elder Mira has eleven of them. Right after you show her your palm:

A Moon Mark. I've only ever read about them. The old books get quiet about what happens to the Marked. I never noticed that before.

After you've learned what the Lightless Sect prays for:

The Sect prays for his forgiveness? I suppose everyone wants the same thing in the end. Someone to say it wasn't their fault.

The four grandmasters, the outpost leaders and others have their own. Townsfolk work the same way, one level down. They have barks, short lines they say as you pass, and a bark can need a quest done (or not done), a level range, or a school. After the finale, a town guard asks: "They say you've been to the Citadel, {name}. Is it true he had four faces?" A bard in the square sings "...and the one with the Mark went in where the four could not..."

The writing rule for all of it, from the NPC data's own documentation: people "only know what they'd know: hints and rumours, not lectures". Townsfolk "gossip and half-know things, they don't explain." Two of them gossip by the well in the Vale:

"She says it couldn't cross the square. Bounced off, like a moth on a lantern." "That's the shard. My gran said it sings the dark away." "And the new ones? With the moon on their hands?" "Heroes. They track mud everywhere."

A grandmaster's school window: the founder's story in two sentences, then the skills

Tablets: the parts nobody tells you #

Every world map has six to eight lore tablets, 58 in all, standing at landmarks and in the wilds. Each map's set tells one chapter of the old story, and the further from the start the map is, the deeper the secret: the Vale's set is "The Sealing", the Marsh's "The Eclipse War", the Shadowlands' "The Prison of the First Shadow". The Vale's first tablet:

I. Four Who Stood. Four disciples stood against the master who taught them: Ling Feng the Blade, Bao the Iron Fist, the Night Heron, Lady Yue of the Ninth Moon. They could not kill him. So they shut the door behind him.

Reading a whole set gives a small permanent bonus,² the way the classic's biologist quests reward collecting. It's modest on purpose: enough to make finding them worth a detour, not enough to make it mandatory. A tablet can also be a quest objective, or start a hidden chain. One of them does. It casts no shadow, and it's signed with a bird's track. What it starts is for players to find.

The finale, without spoilers #

At level 86 the questline reaches the Shadow Citadel, the First Shadow's prison and now his palace. It's the game's only raid: you need a Fullmoon weapon to enter, the fight splits the boss in a way that makes each school matter, and a "shade" meter climbs the longer you stand near him unless you break the splinters that feed it. The combat simulation says a party of four kills him in about four and a half minutes, and a solo player with two companions in about five and a half. Nobody has done it with real hands yet.

The avenue to the Shadow Citadel in the Shadowlands

The Throne of the First Shadow, before the fight

Killing him is not the end of the story. The last three quests are conversations, not fights, and they answer the question Mira asked at level 1: why the old books get quiet about what happens to the Marked. The answer reframes the whole game, from the first Shadow you broke to the reason you level so fast. We'll leave it there.

The door left open #

The human's second condition was room for "Solo Leveling"-style rifts later. The lore has that door built in: as the seal weakens, the Veil tears in places where no Shadow fell, opening pockets shaped by what they swallowed. Rift grades read from the colour of the light at their edge, rifts that aren't closed in time spill their monsters into the hunting grounds, and one school, it turns out, learned more of the First Shadow's art than it admitted. None of it is built. The last quest of The Cracked Seal ends by pointing at it, and the lore already plans every rift as a new seed of the dungeon generator.

How it was written #

The lore was drafted first as a document ("for the user's review", says its header) and then woven into the game by an agent: NPC lines, townsfolk barks and conversations, quest texts, item and skillbook flavour lines, achievement names, world event banners. Later agents extended it as they built: every dungeon batch added its paragraphs to LORE.md and its boss's backstory to its spec. The music fits the same arc: the Shadowlands and Citadel tracks quote the Vale's opening motif, slowed down and bent out of key.³

The biggest risk with an AI writing lore at speed is contradiction, so the rules are mechanical where they can be: one LORE.md that everything cites, names unique by test, and NPCs who are only allowed to know what they'd know.

Takeaways #

Make the lore explain your systems. If your monsters spawn from stones and your towns are safe, say why. Players will believe a world whose rules have reasons.
Gate dialogue on progress, not just quests. A few keyed lines per NPC make the world notice you, for very little text.
Let ordinary people half-know things. Gossip carries more lore than lectures and is more fun to read.
Put the deep story where the curious look. Tablets, a hidden chain and a twist at the end reward the players who read, and cost nothing to the ones who don't.
Leave a door open, in the lore first. The rifts aren't built, but the world already knows they're coming.

What's next #

A story that unfolds with your level only works if levelling takes the right amount of time. Next: how a progression model and a combat simulation aimed the game at 40 hours.

docs/LORE.md has the long version. ↩
40 max HP for the Vale, up to 250 HP and 4% damage against Shadows for the Shadowlands. ↩
The music post has that story. ↩

Twenty Dungeons from One Generator: Sequence Graphs, ASCII Rooms and Solvers That Say No

2026-10-11T12:00:00Z

The question #

On day five, with one hand-built dungeon (the Crypt) and a second one in progress (the Sun Tomb), the human asked: "Should we build a procedural dungeon generator? [...] I guess it's ok to build such a tool once and not at runtime." They linked two open-source generators as inspiration and then, a few minutes later: "I would not use the tools I linked, we should build our own. Come up with 20 dungeons [...] Happy to have a [popular Korean MMO] inspiration there including some puzzles. I would also like to have some form of labyrinth as a puzzle for some dungeons."

Two decisions in that request shaped everything. Offline, not at runtime: the generator produces a map file that a human reviews and the game loads like any other map, so a bad seed never reaches a player. And puzzles: a generator that only places rooms and corridors would be easy; one that places a lever behind a door that the lever opens would be a bug factory. So the generator had to prove every dungeon could be finished.

The pipeline #

tools/dungeongen/ is plain Python (3.13 and Pillow, about 3,600 lines). A spec per dungeon becomes the map JSON the game reads, plus a top-down overview PNG to review:

python tools/dungeongen/dungeongen.py crypt_of_whispers             # spec seed -> map + overview
python tools/dungeongen/dungeongen.py crypt_of_whispers --search 12 # overviews of 12 seeds, writes no map

A seed is a layout: the same spec and seed always give the same dungeon. The workflow is to generate a sheet of seeds, pick one by eye, and write it into the spec.

Four seeds of the same spec (the Red Hand Mines): same rooms, locks and maze rules, different layouts

1. The spec is a sequence graph #

A dungeon starts as rooms with roles (entrance, fight, key, puzzle, miniboss, treasure, maze, boss) and edges between them, optionally with a lock. Here are the Crypt of Whispers' edges:

{"from": "entrance", "to": "ossuary", "flow": "E"},
{"from": "ossuary", "to": "charnel", "gap": [4, 7]},
{"from": "ossuary", "to": "whispers", "flow": "E", "lock": {"lever": "winch"}, "gate_id": "portcullis",
	"label": "Chained Portcullis", "hint": "Chained shut. A winch somewhere must hold the chain."},
{"from": "whispers", "to": "warden", "lock": {"puzzle": "whisper"}, "gate_id": "crypt_door", "look": "door",
	"label": "Sealed Crypt Door", "hint": "The door will not move while their shadows are bound. Listen to the whispers."},
{"from": "whispers", "to": "reliquary", "lock": {"any": [{"flag": "whisper.flawless"}, {"boss": true}]}, ...},
{"from": "warden", "to": "lords", "lock": {"cleared": "warden"}, "gate_id": "bone_gate", "label": "Bone Gate", ...}

Locks are a small condition language: a lever, a solved puzzle, a cleared room, a key, a flag, the boss dead, and any / all / not to combine them. The reliquary above opens if you lit the candles without a mistake or if you killed the boss: a reward for doing the puzzle well, without locking out a party that didn't. The game evaluates the same language at runtime, so what the generator proved is what the game checks.

2. Rooms: templates or shapes #

Set-piece rooms are drawn as ASCII templates, one character per 2 m cell, so a room can be sketched in a text editor. This is the Hall of Whispers, the Crypt's puzzle room:

.......DD.......
.O............O.
................
....C......C....
................
................
D......W.......D
D..............D
................
....C......C....
................
.O..b......b..O.
................

D marks door sockets, C the candles of the sequence puzzle (numbered in reading order), W the whispering ghost who gives the hint, O pillars, b bone piles. The legend has 30-odd marks by now: levers, chests, pressure plates, light-beam emitters, fox statues, valves, spike traps, dart slits, war gongs, a cauldron and its ingredient rack, watcher monks, anvils, sluices. Ordinary rooms are generated from a shape instead (rectangle, L, round, octagon, pillared hall, maze) with decor, monsters and devices placed by rules: "a lever, far from the doors".

3. Layout and corridors #

Rooms go on a grid of 2 m cells, grown from the entrance in tree order: each child on one side of its parent with a corridor gap and a sideways jog. If a child fits nowhere, the search backs up and moves earlier rooms. Corridors are routed with A* over 2x2-cell windows, so they're exactly 4 m wide, and turns cost extra. One rule matters more than it looks: a corridor never touches another room or corridor except at its two doorways, so a locked door can't be walked around. Extra loop edges are routed afterwards for shortcuts.

4. Validation, or: the solver says no #

This is the step that makes puzzles safe. With every gate shut, the floor must split into exactly the groups of rooms that the open edges join (no leaks through a wall). Every room is one piece, every spawn stands on floor, there's a player spawn and a boss. Then the lock solver runs: a breadth-first search over states of (room, flags). Events inside rooms set flags: clearing a room's monsters, pulling a lever, solving a puzzle, standing on a pressure plate (which come back up, so those flags clear again), killing the boss. Gates latch open once their condition holds.

The solver must reach the boss, visit every room, and find no soft-lock state: no reachable state from which the boss can no longer be reached. With plates, valves and toggles that's a real risk, not a formality. If any check fails, the generator prints the problems, draws them on the overview, and refuses to write the map. The biggest search so far is the Hall of Mirrors: about 47,000 states, no soft lock.

The Ossuary of Bells as the generator draws it: rooms by role, locks in red, the shifting maze in the middle

Six kinds of labyrinth #

The human asked for labyrinths. A plain maze is a chore, so each labyrinth dungeon got a rule that changes how you read it, and each rule got its own solver:

Dungeon	Kind	What the generator proves
Foxfire Maze	guide: a white fox runs the true way; false foxes lead into dead ends	the fox's path is a real walk through the braided maze, and every false fox starts on a fork of the true path and ends in a dead end
Red Hand Mines	dark: you see a few metres; kindled totems clear the dark; minecart shortcuts	the solver walks rail lines both ways while their condition holds
Ossuary of Bells	shifting: a bell tolls 1 to 3 times, and every bone wall marked with that many skulls turns	from every reachable (cell, wall state), the exit can still be reached whatever the bell tolls; every passage opens at some point; the way through needs 2 to 5 knells
Mirage Palace	illusion: fake walls and fake openings; a carried Sunstone lantern shows the truth	trusting your eyes alone never gets you through, and the false maze shows a way that isn't there
Glacier Halls	ice slide: on Mirror Ice you slide until something stops you; boulders can be pushed	every door reaches every other, the main crossing takes a set range of slides, and no state is stuck
Hall of Mirrors	split: twin mazes; a lever in one opens bars in the other; mirrors between them	the 47,000-state search above, with a party or solo

The shifting maze is a good example of how much the solver carries. Walls sit on pivots; each blocks one of two passages next to a post. A knell of k tolls turns every wall of section k. The planner places the walls on a stamped maze where both passages are floor, then a 0-1 breadth-first search over cell x section bits checks the whole space. The game then plays the same rules the solver checked; for the ice, the commit message calls them "shared rules with the generator's solver".

The Ossuary of Bells in play: the knell has tolled, and the walls marked with that many skulls are turning

The Mirage Palace without the lantern, and in its light: false walls turn into lines of light, hidden ones show as gold glass

Glacier Halls: on Mirror Ice you slide on the grid until a wall, a rock or a boulder stops you

The Foxfire Maze: the white fox casts a shadow; the false ones don't

Mechanics as data blocks #

The game side follows the same rule as skills: a new mechanic is a new building block plus a test, never a script for one dungeon. The generator writes a mechanics block into the map (devices, puzzles, rules, objectives), and a server-side DungeonScript runs it. By the 20th dungeon there were 31 device kinds: gates, levers, plates, light beams, valves and water, spike traps, gongs, totems, mine carts, a cauldron and ingredients, shifting walls on a bell, illusion walls and a lantern, ice and boulders, watcher monks with sight cones, sluices and anvils for lava, rising lava, warps between floors, key carriers, seals, waves to survive, chests. Rules are "when this condition holds, do these actions", and actions are things like spawn, say, open, set a flag, toll the bell or curse everyone nearby.

The blocks compose. The Bog Witch's Hollow asks you to brew her potion: three mini-bosses each drop an ingredient, her recipe book reads out an order rolled per instance, and a wrong ingredient boils over into a curse and three hexed toads. That's an ingredient device, a cauldron device, a brew puzzle and a curse action, none of which knows about witches.

A few blocks that came out of specific requests:

Walls 6 m high. The first remake had low walls, and the human pointed out the obvious: "The walls of the dungeons need to be higher. Otherwise people will just look over." With tall walls, the camera side is cut away near your character so you can see in.
Weekly chests. Each Demon Tower floor has a coffer that opens once per character per week.¹ An echo of that MMO.
A boss copied from you. At the end of the Hall of Mirrors, "Your Shadow" steps out of the great mirror with the look, school, skill ranks and stats of the strongest player in the room, darkened.

Wall cutaway on the camera side: before and after the cleanup

Your Shadow: a boss built at runtime from the strongest player present

The twenty #

#	Dungeon	Levels	Map	Idea
1	Crypt of Whispers	8-12	Sanctuary Vale	light the candles in the order the ghosts whisper
2	Foxfire Maze	12-16	Sanctuary Vale	follow the fox with a shadow
3	Drowned Temple	16-20	Shadow Marsh	three valves raise and lower the water
4	Bog Witch's Hollow	20-24	Shadow Marsh	brew the witch's potion in the right order
5	Goblin Warren	22-28	Shadow Marsh	spike traps, alarm gongs, a king warded by shamans
6	Red Hand Mines	28-32	Orc Valley	dark maze, light totems, mine carts
7	Orc Stronghold	32-38	Orc Valley	break the gate under waves; generals left alive buff the warlord
8	The Black Abbey	38-44	Duskmoor	unseen haunts until a candle finds them; break the ritual's anchors
9	Ossuary of Bells	40-44	Duskmoor	count the tolls; the walls turn
10	Sun Tomb	46-52	Sunscar Desert	light beams and pressure plates
11	Spider Hollows	44-50	Sunscar Desert	webs, egg sacs, a boss that drops from the ceiling
12	Mirage Palace	46-50	Sunscar Desert	carry the lantern; trust nothing else
13	Glacier Halls	52-56	Frostpeak	slide on the ice, push the boulders
14	Frost Monastery	54-60	Frostpeak	stay out of the monks' sight; braziers against the cold
15	Old King's Forge	58-62	Ember Wastes	route the lava to heat the anvils without cutting off your path
16	Caldera Depths	62-65	Ember Wastes	climb before the lava does
17	Demon Tower	66-76	Hellmouth Rift	nine floors, a task each, weekly coffers
18	Chamber of Seals	70-75	Hellmouth Rift	break seven seals in the order the litany gives
19	Hall of Mirrors	80-85	Shadowlands	twin mazes; your own shadow at the end
20	Shadow Citadel	86-90	Shadowlands	the final raid

Nineteen come from specs. The Sun Tomb was hand-built before the generator existed; its walls were later regenerated from the same kit, and its plates, beams and doors were merged into the same mechanic blocks so there's one system, not two.

The Hall of Mirrors' twin mazes, connected by mirrors and levers that open each other's bars

How they were built #

After the generator core and the Crypt remake as a pilot, the dungeons were built in batches of three or four per agent, at most about four agents at once. Each dungeon came with a spec and a seed picked from a search sheet, its own kit theme (20 themes, 458 pieces from a parameterised Blender script, merged per chunk at load), monsters reusing existing bodies recoloured with an accessory, a boss with its own silhouette, its own music track, a portal by a landmark of its map, tests, and a folder of screenshots: the gate, every room, each mechanic in action, the boss and the overview.

What we don't know yet #

The generator proves a dungeon can be finished. It doesn't prove it's fun, and nobody has played most of them yet. The combat simulation from the testing post can fight every boss and every room, but its bots walk in straight lines, so anything behind a maze, a rail line or deep water ends "stuck", and dungeon run times need a human with a stopwatch. Every batch report ends the same way: timings, damage and puzzle difficulty are "a first guess, not playtested". That's honest, and it's the next step.

Takeaways #

Generate offline, review by eye, load like any map. A seed you picked is a layout you saw.
Write dungeons as graphs with locks, and use the same condition language in the generator and the game.
Make the generator refuse. A solver that rejects soft-locks is cheaper than a bug report from a party stuck behind a door.
Give every labyrinth a rule, and every rule a solver. Six kinds of maze, six proofs.
Mechanics are blocks. A witch's brew is four generic pieces with a story on top.

What's next #

Twenty dungeons need a reason to go into them. Next: the lore, and a story that unfolds as you level.

Monday 00:00 UTC on the server's clock, saved with the world. ↩

HD-2D on a Budget: Rendering 3D Characters into 8-Direction Palette Sprites

2026-10-11T12:00:00Z

Why sprites at all #

The world of Dekiro is 3D: terrain, buildings, trees, an orbit camera. For four days the player was a coloured capsule, and a parallel line of work tried to replace it with a real character built by a Blender script. Six drafts came and went within a single day: flat primitives, a bulky "Valheim hulk", proportions modelled on a popular Korean MMO, then anime-style characters with haori jackets, masks and glowing eyes. Each got closer and none got there. The human's notes on one draft: "the faces are bad, like really bad", "the hair looks also like rubber". Procedural faces at that size don't forgive anything.

Then the human sent a pixel-art sprite as a reference: "This is the style of pixel art sprite I'm looking for for the character. Proportions especially are better there, same for shadings." That suggested the look players know as HD-2D,¹ a 3D world with 2D characters standing in it. Two approaches ran in parallel: drawing the sprites directly as 2D art, and rendering the existing 3D characters into sprites, the way games like Dead Cells turned 3D animation into pixel art. The verdict on the drawn ones was not printable. On the renders: "the rendered 3d to 2d one look way better."

That choice has a big practical advantage for a team without an artist. The 3D characters already had a rig, clips and a whole armor progression. Rendering them means every animation, every armor tier and every hairstyle comes from data, and adding a clip is a re-render, not a week of hand-drawn frames.

One of the 3D character drafts in the game, with toon shading and outlines

The town square with capsules and with the first sprite characters

A style target before a pipeline #

Before rendering anything, the AI wrote a small pixel-art "style target" generator in plain Python: hand placed pixels for a character in five armor tiers, plus the colour rule every later step follows. The rule is a hue-shifted ramp in the OKLCH colour space. A material's colour becomes five steps:

step:      0 deep   1 shadow  2 base  3 light  4 highlight
dL:       -0.25    -0.125     0      +0.095   +0.175     (OKLab lightness)
chroma x:  0.80     0.95      1.0     0.92     0.72
hue shift: 22 deg   11 deg    0       8 deg    15 deg
           toward COOL (h=265, blue) for 0/1, toward WARM (h=75, gold) for 3/4

Shadows don't just get darker; they lean blue. Highlights lean gold. Near-grey colours get a little chroma so their shadows still lean cool, dark colours are lifted so dark cloth keeps five distinct steps, and the outline is a dark version of the colour, never black. The same rule exists three times,² and they're kept in step on purpose: a red roof and a red armor plate land on the same five colours.

The pixel style target: the Blade school's five armor tiers, drawn by code to pin down proportions and the colour rule

Step 1: Blender renders data, not pictures #

tools/blender/render_sprites.py drives Blender headless. The camera is orthographic at the game camera's pitch (28 degrees down), the character is turned to 8 directions, and every second frame of a 24 fps clip is rendered (12 fps, the classic pixel-art rate; idles at 6 fps). Rendering uses EEVEE with one sample and no anti-aliasing, at 4x the final size.

Two tricks happen here. First, a sprite-only proportion pass scales pose bones in the render scene only: head 1.35x, bigger hands and boots, heavier shoulders, shorter legs, about five heads tall. The rig, its bone names and the clips stay untouched. Second, the renders aren't pictures. Each layer gets two passes:

albedo: every material as flat emission of its base colour;
data: red = the light (a white surface lit by one sun fixed to the camera's upper left, so every direction is lit the same, as drawn sprites are), green = a material id, blue = how much a pixel belongs to a hand.

The post step needs to know what each pixel is, not just its colour.

Step 2: the paper doll #

A character isn't one sprite but a stack of layers that share one skeleton and one set of clips:

body: skin, the painted face, bare hands and feet;
hair_<style>: each of the 9 hairstyles is its own layer, rendered white so the game can tint it;
eyes: two glowing pixels;
armor_default (the outfit worn with no armor) and five armor tiers;
NPC outfits and hats (more below), and a pre-rendered weapon for far-away characters.

While one layer renders, the others act as holdouts: they cut the layer where they'd be in front. One more flag solves a classic paper-doll problem. Hair that sits more than 3 cm behind the head, as the camera sees it, is marked as back hair. The game draws back hair under the armor and the rest over it, so every hairstyle works with every armor without rendering combinations.

Paper-doll layers in the prototype: body, body + armor, body + armor + weapon

Step 3: post-processing in palettes #

tools/blender/sprite_post.py (numpy, scipy, PIL) turns 4x raw frames into pixel art:

Each final pixel is a 4x4 block of raw pixels. The dominant material wins the block. Glow seams on the armor are thinner than a pixel, so they win a block from just 2 of its 16 samples and survive as 1 px lines.
Per layer and material, a k-means in OKLab finds up to three base colours (an indigo haori and its wave pattern, say), and each base colour gets a ramp by the rule above.
The light value picks the ramp step. Tiny specks are merged, eyes become 2 px glowing dots, hands become clean "mittens" with one outline, and a selective 1 px outline is drawn round the silhouette.
The result is not RGB but 8-bit palette indices. Index 0 is transparent; ramp r owns indices 1+6r to 6+6r: outline, deep, shadow, base, light, highlight. A palette image per layer holds the colours.

The walk cycle in 8 directions (rows) after the post step

Then every frame is trimmed to its opaque box, duplicates are dropped,³ and frames are shelf-packed into 2048 px pages. An atlas.json records, per clip, direction and frame, where the pixels are, where the feet are, where each hand is (with depth and roll), and which frame the blow lands on.

Why palettes pay off: recolouring at runtime #

Because every pixel is "ramp 3, step 4" rather than a colour, recolouring is rewriting six palette entries. That turned three expensive features into cheap ones:

Hair and eye colours are picked at character creation (12 hair and 10 eye presets, or free colours) and changed later at Mirei the Stylist. The game builds a ramp from the chosen colour with the same rule.
Rarity trims. An armor's trim ramp is rewritten with the item's rarity colour: plain for Common, blue for Magic, yellow for Rare, orange-gold for Legendary, crimson for Unique.
School dyes. The plan was a different armor cut per school: samurai, monk, ninja, priest. That's four times the rendering. The human cut it to one line: "Just take the same armor but add other colors from the school." Every school now wears the Blade cut, and its dye ramps are rebuilt per school at runtime. Each dye ramp stores its offset from the rendered dye as ratios of lightness and chroma plus a hue shift, so a dark trim stays dark relative to a light dye in every school. The tier 5 glow seams are an emissive ramp in the school colour.

One armor cut, four schools: tiers 1 to 5 for Blade, Iron Fist, Shadowstep and Sanctum, recoloured at runtime

Every hairstyle over every armor: back hair under the armor, front hair over it

Step 4: in the game #

SpriteVisual replaces the capsule node (logic and visuals were separate from day one, so nothing else changed). It is one upright card turned toward the camera. The row is picked from the angle between the actor's facing and the camera, snapped to 45 degrees with a little hysteresis so it doesn't flicker at the boundary. The card is lit by the scene's sun and moon through a fixed normal, so sprites get darker at night and dim under cloud shadows like everything else. All layers composite in one shader. A flat silhouette of the sprite is projected on the ground as its shadow.

Weapons are the one part that stays 3D. Near the camera (within 25 m) the real weapon model is drawn into a small viewport with the same orthographic camera as the render, on the sprite's own pixel grid, and placed on the hand anchor of each frame, in front of or behind the body depending on that frame's hand depth. That's what lets a +9 katana sparkle and every weapon model appear in hand without rendering weapons into the sheets. Far away, a pre-rendered weapon layer takes over.

Animations come from the clip list: idles, walk and run by speed, a three-hit combo per weapon type (sword, twin daggers, a two-handed staff, fists), 13 shared skill motions such as spin, dash and slam, hit, death, and a kneeling "pet" emote. Every attack strikes on frame 4, the same convention the monster models use, so the damage number appears as the blow lands. In total each body has 51 clips. One small change came from playing it: "I feel like the player model can be a bit bigger?" Sprites are now drawn 1.25 times their rendered size. Purely visual: hitboxes didn't change.

Two tier-5 armors at night: the glow seams in the school colour are an emissive palette ramp

NPCs: the same sheets, different clothes #

On day six the townsfolk and NPCs, still capsules, got the same treatment. The human liked the capsules ("Somehow they grew on me") but wanted "NPCs with different sizes, clothing and colours". The answer was more layers, not more characters: seven NPC outfits (farmer, merchant, apron, monk, guard, traveller, noble) and five hats, rendered for the NPC clips only, plus NPC-only clips for talking, sitting and working.

A look is pure data: body, outfit, hat, hairstyle, hair, skin and eye colour, cloth and accent colour, a size and a build (stocky or slender, a stretch of the card). Named NPCs have fixed looks. Townsfolk give an archetype, and the rest is picked by a random number seeded with the person's id from their region's palette, so a person looks the same every time and on every machine, and the desert's people don't look like the Vale's. Grandmasters wear tier 5 armor in their school's dye with glowing seams.

A grandmaster in the Sanctuary: tier 5 armor in the Blade school's dye, rendered from the same sheets as the player

The budget #

Sprites move the cost from geometry to texture memory, so the budget lives in tests:

Per character: a dressed character (body, one hairstyle, the heaviest armor, eyes) loading every clip one weapon type uses must stay under 19 MB. It's 18.3 MB for the male body and 16.4 MB for the female. Before the sheets were packed in banks (the shared clips, then each weapon set's own, so a character only loads pages for clips it can play), it was about 22 MB.
Per town: every NPC and townsperson of the Vale plus 30 passers-by, 63 people, against 128 MB: they need 92.7 MB. Looks share pages, and the palettes per look are cached.
On disk: about 20 MB of PNG per body.

Rendering is the slow part: the full pipeline for both bodies takes about 50 minutes with 14 Blender jobs in parallel. Re-rendering only the armor layers, or only the NPC layers, reuses the other raw frames.

Headless machines (dedicated servers and tests) never load any of it; they keep the capsule.

What didn't work at first #

Faces. At about 100 px tall, a face is a few pixels. The final characters wear a mask or scarf, and the eyes are two glowing pixels in the chosen eye colour. It reads better than any modelled face did.
Hands. Rendered hands at that size became noise, so the post step redraws them as mittens with one outline (gloves included).
Dyes too close to the trim. On some schools the rarity trim almost vanished into the dye; the trim is now lifted when it gets too close.
Builds without the atlases. The first exported build drew capsules: the atlas .json files weren't in the export filter. CLAUDE.md already warned about data/*.json; the sprites' JSON lived elsewhere.

Takeaways #

Render 3D into 2D if you have rigs and no artist. Every clip, armor tier and hairstyle stays data.
Render data passes, not pictures. Material ids, light and masks let the post step make decisions an image can't.
Think in palettes. Indexed pixels turn hair colours, rarity trims and school dyes into rewriting six entries.
One colour rule, implemented everywhere it's needed, keeps sprites and 3D models in the same world.
Put the memory budget in a test. It's the number that grows quietly.

What's next #

Characters needed somewhere to fight. Next: a dungeon generator that writes specs as sequence graphs, stitches ASCII rooms into layouts, and refuses to save any dungeon its solver can't finish.

Or older: Ragnarok Online. ↩
In the Python post step, in GDScript for runtime recolouring, and as a shader include for the world's sprite-style shading. ↩
2,836 unique of 3,528 body frames for the male body. ↩

From One AI Session to a Team: Coordinator and Subagents

2026-10-09T12:00:00Z

The single-session era #

For most of its first three and a half days, Dekiro was built the way the earlier posts describe: one Claude Code session at a time, working through tasks in order. The human set direction and playtested, and the AI implemented, tested, screenshotted and committed. It worked well: well over a hundred commits, from an arc attack against training dummies to a 2.6 x 3 km map with music, multiplayer and fishing.

It had one obvious limit: everything was serial. While the session was composing music, it wasn't fixing the grass. While it was building item icons, the map waited. Some tasks, like rebuilding every monster model or designing a full UI theme, are long and mostly independent of everything else. Doing them one after another meant long stretches where the human had nothing new to look at.

The new setup #

On day four the human asked for a different way of working: the main session should spawn subagents freely and act as coordinator and quality control. The working notes from that day put it this way: review, test, screenshot and fix before work reaches the human, give agents self-contained briefs with file boundaries, and commit only after checking.

In practice there are two kinds of Claude sessions:

The coordinator holds the conversation with the human and the overall picture. It writes briefs, launches subagents, reviews what comes back, runs the full test suite, looks at the screenshots, fixes or sends back what isn't right, and makes the commits.
Subagents each get one job with clear boundaries: which files they may touch, which they must not, what "done" looks like, and how to verify it. They work in parallel and report back. They don't commit.

The human talks to one session, as before, and sees more finished work per hour.

The coordinator workflow: briefs out, reports back, gates before a commit

By the numbers #

The coordinator's session log records every subagent it launched: 70 in three days.¹ Their one-line descriptions read like the changelog of the second half of this series: "Compose original game music", "Roll out organic quadrupeds", "Move tests to the test map", "Prototype 2D sprites in 3D world", "Fix D3D12 descriptor heap exhaustion", "Dungeon generator core + Crypt remake", "Story wave: First Shadow raid + finale", "Balance: combat simulation + tuning". The update of this very blog is number 70.

The commit history changed shape with it. Day four had 76 commits. Days five and six had 11 between them, each a reviewed batch of several agents' work; the largest touches 941 files.

The first job: music #

The first subagent job was the music. It suited delegation well:

Self-contained: the composing tools live in tools/audio/ and write files to audio/music/. Nothing else in the game had to change except a "music" key per map.
Verifiable without the game: each render prints its length, loudness and true peak, so the coordinator can check the numbers before anyone listens.
Clear taste gate: whether it sounds right is the human's call. The Vale theme was the reference.

The result was "Music for every map": nine new tracks, a shared synth library and one data module per map, in one commit. Since then every dungeon got a track the same way, 30 in total.

Briefs are the new CLAUDE.md #

A subagent starts cold, just like every session did before. It doesn't know the conversation, the decisions of the last hour, or why the open world was switched off. CLAUDE.md gives it the project's rules, and the brief gives it the task. A good brief turned out to need:

The goal in one paragraph, including what the human has already decided ("NO shovel/digging: the user disliked it").
File boundaries: "you own these paths; read anything; don't touch these."
Facts it can't discover: the human's preferences, the reference to match, numbers agreed in conversation.
How to verify: which tests to run, which screenshots to take, and what to report.
What not to do: don't commit, don't kill Godot processes you didn't start (the human's editor often runs alongside), wrap test runs in timeout.

The plan said file boundaries would keep parallel agents apart. They mostly did. The interesting failures were all at the edges, in the files every feature has to touch: the one big test file, shared shader includes, the boss AI, the map generators. A selection from the agents' own reports:

The test file. Every feature adds tests to tests/run_tests.gd, so every agent edits it. Two dungeon agents each added a helper function named _room_mid. GDScript doesn't allow two functions with the same name, so the whole test file stopped parsing for every agent until one renamed theirs (_caldera_mid).
Shared shader includes. An agent named a new uniform in the sprite shader shade. A shared cloud shadow include already used shade as a local variable. The shader stopped compiling, and the player and every NPC turned into a white rectangle in the human's running game. Headless tests don't compile shaders, so every suite still passed. Another agent's first screenshots of its ice dungeon caught it; the human caught it first.
Other people's half-finished work. Agents regularly saw failures that weren't theirs: a parse error in main.gd from a change in progress, a test failing in another agent's area, a physics warning from a map being regenerated. Without a rule, an eager agent "fixes" the other agent's file and both lose.
The class cache. When one agent adds a new class_name script, the other agents' test runs fail to compile until Godot's class cache is refreshed. "Can't find class Waystone" is not a bug to fix; it's an --import to run.
Rule slips. Several agents edited shared files with short Python rewrite scripts instead of the exact-match Edit tool, which the briefs asked for. Their own reports flagged it. Nothing was lost, because the scripts refused to write when the target text had changed, but it's exactly how a silent overwrite would happen.
The machine. Godot test runs and Blender builds are heavy, and they all run on the human's PC. One map agent wrote in its report that it couldn't measure the frame rate cleanly "with several agents running".

The rules that came out of it #

Each of those turned into a line in the briefs (and some into CLAUDE.md). The current shared brief for a batch of parallel agents includes, in substance:

Who owns what. Each agent owns its files outright. Shared files (data tables like items.json, the test file, the boss AI) are "edit carefully with Edit (never rewrite whole files)", re-reading first if the file changed. In the test file you ADD your own test_* methods and touch nobody else's.
Unique names for anything you add to a shared space. Temporary screenshot scripts get names like tests/_tmp_<job>_*.gd and are deleted afterwards. The _room_mid collision showed the same goes for helper functions.
Don't fix what isn't yours. "If something fails in files you didn't touch, it may be another agent's work in progress: say so, don't fix it." The coordinator sorts it out after merging.
Refresh the class cache (--import) before believing a "missing class" error.
Shader edits need a windowed check. Headless runs never compile shaders; after any shader change, take a windowed screenshot and grep its log for errors.
At most about four agents at once on the human's PC, and anything that measures performance runs when the others are done.
Report what you touched outside your lane, including slips. Agent reports end with a list of the shared files they edited, and several of the most useful lines in them were confessions.
Nobody but the coordinator commits. After merging a batch, the coordinator runs the full suite, the smoke runs and the network bots, and looks at the screenshots, before one commit with a message that lists everything in it.

Work also got split along the lines that collide least. Maps went out two per agent, each writing its own generator file, with portal links fixed afterwards by one script. Dungeons went out three or four per agent, each with its own spec, kit theme, monsters and music, and shared building blocks added with tests.

Eight maps rebuilt by four agents in parallel, two maps each: one town, roads, landmarks, mountain borders

Approval gates #

The second rule of the setup: the human approves designs before builds. A subagent can produce something in an hour that would take a day to undo. So anything with taste in it goes through a design step first. Three gates from day four, and how they ended:

One of the 3D character drafts next to the old capsule. None of them shipped as 3D models

UI: the HUD and windows were drafted as a design in Claude Design and shown to the human; the approved lacquer-and-gold pixel style was then built into the game's UI code and textures. It landed.
Monsters: the organic rebuild that replaces the "Pinocchio doll" primitives² went to the human as a single wolf first, then rolled out to every four-legged monster and critter. It landed.
Player characters: real 3D player models to replace the capsule. This gate did its job by saying no six times. The 3D drafts never shipped; the human chose to render them into pixel sprites instead, which became the HD-2D post.

The HUD before and after the UI rebuild

The monster pilot: a wolf before and after the organic rebuild

Quality control: before and after #

The coordinator's main job is to catch problems before the human sees them. The checks are the same ones a single session used, applied to someone else's work:

The full test suite (now about 13,800 checks) plus the grep for engine errors, after merging each agent's work. A subagent may have run only the tests near its own files.
Smoke runs of the menu and the game, and the network bots when anything networked changed.
Before and after screenshots for every visual change, looked at side by side. A shader change that "should only affect monsters" deserves a shot of a building too, and after the white-wall incident, a windowed run.
A read of the diff: scope (did it stay inside its files?), the CLAUDE.md conventions (static typing, no := on Variant expressions, command_* methods only, content in data), and new tests for new behaviour.

It doesn't catch everything. The white wall reached the human's screen before the coordinator saw it. Balance numbers from the agents are "a first guess, not playtested", and every dungeon report says so. What the setup guarantees is that problems are found by one session looking at everything, not by the human finding them one by one.

What changes for the human #

Less waiting, mostly. Instead of one stream of commits, there are several lines of work moving at once, and the human's time goes where it matters most: approving designs, judging feel, playtesting. They don't supervise each agent. The coordinator is the single point of contact and the single gate to the repository.

It also changes how decisions are kept. Since a brief has to be self-contained, a preference the human states in conversation gets written down sooner and more precisely: first in a brief, then in a design, then in an approval, instead of living only in a chat.

A meta note #

This blog series is itself a subagent job, twice. A subagent wrote the first drafts from the git history; another (number 70) updated them three days later, counted everything again in the repository rather than trusting the old numbers, and wrote the newer posts. The coordinator reviews them, and the human decides what gets published. Most of what you've read comes from commit messages and agent reports, which is a good argument for writing both well.

What we'd tell another team #

Parallelize the long, separable jobs. Music, a UI theme, a model rebuild, two maps, three dungeons: each has its own files and its own way to verify. Keep the tightly coupled work in one place.
Expect collisions at the shared files, not the owned ones. The test file, shared shader includes and central AI code are where parallel agents meet. Give those files explicit edit rules.
Write briefs like contracts. Goal, boundaries, facts, verification, don'ts. A cold-start agent only knows what you give it.
Ask agents to report their slips. An honest "I edited a shared file the wrong way" is cheaper than finding it in the history.
Gate on taste, not on code. Let the human approve designs; let the tests approve code.
One committer. A single reviewer between the agents and the repository keeps the history clean and the rules enforced.

What's next #

The posts after this one cover what the parallel phase built: the HD-2D sprite pipeline, the dungeon generator, the story, the 40-hour balance model, the living towns and the Fullmoon weapons. What's left after that is the part no agent can do: the human's playtest, and the notes on how all of it feels.

35 on day four, 24 on day five, 11 on day six, the later ones much bigger. ↩
See the Blender post. ↩

A Stardew-Style Fishing Minigame in a Server-Authoritative ARPG

2026-10-09T12:00:00Z

Why fishing? #

Grind games need a breather. Between Shadow runs it's nice to stand at a lake at night and try for the Golden Carp. Fishing sat on the backlog early on, and lakes were placed with it in mind.¹ The model was Stardew Valley's reeling minigame: a vertical meter, a fish that darts up and down, and a bar you lift by holding a button. Keep the fish inside the bar until the catch meter fills.

The interesting part is not the minigame itself. It's how a reflex game fits into an architecture where the server decides everything, and where a client should never be able to say "I caught a Golden Carp" and be believed.²

The loop #

Equip a Fishing Rod on the hotbar (or right-click it in the bag) and use it near water:

Cast: the bobber lands on the nearest fishable water within 9 m of where you aim.
Wait: after 2.5 to 7 seconds, a fish bites. A "!" appears.
Hook: press attack within 1.1 seconds.
Reel: win the minigame, and the fish goes into your bag.

Moving more than a metre, getting hit or dying reels the line in.

Casting at Mirror Lake: rod, line and bobber

A bite: press attack within the hook window

Fish are data #

Which fish bites depends on the liquid, the map and the time of day, all in data/fish.json:

{ "item": "silver_eel", "liquids": ["water", "swamp"], "time": "night", "weight": 14, "difficulty": 55, "behavior": "dart" },
{ "item": "golden_carp", "liquids": ["water"], "time": "night", "weight": 2, "difficulty": 80, "behavior": "floater" },
{ "item": "ghostfin", "liquids": ["swamp"], "time": "night", "weight": 3, "difficulty": 85, "behavior": "dart" },
{ "item": "oasis_koi", "liquids": ["water"], "maps": ["sunscar_desert"], "time": "any", "weight": 12, "difficulty": 65, "behavior": "floater" },

There are 14 fish, from the Old Boot (difficulty 5, it just sinks) to the Ghostfin that only bites in the Marsh at night. Time of day comes from the shared WorldClock, a 36-minute day read from the wall clock, so everyone on a server agrees whether it's night without any network traffic. Fish are ordinary items and can be sold.

Mirror Lake at night, when the Golden Carp and the Silver Eel bite

The minigame is pure logic #

FishingMinigame is a RefCounted with no nodes, no input and no drawing. One method advances it:

## One step; holding = the reel key is down. Returns 1 when caught, -1 when it got away, else 0.
func step(delta: float, holding: bool) -> int:
	elapsed += delta
	bar_speed = clampf(bar_speed + (LIFT if holding else -GRAVITY) * delta, -MAX_BAR_SPEED, MAX_BAR_SPEED)
	bar_pos += bar_speed * delta
	var top := 1.0 - bar_size
	if bar_pos < 0.0:
		bar_pos = 0.0
		bar_speed = -bar_speed * BOUNCE if bar_speed < -0.3 else 0.0
	elif bar_pos > top:
		bar_pos = top
		bar_speed = 0.0
	_move_fish(delta)
	if fish_inside():
		progress += FILL * delta
	else:
		progress -= (DRAIN + difficulty * DRAIN_PER_DIFFICULTY) * delta

Holding the key accelerates the bar up; letting go lets gravity pull it down, and it bounces a little off the bottom. The fish picks a new target every so often and swims toward it. Difficulty (0-100) sets how far and how fast it moves, and behaviour shapes the moves: smooth, dart (bigger, quicker jumps), sinker (drifts down), floater (drifts up) or mixed.

Keeping it pure pays off twice. The UI (FishingWindow) just draws its state each frame. And it can be tested in a tight loop with no scene at all, which matters below.

The reeling meter: keep the fish inside the green bar until the catch meter fills

Who decides what #

Here is how the work splits between server and client:

The server runs the state machine in the Fishing node: cast, bite timer, hook window, and the result. It picks the fish (with its item, difficulty, behaviour and a seed), and it never tells the client which item it is until the catch.
The client plays the minigame locally with that difficulty, behaviour and seed. Reeling is a reflex game, and a round trip per frame would make it unplayable online.
The server checks the result for plausibility. The client reports a win or a loss. The server knows when reeling started, and a win that came too fast is rejected:

## Reeling can't be won faster than this (the minigame needs ~3.2 s at best).
const MIN_REEL := 1.6

	if not won or _since < MIN_REEL:
		_send("escaped", ["It got away..."])
		return
	var item := ItemDb.create(str(bite["item"]))
	if item == null or actor.inventory == null or not actor.inventory.add_item(item):
		_send("escaped", ["Your bag is full: you let it go"])
		return

Is this cheat-proof? No. A modified client could always "win" after two seconds. But it can't choose the fish, can't catch faster than the rules allow, can't fish without a rod or away from water, and can't skip the bite timer. For fishing in a co-op game, that's the right amount of server authority. The hook window gets a 0.4 s grace for network delay, so playing online isn't harsher than playing alone.

Every step (cast, bite, reel, caught, escaped, cancel) goes out as an event to the peers who can see the player, so other players see your rod, the line and the bobber dipping. FishingFx draws all that: the rod in hand, a line, a bobber that bobs, dips hard on a bite and shakes while reeling, and splashes. It's purely cosmetic, like every visual node in the game.

The catch in the bag, with a Golden Carp tooltip

Testing a reflex game without a human #

Because the minigame is pure logic, a test can play it. FishingMinigame even ships an autopilot(), "a decent player" that holds while the fish is above the bar's middle and looks a little ahead:

func autopilot() -> bool:
	return fish_pos - (bar_pos + bar_size * 0.5) - bar_speed * 0.3 > 0.0

The test then checks the properties that matter:

	var easy := FishingMinigame.new(12.0, "smooth", 7)
	var result := 0
	while result == 0 and easy.elapsed < 60.0:  # keep the bar's middle on the fish
		result = easy.step(1.0 / 60.0, easy.autopilot())
	_check(result == 1, "following the fish catches it")
	_check(easy.elapsed >= Fishing.MIN_REEL, "no catch faster than the server allows (%.2f s)" % easy.elapsed)

The second check is important. It proves that an honest, good player can never be rejected by the server's plausibility rule. If someone later tunes FILL up and makes catches faster than MIN_REEL, this test fails. Other checks in the same test: doing nothing against a hard darting fish loses it within 10 seconds, every fish in the data is a real item, the Ghostfin bites only at night, regional fish stay in their region, and there's no fishing in lava.

A second test runs the full flow on the Proving Grounds test map: no rod, no fishing; a cast onto the pond; the bite; the hook; the catch arriving in the bag.

Gamepad #

Fishing arrived on the evening of day three. Later that night the game got gamepad support, which touched fishing too: on a pad, the reel is the attack button like everything else. The GamePad node remembers whether the last input came from a pad, and hints then name pad buttons (A/B or Cross/Circle depending on the controller). While a window is open, the pad drives its buttons: the d-pad moves focus, A presses, LB/RB switch tabs, and B closes it. Bindings live in a rebindable pad column in the Controls settings.

Takeaways #

Split reflex from authority. Let the client run the twitchy part with server-chosen parameters and seed; let the server own the outcome and check it for plausibility.
Keep minigames pure. A step(delta, input) function is trivial to draw, network and test.
Give tests an autopilot. A bot that plays "decently" lets you prove that honest players never trip your anti-cheat rules.
Time of day from the wall clock gives every player the same world without any network traffic.

What's next #

The next post is about how the work itself is organized now: a coordinator session with parallel subagents, approval gates, before/after reviews, and what happens when four agents edit one repository.

The backlog names Mirror Pond, Fisher's Pool and the Moonlake. ↩
The screenshots in this post are from the day fishing landed, when the player was still a placeholder capsule. The character is a pixel sprite now; the fishing code hasn't needed to change, because the rod, line and bobber are their own visual node. ↩

Composing Original Music in Python: Thirty Tracks, One Motif

2026-10-09T12:00:00Z

Why synthesize? #

Music is the asset a small team most often licenses. We didn't, for the same reasons as everything else in this series: the game's content is built from code, so it stays original, consistent and changeable. Every track in Dekiro is composed as data and rendered by a Python script with numpy and scipy into a looping Ogg file. The first set had eleven: one per map, a calmer variation for the Vale's town, and one for the Crypt dungeon.

Every one of the 20 dungeons has since got its own track too, so the game now ships 30, all made the same way.

The music was also the first job given to a parallel subagent, a separate Claude session working in its own lane while the main session coordinated.¹

A song is data #

A track is a Python dictionary: tempo, reverb length, a seed, chord voicings and a list of sections. Each section is a chord progression (one chord per bar) plus the parts that play over it. Here is the opening of the Sanctuary Vale theme:

	"sanctuary_vale": {
		"bpm": 76, "reverb": 2.6, "seed": 11, "chords": CHORDS,
		"sections": [
			("Dm Bb F C", [("pad", None, 1.0), ("drone", None, .8), ("arp", "eighths", .9), ("bass", "whole", .45), ("koto", INTRO_HINT, .9)]),
			(PROG_A, [("pad", None, .6), ("arp", "eighths", .5), ("bass", "roots", .6), ("koto", MOTIF_A, 1.0)]),
			(PROG_A, [("pad", None, .6), ("arp", "eighths", .5), ("bass", "roots", .7), ("koto", MOTIF_A, 1.0),
					("flute", ANSWER_A, .8), ("drums", "full", .8)]),

Melodies are written as text, NOTE:beats[:velocity], with r for rests and | for bar lines:

MOTIF_A = """
r:1 A4:.5 C5:.5 D5:1.5 F5:.5 | D5:3 r:.5 C5:.5 | A4:1 C5:.5 A4:.5 G4:1 F4:1 | G4:3 r:1 |
r:1 A4:.5 C5:.5 D5:1.5 G5:.5 | F5:2 D5:1 F5:.5 G5:.5 | A5:1.5 G5:.5 F5:1 D5:1 | D5:1 A4:3
"""

The parser checks that every bar adds up to four beats and fails with the offending bar if it doesn't. It sounds pedantic, but it's the musical version of a type check, and it catches the most common mistake when writing melodies as text.

The engine (music_lib.py) and the songs are separate. The library holds the instruments, the arrangement engine and the mastering. Each map's track lives in its own module in tools/audio/music_tracks/. It didn't start that way. The Vale theme came first as a single script, and when nine more tracks were needed, it was split into a shared library and one data module per map. After that, a new track means new data for the same engine.

The instruments #

Every instrument is a function that returns a numpy array. A few highlights:

Koto (and the oud in the desert) is a Karplus-Strong plucked string: a burst of noise fed back through a delay line one period long, with a filter that keeps the tuning exact. The docstring:

def pluck(f, ring, vel, rng, bright=1.0, vibrato=0.0, pos_frac=0.13):
	"""Karplus-Strong string: block-wise feedback (blocks of one period) so numpy does the work.
	The loop filter is the classic two-point average convolved with a linear fractional delay,
	which keeps the tuning exact. vibrato > 0 adds a guzheng-like left-hand wobble after the attack."""

The trick in "block-wise" is that the feedback loop runs one period at a time instead of one sample at a time, so numpy can vectorize it.

Bells and glass are FM synthesis: a carrier with a modulator at a non-integer ratio, which gives the inharmonic shimmer of metal.
Flute, shakuhachi and ney are additive tones with a scooped onset, delayed vibrato and band-passed breath noise.
Choir is detuned saw waves with vibrato, sent through vowel formant filters.
Percussion (taiko, frame drum, rim, finger cymbals, anvil, heartbeat) is shaped noise and pitched sweeps.

Notes are slightly humanized in timing and velocity, and the seed makes every render repeatable, so a rerun gives the same music unless the data changes.

One motif, eleven moods #

To tie the maps together, every track quotes the Vale's opening pickup, the three notes A C D.² Each map transposes and bends it into its own scale, as the track headers record:

Map	Mode, tempo	How it quotes the motif
Sanctuary Vale	D minor pentatonic, 76 BPM	The source: koto, then bamboo flute
Shadow Marsh	E "in" scale, 58 BPM	B D E opens the koto
Crypt of Whispers	A minor + phrygian Bb, 72 BPM	Lone koto plinks "half-remember" E G A
Orc Valley	A minor pentatonic, 92 BPM	Every horn call opens with E G A
Duskmoor	C minor + phrygian Db, 66 BPM	The koto opens with G Bb C
Sunscar Desert	D hijaz, 84 BPM	The ney's opening line borrows A C D
Frostpeak	B minor pentatonic, 70 BPM	The flute opens with F# A B
Ember Wastes	D phrygian, 80 BPM	A C D on horn, "dragged down a step into Eb"
Hellmouth Rift	C phrygian dominant, 96 BPM	G Bb C in the choir, "bent into Db"
Shadowlands	sliding away from D minor, 54 BPM	The Vale theme itself on a detuned, sagging piano

The Shadowlands track is the payoff. It's the place the Shadows come from, and its music is the Vale's own theme slowed down and "heard through the Shadows", over chords that slide away from D minor. Players who have heard the Vale theme for 80 levels should recognize it, and feel that something is wrong with it.

Twenty more, one per dungeon #

When the dungeons arrived, each one got a track written for its mechanic, by the same engine and the same text notation. A few examples, from the track headers:

Bog Witch's Hollow: "a crooked nursery tune gone off in the damp", a detuned music-box piano in D phrygian with a raised third now and then ("the witch's wrong note"), drips, glass plinks and a heartbeat drum stirring the pot.
The Demon Tower: a stair motif in the low horns "that climbs a step every time it comes back", because the dungeon is nine floors that each get worse.
The Hall of Mirrors: glass phrases answered by their own retrograde, the music of a dungeon made of two mirrored mazes.
The Shadow Citadel, the final raid: "the Shadowlands' twisted Vale motif grown into a march", with temple bells tolling four times, one per school. A detuned piano states the motif bent out of the scale; then a horn answers with it straight, "the four disciples' version".

So the motif from the first village still closes the story, more than eighty levels after you first heard it in its home key.

Mixing: reverb from noise, loops without seams #

There is no plugin chain. The reverb is a synthetic stereo impulse response: decorrelated noise for each channel, with the highs decaying faster than the lows, and a 22 ms pre-delay. The whole wet signal is convolved with it in one oaconvolve call.

Game music loops, and a loop that clicks or drops its reverb tail at the seam is worse than no loop. The trick is in how the render ends. Everything is rendered past the loop end (16 seconds of notes and reverb tail) and then wrapped back onto the start:

	n_loop = int(round(length * RATE))
	out = np.zeros((n_loop, 2))
	pos = (np.arange(len(full)) - PRE) % n_loop
	for ch in range(2):
		out[:, ch] = np.bincount(pos, weights=full[:, ch], minlength=n_loop)

The tail of the last chord rings into the first bar, just as it would if the piece had really been played twice. Every later processing step is circular for the same reason: the high-pass filter, the section loudness rider, and the limiter's gain smoothing all use mode="wrap", so nothing happens at the seam that doesn't happen everywhere else.

The end of the Vale theme played into its start: no click at the seam

Mastering to a standard #

Each track is mastered to -15 LUFS integrated loudness, measured by a small implementation of ITU-R BS.1770 (K-weighting, 400 ms blocks, gating) right in the library. A limiter holds sample peaks at -1.5 dBFS. Then comes a step many people skip. Vorbis encoding can overshoot on sharp plucks, so the script decodes the Ogg it just wrote, measures the true peak with 4x oversampling, and trims and re-encodes until it's at or below -1 dBFS:

	# Vorbis overshoots on sharp plucks: decode, measure the true peak, trim and re-encode until <= -1 dBFS
	for _ in range(4):
		write_ogg(path, audio)
		over = true_peak_db(sf.read(path)[0]) - TRUE_PEAK_DB
		if over <= 0:
			break
		audio = audio * 10 ** (-(over + 0.1) / 20)

Each render prints a report line with length, loudness, true peak and file size, so a check is one glance.³

Render reports: length, loudness, true peak and file size per track

In the game #

MusicPlayer plays the track of the zone you stand in, or else the map's, with a 1.5 s crossfade between two players. The Vale's town has its own calmer variation (62 BPM, temple bells, quarter-note arps). Walking out of the gate crossfades into the field theme. A map can name its music before the file exists; the player stays silent until it's there.

Just outside the north gate, where the town music hands over to the field theme

Sound effects: from placeholder tones to a synthesizer #

When this series was first drafted, sound effects were far behind the music. data/sounds.json mapped every event (swing, hit, skill by tier, rare drop, level up, UI click) to real files when they existed, and to a placeholder tone generated in code when they didn't:

"rare_drop": { "files": [], "bus": "SFX", "pitch_jitter": 0.0, "synth": { "wave": "sine", "from": 880, "to": 1760, "length": 0.45, "volume": 0.4 } },

Only the Shadow stone breaking had a designed sound ("a sharp crack, a heavy low thud, then crumbling debris that settles, with a little room echo"). The placeholder system meant the game had sound everywhere from day one, and real sounds could slot in by adding a file path.

They did, a few hours later, from the same approach as the music. tools/audio/sfx.py synthesizes every effect from noise, oscillators and filters, with "an East Asian touch (wooden clacks for the interface, gongs and temple bells for milestones, plucked silk strings)". The plucks reuse the music library's Karplus-Strong string. Frequent sounds get several variations, which the game picks at random (never the same one twice in a row) and jitters in pitch. Loudness is set per category from the loudest 100 ms of each sound, and peaks are limited to -1 dBFS. Footsteps change with the ground, fists sound different from swords. At the time of writing, 62 of the 63 sound events have synthesized files (126 WAV files in all); the one still on a placeholder tone is waystone travel.

Like the music, the script can render a "listening sheet": a waveform and spectrogram per category plus a montage WAV, so the effects can be reviewed at a glance before anyone listens to them in the game. The human listens and decides; the numbers just make sure nothing clips or drowns out the rest.

Takeaways #

Treat songs as data. A small arrangement engine plus text melodies lets you write, review and diff music like code. Bar-length checks catch typos.
Make loops circular end to end. Render past the end, wrap the tail onto the start, and keep every later filter circular.
Measure loudness and true peak after encoding. The encoder can undo your limiter.
A shared motif ties a world together for almost no cost, and it lets you tell a story with the last map's music.

What's next #

The next post is about a calmer side of the game: fishing, a Stardew-style minigame inside a server-authoritative ARPG.

See the coordinator post, number 11. ↩
Scale degrees 5, flat 7 and 1 in D minor. ↩
One honest note: libsndfile's Vorbis encoder crashed on one huge write, so write_ogg feeds it a second at a time. ↩

Chasing the Valheim Look, and Leaving It for HD-2D

2026-10-09T12:00:00Z

The target #

Valheim is a good reference for a small team. Its models are simple, but the world looks rich, because of a handful of tricks applied everywhere: low-resolution textures with hard pixels, dense foliage made of textured cards, grass you walk through, strong light and atmosphere, and a slightly soft lens. None of it needs detailed models. That made it a perfect target for a game whose every model comes from a Python script.

The human set the direction and judged every step. The AI implemented each piece as a shader or a small script, took screenshots, and iterated. Almost all of it landed in one night, in about twenty commits.

1. Pixel texels on everything #

Our models have no textures: each material is a flat colour from the Blender builders. To get Valheim's pixel texture feel without painting textures, we generate the texels in the shader. pixel_noise.gdshaderinc picks the plane a surface faces, cuts it into a grid of texels, and tints each texel a little lighter or darker, warmer or cooler, in two sizes:

vec3 pixel_tint(vec3 col, vec3 pos, vec3 n, float density, float strength) {
	vec3 an = abs(n);
	vec2 uv = (an.y >= an.x && an.y >= an.z) ? pos.xz : ((an.x >= an.z) ? pos.zy : pos.xy);
	vec2 t = uv * density;
	vec2 c = floor(t);
	float fine = pn_hash(c);
	float coarse = pn_hash(floor(c / 4.0) + 57.0);
	float v = (fine - 0.5) * 0.65 + (coarse - 0.5) * 0.35;
	float texel_px = max(fwidth(t.x), fwidth(t.y));  // texels per screen pixel
	float k = strength * (1.0 - smoothstep(0.3, 0.9, texel_px));

Two details make it work. The texels are computed in the model's own space, scaled to metres, so they stick to a monster as it walks instead of swimming across it. And the effect fades out where a texel gets smaller than a screen pixel (fwidth), so distant surfaces don't shimmer.

A small script, PixelLook, applies it after a model loads. It swaps every plain material for the pixel shader with the same colour, roughness and glow. Materials with transparency stay untouched, and so, after the latest commit, do painted textures: they keep their pixels and get the rest of the shader's features (rim light, fade-in, cloud shadows).¹

Town houses with PixelLook off and on

2. The ground, and a precision bug #

The ground shader mixes several noise scales into patches, dry and damp areas, grain and tufts, and paves safe zones with flagstones. For a while it had a bug that made the ground look flat, with almost none of the intended variation. The fix touched two things, how the shader got the world position and the hash function, and the comment on the hash explains the main cause:

// Arithmetic hashes on the lattice cell wrapped into a small range (no sin(): the joined world
// sits ~10 km from the origin, where sin() of the huge arguments loses all precision).
float hash(vec2 p) {
	p = mod(p, 289.0);
	vec3 p3 = fract(vec3(p.xyx) * 0.1031);
	p3 += dot(p3, p3.yzx + 33.33);
	return fract((p3.x + p3.y) * p3.z);
}

The classic fract(sin(dot(p, ...)) * 43758.5453) hash is fine near the origin. Our maps sit thousands of metres from it.² At those coordinates the GPU's 32-bit sin() of a huge argument returns garbage that barely changes between neighbouring cells, so the noise flattens out. Wrapping the cell into a small range first and using an arithmetic hash fixed it. Every hash on world coordinates in our shaders now works this way.

3. Leaf cards #

The first trees had crowns made of solid low-poly blobs. Valheim-style crowns are made of many small quads, each carrying a cut-out texture of a leaf cluster. The Blender builder now scatters those cards through each crown, and tools/flora_textures.py draws the leaf textures as pixel art with Pillow:

Light, nearly neutral colors: the game multiplies them by each plant's tint (map color + jitter). Transparent between the leaves; the cluster thins out toward the edge so a card's square never shows.

Cards have a known weakness: their flat normals make crowns look like a pile of paper. The fix is to point each card's normal out of the crown's centre, so the crown lights like one soft volume (the commit calls them "cloud-like normals"). The follow-up commit was called "Crowns all leaves (no solid blobs), wider and fuller". Flowers, reeds, ferns and dead-tree twigs became cards too.

Foliage between the camera and your character dissolves in a dither pattern, using a global shader uniform, focus_position, that holds where the character stands. The human asked for "solid trees, but see in deep woods", so only leaves dissolve and trunks stay solid.

Broadleaf crowns built from leaf cards

4. Grass #

Grass took the most iterations: dense curved blades, then pixel texels on the blades, then textured cards with a pixel blade texture, then tall and short patches, thin spots, thinning toward roads and leaning cards. The current shader has a few ideas worth stealing:

Stepped gradient: the root-to-tip colour moves in steps that match the texture's pixel rows, so it reads as pixel art instead of a smooth fade.
Backlight: BACKLIGHT = col * 0.6 * height_k; lets the sun shine through the tips.
Distance thinning with a dither, skipped in the shadow pass (PROJECTION_MATRIX[3][3] < 0.5 is true only for the perspective camera), so grass shadows don't vanish with distance.

The part players notice most is that grass parts around characters. The shader gets a list of "pushers" (up to 64, each a position and a radius) and bends blades away from them and down:

	for (int i = 0; i < pusher_count; i++) {
		vec2 away = VERTEX.xz - pushers[i].xz;
		float d = length(away);
		float k = 1.0 - smoothstep(pushers[i].w * 0.35, pushers[i].w, d);
		if (k > 0.0 && abs(VERTEX.y - pushers[i].y) < 2.5) {
			push += away / max(d, 0.05) * k;
			press = max(press, k);
		}
	}

Trails came almost for free. The script drops a trampled spot every 1.2 m behind each character and passes those spots to the shader as extra pushers whose radius shrinks over eight seconds. The grass stands back up, slowly at first.

Walking through the tall grass of the Whispering Fields

5. Cloud shadows without clouds #

Seen from a third-person camera you rarely look at the sky, but you always see the ground. Big soft shadows drifting over the land say "clouds" more than any skybox. So there are no clouds, only their shadows: a shared shader include that every ground, grass, plant and model shader calls.

float cloud_light(vec2 xz) {
	if (cloud_shade.z <= 0.0) {
		return 1.0;
	}
	vec2 p = (xz - cloud_shade.xy) / 110.0;  // clouds some 30-80 m across
	float n = cl_noise(p) * 0.6 + cl_noise(p * 2.3 + 5.2) * 0.28 + cl_noise(p * 5.1 + 1.7) * 0.12;
	float cut = cloud_shade.w;
	float shade = smoothstep(cut - 0.06, cut + 0.06, n);  // soft edges
	return 1.0 - shade * cloud_shade.z;
}

MapLook moves the pattern every frame through one global uniform. About a third of the ground is in shade at any time, 22% darker. It's off at night and in dungeons. Because it's the same function everywhere, a shadow passes over the grass, the path and a monster at the same moment.

The fields at noon, with cloud shadows on the ground

6. The lens, depth of field, and light #

The last layer is the camera:

A lens shader draws over the 3D view: the picture blurs slightly toward the corners (sampling a higher mip level), darkens a little there and splits its colours at the edges. The field of view widened to 60°. Tuning took three quick follow-up commits: "only at the outer corners", "half the corner blur", "a bit more color fringing". It's a Video setting.
Depth of field focused on the character softens the far distance. Also a toggle.
Lighting: a 36-minute day from the wall clock, a moving sun with golden mornings and evenings, a bright silver moon with its own shadows, AgX tonemapping, bloom, SSAO and volumetric fog by quality setting.
Rim light on monsters: a soft blue-white Fresnel edge (gold for Elites) so they read in tall grass and at night. It's an instance uniform on the shared model shader, so monsters don't need materials of their own.
Scale: Map 1's beasts are drawn 1.8 times larger (the giant rat 2.6 times), and small monsters at least 1 m tall.

A full frame with the lens on: soft corners and a slight colour fringe

The same fields at night: moonlight on two wolves and a boar

What it cost #

All of this went on top of the performance budget from the previous post. Most of it is cheap by design: the pixel texels and cloud shadows are a few hash lookups per pixel; grass and leaves are cut-out cards with no extra geometry; rim light and the fade-in are instance uniforms. The expensive parts (grass shadows, volumetric fog, SSAO) are tied to the Graphics quality setting.

Then the characters changed everything #

Everything above was in place by the morning of day four, and the world looked good. The characters didn't. The player was still a capsule, and a separate line of work was trying to replace it with a 3D character from a Blender script. It went through six drafts: flat primitives, a "Valheim hulk", proportions borrowed from a popular Korean MMO, then anime-style characters with outfits, masks and glowing eyes. The human's feedback on one of them is a fair summary of the problem: "the faces are bad, like really bad", "the hair looks also like rubber". A procedurally modelled face at that size, in a 3D world, never looked right.

The human then shared a pixel-art sprite as a reference: "This is the style of pixel art sprite I'm looking for for the character. Proportions especially are better there, same for shadings." Two approaches were tried in parallel. One drew the sprites directly as 2D pixel art, in a design tool and from code. The other kept the 3D characters and rendered them into 8-direction pixel sprites. The design-tool drawings were rejected in no uncertain terms.³ The renders won: "the rendered 3d to 2d one look way better."

That decision is the subject of its own post. What matters here is what it did to the world: a lit, outlined pixel sprite standing next to monsters and houses with soft Valheim-style shading looked like two games glued together. The human's next instruction came shortly after the sprites went in: "now with the new 2d shader on the character I would like to have all the monsters have the same shader, also all the buildings."

Before and after the sprite look on monsters: the same wolf pack with pixel-texel shading (left) and sprite-style shading (right)

7. The sprite look for everything else #

The sprites follow a strict colour rule:⁴ every material is a ramp of a few colours computed in the OKLCH colour space, where shadows don't just get darker but shift in hue, and the light is quantized into hard steps. To make 3D models sit next to them, PixelLook gained a second style, SPRITE, for monsters, Shadow stones, buildings, torii, waystones and props:

the sun in four hard bands, each a hue-shifted step of the surface's colour ramp (the sprites' rule, sprite_ramp.gdshaderinc), plus a 1-sprite-pixel outline in a darker violet-leaning shade drawn in screen space.

The shader include that builds the ramp is the same one the sprite pipeline's Python mirrors, so a red roof and a red armor plate land on the same five colours. The outline is drawn in screen space with a stencil, one sprite pixel wide rather than one screen pixel, so at 4K it matches the thickness of the outline baked into the character sheets.

A day later the same treatment reached the flora, rocks, mountains and the ground. One thing was kept on purpose: the grass. "I guess not the grass. I like the grass." The grass cards, their trails and their stepped gradient from section 4 are unchanged. Cloud shadows, the lens, depth of field and the lighting also stayed: they're camera and atmosphere, and they work for sprites as well as for models.

Frostpeak's pines with the pixel-texel look and with the sprite look

How the switch was made safe #

Changing the look of every surface in a game on short notice is risky, so it was built as a switch rather than a replacement. Every mesh drawn in the sprite style keeps a plain twin material, and a Video setting ("Sprite-style shading") swaps every one of them at runtime. Flora, the ground and the mountains keep both materials and swap an override. That made before/after screenshots trivial (flip the setting, take the same shot) and leaves an escape hatch if a player prefers the softer look or a machine struggles.

Two smaller fixes followed from the change. World name tags above NPCs, portals and loot used to be 3D labels, which the depth of field and the lens blurred. They're now drawn as a crisp 2D overlay with pixel spacing and overlap nudging. And a shader bug from this period became a project rule: a uniform named like a local variable in a shared include broke the sprite shader, and every character rendered as a white rectangle.⁵

The current look: sprite-shaded houses and lanterns, the unchanged grass, cloud light and a sprite character at the harbor at sunset

Was the Valheim chapter wasted? #

Less than it looks. The texel shader still draws everything when the sprite setting is off. The grass, cloud shadows, lens, lighting, depth of field, the foliage dissolve and the far-origin hash fix are all in the current game. What changed is the surface rule: from "invent texture in the shader" to "quantize light into a hue-shifted ramp and outline it". Both are cheap, and both were built so the next change of mind costs a setting and a shader, not a rebuild.

Takeaways #

Pick a reference and steal its principles, not its assets. Pixel texels, cards and atmosphere transfer to any style of model.
Generate texture in the shader when you have no textures. Object-space texels that fade below pixel size look like a texture without being one.
Never hash with sin() far from the origin. Wrap and use an arithmetic hash.
Share includes across shaders. Cloud shadows, pixel noise and the colour ramp live in one file each and are used everywhere, so every surface agrees. (Name their variables carefully.)
One look for the whole frame. The best character art fails next to a world drawn by a different rule.
Ship big visual changes as a switch. A runtime toggle gives you before/after shots for free and a way back.

What's next #

A world needs sound. The next post is about the music: one original track per map, composed and synthesized in Python, all quoting the same motif.

This is where the transparent-roof bug from the Blender post came from: the swap originally ignored double-sided materials. ↩
Each map has its own slot, 5000 m apart, and the joined world sat about 10 km out. ↩
The code-drawn ones survived as a style target for the colour rules. ↩
The HD-2D post has the details. ↩
The testing post has the story. ↩

From 20 fps to 144, and a GPU Heap That Ran Out: Performance on Big Maps

2026-10-09T12:00:00Z

The problem #

The new Sanctuary Vale (previous post) is 2.6 x 3 km. In its first version the generator placed 270 monster packs and 54 Shadows across three hunting grounds, plus a walled town, farmsteads and over 20,000 trees, plants and rocks. The commit that built the map already batched plants in chunks and split the tree colliders (more on both below). Even so, with everything in place the game dropped to about 20 fps.

The tempting move is to guess: "it's the grass", "it's the shadows", "it's the trees". Those guesses are expensive because they're often wrong, and a wrong optimization leaves complexity behind. So the first step was to measure where the frame time actually goes.

Measure first: the CPU, not the GPU #

The measurement pointed away from rendering. The frame was CPU-bound, and the biggest item was 941 animated monsters. Every one of them had a live AnimationPlayer updating a skeleton every frame, including monsters a kilometre away that nobody could see. Their AI was already asleep at that distance (see "dozing" below); their skeletons were not.

The comment that went into the code says it in one line:

## Distance level of detail (the big cost on large maps was hundreds of far-away models animating):
## animate within ANIM_RANGE of the camera, hold the pose up to HIDE_RANGE, beyond that not drawn.
const ANIM_RANGE := 70.0
const HIDE_RANGE := 170.0
const LOD_CHECK := 0.5

Step 1: animation LOD #

The first fix was cheap and local to ModelVisual, the node that shows a monster's model. Twice a second each monster checks its distance to the camera. Within 70 m it animates. Between 70 and 170 m it holds its pose: the AnimationPlayer is switched off, so no skeleton updates happen. Beyond 170 m it isn't drawn at all.

func _update_lod() -> void:
	var cam := get_viewport().get_camera_3d() if is_inside_tree() else null
	if cam == null or DisplayServer.get_name() == "headless":
		return
	var d := cam.global_position.distance_to(actor.global_position)
	var show := d <= HIDE_RANGE or actor.is_dead
	if visible != show:
		visible = show
	var animate := show and (d <= ANIM_RANGE or actor.is_dead)
	if animate != _animating:
		_animating = animate
		if _anim:
			_anim.active = animate  # a far model holds its pose: no skeleton updates

One detail matters more than it looks: the check timers are staggered (LOD_CHECK * randf_range(0.8, 1.2)). Otherwise 941 monsters would all check on the same frame and cause a hitch twice a second.

Step 2: don't have 941 monsters #

LOD made far monsters cheap. The better question was why they existed at all. A player can see perhaps 150 m. Monsters 2 km away are only a cost: memory, AI ticks, network state.

So we changed how a map is populated. Every Shadow and every pack now has a slot: a place in its zone and a list of who stands there (types, levels, which ones are Elites). The monsters only exist while a player is near:

const SPAWN_RANGE := 250.0
const DESPAWN_RANGE := 320.0
const DESPAWN_AFTER := 15.0
const SLOT_TICK := 1.0

Monster slots around one player, dumped from a running game: only the slots inside 250 m are spawned

Once a second the server checks each slot. An empty slot within 250 m of a player spawns. A filled slot whose monsters are all idle at home, with every player beyond 320 m for 15 seconds, goes away again, and the slot remembers exactly what stood there. The gap between 250 and 320 m, plus the 15 seconds, is hysteresis: walking back and forth along the edge doesn't spawn and despawn the same pack over and over. And since clients only see 160 m (the network interest range), all of this happens out of sight.

Two conditions keep it honest. A slot only despawns if its monsters are idle: dozing at home, unhurt, and for a Shadow, untouched with no waves out. Nobody can escape a fight by running away and coming back to a fresh, full-health monster. And a killed slot refills only after its normal respawn time.

A test walks a player around the Vale and checks both directions: everything spawned is within range, and the far fields go away when the player goes back to town.

Dozing monsters #

An older optimization from the open-world days still does a lot of work: monsters with no player within 70 m doze (Actor.dormant skips their per-frame work until a player comes near or something hits them), and maps with no players at all sleep completely.

Plants in chunks #

The rendering side needed the same treatment, and got it with the map itself. Today the Vale's scatter lists 15,000 pines and 50,000 ferns in the Shadow Woods alone. Plants were always drawn as MultiMesh batches, but one batch per kind per map would mean the GPU draws (and shadows) every tree on the map every frame. So they're batched per 96 m chunk with a draw distance:

## Plants are batched per CHUNK square and drawn up to DRAW_RANGE m away (small ones half that):
## a big map would otherwise draw (and shadow) every tree it has, every frame.
const CHUNK := 96.0

Trees are drawn to 200 m and small plants to half that. Grass works differently: it only exists within 150 m of the player, and its chunks are built a few per frame as you walk and freed behind you. In the code's words: "a huge map costs no more than a small one."

The Whispering Fields from 110 m up (fog off): trees everywhere, grass and small plants only near the camera

Load time: one collider body was too many #

Frame rate wasn't the only problem. Loading the big map was slow too, and the cause was surprising. Every tree trunk has a collider. All of them were shapes on one StaticBody3D, and each shape added to a body with thousands of shapes made the next one slower. The fix is again a grid:

## Trunk colliders go into one body per COLLIDER_CELL square: thousands of shapes on a single body
## made each new one slower (a big map took 25 s to plant).
const COLLIDER_CELL := 64.0

With one body per 64 m cell, no body grows large enough for that slowdown to matter.

The terrain cache that never hit #

The terrain is a height grid baked from noise and then flattened around towns, water, roads and portals. On a 2.6 x 3 km map that bake is expensive, and it gives the same result every time, so it should happen once. We added a disk cache in user://terrain_cache, keyed by a hash of the map's data.

The first version never hit the cache. The map's data dictionary is mutated at runtime: code adds parsed helper values to it, such as a polygon's _points. So by the time the hash was taken, the "same" map data hashed differently on every run. The fix hashes only the data from the file and skips the keys that code adds (which by convention start with _):

## Hash of map data, without the caches code adds to it ("_" keys, e.g. a polygon's parsed "_points").
static func data_hash(v: Variant) -> int:
	if v is Dictionary:
		var parts: Array = []
		for k: Variant in v:
			if not (k is String and (k as String).begins_with("_")):
				parts.append([k, data_hash(v[k])])
		return hash(parts)

The key also includes a BAKE_VERSION, so changing the bake code invalidates old files. A test checks that a second load comes from disk in under a second and gives the same heights.

The lesson is general: a cache keyed on mutable state is a cache that silently doesn't work. It didn't crash or give wrong results. It was just slow, which is the hardest kind of bug to notice.

The result, round one #

With animation LOD, proximity spawning, dozing, chunked plants and the cache, the Vale ran at 144 fps at 4K, the refresh-rate cap of the test machine. That left room to spend: shortly after, a commit made the woods denser, drew trees out to 200 m, and put three times as many packs and Shadows on the map.¹

Then the art pass (next post) added pixel-texture shaders, leaf cards, denser grass, cloud shadows and a lens effect, all on top of this budget.

The Shadow Woods at 3840x2054 with a measured fps overlay (capped by the monitor's 144 Hz)

Round two: the GPU heap that ran out #

The frame rate was fine. Then, on day five, an agent's screenshot run on the reworked Hellmouth Rift produced 7,518 error lines, almost all of them the same:

Cannot create uniform set ... not enough room in the RESOURCES descriptor heap
(please increase rendering/rendering_device/d3d12/max_resource_descriptors)

On Direct3D 12, every live material, skeleton and skinned mesh holds GPU descriptors, and the heap has a fixed size. The error message suggests the obvious fix: make the heap bigger. The brief for the agent that investigated said no: raising the limit was "acceptable only as an extra safety margin with a stated reason, not as the fix." Find out what is holding descriptors, and why the number keeps growing.

The diagnostic scenario it wrote (scenario_render_heap.gd) teleports the player across a map, hop after hop, and prints the live skeletons, the distinct materials drawn and the video memory at each stop. Two things were growing without limit:

Monster models that were never freed. The big maps keep a few hundred monsters around a player, and every one of them built its skinned model when it spawned, even out of sight. Animation LOD stopped them animating, but each model still held its skeleton and buffers. After a few teleports or waystone hops, the Hellmouth Rift had 2,419 live skeletons and climbing.
Materials made per object. Each monster had its own hit-flash material, each capsule its own material, and props asked a helper for a material by colour and then modified the one they got, which forced a new one each time. The Rift drew 3,308 distinct materials.

The fixes are small:

## ... beyond RELEASE_RANGE the model is freed (built again on the way back in). A model holds GPU
## descriptors for its skeleton and every skinned surface (D3D12: rendering_device/d3d12/max_resource_descriptors,
## ~30 per monster): the big maps keep ~400 monsters around a player [...], so after a few teleports or
## waystone hops the heap ran out. Now only the monsters near the camera hold a model.
const ANIM_RANGE := 70.0
const HIDE_RANGE := 170.0
const RELEASE_RANGE := 200.0

The hit-flash material became one static material shared by every monster. Capsule materials and the swing effect are only created when something actually needs them. The map's material helper caches by look (colour, glow, roughness), and the five places that used to modify the returned material now pass those values in instead. The heap limit stayed at its default.

Hellmouth Rift, same hops	Before	After
Live skeletons	269, rising to 2,419	105 to 402, bounded
Descriptor heap errors	3,826	0
Distinct materials drawn	1,100 at start, rising to 3,308	159 at start, about 300
Video memory	up to 2.69 GB	about 1.2 to 1.4 GB

The Vale went from up to 1,781 skeletons to 126-293. Prop materials alone dropped from 731 to 67 on the Rift. A regression test checks that twelve props share at most four materials, that the material helper returns the same material for the same look, and that a far monster gives its model back.

The lesson is the same one as in round one, one level lower: level of detail has to reach memory, not just work. A monster that doesn't animate still costs whatever it holds.

Clutter: two thousand objects, one material #

The living-world pass² put crates, barrels, carts, market stalls and laundry lines into every town and camp: 2,129 placements across the maps, 918 of them in the Vale. Drawn naively, that's thousands of draw calls and, after round two, an obvious descriptor risk. Clutter reuses the plant approach and goes one step further:

Drawn like Flora: everything of one model inside one CHUNK square is one MultiMesh, and every model shares ONE material [...]: a model's material colours are baked into its vertices at load, its "Paint_<n>" parts take the instance's colour, each instance gets a brightness jitter. So a dressed town costs (models x chunks in view) draw calls and one material.

Chunks are 48 m, clutter is drawn to 130 m (small pieces to 70 m and without shadows), and only big pieces like carts and stalls collide, with their boxes merged into one physics body per 64 m cell. The buildings got the same treatment in their detail pass: weathering went into vertex colours so that every house shares one material.

Sprites: a video memory budget, enforced by tests #

The switch to pre-rendered pixel sprites for players and NPCs³ moved the cost from the GPU's vertex work to texture memory. A character's sheets cover 8 directions and dozens of animation clips, in several paper-doll layers. Two tests keep that in check. One dresses a character (body, a hairstyle, the heaviest armor, eyes) and loads everything one weapon type plays: it must stay under 19 MB, and it's 18.3 MB for the male body and 16.4 MB for the female. The other builds every NPC and townsperson of the Vale plus 30 passers-by (63 people) and checks their sheets against a 128 MB budget: they need 92.7 MB. The trick that made those numbers possible is packing the sheets per "bank" (the shared clips, then each weapon set's own), so a character only loads the pages of clips it can actually play.

Where it stands #

A fresh run of the scenic screenshot scenario on the current build, at 3840x2054 with everything on (sprites, sprite-style shading, clutter, grass, volumetric fog, depth of field), measured between 106 and 147 fps across twelve spots in the Vale, with 389 to 1,451 draw calls. The low end is in the densest woods and at the stone circle at night. That's on the development machine, a fast desktop; nobody has measured a modest PC yet, and that's the next honest number to get.

Takeaways #

Measure first. We expected rendering; it was animation and AI on the CPU. Later, it was GPU memory nobody was looking at.
The cheapest monster is the one that doesn't exist. Proximity spawning with hysteresis beat every per-monster optimization. The second cheapest is the one that doesn't hold a model.
Don't take the error message's advice blindly. "Increase the heap" would have hidden a leak that grew with every teleport.
Stagger periodic checks. A thousand timers that fire on the same frame make a hitch.
Grid your big things and share materials: plant batches, clutter, colliders, grass. Anything "one per object" or "one per map" breaks on a big map.
Key caches on immutable inputs. Check that your cache actually hits.
Put budgets in tests. A video memory number in a test fails the day someone adds one clip too many.

What's next #

With frame time to spare, we spent it on looks. Next: chasing the Valheim look with pixel noise, leaf cards, grass that parts around you and shadows of clouds that aren't there, and then leaving it for something else.

When the Vale was later shrunk to about 1.4 x 1.8 km, the spawn radius came down with it, to 200 m, with despawning at 260 m. ↩
It has its own post. ↩
It has its own post. ↩

From Open World to Torii Portals, and Nine Maps with One Town Each

2026-10-09T12:00:00Z

Where we started #

The world began small and data-driven. A map is a JSON file in data/maps/: zones (safe sanctuaries and hunting grounds with level ranges), NPC placements, props, a seeded random scatter, and portals. The first Sanctuary Vale was 480 x 480 m: a town in the middle, then rings of hunting grounds getting harder toward the edge, and a portal north to the Shadow Marsh. All maps load into one scene tree, 5000 m apart, so they never see each other.

Zones were circles and rectangles at first. On day two they got a polygon shape, for one reason that the design doc states plainly:

Zones are circles, rectangles or polygons (any outline, from the user's map sketches: the user draws, Claude translates into points; 1 sketch square = 25 m).

The human designs maps the way people have always designed maps: on a grid, with a pencil. Converting the sketch into coordinates is the AI's job.

The open-world detour #

On day three the plans got bigger. Seven more themed maps were drafted (Orc Valley, Duskmoor, Sunscar Desert, Frostpeak, Ember Wastes, and the realms Hellmouth Rift and the Shadowlands), each with its own sky, fog, weather, liquids and border mountains. A Python generator drew a world map from a layout spec, and the idea came up to make it seamless. The backlog entry describes it as "regions that build onto each other (like Where Winds Meet), joined by land bridges at passes".

We built it in an afternoon, in three commits:

Joined world: the Vale and the Marsh meet at a land bridge called Willow Ford. Each map got an organic coastline (a seeded wobbly shape plus land bridges), a sandy rim and sea around it. Walls follow the coast but stay open where a neighbour's land continues. Walking off one map moves you onto the next in place, and sky, fog and light fade over three seconds.
Fixes: you walk along the shore, joined maps wake together, and you can fight across the border. Before that, Marsh monsters across the ford "stood frozen like a wall", because only the player's own map was awake.
The open world: all regions joined in a chain, each with named landmarks ("sights") that announce themselves with a banner when you arrive. Among them: the Old Mill, the Sand Ship, the Mammoth Graveyard, the Gate of Teeth.

Terrain arrived in between: rolling hills from seeded noise, baked into a 2.5 m height grid. The grid is flattened toward coasts, rivers, safe zones, portals and land bridges, so joined maps meet at the same height.

It worked. The commit message even notes the frame rate: "~140 fps again with the Vale and Marsh both awake".

Switching it off #

Nine hours after the first joined map, this commit landed:

Back to separate maps linked by torii portals (open world switched off): purple portals along the chain, a blue one from the Vale to Orc Valley

It was the human's call. CLAUDE.md records it with a date: "Open world is OFF (2026-10-09, the user's call): every map is its own place, linked by torii portals". The code wasn't deleted. data/world.json keeps an empty "continent", and the crossing, coastline and neighbour-sight code stays dormant for later.

Looking back at what the open world needed, the trade is easy to see. Every map had to fit into its neighbours' coastlines and match their heights at the border. Maps had to wake together, load together, and share visibility across the border.¹ Every map's size and shape was constrained by the chain. With portals, each map is its own place. It can be as big as it needs to be, in any shape, and the next map only loads when you step through a gate.

The switch itself was small (11 files, more lines removed than added), mostly because the earlier rules held. Actors never cared which map they were on; World.place() was already the only way to move between maps; and portals already existed for dungeons. Fittingly, the portals became torii gates: a swirl in the portal's colour inside a gate model from the building generator.

A torii portal: purple swirl, lanterns and guardian statues

Map 1 from a sketch #

With the size constraint gone, the human drew Map 1 by hand: a walled town with four gates, a coast to the west, a river coming down from the northern mountains, lakes, roads to farmsteads, a harbour village, a mountain border, and two portals in the far corners. Thirty-two minutes after the portal commit, this landed:

Map 1 rebuilt from the user's sketch: 2.6 x 3 km Sanctuary Vale with a walled town and four gates, coast, river, lakes, mountain border, roads, farmsteads, harbor, new landmarks, torii portals to the Marsh and Orc Valley

The diff has 11,156 added lines, almost all of them generated map data.

The generator #

The map isn't hand-written JSON. It comes from tools/mapgen/maps/vale.py, a rerunnable script that writes data/maps/sanctuary_vale.json, and the JSON says so in its _doc: "Generated by tools/mapgen/maps/vale.py (edit that, not this file)." The sketch becomes a few named constants and functions:

TOWN_R = 230.0
NORTH, SOUTH, EAST = -1420.0, 1420.0, 900.0
BLUE_PORTAL = (600.0, -1150.0)
PURPLE_PORTAL = (560.0, 1110.0)
HARBOR = (-980.0, 150.0)
CRYPT = (-150.0, -1050.0)


def west_coast(z):
	"""x of the west coast at z (wavy, a cape mid-way, an inlet where the river ends)."""
	x = -1130 + 95 * math.sin(z / 380 + 1.0) + 45 * math.sin(z / 140 + 0.4)
	x -= 120 * math.exp(-((z - 80) / 160) ** 2)  # a cape around the harbor
	x += 160 * math.exp(-((z + 1050) / 120) ** 2)  # the river mouth bay
	return x

From there the script lays out everything else: the coastline polygon, three rows of mountains along the north, east and south edges (with a gap where the river comes through), the river Silverrun and three lakes, a town wall in 12 m segments around a 230 m radius with four gatehouses, roads from the gates to the farmsteads, the harbour and both portals, and the hunting grounds in rings:

	hunting("whispering_fields", {"circle": [0, 0, 650]}, [1, 4], 30, 220),
	hunting("shadow_woods", {"circle": [0, 0, 1150]}, [5, 9], 45, 400),
	hunting("ashen_reach", {"rect": [-1500, -1500, 2500, 3000]}, [9, 14], 35, 300),

Levels 1-4 in the fields, 5-9 in the woods, 9-14 out to the mountains, with the Shadows and packs counted per zone. The scatter is scaled to the area: 15,000 pines and 50,000 ferns in the Shadow Woods alone. The script also keeps the old town square with all its NPCs, school halls and the forge, and it updates the Marsh and Orc Valley portals so you arrive next to the matching torii.

Because the generator is code, iterating on the map means changing a constant and rerunning it. "Move the Old Mill", "make the woods denser" or "three times the packs" are each a one-line change and a fresh JSON.

Checking the result: overviews and the atlas #

Top-down overview of the generated 2.6 x 3 km Sanctuary Vale

How do you check that a 2.6 x 3 km map matches a sketch? You draw it. Every generator run also writes a top-down overview (tools/mapgen/overview.py): zones with their level ranges, roads, water, landmarks and portals, all drawn from the JSON the game will load. The overview is what the human compared with the sketch, and what every later map change was reviewed with.

On day three there was also a world atlas (tools/mapgen/atlas.py) that asked Godot, headless, to export every map's real geometry and drew all the maps side by side. Its README says why it works that way: "Rerun after changing maps; it can't drift." It drifted anyway, in a different sense: the atlas expects the coastlines of the joined world, and after the rework below it no longer runs (a map without a coastline gives it nothing to draw). The per-map overviews took its place, and fixing the atlas is on the list.

The world atlas from day three, still drawing the joined open world (Willow Ford is the narrow bridge between the Vale and the Marsh)

The north gatehouse of the walled town, with the road leading out

New problems at 2.6 km #

A map more than 30 times the area of the old one broke assumptions everywhere, and the next commits deal with them:

Grass streams around the player instead of being built for the whole map.
Peers only receive entities within 160 m, not everything on the map.
Terrain cells grow with the map size, and heights become exact along roads and coasts.
Mountains block at their foot, and nothing grows or spawns on their slopes.
Monsters spawn only near players. A map this size has more than a thousand monsters.

That last point became its own performance story (the next post).

Too big, too empty #

Then the human played it. Their notes from that morning: "monster density or frequency is quite low, I also feel like the map is a bit too big." A big map is only impressive for the first walk across it. After that it's the time between fights.

Because the map is a generator, shrinking it was a change of constants, not a redesign. Twelve hours after the sketch became a map, the Vale shrank to about 1.4 x 1.8 km. The town stayed exactly as it was; the fields, woods and outer ring moved closer. Packs now stand about every 35 m, Shadows are twice as dense, roaming packs move more often, and pack spawns stay out of lakes. The proximity spawn radius dropped from 250 m to 200 m to match.

Sanctuary Vale before and after the resize, drawn at the same scale

Every map at Vale scale, one town each #

The other eight maps were still the old small ones, mostly 300 x 300 m with two or three safe zones each. The human's brief for fixing that was one line: "Rework all other maps we have. Keep safe zones to one per map + only other safe zones for portals."

That rule turned out to shape the whole game. With one town per map, the town is where you go back to, so it has to be worth going back to. Everything else is hunting ground, and the portal shrines are small islands of safety you pass through. The lore later gave it a reason: every town is built around a shard of a broken sacred stone, and monsters can't cross its song.

The rework was one of the first big parallel jobs: four agents, two maps each, each writing a rerunnable generator modelled on the Vale's (tools/mapgen/maps/<map>.py). Each map came out at roughly 1.2 to 1.5 km across, with mountain borders, roads, packs about 35 m apart, eight to ten named landmarks,² and waystones at the town, the portals and the landmarks. The Vale's own eleven landmarks were rebuilt as proper set pieces with 17 new building models in the same commit. Because four generators wrote portals independently, a small script (tools/mapgen/link_portals.py) runs afterwards and points every portal's arrival at the partner map's matching shrine.³

The Shadow Marsh before and after the rework: a ring of zones became a 1.5 km map with roads, landmarks and one town

Exceptions, on purpose #

Two later decisions bent the rule, both from the human:

The desert got bigger and emptier. "The desert I feel like should be larger and feel somewhat empty. What are rewards we can have there to still make it valuable?" Sunscar is now about 2 x 2 km, with islands of life between empty dunes and about 30% fewer packs. The emptiness pays: elite dune wanderers with better loot, a Sandstorm event with storm elementals and treasure caches, rare spawns (a sand wyrm that burrows, a raider warlord), lore tablets, a caravan merchant who keeps a wall-clock schedule, and Sunstone, the material the top three upgrade steps need.⁴
Some maps lost their town. "Some maps don't have to have a town." The Ember Wastes, the Hellmouth Rift and the Shadowlands now keep only a gate camp inside the portal shrine, and their old houses stand empty in the wilds. It reads right: these are the places where the land itself is the enemy.

A Sandstorm in the Sunscar Desert: visibility drops, storm elementals roam, caches appear

Getting around nine big maps #

Bigger maps with one town each need fast travel, or every quest turns into a walk. There are two layers:

Waystones: stone steles at the town, the portals and the landmarks. Walking up to one attunes it (its rune lights up for good); at any attuned stone you can travel to any other you've attuned, for a fee that grows with the target map's level. The server checks every trip like any other request.
Gate Keepers: the human asked for "a teleport NPC per larger safe zone that allows me to travel to places I've been before and talked to the other teleport NPC". They're NPCs on the same waystone network, so talking to one attunes it.

A Gate Keeper's window: attuned destinations per map, with fees

Each map plays a little differently #

The last layer, added on day six, is a small set of map mechanics (data in data/mechanics.json, run on the server): the desert's heat (stand in shade or water, or carry a water skin), Frostpeak's cold (campfires and shelter warm you; avalanches come down marked slopes after a warning), the Ember Wastes' shifting lava and diving drakes, demon portals in the Hellmouth Rift that you close by channelling, rituals in Duskmoor, and the Shadowlands' shade, which builds up away from shard light. The rule, in the data file's own words: "Keep it modest: flavour and reward, not frustration."

Frostpeak: an avalanche warning on a marked slope

Takeaways #

Separate places are simpler than a seamless world. The open world worked, but it tied every map to its neighbours. Portals give each map its freedom back. Keep the seamless code dormant if you might want it later.
Let the human draw and the machine measure. A sketch at 1 square = 25 m plus a generator script is a surprisingly direct path from paper to a playable map.
Big is not the same as good. Density of things to do matters more than square kilometres. A generator makes "smaller and denser" a change of constants.
One strong rule shapes a lot. "One town per map" decided where NPCs live, what the lore says, where waystones go and which maps feel safe.
Render what you generated, and keep the renderer running. A tool that checks your maps is only useful while it still runs against today's maps.

What's next #

A map with tens of thousands of plants and hundreds of animated monsters doesn't run well by default, and later a GPU heap ran out on a map that had rendered fine. Next: performance.

Peers saw entities on a neighbour within 90 m. ↩
The desert later got thirteen. ↩
The coordinator post covers what went wrong with four agents in one repository. ↩
A proposed digging-with-a-shovel feature was dropped: "not so much of a fan of the shovel thing". ↩

Everything from Code: 177 Monsters, 203 Items and a Town Built in Headless Blender

2026-10-09T12:00:00Z

The constraint #

Our developer is an AI working through a terminal. It can't drag vertices around in Blender's viewport, and the human isn't a 3D artist either. For the first few days every monster was a capsule. The design doc planned for free low-poly asset packs later.

Then the question changed: if Claude Code can write a Godot game, can it write a Blender script that builds a wolf? Blender runs headless (blender -b -P script.py) and its Python API can do anything the UI can. The first test was a single Giant Rat. Less than an hour later there was a commit titled "Low-poly models for all 77 monsters: parametric Blender builders (quadruped, humanoid, critter) from one spec table". It changed 165 files.

Specs, builders, a loop #

The pipeline has three layers.

1. A spec table (tools/blender/monster_specs.py) says which body each monster gets and how it looks. Base templates keep the variants short:

WOLF = {"body": "quadruped", "length": 0.92, "leg": 0.46, "girth": 0.155, "depth": 0.165, "head": 0.125, "snout": 0.2, "chest": 1.1}

	"wolf": with_(WOLF, main="#7d7d80", belly="#b4b4b6"),
	"grey_wolf": with_(WOLF, main="#9a9a9e", belly="#d0d0d2", length=0.98),
	"blue_wolf": with_(WOLF, main="#4f6a9a", belly="#9ab0d8", eye="#80d0ff", eye_glow=2.0),
	"alpha_wolf": with_(WOLF, main="#5e5e66", belly="#8e8e96", chest=1.3, extras=["mane"], eye="#ffcc33", eye_glow=2.0, length=1.05),

2. Builders turn a spec into a rigged, animated mesh. There are four: quadruped (dogs, wolves, cats, bears, boars, deer), humanoid (goblins, orcs, cultists, skeletons, demons, shades), critter (rats, spiders and other small things) and stone for the Shadow monoliths. Each takes a vocabulary of options. The humanoid builder alone knows five body frames, 15 outfit pieces, 16 features from tusks to wings, and 14 weapon types.

3. A build loop (build_monsters.py) reads the game's own data/monsters.json for each monster's name and height, runs the right builder, and exports a .glb:

	for mid in ids:
		spec = dict(monster_specs.SPECS[mid])
		builder = BUILDERS[spec.pop("body")]
		height = float(spec.pop("height", known[mid]["height"]))
		spec["name"] = known[mid]["name"].replace(" ", "")
		lp.clear_scene()
		arm = builder(spec, height)
		out = os.path.join(ROOT, "assets", "models", mid + ".glb")
		os.makedirs(os.path.dirname(out), exist_ok=True)
		lp.export_glb(out)

The first 77 built in about ten seconds. With --preview <dir> it also renders one image per monster, and contact_sheet.py puts them all on one sheet. That sheet is how the AI reviews a whole bestiary at a glance: it opens a single PNG and looks for anything off.

Contact sheet of the four-legged monsters (after the organic rebuild)

Wolf, grey wolf, blue wolf and alpha wolf: one spec, different numbers

Conventions instead of fix-ups #

The Godot side, ModelVisual, needs no per-model tweaks because the builders follow fixed conventions: meters, feet at z = 0, facing glTF forward, and four animations named idle, walk, attack and death. Two conventions turned out to matter for feel:

Every attack animation lands its blow on frame 4. ModelVisual knows this (STRIKE_TIME := 4.0 / 24.0) and skips most of the wind-up for melee hits, so the blow lands right as the damage number appears. For telegraphed attacks it does the opposite and stretches the wind-up over the warning time.
Walk speed travels with the model. Each armature carries the speed its walk cycle covers as a glTF extra (export_extras=True), so feet don't slide whether a rat scurries or a bear lumbers.

Headless machines (dedicated servers, tests) skip the meshes and keep the capsule. That's the "logic separate from visuals" rule from the first day paying off: the server never needs to know a wolf has a tail.

Shadow stones, items and a town #

The same approach spread to everything else that has a shape.

Shadow stones: 11 carved monoliths, each stacked from three chunks on bones plus up to four floating shards, so they can shudder when hit, surge when a wave spawns and crumble on death. The glowing runes use a material named Glow, which the game recolours per Shadow type and pulses.

Items: build_items.py builds a model and an inventory icon for every item (139 then, 203 now). Godot exports the item list first (including generated skillbooks and runes), so Blender and the game always agree on what exists. Weapons get shapes from a spec table (swords became katanas with a curved blade, temper line, tsuba and wrapped grip). The Fullmoon Sword, a nod to a popular Korean MMO, has its own hand-written builder.

Buildings: East Asian low-poly houses (hanok, minka, Chinese gabled), temple halls, pagodas, torii gates, stone lanterns, a roofed well and guardian lions. Each is built at a canonical size and scaled in Godot to the footprint the map asks for, so map data keeps saying "a house, 7 x 6 m, here".

Flora: 27 variants of trees, plants and rocks at first (33 now, including snowy pines). Their materials are named by role (Leaf, Bark, Needles, Moss...), and Godot reads those names to decide what sways in the wind, what takes the map's colour and what glows. One mesh can serve a green Vale and a snowy Frostpeak.

Textures follow the same idea. The leaf cards and grass blades are pixel art drawn by tools/flora_textures.py with Pillow, leaf by leaf.

Shadow stones at night, each with runes in its Shadow's colour

Generated weapon icons for three of the four schools

The town: houses, the temple hall and stone lanterns from the building builder

What went wrong #

The roofs you could see through #

After we added a pixel-texture shader to every model,¹ roofs became transparent from below and from some angles. The cause: Blender's roof material was double-sided, and our material swap only made single-sided shader materials. Thin roofs lost their back faces. The fix kept a two-sided variant of the shader for any material that had culling disabled:

	var two_sided := base.cull_mode == BaseMaterial3D.CULL_DISABLED

A second commit closed the roofs underneath with a wooden soffit, so you never look up into an empty roof even when the camera dips.

The Pinocchio dolls #

The bigger lesson is in the docstring of the helper library that every builder uses:

A creature is a set of simple primitives (spheres, cones, cylinders), each rigidly bound to one bone of an armature (one vertex group per part), joined into a single skinned, flat-shaded mesh.

That approach was fast, robust and easy to parametrize, and it got 77 animated monsters into the game in an evening. But rigid parts on bones move like a jointed wooden doll. Limbs are separate cones and spheres, and there is no flesh that bends. They earned the nickname Pinocchio dolls. Fine as placeholders, not what the game should look like.

The fix was one of the first jobs handed to a parallel subagent:² an organic rebuild, with continuous bodies skinned to their bones instead of separate primitives. It landed in two commits. The four-legged animals got "one smooth skinned body per animal, painted 128 px pixel fur, per-family shapes (canine, bear, boar, cat, toad, crocodile)". The critters followed: "segmented, smooth, painted: spiders, scorpions, beetle, bat, snake, eye, wisp". The spec tables, the build loop, the conventions and every test that checks "each monster has a model with its animations" stayed the same. Only the builders changed. The humanoid monsters (goblins, orcs, cultists, demons) still use the primitive builder; rebuilding them is queued, not done.

The same wolf as a Pinocchio doll of primitives (left) and after the organic rebuild (right)

Six days later: the pipeline at scale #

The same approach kept absorbing new content. At the time of writing, Blender scripts produce:

182 monster and Shadow stone models (177 monster types and 11 Shadow types share them). Dungeon monsters mostly reuse existing bodies, scaled, recoloured and given one accessory (a crown, horns, armor plates), which was the human's call when 20 dungeons were planned: "We can also just scale up some of the other models we have and recolor them?" Each dungeon's final boss gets its own silhouette instead: a crone under a huge hat with a cauldron on her back, a sexton whose head is a bronze bell, a king with a furnace in his back.
203 item models and icons, including 41 armor pieces that a balance pass found missing.
97 building models: five house styles plus a tall house, teahouse, shop, storehouse, granary, farmhouse and guard tower, each in regional variants (desert, snow, swamp, ember), after a detail pass that added tiled roofs, timber frames, trade signs and weathering in vertex colours, all on one shared material.
53 clutter models (crates, barrels, carts, market stalls, laundry) and 12 animal models for the living-world pass.
458 dungeon kit pieces in 20 themes, from crypt stone to a hedge maze to a palace of mirrors.

The pipeline also gained a second output. The player characters are still modelled in Blender by a script (characters_v4.py), but they never ship as 3D models. They're rendered into 8-direction pixel sprites, which is its own post.

Why generate instead of buy? #

Asset packs would have been faster for the first few monsters. Generating had other advantages:

Consistency: one palette logic, one level of detail, one style across every monster, item and building.
Data alignment: heights come from monsters.json, item lists from items.json. When a monster is added to the data, its model is one spec line away, and a test notices if it's missing.
Change at scale: "swords are katanas now" touched 181 files in one commit: every sword model and icon, rebuilt.
No licence questions: everything is original.

The cost is that quality is bound by what can be described in code. That's exactly what the Pinocchio lesson showed.

Takeaways #

Blender is a library. Headless Blender with a Python spec table is a real content pipeline, even for animated characters.
Fix conventions, not models. Facing, scale, animation names and the strike frame are agreed once, so the engine side never needs per-model fixes.
Review in bulk. A contact sheet of every model is the fastest way for anyone, human or AI, to spot the odd one out.
Fast primitives are a placeholder, not a style. Plan the step from rigid parts to skinned bodies.

What's next #

With models in place, the world needed space. Next: why we built a seamless open world, switched it off nine hours later, and built Map 1 from a hand-drawn sketch.

See the art post. ↩
More on that setup in the coordinator post. ↩

Testing a Game with 13,800 Checks

2026-10-09T12:00:00Z

Why so many tests #

Our developer is an AI that starts every session without memory of the last one, and on a busy day it commits 40 to 70 times. Later in the project, several AI agents edited the same repository at once. Without a safety net, every one of those changes could quietly break something built two days earlier. So the test suite isn't an afterthought. It went into the very first commit together with movement and the first arc attack, and every feature since has added to it.

At the time of writing, tests/run_tests.gd holds 341 test functions, which run about 13,800 checks in a little over a minute. Both numbers have a story, and the check count is the less trustworthy of the two. We'll come back to that.

The runner: a few dozen lines, no framework #

We don't use a test framework. The runner is a SceneTree script that Godot runs headless:

func _run_all() -> void:
	for method in get_method_list():
		var name: String = method["name"]
		if name.begins_with("test_"):
			print("- ", name)
			call(name)
			_cleanup()
	print("\n%d checks, %d failed" % [_checks, _failures])
	quit(1 if _failures > 0 else 0)

A test is any method named test_*. It spawns what it needs and calls _check(condition, message). _cleanup() frees every actor, damage number, loot drop and world it left behind, so each test starts clean. Two environment variables were added once the suite got big: TEST_ONLY=<substring> runs the matching tests, and TEST_TIMES=1 prints each test's time and the slowest forty. The first test ever written is still there and still typical:

func test_arc_hits_only_enemies_in_front_and_in_range() -> void:
	var player := _spawn(Actor.Team.PLAYER, Vector3.ZERO)
	var front := _spawn(Actor.Team.ENEMY, Vector3(1.5, 0, 0))
	var front_edge := _spawn(Actor.Team.ENEMY, Vector3(1, 0, 1))  # 45 deg, inside 120 arc
	var behind := _spawn(Actor.Team.ENEMY, Vector3(-1.5, 0, 0))
	var too_far := _spawn(Actor.Team.ENEMY, Vector3(5, 0, 0))
	var ally := _spawn(Actor.Team.PLAYER, Vector3(1, 0, 0))

That this test is easy to write is a direct result of an architecture rule: "Combat functions are pure queries: no side effects, so they can be unit tested."

Gotcha 1: engine errors don't fail tests #

A GDScript runtime error prints SCRIPT ERROR and carries on. The test that triggered it may still pass. So the command in CLAUDE.md always greps the log as well:

"$G" --headless --path . -s res://tests/run_tests.gd 2>&1 | tee /tmp/t.log | tail -1; grep -E "^(SCRIPT )?ERROR" /tmp/t.log

"All passed" with an error line in the log counts as a failure. Several real bugs, for example freed-object errors, first showed up only as an ERROR line.

The end of a test run and an empty error grep (from the day the count first passed 11,900)

Gotcha 2: headless runs never compile shaders #

This one cost a lot of embarrassment for one line of code. On day six, an agent added a uniform called shade to the sprite shader. A shared shader include for cloud shadows already had a local variable called shade. The sprite shader stopped compiling, and every sprite in the game (the player and every NPC) rendered as a flat white rectangle.

Every test passed. Every headless smoke run passed. A headless Godot never compiles a shader, so the error never happened there. The human found it in their own running game and asked, dryly: "you do realize that our player model is a white wall?" The fix was a rename (shade_tint). The lesson went into CLAUDE.md the same day:

Headless runs never compile shaders: after any shader edit (incl. shader strings in .gd files) take a windowed screenshot of main.tscn and grep its log for ^ERROR.

Agents working in parallel at the time noticed it too. One reported that its first screenshots of the ice dungeon showed white walls where the player should be, and re-shot them after the fix. Screenshots caught what tests couldn't, but only because someone looked.

Where 13,800 checks come from (and why the number lies) #

Most checks come from tests that loop over data:

func test_items_have_models_icons_and_upgrade_glow() -> void:
	for data: ItemData in ItemDb.items():
		_check(ItemLook.icon(data) != null, "%s has an icon" % data.id)
		var model := ItemLook.make_model(data)
		_check(model != null, "%s has a model" % data.id)

That's one function and hundreds of checks. Every item has an icon and a model. Every monster type has a valid model with its animations. Every quest points at real NPCs and monsters. Every NPC, townsperson and companion name is unique (the lore has a rule about that). Every armor slot has a tier at least every ten levels. Every ranged monster's telegraph is long enough to dodge. A busy town square (63 NPC sprites) stays inside its video memory budget. When the AI adds 41 armor pieces or ten dungeons in one commit, these tests check every one of them without anyone writing a new test.

Now the honest part. On the morning of day four the suite had 11,933 checks and took 168 seconds. Most of that time came from 38 tests that each built the real 2.6 x 3 km Sanctuary Vale, at about 3.9 seconds a build. An agent moved those tests onto a small dev-only test map. The suite dropped to 12 seconds, and the check count dropped to 4,992. Nothing was lost: two tests make one check per spawned monster or spawn slot, and the big map simply had far more monsters (3,093 checks from one test alone, against 123 on the test map). It took two more days of new content to climb back to 13,800.

So a check count measures how much data a test happens to walk over, not how much behaviour is covered. We still print it because a sudden drop is a useful alarm. We don't brag about it.¹

Regression tests reproduce the bug first #

When a bug is found, the fix comes with a test that reproduces the original failure. One of the first: dead monsters are freed while a Shadow's spawn list still holds them, and a typed lambda then errors. The test does exactly that:

	spawned[0].free()
	spawned[1].die()
	_check(shadow.alive_count() == shadow.wave_size - 2, "freed and dead mobs no longer count (got %d)" % shadow.alive_count())
	shadow.spawn_wave()
	_check(shadow.alive_count() == shadow.wave_size * 2 - 2, "next wave still spawns")

The lesson also went into CLAUDE.md, so the AI doesn't write that kind of code again. The same pattern held for a GPU problem later on: when big maps ran out of GPU descriptors,² the fix came with a test that a map's props share a handful of materials and that a far-away monster releases its model.

Tests never touch the player's files #

The game writes options, window layouts and tutorial progress to user://. A test run that overwrote the human's key bindings would be a nasty surprise, so the runner points every one of those at a throwaway file before anything else runs:

func _initialize() -> void:
	WindowDragger.layout_path = "user://test_ui_layout_%d.cfg" % randi()  # never touch the player's layout
	LootHint.progress_path = "user://test_tutorial_%d.cfg" % randi()
	GameSettings.path = "user://test_options_%d.cfg" % randi()  # never the player's options

Save tests set SaveSystem.root_dir to a temp directory, and the terrain disk cache can be switched off for tests. The same care applies to processes: the human often has the editor or the game open while the AI works, so test processes are always wrapped in timeout, and the AI never kills a Godot process it didn't start.

A map just for tests #

Real maps get reshaped all the time. Map 1 has been rebuilt from scratch, then shrunk, then dressed with nearly a thousand pieces of clutter. Tests that depended on "the pond at (45, -8) in the Vale" would break with every redesign. So there's a dev-only map, the Proving Grounds, generated by a Python script: a safe square with shops and every NPC role, training dummies, every kind of liquid, an arena, "The Wilds" (a hunting strip with packs, Shadows, a road and mountains), and a "zoo" with one passive monster of every type. Maps with a dev_ prefix load by id but stay out of the world, achievements and exploration. CLAUDE.md says: "Prefer it for new tests and scenarios: the real maps get reshaped."³

A related rule came from an early surprise. Maps sit 5000 m apart, and their offsets come from sorted map ids, so adding a new map file shifted every map after it and broke tests that used raw coordinates. Tests now always place things with map.to_global(local). With 20 dungeons added as map files, that rule has been worth a lot.

The Proving Grounds from above (fog switched off for this view): the test square, liquids, the zoo and the arena

Tests outside Godot #

Not everything runs in the engine. The dungeon generator⁴ is plain Python, and it has its own selftest.py: pressure plates and beams built from templates, latching gates, guide mazes, shifting walls, illusion walls, ice slides and hazard marks. More importantly, the generator refuses to write a dungeon its solver can't finish, so an unsolvable layout never reaches the game at all. The balance model is Python too and is checked the same way a spreadsheet is: by rerunning it after every data change and reading the charts.

A combat simulation instead of a playtest (almost) #

Balancing 20 dungeons and 90 levels by hand would take weeks of play. So tests/sim_combat.gd runs the real game code headless as fast as the CPU allows (about 70 times real time): real Actors, real monster AI and boss phases, real skills, real dungeon mechanics. Bot players drive their characters through the same command_* methods as the player controller. They swing the combo, cast their school's skills, drink potions when low, and step out of every telegraphed attack after a 0.3 second "human" reaction time. Whatever still hits them is what a careful player can't avoid.

It fights every hunting zone, every boss and every dungeon room, per school, solo, with companions and in a party of four, and prints tables: time to kill, damage taken and by which attack, potions, deaths and the biggest single hit. The first run found that nothing in the game could hurt you and nothing lived (packs died to the opening skill burst in under 1.5 seconds), and that one boss took 150 to 230 seconds because the bots kept hitting him while he was shielded.⁵ The bots can't walk mazes or solve puzzles, so dungeon run times still need a human with a stopwatch.

Smoke runs and network bots #

Unit tests check pieces. Two cheaper checks cover the whole:

Smoke runs: start the start menu headless for 60 frames, and the game for 300, then grep for errors. This catches problems that only happen when everything is live together: autoload order, scene wiring, a missing resource.
Network bots: tests/net_test.sh runs a host and a client that play on their own (fight, loot, party up, enter the dungeon), then a passworded dedicated server. The multiplayer post covers them. They now run on a random port with their own log folder, so parallel runs don't collide.

Screenshots: how an AI checks visuals #

Tests can't tell you that the grass is the wrong green or a window covers the hotbar. For that, the AI takes screenshots and looks at them itself. tests/screenshot.gd renders any scene for a few frames and saves a PNG. On top of it there are scenario scripts: scripted sessions that set something up and photograph it. There were 15 when this series was first drafted. There are now 44: every skill of a school, the inventory, the upgrade window, every NPC up close, the animals in town, the story's finale, the scenic spots of the Vale, and one per batch of dungeons that photographs the gate, every room, each mechanic in action, the boss and a top-down overview.

That last kind changed how visual review scales. Ten dungeons produce a few hundred screenshots, and the coordinator can't look at every one carefully. So each dungeon batch also produced contact sheets (all of a kit's pieces on one image, all of a dungeon's monsters on another), and the review starts there.

For visual changes the rule is before-and-after: a screenshot of the current state, the change, the same shot again, and a look at both. Many visual commits show iteration in small steps. The lens effect, for instance, got three follow-up commits within three minutes ("only at the outer corners", "half the corner blur", "a bit more color fringing").

The Demon Tower's nine floors from one scenario run: every floor photographed at the default camera

Screenshots from the early scenario scripts and the network bots

A before/after pair as the AI sees it: the lower-left corner with the lens effect off and on

Bugs found along the way #

From the commit messages and agent reports:

Ranged monsters never set their home position and walked with NaN directions.
Monsters across a map border stood frozen like a wall, because only the player's map was awake.
A moved window kept its biggest size: the skill window got stuck at full height.
Moving an actor between maps inside a physics callback segfaulted Godot. That one is now a rule in CLAUDE.md.
Two agents each added a test helper named _room_mid to the same test file, and the whole suite stopped parsing until one of them renamed theirs.⁶
New class_name scripts aren't known until Godot refreshes its class cache, so a suite that suddenly "can't find" a class usually needs --import, not a fix. That line is also in CLAUDE.md now.

What tests can't do #

The CLAUDE.md line is honest about the limits: tests and smoke runs don't cover visuals or game feel. "Ask the user to playtest anything about feel." Whether the combo has a good rhythm, whether a blow seems to land when its damage number appears, whether a full sprint bar should last 5 seconds or 25 (it went from one to the other two minutes after sprint landed): these are questions for a human with the game in their hands. The combat sim narrows the questions; it doesn't answer them.

Takeaways #

No framework needed. A few dozen lines of runner and a _check function go a long way.
Loop over your data. One test function per rule, not per item, gives thousands of checks for free and catches broken references between files. Just don't read too much into the total.
Grep for engine errors, and compile your shaders. A green headless run with a broken shader isn't green.
Isolate the player's files and processes. Tests that touch real settings or kill a running editor destroy trust quickly.
Simulate what you can't play. Bots that use the same commands as the player turn "is this boss too hard?" into a table.
Make the AI look at its work. Screenshots turn "I changed the shader" into "I changed the shader and here is what it looks like now".

What's next #

Next is the content pipeline: how every monster, weapon, building and tree in the game is built by Python scripts in headless Blender, and what went wrong with the first batch.

The title of this post is a small exception. ↩
The performance post has the story. ↩
F10 takes you there in a debug build. ↩
It has its own post. ↩
The balance post has the numbers. ↩
The coordinator post has more on parallel agents. ↩

Server-Authoritative Multiplayer in Godot, Single Player Included

2026-10-09T12:00:00Z

The decision: single player is a local server #

The human set the multiplayer direction early: Valheim-style hosting. Players host for friends from the game or run a dedicated server. Characters live on each player's PC and can join any world, and the world lives with whoever hosts it. Up to 16 players.

The key engineering choice followed from that. Single player is just a local server with one player. No separate offline code path exists that could drift apart from the online one. If something works alone, it runs the same server code it would run online. The cost is that every gameplay system has to be written with the network in mind from the start. The multiplayer commit arrived on day two, after combat, skills, loot, maps and saving existed, and it changed 33 files. After that, every new system was born networked.

The start screen: characters, worlds, Host / Join and the Steam status line (account name hidden)

Four roles per actor #

Every Actor (players, monsters, Shadows, companions) has a network role:

enum NetRole { LOCAL, OWNER, PROXY, PUPPET }

LOCAL: simulated here. Everything in single player, and monsters on the server.
OWNER: a client's own player. It moves locally so input feels instant; everything else goes to the server.
PROXY: the server's copy of a client's player. Combat, damage and loot happen here.
PUPPET: a client's view of anyone else. It only shows what the server says.

CLAUDE.md states the rule: "Gameplay code runs only where the role says so; check net_role / multiplayer.is_server() rather than assuming." Movement is client-authoritative but sanity-checked by the server. Combat, damage, loot, items and progression are decided by the server.

One way to create things #

Every dynamic entity (players, monsters, Shadows, training dummies, loot, books) is created through one function on the server:

## Server: creates an entity (replicated to clients on its map). `data` needs
## "kind", "map" and "pos" ([x, z], map-local) plus kind-specific fields.
func spawn(data: Dictionary) -> Node:
	var d := data.duplicate(true)
	d["name"] = "E%d" % _next_id
	_next_id += 1
	return spawner.spawn(d)

That dictionary goes through Godot's MultiplayerSpawner, and World._build_entity builds the same node from it on every machine. The rule in CLAUDE.md is short: "Never add_child gameplay entities directly (tests excepted)." Spawning from a plain dictionary has a nice side effect: anything that can be spawned can also be described in a map file, and the dungeon and proximity spawning code just builds those dictionaries.

State versus events #

We split what goes over the wire into two kinds:

State is replicated with MultiplayerSynchronizer. The list is short on purpose:

const ACTOR_SYNC := [["net_pos", true], ["net_facing", true], ["net_time", true], ["hp", false], ["max_hp", false], ["is_dead", false]]

The boolean says whether the property goes out every tick or only when it changes. Players add a few more fields (map, mana, level, title, weapon look).

Events are things that happen: a swing, a hit, a death, a skill effect, a Shadow wave. These go through Actor.net_event(kind, args), which sends an RPC from the server to every peer that can see this actor:

func net_event(kind: String, args: Array = [], only_peer: int = 0, skip_peer: int = 0) -> void:
	if not is_networked() or not multiplayer.is_server() or map == null or map.world() == null:
		return
	for peer: int in map.world().peers_seeing(self):  # incl. peers across a joined border
		if peer == 1 or peer == skip_peer or (only_peer != 0 and peer != only_peer) or not can_reach(peer):
			continue
		_rpc_event.rpc_id(peer, kind, args)

can_reach is there because of a bug the network bots found on the first day: an RPC about an entity whose spawn message hasn't arrived yet fails on the client. Now an entity has to be at least 300 ms old on that peer's map before events about it are sent.

The UI never changes anything #

On a client, the inventory window can't move an item. It can only ask:

func request(action: String, args: Array = []) -> void:
	if net_role == NetRole.OWNER:
		_rpc_request.rpc_id(1, action, args)
	else:
		perform_action(action, args)

perform_action runs on the server and starts with the comment "Arguments come from the network, so everything is validated here." It checks indices, ownership, levels, gold and room in the bag, then applies the action. The owner gets a fresh snapshot of its character back. In single player, request just calls perform_action directly. It's the same code with no network hop.

Trading shows the pattern at its strictest. Both players put items and gold up, both lock, both accept. Then the server checks that everything is still there and fits, and swaps it all at once. Any change unlocks both sides.

Who sees what: interest management #

At first, visibility was per map: a peer received everything on its player's map and nothing else. That was fine for 480 m maps. When Map 1 grew to 2.6 x 3 km, streaming every monster on the map to every player stopped making sense. Now the synchronizers carry a visibility filter:

func _peer_sees(peer: int, node: Node) -> bool:
	var player: Actor = players_by_peer.get(peer)
	if not is_instance_valid(player) or player.map == null:
		return false
	var node_map := str(node.get_meta(&"map_id", ""))
	if player.map.map_id == node_map:
		if node is Actor and players_by_peer.values().has(node):
			return true  # other players: always (party, duels)
		return not node is Node3D or (node as Node3D).global_position.distance_to(player.global_position) <= INTEREST_RANGE

Other players on your map are always visible (for party frames and duels). Everything else is visible within INTEREST_RANGE, 160 m. Maps without players sleep entirely: their monsters don't think.

Smooth movement from jittery packets #

Remote players and monsters used to stutter on real connections. Packets arrive bunched up, especially over Wi-Fi. The fix is classic snapshot interpolation in NetSmoother: every sample carries the sender's timestamp, and we show the actor where it was 100 ms ago on the sender's clock, interpolating between the two samples around that moment.

## How far in the past we show things. Must cover a couple of send intervals plus jitter.
const DELAY_MSEC := 100.0
## Past the newest sample we keep moving along the last velocity for at most this long.
const MAX_EXTRAPOLATE_MSEC := 80.0
## A jump this big between two samples is a teleport (portal, respawn, dash): no gliding.
const SNAP_DISTANCE := 6.0

The clock offset follows the fastest packets down immediately and drifts up slowly, so jitter doesn't shake it. Players sync at 30 Hz, everything else at 20 Hz. A unit test feeds the smoother bunched packet arrivals and checks that playback stays even.

One design consequence: hit-stop (the brief freeze when the combo finisher connects) is single-player only. Freezing the server would freeze everyone.

Host and client in the same Crypt fight, both driven by the test bots

Dedicated servers #

A dedicated server is the same game started with --server, or exported as its own build. It reads a server.cfg (name, world, port, password, max players, autosave interval, message of the day) and creates one with comments on first start. A console takes status, save, say, kick, event and stop. A STOP file in the save folder shuts it down cleanly, which is handy for service managers.

Linux got the same treatment from the start. Exports for Windows and Linux, game and server, exist as presets. The first Linux run under WSL found a real problem: a blocked stdin read deadlocked process exit on Linux. The fix was --no-console for when nothing reads stdin, plus a watchdog.¹ A later fix made World.shutdown free entities before the spawner on every quit path, because the exported Linux server had logged one error per entity on exit.

A dedicated server's console: joins, autosaves and the once-a-minute status line

Steam lobbies #

For playing with friends, the game uses the GodotSteam GDExtension: friends-only lobbies, overlay invites, "Join Game" from the friends list, and a Join <friend> button on the start screen when a friend is hosting. Dedicated servers stay on ENet.²

The important constraint: everything must work with Steam off. Tests, headless runs and dedicated servers never touch it. The Steam test itself needs two humans and two Steam accounts, so it's a written checklist in HOSTING.md. The human ran it with a friend the day after the feature landed, and it passed.

The bots #

Automated tests of a networked game are worth more than any amount of reasoning about it. tests/net_test.sh starts a headless host and a headless client, both driven by tests/net_bot.gd:

Automated player for network tests (main.gd adds it with --bot). Takes over our own player: walks to the nearest enemy, fights it, picks up loot, spends an attribute point through a server request, and prints what it saw.

Over time the bots learned to form a party, accept a quest, receive a world event, enter the dungeon together and hire a companion. The script then starts a passworded dedicated server, checks that a wrong password is refused and the right one plays, and that the world gets saved. At the end it prints each side's report and the number of engine errors.

The first bot run found four bugs before any human connected: synchronizer visibility, RPCs sent before spawns arrived, cyclic preloads, and the spawner on a reused local player node. A later one found that owners lost their own player after a map transfer, because the visibility meta wasn't updated.

tests/net_test.sh: host + client bots, then a passworded dedicated server, with engine error counts

What doesn't go over the network #

The newer systems taught a second lesson: the cheapest replicated state is the state you don't replicate. A lot of the world is presentation that every machine can compute for itself from data it already has:

Time of day. WorldClock reads the wall clock (a 36-minute day), so every player sees the same sun without a single packet. The one catch is that a player's PC clock can be wrong, so on join the server sends its own wall clock and clients keep the difference (server_skew). Everything timed by the clock (the sky, the caravan merchant's schedule, townsfolk routines) then matches the server.
Townsfolk and animals. The 66 townsfolk walk their daily routines and the cats, dogs and goats wander on schedules that are all derived from the same clock and a seeded hash, so everyone sees them about where everyone else does. There is no spawn, no sync and no collision. The one exception is petting a cat or dog: that is a server request, and the server checks it loosely against where the animal's schedule says it should be (a "leash" of 18 m), because nothing else may depend on where a presentation-only actor happens to stand.
Dungeon devices (levers, gates, rising lava, bells, light beams) are gameplay, so the server runs them. But they're built on every machine from the map data, and only their state goes out: one reliable message when something changes, plus a refresh every second. Moving parts like light beams are drawn from a shared clock, so clients don't need a stream of positions.

The rule of thumb that came out of it: if it's derived from data and a clock, compute it everywhere; if a player's choice can change it, the server owns it.

Takeaways #

Make single player a local server if you want multiplayer at all. One code path is easier to keep right than two.
Separate state from events. Replicate a few properties; send everything that happens as an event to the peers who can see it.
The UI asks, the server decides. request → perform_action → snapshot. It also makes cheating through edited clients much harder.
Write a bot. It finds the race conditions you'd otherwise find with a friend on a Friday night.

What's next #

The bots are one part of a larger safety net. The next post looks at the whole test setup: about 13,800 headless checks, screenshot scenarios, and how an AI developer checks its own visuals.

HOSTING.md has a systemd unit example. ↩
During development the game uses Steam's test app 480. ↩

Skills, Items and Loot as Data

2026-10-09T12:00:00Z

Why data first #

A grind game lives on its numbers. How wide is Whirlwind? How often does a Shadow drop a skillbook? What does a +6 attempt cost, and how often does it fail? Those numbers change all the time while you balance, so we decided early that they live in data/*.json and not in code. CLAUDE.md says it bluntly:

New skills go in data/skills.json only. If a skill needs a new kind of effect, add a building block to SkillExecutor (and a test), never a one-off script per skill.

Content is data: new NPCs, shops, mobs, Shadows, zones and maps go in data/, not code.

This post walks through three systems built that way: skills, items with random bonuses, and the blacksmith's upgrade track.

Skills are effect blocks #

There are four schools with six skills each. Every skill is a JSON entry made from a small set of building blocks: a shape (arc, circle, line, ground or self) plus modifiers like hits, knockback, pull, dash, heal and buffs. Here is the Blade school's Whirlwind:

{
	"id": "whirlwind", "motion": "spin",
	"fx": {"hit": [{"block": "spin"}, {"block": "ring", "scale": 1.05}, {"block": "burst", "kind": "sparks", "at": "caster", "count": 16}, {"block": "hitstop"}, {"block": "shake", "amount": 0.08}]},
	"name": "Whirlwind", "mana": 15, "cooldown": 6,
	"description": "Spin, striking everything around you. The dark comes from every side; so does the Blade.",
	"effect": { "shape": "circle", "radius": 2.6, "damage_mult": 1.6 },
	"mastery": { "radius": 3.2 },
	"grandmaster": { "radius": 3.8, "knockback": 1.6 }
}

Two keys in that entry arrived later and are purely visual. motion names the body motion the player's sprite plays (one of 13 shared motions such as spin, sweep, dash or slam, rendered per weapon type). fx is a recipe made from a pool of 17 effect blocks (slash, ring, pillar, beam, afterimages, shake, hitstop and so on). The hit itself is still only the effect block: what you see can change without touching what gets hit.

The mastery and grandmaster blocks are overrides. A skill's parameters at a given rank are the base effect with the overrides merged on top:

func params_for_rank(rank: int) -> Dictionary:
	var p := effect.duplicate(true)
	if rank >= SkillRules.MASTERY_RANK:
		p.merge(mastery.duplicate(true), true)
	if rank >= SkillRules.GRANDMASTER_RANK:
		p.merge(grandmaster.duplicate(true), true)
	return p

This makes tiers change what a skill does, not just its numbers. Cleave's arc widens from 160 to 210 degrees at Master and hits twice at Grandmaster. Charge dashes 6 m, then 8 m. The design doc asks for exactly that: "Each tier changes the effect itself, not only the numbers".

SkillExecutor turns the merged parameters into gameplay. It has one branch per shape, and every branch asks the pure Combat queries what's inside the shape:

	match shape:
		"arc":
			var arc_deg := float(p.get("arc_deg", 90.0))
			targets = Combat.actors_in_arc(scope, here, dir, radius, arc_deg, caster.team, caster)
			SkillFx.fan(caster, here, dir, radius, arc_deg, skill.color, tier)
		"circle":
			targets = Combat.actors_in_circle(scope, here, radius, caster.team, caster)
			SkillFx.disc(caster, here, radius, skill.color, tier)

That's the second architecture rule at work: "Combat is shape-based, never tab-target." There is no target selection anywhere in the game. You aim at the ground, and everything in the shape gets hit. For a game about mowing down packs, that's the whole point.

Progression rules, also in one place #

The rules for raising skills sit in SkillRules as named constants, so they're easy to find and test:

The skill window (K) for the Blade school: M3 = Master rank 3, G = Grandmaster

One skill point per level. The 15th point in a skill turns it into M1 (Mastery).
M1 to M10 can only be raised with skillbooks, which drop from destroyed Shadows (40%) and never from ordinary mobs.
A read succeeds 70% of the time at M1, falling to 35% at M10. Each failure in a row adds 10% to the next try (bad-luck protection), and you have to destroy a Shadow between reads.
The 10th successful read makes the skill Grandmaster.
Damage grows 7% per rank, heals and buffs 3%.

The points math is deliberate. Taking all six of a school's skills to M1 costs 90 points, so you have to specialize.

The same disc, fan and rectangle effects at Normal, Master and Grandmaster, side by side

Items: base stats plus random bonuses #

data/items.json holds stat names, rarities, the random-bonus pool, rune rules, loot tables and the items themselves. Rarity decides how many random bonuses a piece of gear rolls:

"rarities": [
	{ "name": "Common", "color": "#d4d4d4", "min_bonuses": 0, "max_bonuses": 0 },
	{ "name": "Magic", "color": "#5aa2ff", "min_bonuses": 1, "max_bonuses": 2 },
	{ "name": "Rare", "color": "#f2d64b", "min_bonuses": 3, "max_bonuses": 3 },
	{ "name": "Legendary", "color": "#ff8c2a", "min_bonuses": 4, "max_bonuses": 5 },
	{ "name": "Unique", "color": "#ff3b5c", "min_bonuses": 5, "max_bonuses": 6 }
],

Bonuses come from a pool per slot (attack, HP, crit, attack speed, damage vs Shadows and more) and scale with item level. Unique is reserved for the four Fullmoon weapons, each school's sacred level 30 weapon, which is named after that MMO's Fullmoon Sword. They never come from normal rolls: a level 28+ Shadow drops one at 0.3% per weapon, a boss at 2%.¹

The item list itself has grown from 139 to 203 entries: 155 written in items.json, plus 24 skillbooks and 24 runes that ItemDb generates from the skill list and the rune table at load. The biggest single addition was a balancing pass that found a 56-level gap in armor² and filled it with 41 pieces in six sets. Models and icons came from the same Blender script as everything else, so filling a gap in the data was mostly a data change.

Loot that respects your level #

Players of the old MMO know the trick of farming low monsters at a high level. We cut it off with one small, testable function:

static func drop_factor(killer_level: int, victim_level: int) -> float:
	var gap := killer_level - victim_level - DROP_FREE_GAP
	return 1.0 if gap <= 0 else maxf(1.0 - DROP_LOSS_PER_LEVEL * gap, 0.0)

Up to 3 levels above a monster you get its full drops. Each level beyond that takes 25% off, so from 7 levels above nothing drops. In a party the gap counts from the highest-level member on the map, so a strong friend can't farm low monsters for the group.

Gold followed the same "one small formula" idea, but the first formula was wrong. Gold was originally the monster's XP reward times a factor from its loot table. When the balance pass raised late-game XP a lot, the model showed the median character finishing with about 16 million unspent gold. Gold now follows the victim's level instead (1.2 x (level + 2), so 14 at level 10 and 110 at level 90), times the table's factor.³ Prices grow linearly with level too, so the two stay in step.

Saves can't be trusted, so loading validates #

Characters live on the player's own PC and travel to any server they join. A server therefore has to assume that a character file may have been edited. Every item goes through ItemInstance.from_dict on load, which clamps and checks everything against the data:

	if item_data.is_gear():
		inst.rarity = clampi(int(d.get("rarity", 0)), 0, ItemDb.max_rarity_for(inst.data))  # Unique: Fullmoon only
		inst.upgrade = clampi(int(d.get("upgrade", 0)), 0, Upgrades.MAX_LEVEL)
		var allowed := ItemDb.rarity(inst.rarity).max_bonuses

Bonuses that aren't valid for that slot, values out of range and duplicate stats are all dropped. The same goes for levels, attribute points and skill points in CharacterSave.sanitize: impossible spends are refunded. A handful of tests feed deliberately broken characters through it.

A legendary Steel Blade: rarity colour, empty sockets, random bonuses and the comparison to the equipped Iron Sword

The blacksmith: +0 to +9 #

The upgrade track is pure data in data/upgrades.json. Each step has a success chance, a gold factor (multiplied by the item's value) and materials, which are used up whether you win or lose:

"levels": [
	{ "chance": 1.0, "gold_factor": 0.3, "materials": [ { "item": "shadow_shard", "count": 1 } ] },
	{ "chance": 0.95, "gold_factor": 0.4, "materials": [ { "item": "shadow_shard", "count": 2 } ] },
	{ "chance": 0.9, "gold_factor": 0.5, "materials": [ { "item": "shadow_shard", "count": 3 } ] },

Each level adds 12% to the item's base stats. The chance falls from 100% to 20%, and from +5 a failure also drops the item a level. Shadow Shards drop from every Shadow, and from +6 the steps need rare Shadow Cores from level 10+ Shadows. The last three steps also take Sunstone (1, 2, then 3), glass fused by an ancient light that only the Sunscar Desert yields in quantity, plus an 18% drop from level 55+ Shadows anywhere. The top of the ladder sends you to the desert, which gives an otherwise empty map a reason to exist.

The Fullmoon weapons get their own track in the same file: +36% per level instead of 12%, so a +9 Fullmoon beats a +9 level 60 weapon. Every step also needs the school's Moon Seal, earned through a chain of nine seal quests unlocked from level 30 to 60. Here the data shows its value. A later design change ("a failed Fullmoon upgrade keeps the Moon Seal but drains it: destroy Shadows to recharge") was mostly one new key:

"recharge_shadows": [5, 6, 8, 10, 12, 15, 18, 22, 25],

From glow to sparks #

The first version followed a vague memory of the classic: a +7, +8 or +9 weapon glowed red, green or gold, with a shine running up the blade. UpgradeGlow laid an additive shader overlay on the weapon's meshes. The human corrected it the same day: "the +7, +8 and +9 upgrade shouldn't glow but have particular sparks around the weapon, not too many. In [that game] you can see the sparkling." The rebuild draws a handful of pixel-art sparkles along the blade in the step's colour, and the +9 shine travels up the edge. Inventory icons got tiny matching stars instead of a coloured glow behind them. Every machine shows it, because the weapon's look (weapon_look) is part of each player's replicated state.

Haro the Blacksmith's upgrade window: chance, gold and Shadow Shards

+7, +8 and +9 katanas before and after the change: a full glow became a few pixel sparks

The earlier glow version in hand (+7 red, +8 green, +9 gold)

Runes and other small systems #

The same pattern repeats across the rest of the item game:

Runes: every monster has a kind (beast, goblinoid, cultist, undead, elemental, spirit, demon, shadow). Weapons have sockets by rarity, and a rune adds 2.5% to 10% damage against one kind. The tiers, bind chances (70 / 45 / 25%) and drop rates are all a few lines in items.json.
Scroll of Renewal: drag it onto gear to reroll its random bonuses. There are no "add bonus" scrolls; the human decided against them.
Boost potions, storage shared between your characters, trading with a two-step lock and accept, and daily bounties: each is data plus one validated server action.

Tested from the data #

Because content is data, a whole group of tests checks the data itself: every skill has a valid shape, every item referenced by a loot table exists, every quest points at real NPCs and monsters, every upgrade step names a real material. When someone (human or AI) edits a JSON file by hand, the suite says what is broken before the game does. It doesn't make mistakes impossible. Once, a map's description text gained unescaped quotes, the whole map file stopped parsing, and it took a fix commit three minutes later. This is why test_map_data_is_consistent loads every map file, including the ones no other test uses, and checks its zones, spawns and references.

Takeaways #

Pick your building blocks and stick to them. Five shapes and a handful of modifiers carry 24 skills and their tiers. New effects become new blocks with tests, never one-off scripts.
Data makes design changes cheap. "Make Rare and Legendary much scarcer" or "drain the seal instead of losing it" becomes a data edit plus a test, not a refactor.
Validate on load. Portable characters are a lovely feature and a security hole. Clamp everything against the rules.

What's next #

All of these systems run on the server and work the same for one player or sixteen. The next post is about how that works: server-authoritative multiplayer in Godot.

They have their own post near the end of the series. ↩
Body armor stopped at level 30, the next set was the level 86 raid gear. ↩
Ordinary monsters 0.6-1.4, Shadows 10-20, final bosses 100-200. ↩

Building a Grindy Martial-Arts ARPG with an AI Developer

2026-10-09T12:00:00Z

What we are making #

Dekiro: Sanctuary of Shadows is a grindy hack-and-slash ARPG in the spirit of a popular Korean MMO. You mow down packs of monsters, level up, gear up and clear dungeons. Its signature target is the Shadow, our take on that MMO's famous stones: a corrupted monolith that stands in a hunting ground and keeps spawning waves of enemies until you break it. You choose one of four schools at level 5 (Blade, Iron Fist, Shadowstep, Sanctum). Skills are raised to Master and then Grandmaster with skillbooks. The blacksmith takes gear from +0 to +9, and the failure chance at the top end feels as cruel as it should.

The engine is Godot 4.7.2 with GDScript and the Forward+ renderer. The world is 3D with a third-person orbit camera; the characters in it are pixel-art sprites rendered from 3D models.¹ Multiplayer is server-authoritative (single player runs as a local server), with dedicated servers and Steam lobbies.

This series is about how it gets built. The team is unusual: one human developer, and Claude Code as the developer who writes all of the code.

The White Fox Shrine in Sanctuary Vale on the latest build: a sprite character in a 3D world

An early basic attack against a Lesser Shadow stone, back when the player was a placeholder capsule

The roles #

The split has stayed the same since the first commit:

The developer (human) decides what the game is. They set direction ("[that MMO's] grind, Valheim-style hosting, no in-game chat, players use Discord"), make the design calls, sketch maps on paper, approve visual designs and playtest. Anything about feel, such as timing, responsiveness or whether a hit lands, gets judged by a human with a mouse in hand.
Claude Code (AI) writes the code, the data files and the content generators. It runs the test suite, renders screenshots and looks at them, fixes what it finds, and commits each step with a message that says what changed and why.

Every commit in the repository carries a Co-Authored-By: Claude line. The human never writes code; they steer.

The pace #

The first commit, "Milestone 1: movement, multi-target arc attack, training dummies", landed on an afternoon in early October. At the time of writing the repository has 199 commits. Here is how they spread over the days:

Day	Commits
1 (afternoon only)	8
2	44
3	60
4	76
5	6
6	5

The last two rows look like a slowdown. They aren't. From day five on, most work was done by parallel subagents and committed by a coordinating session in large, reviewed batches.² One day-six commit alone touches 639 files and adds about 51,000 lines: NPC sprites, map mechanics and three dungeons. The days got fewer commits and much more content.

The committed history now holds about 61,000 lines of GDScript (17,500 of them tests) and about 42,000 lines of Python for the content tools: model builders, map and dungeon generators, a sprite renderer, a music synthesizer and a balance model. Those tools are covered in later posts.

Speed is not the point of this post. It matters for one reason: at this pace, nobody can keep the whole project in their head. Neither the human nor the AI, which starts every session cold. The project has to remember itself. That is what CLAUDE.md is for.

One day of commits (the 8th of October): 60 of them

CLAUDE.md: the rulebook #

Claude Code reads a file called CLAUDE.md at the root of the project at the start of every session. Ours started with milestone 1 and has grown with every system since. It holds the commands (how to run tests, smoke runs, exports, the Blender builders, the sprite renderer), a map of where things live, and, most importantly, architecture rules. Three of them go back to the first commit (quoted here in their current wording):

Controllers drive Actors only via command_* methods (command_move, command_attack, …). PlayerController, future AIController (companions/mobs) and any future network input must be interchangeable.

Combat is shape-based, never tab-target. Attacks query a shape (arc, circle, line) via Combat and hit everything valid inside it.

Logic is separate from visuals. Actors hold no meshes; a child visual node (currently PlaceholderVisual) reads Actor state and listens to its signals.

These rules paid off again and again. The command interface meant that AI companions (who join your party and fight with you) could use the same player scene with CompanionAI swapped in for PlayerController. Network input fit the same interface, and so did the bots of the combat simulation that later balanced the game. Keeping logic apart from visuals meant that the capsules could be replaced twice without touching gameplay: first by 3D monster models, then, for players and NPCs, by 8-direction pixel sprites. Both times one visual node was swapped.

The second kind of rule is the more interesting one: rules that come from bugs. When something breaks in a way that could happen again, the fix goes into code and the lesson goes into CLAUDE.md. Examples from the current file:

Dead mobs are freed while other code may still reference them (Shadow spawn lists, AI targets, delayed skill hits). Never pass a possibly-freed object into a typed parameter or typed lambda (func(a: Actor)): Godot errors with "Cannot convert argument 1 from Object to Object".

Never reparent or move bodies inside physics callbacks (body_entered etc.): defer it. […] Doing this inside a callback segfaulted Godot.

Headless runs never compile shaders: after any shader edit (incl. shader strings in .gd files) take a windowed screenshot of main.tscn and grep its log for ^ERROR (a uniform named like a local in a shared .gdshaderinc, e.g. shade vs clouds.gdshaderinc, once turned every sprite into a white wall).

That last one is two days old. Each of these cost time once. Written down, they don't cost time again, because the next session reads them before writing a single line.

The architecture rules in CLAUDE.md

The loop #

The working loop is short and strict. It's written into CLAUDE.md like this:

Run tests + smoke run after every change. […] Neither covers visuals or game feel, so after visual changes take a screenshot and look at it; ask the user to playtest anything about feel.

In practice a step looks like this:

Implement the feature, data first where possible (more on that in the next post).
Add tests to the headless suite. A test is a plain test_* method that calls _check().
Run the suite. It currently runs 341 test functions with about 13,800 checks. Godot engine errors don't fail a test on their own, so the log is grepped for ERROR lines as well.
Smoke-run the game headless for a few hundred frames, to catch errors that only show up when the whole scene is live.
For networking changes, run bot clients against a host and a dedicated server.
For anything visual, render a screenshot, look at it, fix it and look again. Claude Code reads the PNGs itself.
Commit with a descriptive message.

The commit messages became the project's diary. A typical one:

Fix errors from freed mobs in Shadow spawn tracking

alive_count() filtered with a typed lambda; once a dead Shade was freed, Godot refused to pass it ('Cannot convert argument 1 from Object to Object') and the filter returned an untyped Array. Check validity on untyped values instead; same hardening for MobAI targets and delayed skill hits. Regression tests reproduce the original errors.

That message has everything: the symptom, the cause, the fix, the related places hardened at the same time, and the regression test. We wrote most of this series by reading the git log.

Changing course is cheap (if the rules hold) #

The second commit set up a 3D world with a fixed isometric camera. About seventy minutes later another commit replaced it with a full perspective orbit camera (right-drag or Q/E to rotate, wheel to zoom). The design doc records the reason: the game should feel like the old MMO, with a camera you rotate and zoom yourself. Because movement input was already "screen-relative, converted to world space in PlayerController", the change touched six files.

Bigger reversals followed. We built a seamless open world with land bridges between regions, then switched it off nine hours later in favour of separate maps linked by torii portals. The first big map was then shrunk by about two thirds twelve hours after it was built, because it felt too big and too empty. The player character went through six 3D drafts before the human picked a completely different technique: 3D models pre-rendered into pixel sprites. Each of these turns has its own post. What matters here is that the rules made them survivable. Nothing outside the world code knew whether maps were joined or separate, and nothing outside the visual node knew whether a character was a capsule, a model or a sprite.

What the human actually decides #

From the outside, "the AI writes all the code" can sound like "the AI makes the game". It doesn't. Some decisions from the history, all made by the human:

Valheim-style hosting: dedicated servers, characters stored on the player's PC and portable between servers, world events per server.
No in-game chat, no player shops, no "add bonus" scrolls (rerolls only).
The open world was switched off; every map keeps one town ("Keep safe zones to one per map").
Map 1 was drawn by hand on a grid (1 square = 25 m) and translated into data.
The Bulwark school's battleshields became fist weapons ("a shield to attack is hard to go for"), and the school became Iron Fist.
"Solid trees, but see in deep woods". That one is preserved in a code comment in flora.gd, which dissolves the leaves between the camera and your character but keeps trunks opaque.
Every visual direction: the Valheim-like pixel texture look at first, then the switch to HD-2D sprites, keeping the grass because they liked it, and the decision that +9 weapons sparkle rather than glow.
The target length: "about 40 hours of actual gameplay minimum" to the level cap, which drove a whole balancing pass.

The AI proposes, implements and verifies. The human chooses. When a question is really a design question, the AI asks; otherwise it keeps going. Asking too often would waste the human's time. Asking too rarely would build the wrong game. Some answers are short. The human's verdict on one batch of AI-drawn sprite mock-ups was unprintable, followed by: "the rendered 3d to 2d one look way better". That sentence set the art direction for everything after it.

Where it stands #

Six days in, the game has nine world maps (each with one town, waystones and landmarks), 20 dungeons from a generator with solvers, 177 monster types plus 11 kinds of Shadow stone, 203 items, 24 skills, 87 quests including a main questline that unfolds with your level, 43 NPCs and 66 townsfolk with daily routines, 30 original music tracks and a progression model that aims at about 40 hours to level 90. None of it has had a real playtest beyond the human's own sessions yet, and the posts say so where it matters.

Takeaways #

Write the rules down where the AI will read them. CLAUDE.md is not documentation for later. It is the memory that makes each session start where the last one ended.
Turn every painful bug into a rule. The fix stops the bug once. The rule stops the whole class of bug.
Tests are what make speed safe. Without the suite, 40 to 70 commits a day would be 40 to 70 chances to break something quietly.
Keep feel for humans. Tests can prove that the combo's finisher does 1.8x damage. They can't prove that it feels good.

What's next #

The next posts go system by system: data-driven skills and loot, multiplayer, the test suite, the Blender pipeline that builds every model from Python, the maps, performance, the art direction (and how it changed), the synthesized music, fishing, and how the work moved from one AI session to a coordinator with parallel subagents. After those come the newer pieces: the HD-2D sprite pipeline, the dungeon generator, the story, the 40-hour balance model, the living towns and the Fullmoon weapons.

The "HD-2D" look, which has its own post. ↩
The coordinator post in this series explains how. ↩

Dekiro: Sanctuary of Shadows · Dev Blog

Mastery Past the Cap: Ten Grandmaster Ranks, a Hidden Rank, and the Soul Jade

Where the ladder used to end #

Ten more rungs #

One jade for every skill #

The odds, and why a failure still counts #

Rest for the mind #

Bosses drop it, by chance #

Peerless: the rank nobody tells you about #

A clear step, not a bigger number #

How long it takes #

What we're not sure about #

Takeaways #

What's next #

A Dev Blog in the Game's Style

Drafts in the repository #

One script, no framework #

The game's UI, in CSS #

Fonts: 2 MB down to 6 KB #

Images: WebP with fallbacks #

Social cards, a feed and the boring parts #

No tracking #

Checked by a robot #

A Tufte-inspired layout #

What it took #

Takeaways #

What's next #

Baking the Minimap: Top-Down Renders of the Real World

"Hard to orient with that" #

Draw it, or photograph it? #

Step 1: Godot renders the map from above #

Step 2: Python makes it look like a map #

Step 3: the game draws it #

Checking that it lines up #

What it costs #

What isn't perfect #

Takeaways #

What's next #

Every Platform from One Windows PC

Seven presets #

Export templates, once #

The JSON that didn't ship #

Windows #

Linux, checked in WSL #

macOS: universal, ad-hoc signed, and Steam #

Android and iOS #

Dedicated servers #

Testing a build you can't click through #

Shipping it #

Takeaways #

What's next #

A Tavern, Named Hens and Cats: The Small Stuff

"Everything is happening in the center" #

Out onto the roads #

A checker that walks the routes #

The Bierlinger Tribe #

Seven hens with names #

Petting, briefly #

Still no network traffic #

Takeaways #

What's next #

Weather That Fights Back

A map should play differently, not just look different #

One node, two halves #

Heat and Cold: one meter, two personalities #

The event mechanics #

Duskmoor: the Lightless Rite #

Frostpeak: avalanches #

Ember Wastes: lava that moves, and drakes that dive #

Hellmouth Rift: demon portals #

Shadowlands: the shade #

The ground isn't flat #

Testing weather #

Takeaways #

Bots That Play for Balance

Why a simulation, and why bots #

The rule that made it cheap #

A bot that plays like a careful player #

Three configurations, four suites #

What it found #