DEV Community: Charles Zhang

Building Multilingualism with Claude and Divooka App Platform

Charles Zhang — Thu, 22 Oct 2026 19:21:39 +0000

There is an interesting theory in linguistics, namely the arbitrariness of the linguistic sign: there is no inherent or necessary connection between a word's sound (the signifier) and its meaning (the signified).

Background

The arbitrariness of the linguistic sign - a fundamental principle of linguistics associated with Swiss linguist Ferdinand de Saussure - dictates that there is no inherent or necessary connection between a word's sound (the signifier) and its meaning (the signified).

For example, the same animal is called:

English: dog
French: chien
German: Hund
Japanese: inu (犬)
Mandarin: gǒu (狗)

These different sounds refer to essentially the same concept. Nothing about the animal inherently requires any particular pronunciation. Saussure formalized this principle in his Course in General Linguistics (1916).

However, arbitrariness doesn't mean complete randomness. There are important qualifications, including onomatopoeia (words imitating sounds), sound symbolism (certain sounds being associated with particular qualities), and historical relationships between languages.

The deeper implication is that meaning is established through social convention rather than through any intrinsic relationship between sound and concept.

Motivation

I'm not a language expert. I just enjoy exploring languages, particularly when designing my own fictional languages. Sometimes I want to know how a word or phrase is expressed across different languages, either out of curiosity or simply for inspiration.

For years, In Different Languages has been a great resource for this. Enter an English word, and you get translations in over 100 languages. Simple and useful.

Unfortunately, the website frequently becomes unavailable or unreasonably slow. Sometimes a simple word lookup takes far longer than it should.

To be clear, I never had a problem with its advertisements. Hosting a website costs money, and I have no objection to reasonable monetization. My frustration was purely about reliability and responsiveness.

Eventually, I thought: why not build my own?

There was another motivation. I've been developing Divooka App Platform, and wanted a practical project to test its capabilities. Rather than making another trivial demo, I figured a multilingual dictionary would be a useful real-world test.

That's how Multilingualism came about.

Building with Claude and Divooka

The entire application was built with Claude through Divooka App Platform's MCP connector.

Instead of manually writing the website and processing scripts, I worked with Claude to define the requirements, develop the translation pipeline, implement the interface, and iterate on the results.

For me, this was as much an experiment in AI-assisted development as it was a dictionary project. I wanted to see how far we could take a complete, usable application through the platform's MCP integration, rather than just generating isolated code snippets.

The initial concept was straightforward: gather translations from available open sources, fill missing entries where possible, and publish the results through a fast, lightweight website.

Of course, collecting translations is one thing. Making them reasonably consistent across 108 languages is another.

Since I'm not a linguist, I didn't want to pretend I could personally verify every translation. Instead, we designed the process around existing dictionary data, explicit source attribution, automated checks, and community corrections.

Building the Translation Dataset

We started with the English Wiktionary, using structured extracts provided by kaikki.org through Wiktextract.

Rather than importing the entire dictionary, Claude helped build a Python pipeline that processes the data in several stages:

Extract: Stream the Wiktionary JSONL dump, keeping English entries with translation tables, definitions, parts of speech, and relevant metadata.
Select: Use wordfreq to prioritize common English words and phrases, considering translation coverage and normalizing language variants.
Fill: Identify missing word-language pairs and generate translation jobs for Claude, including the intended meaning and part of speech.
Validate and merge: Compare machine-generated results against hidden Wiktionary control samples, flag uncertain translations, and prioritize Wiktionary when both sources are available.
Publish: Generate compact JSON files organized by word and language, along with metadata and source information.

We also use Princeton WordNet to organize words into categories.

The resulting dataset contains 9,852 English words and phrases across 108 languages, representing over a million word-language translation entries. Roughly half come from Wiktionary, with the remaining gaps filled by machine translation.

One interesting challenge is that translation isn't always one-to-one. A word like "light" can refer to illumination, weight, or colour. Translating the wrong meaning produces perfectly valid words that are completely wrong in context.

The pipeline therefore considers definitions and senses rather than translating isolated English strings.

There are also complications involving writing systems, transliteration, dialects, archaic forms, and regional conventions. For example, Simplified versus Traditional Chinese, or Serbian versus Croatian spelling conventions.

Quite a bit of processing logic goes into these details.

A Website Without a Backend

For the website itself, we deliberately kept the architecture simple.

The frontend uses plain HTML, CSS, and JavaScript. No frontend framework, no build step, and no application server.

All translation data is stored as JSON in the GitHub repository and served through the jsDelivr CDN. The application fetches only the necessary files, caches requests in memory, and falls back to GitHub-hosted data if the primary source fails.

There is no reason to query a translation model every time someone looks up a word. The expensive processing is done ahead of time.

This design also gives us something useful almost for free: a public JSON API.

For example, the following URL retrieves translations for "thank you":

https://cdn.jsdelivr.net/gh/MethodoxTech/Multilingualism@main/data/words/thank_you.json

Developers can also retrieve complete language datasets, such as data/langs/ja.json, or the full word index. For reproducible applications, CDN URLs can be pinned to a specific Git commit instead of main.

There's no API key, authentication, or dedicated backend to maintain. The data is also accessible directly from JavaScript applications through CORS-enabled responses.

More details are available on the API page.

Accuracy and Open Contributions

Naturally, machine translation isn't perfect, especially across so many languages.

We generate translations with specific meanings and language conventions, and use control samples to estimate agreement with existing Wiktionary translations. However, automated checks are not a substitute for native-speaker review.

That's why we explicitly identify machine-generated translations, including those marked as uncertain, rather than presenting everything as equally authoritative.

We also preserve the translation sources and publish machine-generated entries as reviewable TSV files.

If you spot an incorrect or awkward translation, you're welcome to open a GitHub issue. The website provides a correction link that pre-fills the relevant context.

Corrections to Wiktionary-derived translations are best contributed upstream, so other projects can benefit from them as well.

The application and pipeline code are MIT-licensed, while the translation data is published under CC BY-SA 4.0.

Final Thoughts

Multilingualism started from two rather different motivations: my frustration with an unreliable but otherwise useful website, and my curiosity about what Claude could build through Divooka App Platform.

The result is a small but practical application that I can actually use when exploring languages or inventing my own.

It's also a useful test of the development platform itself. We went beyond a simple UI demo and built a complete data-processing workflow, a static frontend, and a publicly accessible API through an AI-assisted development process.

I don't expect the dictionary to be perfect. Language is complicated, and even native speakers sometimes disagree on the most appropriate translation.

But the project is open. Anyone can inspect the data, report mistakes, suggest improvements, or use the JSON in their own applications.

And perhaps that's the part I appreciate most: something that began as a personal frustration has become a useful application and a real-world development experiment.

Try it: https://multilingualism.divooka.app/

Source code: https://github.com/MethodoxTech/Multilingualism

Built with: https://divooka.app/

DevLog: 2026-10-15 A Detective Story - Making It to The Release.

Charles Zhang — Fri, 16 Oct 2026 02:26:16 +0000

Overview

A Detective Story is a compact detective simulator that brings natural conversation to the heart of interactive fiction, where you can interrogate NPCs using natural languages - as they are powered by LLMs (well, SLMs to be precise).

A murder has taken place in the sunlit seaside town of Baytown, where everyone has a story. Question suspects, explore the town for clues, and test their alibis against the evidence. You may have only three days to solve the crime - and there may be more than one murderer!

Development Experience

Making a game is very different from building an app - or any other kind of software, for that matter. I don't think I've ever worked on a software project where even the smallest incremental improvement could feel so difficult.

Ironically, even though engine and gameplay development consumed nearly 80% of the development time, I'd still call it the "easy part" of the whole endeavor. Designing the story, integrating the graphics, and, most importantly, making sure the mystery is actually solvable - those turned out to be challenges that go well beyond the usual technical maneuver.

Reception

The initial trailer, despite its relatively simple graphics by today's standards, felt quite intriguing to me. The idea of fully integrating LLM-powered NPCs into a game is certainly nothing new, but it's still rarely seen in actual games.

I even told my friends that A Detective Story might end up being more popular than Fantasy Planet Painter. Both are niche titles, but ADS seemed more approachable and appealing to a broader audience.

Reality, however, told a different story. The game attracted relatively little interest during its first few months, which eventually led me to scale back the time and effort I was putting into getting it released.

Revival of Effort

With Divooka approaching maturity and preparing for its public release later this year, it's time to revisit and refine the integrated LLM capabilities within the Divooka ecosystem, particularly features such as RAG and knowledge base management.

ADS runs on Crime Engine, which itself is built upon components from Divooka, making it a natural testing ground for these capabilities.

On a more personal note, I also have other game projects in mind for Methodox. However, Project Aegis has made little progress, and Codename Wayhome remains a prototype. At some point, I really need to get a game across the finish line. Otherwise, I'm not sure I'll have the courage to embark on yet another game project!

The Things I Am Still Not Satisfied With

I suppose this is something every creative endeavor struggles with. I wish we could polish the scenes a little more, make the story more vibrant, bring the characters to life, and make our little fictional town feel more realistic and expansive. The list goes on and on. But we can't stay hidden forever. At some point, when things are good enough, we have to let our creations out into the world and see how they fare. Perfection is a difficult goal to chase, and perhaps an impossible one to reach.

On the model side, I can't honestly say the conversation experience is optimal yet. NPCs can sometimes be overly restrictive or reluctant to reveal information, making it unnecessarily difficult for players to piece together clues and solve the mystery. I suspect the best long-term solution might be to train a custom model specifically for this kind of interaction, perhaps taking inspiration from how Character.AI approaches conversational characters. That's certainly something worth exploring further.

Remarks

I'll share more about the technical side of using AI in game development in a future post.

References

Fantasy Planet Painter 2.0 Is Here!

Charles Zhang — Tue, 13 Oct 2026 17:55:06 +0000

Fantasy Planet Painter 2.0 is here! This is our biggest update so far: a completely rebuilt application, a new physical terrain system, richer rendering, layered painting, fantasy world layers generation, and a much more capable World to Beyond integration.

The Basics: From a Sketch to a World

In our earlier introduction to 2.0, we shared a first look at where Fantasy Planet Painter was heading. Now we would like to take a closer look at what you can create with this release.

Fantasy Planet Painter started with a simple approach to world-map creation: paint the broad shape of a world on a cell grid, and a procedural algorithm generates the details. A creator focuses on where continents, oceans, and mountains belong without having to draw every terrain detail.

That idea remains at the heart of 2.0. What has changed is how much more you can do around it. Heights can now have a physical meaning. Terrain can be built in layers. A painted planet can become an atlas of countries, cultures, settlements, and roads. And jump into very specific region of a world with additional details. After you are done experimenting with the shape, you can export the map and interactively play in Beyond All Reason.

A New Physical Planet

The new Physical World generator works with elevations measured in meters, and provides broader control of flexible height ranges, with 12 levels by default. This gives you finer control over the relationship between your painted terrain, the generated detail, and the sea.

Continuous elevations: paint specific heights, from deep ocean floors to mountain peaks, with twelve customizable paint bands to keep everyday painting approachable.
Independent sea level: explore how changing the water level reshapes your coastlines without repainting the whole planet.
Planet size and relief: adjust the planet radius and the strength of its terrain, with procedural detail that takes physical scale into account.
Seed control: keep a result you like or try a different realization of the same broad geography.
Painted terrain alone: turn off the added procedural detail when you want to see the heightfield you have authored more directly.
Terrain operations: set, add, multiply, reshape with a power curve, smooth, normalize, terrace, or invert elevations. Operations can target land, water, or the whole canvas, and work with selections; coast preservation is available where appropriate.

There are also (experimental) fourteen editable preset terrain recipes, including Volcano and Fractious, for exploring different starting shapes. Recipes combine a seed and density with editable generation instructions, can be previewed before applying them, and can be retained with a terrain layer. They are useful both as starting points and as material to paint over.

More Ways to Create Your World

A world can feel very different as an atlas, a globe, or a view looking across its surface. 2.0 expands the rendering tools so you can explore those differences without rebuilding your geography.

Physical terrain colouring: elevation, slope, and climate views, alongside the familiar classic palettes. Latitude can influence the appearance of the land and polar regions.
Terrain lighting: cast shadows, sky occlusion, adjustable sun direction and height, and shading exaggeration to bring out the shape of the landscape.
A rendered 3D view: look toward the terrain from different distances and angles, with atmosphere, ocean, and volumetric clouds. Adjust cloud coverage and height to change the mood of a scene.
Geographic guides: latitude and longitude grids, plus a kilometre scale tied to the size of your planet.
Live previews: see updates while painting, with background rendering, progress feedback, and cancellation for longer renders.
A clearer connection between canvas and preview: the viewport outline helps you keep track of the area you are looking at when working across projections.

The eleven map projections are the same Equirectangular, Mercator, Orthographic, Gall–Peters, Mollweide, Interrupted sinusoidal, Stereographic, Gnomonic, Icosahedral, Equal-area azimuthal, and Conical. Use them to compare the same world from different perspectives, or choose the one that suits your finished map.

Painting, Layers, and More Space to Experiment

The painting workspace has been rebuilt around a more flexible canvas and terrain layers, allowing a non-destructive workflow. This allows you to manage different features and separate terrain changes from exiting shapes, such as trying a different mountain range, or hiding a layer to compare different versions of your geography.

Layer controls: add, name, reorder, hide, lock, and remove terrain layers. Transparent areas and the eraser reveal what is underneath.
Direct and shaped painting: Point, Box, Circle, and Polygon tools for everything from a single cell to a whole landmass.
Soft and blending brushes: shape transitions with Linear, Smoothstep, Quadratic, Cubic, Exponential, or Gaussian falloff.
Two kinds of fill: fill a connected neighbourhood or replace matching heights across the canvas.
Selections: isolate part of the map for painting and terrain operations, or move selected geography.
Canvas transformations: raise or lower terrain, shift with wrapping or clipping, flip a map, and fill areas.
Grid controls: resize, expand or shrink the canvas, and double or halve its resolution.
Painting conveniences: zoom and pan, preview the brush footprint, and pick an existing height from the canvas.
Undo and redo: revisit strokes and other changes through the history, with clearer handling of unsaved work.

Several of these tools grew through the 1.x updates. They now sit together in a workspace designed for the larger range of things a 2.0 world can contain.

Build a Fantasy World to Suit Your Terrain

Once you have a Physical World you like, world layers can develop it into a fantasy atlas. Choose the number of countries and settlements, the map detail, and a presentation style, then generate a world that follows your geography.

This can add biomes, rivers, lakes, countries, borders, cultures, religions, provinces, settlements, place names, and roads. Building the atlas leaves your painted terrain intact, and rebuilding can be undone if you prefer the previous result.

Different map presets let you explore different sides of the same world:

Political: countries, borders, towns, rivers, and roads.
Cultural, Religions, and Provinces: the people of the world, their beliefs, and its internal divisions.
Biomes, Physical, and Heightmap: the landscape, climate zones, ice, and elevation.
Temperature, Precipitation, and Population: climate and patterns of habitation.
Goods, Trade, and Military: resources, markets, trade routes, and armies.
Emblems and Points of interest: heraldry and places worth a journey.

You can also switch individual overlays on and off to create your own combination. Changing what is shown does not regenerate the world, so you can move between a political map and a climate map while keeping the same underlying geography.

For your own landmarks, named world locations let you mark locations and retain their names and coordinates as you change projection. A useful way to start making the world yours is to name the first island, mountain, or city that catches your imagination.

A World with Many Styles

World layers come with fifteen presentation styles: Atlas, Parchment, Ink, Climate, Ancient, Political Atlas, Clean, Cyberpunk, Dark Seas, Gloom, Light, Monochrome, Night, Pale, and Watercolor.

Each changes the colours, lettering, and linework while keeping the geography in place. The same world can become a restrained reference atlas, an old parchment chart, a dark ocean map, or a softer illustrated view. You can explore the styles without committing to a new generation of the world.

When it is time to share your work, export the terrain and visible world layers together as an image, or take the world layers out separately as vector SVG or transparent PNG. Vector exports include shapes and outlined lettering, with optional legend and scale, for further composition in a drawing application.

Save and Share Your Worlds

The .fpp2 document format keeps terrain layers, physical elevations, sea level, seeds and generation settings, named places, and the generated atlas with its presentation. It is the format to use when you want to continue developing a 2.0 world.

Your existing .planet files still open. Legacy export is also available for older workflows, including the bridge to World to Beyond. That export flattens the visible terrain into the original nine height categories, so keep a .fpp2 master to preserve the new layers, places, and atlas.

Other import and export options include:

Heightmap import: greyscale images, colour-to-height mapping, and Terrain-RGB elevation data.
16-bit heightmaps: take continuous terrain elevations into other terrain tools and game workflows.
Painted map images and text: exchange the underlying grid as an image or in the classic text format.
Rendered PNGs: export Physical and Legacy views up to 8K on the long edge, and Flat Land views up to 4K.
Drag-and-drop opening: bring an existing world into the painting workspace.

The rebuilt interface also brings a more adjustable workspace, scrollable palettes, canvas navigation, and built-in help for the main workflows.

Flat Worlds and Familiar Favourites

Physical Planet is the new focus moving forward, but the other ways of making maps remain part of the app.

Legacy preserves the original generator and its nine height categories, eleven projections, and eighteen themes. It is there for returning projects and for anyone who enjoys the original approach.
Flat Land is a useful choice for bounded maps rather than whole planets. It offers 2D and relief views, eight themes, and controls for erosion, hydrology, inland lakes, and the water plane. It can take your work in a different direction when you are thinking about a single landscape or a game map.

Experimental Steam Achievements

We are also adding experimental Steam achievements to bring a little extra fun to using the app. They celebrate creative milestones and encourage you to try different tools, views, painting techniques, and worldbuilding possibilities.

Alongside them is a curated set of achievement illustrations with a stylized look. We hope these small rewards adds a bit more reward to your journey as you explore and create. They are also useful to guide you what to try next.

Achievement support is experimental in this release, and we welcome feedback if an unlock does not behave as expected. Some milestones are tied to capabilities beyond the current public build, so the achievement list will continue to develop with the app.

World to Beyond: A Rebuilt Map Studio

The free World to Beyond DLC now arrives alongside 2.0 with a rebuilt GUI for creating maps for Beyond All Reason and other Spring/Recoil games. The major road block from previous teaser is the now fully integrated map format generator, getting rid of third-party dependencies.

The earlier exporter centred on turning a planet into a map. The new studio workflow gives the other parts of that map their own space: resources, vegetation, water, scenery, and the final output.

Its seven stages cover the complete project:

Source: begin with a painted planet or a procedural map, choose a generation scheme, and set the map size.
Terrain: tune height range; procedural sources offer terrain styles, themes, generation controls, erosion, previews, and playability readouts. Imported heightmaps and ground textures provide further ways to bring in your own material.
Metal: place resources in a dedicated painting workspace, with automatic placement and brush controls including softness and symmetry.
Grass: grow vegetation from terrain rules, then paint over the result to refine its coverage.
Water: adjust the water appearance and judge it against a live coastline sample.
Features: use generated scenery or import .obj, .gltf, and .glb models. Set scatter rules and paint a separate placement mask for each model—for example, trees along a ridge and boulders near the shore—and preview where they will land.
Output: build a complete .sd7 map archive, including terrain, textures, resources, grass, water settings, and scenery, with progress feedback and cancellation.

There is also a real-time 3D viewer for inspecting the terrain, water, vegetation, scenery, resource spots, and start positions before compiling the archive. It currently requires OpenGL 4.3 support and will not work on macOS. And if you are patient enough to read till this line - there are more interactive ways to inspect and play with your map coming in future updates!

Studio projects can be saved as .w2b files, retaining settings and painted channels so you can return to a map over several sessions. Custom model files remain external references, so keep those assets with your project.

Whether you want to turn an unusual planet into a battlefield or just use W2B as a really easy utility to assembly a fully functional BAR map, there is a lot of freedom here.

Availability

Free for existing owners: 2.0 is an update to Fantasy Planet Painter, with the free World to Beyond DLC releasing alongside it.
Windows first: macOS is coming later; we will share more when it is ready.
Updated pricing: the price for new purchases has already changed to reflect the app's progress. Regional prices are shown on the Steam store.
The current build is released with the hope that you could try the new features early on - it may contain many features that we have not tested thoroughly - expect follow-up updates to address rough corners.

References

Steam Annoucement

DevLog 20261007: A Detective Story - First Satisfying Fully Playable Build

Charles Zhang — Wed, 07 Oct 2026 17:52:44 +0000

Overview

I've always wanted to develop a video game — in fact, many of them. A Detective Story is far from the first attempt at Methodox; several earlier projects stalled along the way (you can still catch a glimpse of one in Codename Wayhome).

As we set out to build Divooka — a general-purpose visual programming system — the ability to create even a simple 2D game became an essential touchstone. So the game was never just a game.

Motivation

The idea for A Detective Story grew out of our work on Methodox ChatGateway, a RAG-based knowledge engine we were running as an online service. Behind the scenes we were also spending a lot of time with locally hosted LLMs and general knowledge-base applications. The underlying technology isn't new, but none of the existing solutions quite met my requirements. Most are poorly organized and extremely heavy in (Python) dependencies. I could talk about my complicated relationship with Python for hours — the love and, mostly, the hate — but one principle I value above almost everything else is portability and compactness in local software.

A complete RAG knowledge-base solution shouldn't be much larger than the knowledge source itself. That's the bottom line.

As with so many other things we build for Divooka, the best way to prove what the platform can deliver is to find a real application for ourselves and push it as far as we can. That led us to the idea of Crime Engine.

On a Reusable, Configuration-Based Detective Story Game Engine

Crime Engine is a 2D detective-story game engine with fully configurable maps and characters. Players interrogate suspects using natural language, powered by locally hosted models through llama.cpp.

The setup is deliberately lightweight. It supports the major flavours of GGUF-based SLMs and includes built-in RAG. On the gameplay side we have map navigation, fully functional menus, story backgrounds, interrogation rooms, and a verdict screen for concluding a case. There are also interactions with NPCs on the streets in map view, item discovery, and item exchange.

The item-exchange system turned out to be the trickiest piece. It may simply be a limitation of current local models, but I still don't find locally hosted LLMs reliable enough for consistent tool use.

The Development of A Detective Story

We announced the Steam “Coming Soon” page with a trailer back on 6 March, yet we never felt confident enough to release. Three main challenges kept holding us back:

Graphics quality — Much of the art was AI-generated with manual adjustments, but the overall integration still fell short of the standard we wanted.
NPC behaviour and tool use — The item-exchange mechanic is genuinely interesting, but relying on an LLM for reliable outcomes proved difficult. We eventually solved this by scouting a stronger SLM.
Plot completeness — Closely related to the point above: because LLM responses are hard to control tightly, it was tricky to guarantee that players could smoothly finish the game with all the necessary clues. Of course, Divooka remained our primary focus, so we couldn't pour unlimited effort into fine-tuning the plots.

Plot Work

This is still an experimental game and a tech demo for the engine, yet we wanted it to feel like a coherent little story we could build on later — expansions, a series, that sort of thing. As we kept working, the characters became more polished: Ronan, Jack, Lady Garba, Helen, and the rest. It turns out it's simply fun to dwell in fiction once in a while.

Even though it's a small 2D title, we ended up planning a surprisingly large set of graphics assets and subplots worth exploring. We originally sketched a gigantic cast of almost 500 NPCs, then deliberately shifted toward fewer, more personalized characters instead of a generic population.

Release

Major improvements since the earlier builds include:

Significant engine work — better NPC stability, improved tool use, and far more thorough internal (automated) testing.
Noticeable graphics upgrades.
A full GUI overhaul using our proprietary framework ShadowGUI. All Divooka users will benefit from this soon enough.

I did a final playtest today and, for the first time, the game felt genuinely enjoyable, smooth, and fun. It's almost ready to go.

We plan to release A Detective Story first while we continue polishing Crime Engine itself. It will be a while before CE is generally available.

References

2026-10-03 Graphics Update Announcement

DevLog 20261002: Desktop Automation Toolbox and Mouse Emulation

Charles Zhang — Fri, 02 Oct 2026 15:15:03 +0000

I remember when I used to use Macro Recorder to automate simple repetitive tasks — I especially liked its macro recording feature. It requires no programming and can easily get tedious jobs involving clicking and waiting done.

Since then, I've long moved past automating with basic mouse/keyboard emulation and have sunk deep into an API-driven approach — I just love how clean everything is when you can really program it. Well, that's a major reason why I started Divooka in the first place — lots of ecosystems and lots of tools we use are broken beyond repair and inherently NOT designed to be automated cleanly. MCP partly addressed that problem, but it's really just a modern remedy for mediocre design.

Either way, when I set out to implement procedural context for Divooka, desktop automation is nonetheless one of the first things that comes to mind. As we get more mature in OOP programming, generics, and recently achieved a true data structure algorithm implementation in Divooka, that is drawing closer.

In this short video, I show a desktop example for the automation toolbox that will come with the upcoming Divooka Explore. It's small, but it shows quite a few interesting things:

It creates a countdown GUI using the Immediate GUI framework.
It interacts with an opened window — in this case, the Paint program — through keyboard shortcuts and mouse input.
It can parse a stroke-based font at runtime and draw text with it.

If you ask me, that's a lot of cool features in such a small example! Really excited, and there's still more work to do, so see you soon!

DevLog 20260919: Upcoming Fantasy Planet Painter 2.0 and the Making of It

Charles Zhang — Sat, 19 Sep 2026 14:29:27 +0000

Fantasy Planet Painter

Whole-planet-scale fictional world-building: continents, mountain ranges, rivers, valleys, and features as small as individual hills. Maybe eventually trees, buildings, houses, roads, and cities too?

That has always been roughly the idea behind Fantasy Planet Painter (FPP).

Making a good-looking fantasy map is one part of the goal, but the longer-term idea is more ambitious: making an entire fictional planet something you can actually author, organize, inspect, render, and use.

With the upcoming Fantasy Planet Painter 2.0, we are finally starting to build more seriously toward that idea.

The Beginning

FPP had a rather humble origin: I needed to create a world map.

Naturally, I started with GIS software. First ArcGIS, then QGIS, and along the way I learned my way through map projections, layers, coordinate systems, GeoServers, and all the other fun stuff that comes with GIS.

GIS is incredibly powerful, but for making a fictional planet from scratch, the workflow was not particularly efficient. I wasn't really trying to analyze an existing world; I wanted to sit down and make one.

Eventually I came across Torben Mogensen's planet program (planet.exe on Windows). It was rather eye-opening because the program works on an entire spherical planet at once instead of treating the world as just another flat image.

The underlying terrain generator uses recursive tetrahedral subdivision to produce planetary terrain, and it can render the generated planet using many different cartographic projections. That became the technical foundation from which FPP originally grew. We later ported the original code to C# and gradually modernized and extended it.

The Start

The first practical problem was obvious: planet.exe is essentially a command-line program, and custom maps are represented through text-based input.

That is powerful if you already know exactly what you want to type, but not particularly convenient if you are trying to draw a world.

Before FPP, I even made several small command-line utilities for operations such as moving and scaling cells around. It technically worked, but authoring by repeatedly modifying parameters, rendering an image, looking at the result, and trying again was painfully inefficient.

So the first major goal became exposing all of this through a much more usable graphical interface.

That took much longer than expected.

The original code is quite old and was never designed with this kind of interactive editing workflow in mind. Adding a GUI was therefore not simply a matter of putting some buttons around it. Rendering, state management, editing, visualization, save files, projections, cross-platform support, and eventually performance all had to be integrated around the original generator.

Version 1.0 was really the beginning of that process rather than its end.

Over time we added higher-resolution authoring, more output options, brushes, polygon editing, region selection, map themes, improved rendering controls, and substantial performance work. By v1.4, techniques we had been developing for Divooka - erosion, terrain processing, procedural coloring, texturing, and rendering - also started finding their way back into FPP.

The Road Map

Once you start thinking seriously about authoring an entire planet, a lot of other problems immediately appear.

Some of the major ones are:

Location and region management
Local and regional maps
Countries, cultures, biomes, settlements, etc.
Different levels of detail
Map rendering and map serving
Exporting the same world into other tools and applications

This is why I don't really think of FPP as only a procedural map generator.

A nice-looking map is important, of course. But a fictional world can easily contain thousands of named places and many completely different scales of information. A mountain range visible on a world map may contain hundreds of valleys, rivers, lakes, roads, towns, and individual terrain features that should not even exist at the resolution of the original world map.

That creates an interesting authoring problem.

A single giant bitmap is clearly not the answer. At the same time, splitting everything into unrelated maps loses the fact that they all belong to the same world.

Our original public roadmap already described Version 2 as Advanced World Editing, beginning with location management, followed eventually by better brushes, color control, biome editing, 3D worlds, roads, and cities. The exact implementation has changed quite a lot since that roadmap was written, but the overall direction has not.

The important part is that FPP needs to gradually move from "a program that generates a picture of a planet" toward "a program that understands the things making up that planet."

Feedback and Improvements

There haven't been many direct comments on the Steam community page so far. FPP is still a small and fairly niche product.

Refund information, however, gives us another source of feedback, and the pattern is fairly understandable: people want more power, more detailed editing, and more features.

None of those are particularly surprising.

They correspond closely to limitations we were already aware of in Version 1.x. FPP became quite good at quickly establishing the large-scale shape of a planet, but there is a substantial gap between sketching continents and actually authoring the world inside those continents.

That feedback has helped us decide which parts of the longer-term roadmap should move closer to the front.

Version 2.0

There are three big areas we want to address at the beginning of Version 2.0:

World regions
A new custom spherical tetrahedral-subdivision system with real-world physical units
Major mapping, editing, theming, and rendering improvements

The first one is perhaps the most important structurally.

Regions give us a way to start treating parts of the world as actual objects rather than just pixels or height values. Once regions exist properly, a lot of other ideas become much easier to build around them: locations, countries, biome areas, local maps, selections, metadata, exports, and eventually much more detailed world-building information.

The second area goes much deeper into FPP's original foundation.

The new subdivision system is also closely tied to another important change in 2.0: the metric system. FPP now operates using real physical units, with distances and elevations represented in meters rather than abstract map values. A planet can have an Earth-scale radius, mountains can genuinely be several kilometres high, and distances between locations can be measured and discussed precisely.

This sounds like a relatively small change, but it makes world-building much more practical. Terrain, regions, local maps, roads, settlements, and eventually buildings can all exist within the same physical frame of reference instead of relying on arbitrary scales that change depending on context.

The tetrahedral subdivision approach has served FPP very well, but we are now experimenting with our own spherical subdivision implementation and data structures. Having control over this level of the system lets us build that real-world scale directly into the geometry while also making it easier to integrate editing, generation, resolution changes, region handling, and future algorithms without constantly working around assumptions inherited from the original renderer.

And finally there is everything users actually interact with every day: mapping, editing, theming, and rendering.

Version 1.x accumulated many useful features, sometimes rather experimentally. Version 2 gives us a chance to reorganize some of those ideas around a more coherent model instead of continuously extending what was originally a relatively simple world-map painter.

These three areas should provide a much better foundation for extending FPP going forward.

The W2B Project

A surprisingly useful side project in all of this has been World to Beyond, or W2B.

It was originally proposed mostly out of curiosity.

I sometimes play Beyond All Reason with my friend. Well, nowadays he is so good - even though I was the one who first got him into the game - that he no longer plays with me 😟.

At some point he looked at FPP and said that its maps kind of looked like BAR maps, so: couldn't FPP make one?

Visually, the answer seemed like it should be "yes."

Technically, of course, it was considerably more complicated.

BAR uses the Spring RTS engine, and producing an actual playable map means much more than exporting a nice-looking heightmap. Terrain needs to work from a gameplay perspective. You have textures, metal distribution, grass, water, features, map metadata, engine-specific formats, reachability, and all kinds of details that don't really matter when the final output is only an image.

So we made a first attempt, but never really published much around it.

People on Discord also quickly pointed out some obvious weaknesses, particularly the lack of convincing erosion and proper texturing.

Conveniently, those were exactly the kinds of problems we had independently started working on in Divooka.

Over the past year, our terrain work in Divooka has expanded from basic noise generation into erosion, hydrology analysis, masks, terrain coloration, texturing, and eventually PBR terrain rendering. FPP has already started benefiting from some of that work.

So when we returned to W2B, we were in a rather different position.

The new W2B has now been rewritten from scratch. Earlier prototypes required users to provide a template extracted from an existing map, which was awkward both technically and from a redistribution/licensing perspective. The current implementation writes the core Spring map files - .smf, .smt, and mapinfo.lua - itself.

The authoring process has also grown into several distinct stages: source terrain, terrain setup, metal, grass, water, features, and final output. In other words, it is slowly becoming an actual map-making pipeline rather than an FPP export button.

And this experiment is useful for FPP itself.

It forces us to deal with questions that don't appear when creating a world map purely for viewing: Is this terrain navigable? What happens when we look much closer? Where does vegetation belong? How do large-scale shapes survive when converted into local terrain? How should a procedural world turn into something another application can actually use?

Those questions are very relevant to where we want Fantasy Planet Painter to go.

With all the work that has gone into FPP, Divooka, procedural terrain generation, and the first W2B experiment, we are much better equipped this time around.

And the new W2B is already much more powerful - and, importantly, much prettier - than the original attempt.

Going Forward

Fantasy Planet Painter started from a relatively simple problem: I wanted a convenient way to draw a fictional world map.

That problem turned out to contain a surprisingly large number of smaller problems.

Some are mathematical. Some are GIS problems. Some are rendering problems. Some are UI problems. And increasingly, some are really data-modeling problems: how do you represent an entire fictional world in a way that remains editable from the scale of a planet down to individual regions - and where those scales correspond to actual physical measurements?

With 2.0, an Earth-sized world is actually Earth-sized, mountains can be described in kilometres, and distances between places have a concrete meaning. That gives the rest of the world-building system a much more practical foundation.

Version 1.x gave us a functional planet painter.

Version 2.0 is where we start taking the "world-building" part much more seriously.

There is still a lot to figure out, and some of the ideas described here will certainly change as we implement them. But the pieces developed over the past year - especially the work on terrain generation in Divooka and experiments such as World to Beyond - are starting to connect together rather nicely.

We will share more as 2.0 takes shape.

References

DevLog 20260731: FPP v1.4.0 and Divooka Explore Demo Updates

Charles Zhang — Sat, 01 Aug 2026 18:43:48 +0000

Overview

The past few months have seen several Divooka Explore Demo releases, with our efforts focused on rolling out procedural terrain generation features. These include random noise-based terrain generation, procedural and simulation-based terrain processing, natural effects such as erosion and hydrology analysis, procedural coloration and texturing, and, more recently, improved 3D previews of generated terrains directly within the Divooka visual programming environment.

One small lesson from this cumulative effort is that there always seems to be more academic material, papers, tutorials, online examples, and even source code snippets to discover and use to improve existing systems. That is a shiny silver lining, since we are still fairly new to this domain and desperately need broad exposure to existing techniques.

Another useful lesson is that, although many papers approach these subjects from a real-time rendering perspective - such as the old GPU Gems articles - the same techniques are often equally applicable in a pure-CPU regime.

Procedural Terrain Generation in Divooka

As mentioned, we have made quite a large number of functions available in this area, and the subject definitely warrants much more detailed treatment. Documentation and comprehensive video guides are dearly needed.

To recap, we have moved from very basic noise-based terrain generation to custom heterogeneous multifractal terrains, functional erosion - although there is still plenty of room for improvement - various masking techniques, practical procedural coloring using either masks or SQL queries, and preliminary texturing support.

The terrain generation is only the first step, and there is still plenty of room for improvement despite we have achieved useful basic implementation for now.

Once we became comfortable with generating functional procedural terrains, we could move on to coloring, texturing, and eventually shading.

At this point, I realized a fundamental limitation of heightmaps and image textures. They may be able to represent distant views of terrains spanning 8–64 km when viewed from above, but for ground-level rendering, procedural shading techniques are a must.

The 3D rendering work is still new, and there is a long way to go. We started with basic baked shadows, moved on to experimental texture mixing, and eventually reached full PBR rendering.

PBR rendering is the holy grail. Once we figure out how to dynamically populate terrains with trees, grass, and rocks - and generate ripples across reflective water - we will be able to share all of it through Divooka as reproducible workflows!

Below is an intermediate result so far. It uses simple slope-based texturing, which we plan to replace with mask-layer-based materials in the next attempt.

We have learned so much and cannot wait to share more about the specific techniques once we have more spare time!

The Fantasy Planet Painter v1.4.0 Update

While the eventual goal is to support whole-planet procedural generation and content management, we began with basic Earth-like world map generation. At the moment, our work is mostly focused on improving the existing editing experience. The previous update significantly improved the multithreaded generation performance of the tetrahedral subdivision method.

The 2D cell-based height-value canvas is an interesting medium. It allows us to sketch the desired elevation levels quickly at a high level while the program procedurally populates the remaining details.

There has also been some experimental exploration into using this medium for direct 2D terrain editing, as seen in our previous video, World to Beyond (BAR map export from FPP). Although BAR export is still in its early stages, the potential of this kind of authoring technique is indeed interesting.

Following the advances in procedural terrain generation within Divooka, we have gathered quite a collection of useful tools and made them available at a high level in the latest FPP update.

The results are very interesting, and I am glad that we are moving beyond practical utility toward generating worlds that - at least in my eyes - are also visually appealing.

Conclusion

That is a brief recap for today. I have been busy diving headfirst into all the nitty-gritty work, which has left less time for DevLog updates and for sharing the techniques and progress behind them.

Still, let us look forward to the day when new results are ready to shine, when we are comfortable placing an early-access version of Divooka into the hands of users, and when we can talk in much greater detail about the road that led us there!

Designing a Binary Data API for Divooka with PPM and PLY Examples

Charles Zhang — Tue, 12 May 2026 20:14:30 +0000

Revision: 001

Last Update: 2026-05-12

One thing I feel is not discussed enough in typical programming conversations is working with binary data. It often seems as though there is a ready-to-use library for whatever data type we need. But that illusion breaks whenever we want to do something new, interface with a less common format, work with legacy data, or build high-performance applications around custom data formats.

Designing a custom data format that fits the application at hand is an important skill. In this post, however, we will focus less on the philosophy and more on the operational details.

Binary formats are everywhere: images, meshes, save files, network packets, custom asset bundles, compressed streams, hardware protocols, game data, and many old file formats that are still useful decades later. Yet in application code, binary parsing often becomes messy very quickly. You start with a byte[], then an offset integer, then a few helper methods, then nested offset calculations. Before long, the parser has two responsibilities at once: understanding the file format and manually managing where the cursor is.

File Container Formats WikiCommons

Design Motivation

At a higher abstraction level, the goal of Divooka is to move cursor-management logic into something closer to Kaitai Struct or DFDL, the Data Format Description Language. This makes it easier to work with standardized, well-documented formats such as RIFF.

Instead of writing code like this:

int offset = 0;

string magic = Encoding.ASCII.GetString(bytes, offset, 4);
offset += 4;

int version = BinaryPrimitives.ReadInt32LittleEndian(bytes.AsSpan(offset, 4));
offset += 4;

int count = BinaryPrimitives.ReadInt32LittleEndian(bytes.AsSpan(offset, 4));
offset += 4;

we want this:

var remaining = ImmutableByteArrayReader.FromFile("Data.bin")
    .ReadString(4, out string magic)
    .ReadInt(out int version)
    .ReadInt(out int count);

This is similar in spirit to a stream-based API:

using var reader = new BinaryReader(stream, Encoding.ASCII, leaveOpen: true);

string magic = Encoding.ASCII.GetString(reader.ReadBytes(4));

int version = reader.ReadInt32();
int count = reader.ReadInt32();

The involved types here are ImmutableByteArrayReader, MutableByteArrayWriter, and ImmutableByteArrayWriter, all exposed through a fluent API. The parser reads like the binary format itself.

The writer mirrors that idea:

var data = new MutableByteArrayWriter()
    .WriteStringFixedSize("DATA")
    .WriteInt(version)
    .WriteInt(count);

The idea is simple: binary data should be represented as a sequence of explicit read and write operations, not as scattered offset arithmetic.

Reading Binary Data

Binary Buffer Reader: `ImmutableByteArrayReader`

ImmutableByteArrayReader is a reader-oriented abstraction over binary data.

It is immutable. Reading from it does not mutate the current object. Instead, read operations return the remaining unread portion of the buffer.

The main API shape is:

public ImmutableByteArrayReader ReadInt(out int value);
public int ReadInt();
public int ReadIntWithOffset(int byteIndex);

These three forms cover three common use cases.

The out form is for fluent parsing:

var remaining = data
    .ReadString(4, out string magic)
    .ReadInt(out int width)
    .ReadInt(out int height);

The direct-return form is for reading a value from the start of a buffer when the remaining data is not needed:

int width = data.ReadInt();

The offset form is for random access without consuming anything:

int width = data.ReadIntWithOffset(4);

This gives the type this clear behavior: Sequential reads consume by returning a new remaining buffer. Offset reads do not consume. Because the reader is immutable, slicing can be cheap: reading a subrange can return another reader over the same underlying data instead of copying bytes.

That means this kind of operation is cheap:

var remaining = data.ReadBytes(32, out ImmutableByteArrayReader header);

Both remaining and header can be views over the same internal byte array. Since neither object can mutate the backing storage, this remains safe.

Reading blocks

Binary formats often have fixed-size blocks. For example, a file might contain a 32-byte header, followed by 32 bytes of padding, followed by records.

The API shape for bytes is:

public ImmutableByteArrayReader ReadBytes(int count, out ImmutableByteArrayReader value);
public ImmutableByteArrayReader ReadBytes(int count);
public ImmutableByteArrayReader ReadBytesWithOffset(int byteIndex, int count);
public ImmutableByteArrayReader ReadBytes(int count, out ImmutableByteArrayReader value, Action<ImmutableByteArrayReader> continuation);

The continuation form is useful when a sub-block should be parsed separately:

int versionNumber = 0;

var remaining = ImmutableByteArrayReader.FromFile("MyData.bin")
    .ReadString(4, out string magic)
    .ReadBytes(32, out ImmutableByteArrayReader _, header => header.ReadUInt(out versionNumber))
    .ReadBytes(32, out _)
    .ReadInt(out int count);

The main stream advances by 32 bytes, while the continuation reads from the isolated header block.

This is especially useful for formats where blocks have fixed sizes, but only some fields inside the block are currently relevant.

Strings

Strings usually appear in binary formats in two common forms.

The first is fixed-size:

public ImmutableByteArrayReader ReadString(int size, out string value);
public string ReadString(int size);
public string ReadStringWithOffset(int byteIndex, int size);

For example, a file magic value:

data.ReadString(4, out string magic);

The second is zero-terminated:

public ImmutableByteArrayReader ReadString(out string value);
public string ReadString();
public string ReadStringWithOffset(int byteIndex);

This reads until the first 0x00 byte.

data.ReadString(out string name);

Fixed-size strings are common in headers. Zero-terminated strings are common in older binary formats, mesh files, embedded metadata, and C-style structures.

Writing Binary Data

Binary Buffer Writer: `MutableByteArrayWriter`

MutableByteArrayWriter is the mutable writer.

It is a fluent append-only byte builder:

var current = new MutableByteArrayWriter()
    .WriteStringFixedSize("CBA1")
    .WriteInt(1)
    .WriteDouble(3.14159);

It is mutable in-place. Each call appends bytes to the same underlying buffer and returns this.

This makes it the practical default for producing binary files.

The API deliberately uses explicit method names:

WriteInt(...)
WriteUInt(...)
WriteDouble(...)
WriteStringFixedSize(...)
WriteStringZeroTerminated(...)
WriteBytes(...)

This avoids the ambiguity of a single overloaded Write(...) method. In binary code, explicitness is usually worth the extra characters.

Immutable writer: `ImmutableByteArrayWriter`

ImmutableByteArrayWriter mirrors the writer API, but every write returns a new object.

var baseFile = new ImmutableByteArrayWriter()
    .WriteStringFixedSize("TEST")
    .WriteInt(1);

var pathA = baseFile.WriteStringZeroTerminated("Variant A");
var pathB = baseFile.WriteStringZeroTerminated("Variant B");

This is useful when experimenting with different downstream write paths.

For example, you may have a common header, then several possible payload layouts:

var common = new ImmutableByteArrayWriter()
    .WriteStringFixedSize("MESH")
    .WriteInt(version);

var triangleMesh = common
    .WriteStringZeroTerminated("triangles")
    .WriteInt(triangleCount);

var pointCloud = common
    .WriteStringZeroTerminated("points")
    .WriteInt(pointCount);

The mutable writer is faster and more memory efficient. The immutable writer is better for branching, testing, and functional construction patterns.

Writing fixed-size blocks

Writers also support fixed-size subblocks:

public MutableByteArrayWriter WriteBytes(int count);
public MutableByteArrayWriter WriteBytes(int count, Action<MutableByteArrayWriter> subblock);
public MutableByteArrayWriter WriteBytes(MutableByteArrayWriter source);

For the mutable version:

int versionNumber = 1;
int count = 15;

MutableByteArrayWriter current = new MutableByteArrayWriter()
    .WriteStringFixedSize("CBA1")
    .WriteBytes(32, con => con.WriteUInt((uint)versionNumber))
    .WriteBytes(32)
    .WriteInt(count);

for (int i = 0; i < count; i++)
    current = current.WriteBytes(128);

current.Save("Copy1.bin");
current.Save("Copy2.bin");
current.Dispose();

The block continuation writes into a temporary sub-buffer. If it writes fewer than 32 bytes, the result is automatically padded with zeroes. If it writes more than 32 bytes, the writer should throw.

This makes fixed-size binary structures much easier to express.

The immutable version uses a functional continuation instead:

ImmutableByteArrayWriter current = new ImmutableByteArrayWriter()
    .WriteStringFixedSize("CBA1")
    .WriteBytes(32, con => con.WriteUInt((uint)versionNumber))
    .WriteBytes(32)
    .WriteInt(count);

Internally, that continuation should be shaped as:

Func<ImmutableByteArrayWriter, ImmutableByteArrayWriter>

because immutable writes return new objects.

Examples

Example: reading a PPM image

PPM is a simple image format from the Netpbm family. It is useful as a teaching format because the structure is small and direct. The examples below intentionally implement a minimal binary P6 reader and writer, rather than a complete Netpbm parser.

A binary PPM file starts with an ASCII header:

P6
width height
maxValue

followed by a single whitespace byte and then the binary RGB pixel data.

For example:

P6
256 256
255
<binary RGB bytes>

The header is text, but the pixel payload is binary. This makes PPM a good example of mixed text and binary parsing. In the common 8-bit case where maxValue is 255, the payload is width * height * 3 bytes. PPM also allows comments in the header and larger sample values, but this example deliberately supports only simple comment-free P6 files with maxValue == 255.

A simple PPM image type might look like this:

public sealed class PpmImage
{
    public int Width { get; }
    public int Height { get; }
    public byte[] Pixels { get; }

    public PpmImage(int width, int height, byte[] pixels)
    {
        Width = width;
        Height = height;
        Pixels = pixels;
    }
}

This simplified parser supports only the common 8-bit RGB form. General P6 files can use larger sample values and may contain comments in the header, so a production parser would need to handle those cases before reading the raster payload. Using ImmutableByteArrayReader, a basic parser could be written as:

public static PpmImage ReadPpm(string path)
{
    ImmutableByteArrayReader data = ImmutableByteArrayReader.FromFile(path);

    data = ReadAsciiToken(data, out string magic);

    if (magic != "P6")
        throw new InvalidDataException("Only binary P6 PPM files are supported.");

    data = ReadAsciiToken(data, out string widthText);
    data = ReadAsciiToken(data, out string heightText);
    data = ReadAsciiToken(data, out string maxValueText);

    int width = int.Parse(widthText);
    int height = int.Parse(heightText);
    int maxValue = int.Parse(maxValueText);
    data = ConsumeSingleAsciiWhitespace(data); // Skip delimiter whitespace

    if (maxValue != 255)
        throw new InvalidDataException("Only 8-bit PPM files with max value 255 are supported.");

    int pixelByteCount = width * height * 3;

    data.ReadBytes(pixelByteCount, out ImmutableByteArrayReader pixelData);

    return new PpmImage(width, height, pixelData.ToArray());
}
private static ImmutableByteArrayReader ConsumeSingleAsciiWhitespace(ImmutableByteArrayReader data)
{
    if (data.Length == 0 || !IsAsciiWhitespace(data[0]))
        throw new InvalidDataException("Expected whitespace before PPM raster data.");

    return data.Skip(1);
}

The helper token reader can be implemented as a small routine over the immutable buffer:

private static ImmutableByteArrayReader ReadAsciiToken(ImmutableByteArrayReader data, out string token)
{
    data = SkipAsciiWhitespace(data);

    int count = 0;

    while (count < data.Length && !IsAsciiWhitespace(data[count]))
        count++;

    token = Encoding.ASCII.GetString(data.AsSpan(0, count));
    return data.Skip(count);
}

private static ImmutableByteArrayReader SkipAsciiWhitespace(ImmutableByteArrayReader data)
{
    int count = 0;

    while (count < data.Length && IsAsciiWhitespace(data[count]))
        count++;

    return data.Skip(count);
}

private static bool IsAsciiWhitespace(byte value)
{
    return value == (byte)' ' || value == (byte)'\t' || value == (byte)'\r' || value == (byte)'\n';
}

This parser is intentionally minimal: it demonstrates the cursor-management pattern without implementing every detail of the Netpbm format. It does not support comments, alternate sample sizes, or multiple concatenated images in one file.

The parser is not fighting offsets. Each helper receives a buffer and returns the remaining buffer. That is the central pattern.

Example: writing a PPM image

Writing a binary PPM file is straightforward with MutableByteArrayWriter.

public static void WritePpm(string path, int width, int height, ReadOnlySpan<byte> rgbPixels)
{
    int expectedLength = width * height * 3;

    if (rgbPixels.Length != expectedLength)
        throw new ArgumentException($"Expected {expectedLength} RGB byte(s).", nameof(rgbPixels));

    new MutableByteArrayWriter()
        .WriteStringFixedSize("P6\n")
        .WriteStringFixedSize(width.ToString())
        .WriteByte((byte)' ')
        .WriteStringFixedSize(height.ToString())
        .WriteByte((byte)'\n')
        .WriteStringFixedSize("255\n")
        .WriteBytes(rgbPixels)
        .Save(path)
        .Dispose();
}

This writes:

P6
width height
255

then appends raw RGB bytes.

The string methods are still explicit. We are not pretending the whole file is text. We are building a binary byte sequence with some ASCII sections.

You can open a .ppm image with GIMP.

Contrast this with a traditional stream-based version:

public static void WritePpm(string path, int width, int height, ReadOnlySpan<byte> rgbPixels)
{
    int expectedLength = width * height * 3;

    if (rgbPixels.Length != expectedLength)
        throw new ArgumentException($"Expected {expectedLength} RGB byte(s).", nameof(rgbPixels));

    using FileStream stream = File.Create(path);
    using BinaryWriter writer = new BinaryWriter(stream, Encoding.ASCII, leaveOpen: false);

    writer.Write(Encoding.ASCII.GetBytes("P6\n"));
    writer.Write(Encoding.ASCII.GetBytes(width.ToString()));
    writer.Write((byte)' ');
    writer.Write(Encoding.ASCII.GetBytes(height.ToString()));
    writer.Write((byte)'\n');
    writer.Write(Encoding.ASCII.GetBytes("255\n"));
    writer.Write(rgbPixels);
}

The code is command-oriented, whereas the fluent writer makes the data structure visually continuous.

Example: reading a PLY file

PLY is a common polygon mesh format. It is especially visible today because of its use in workflows such as Gaussian Splatting. It can be ASCII or binary. A binary little-endian PLY file starts with an ASCII header, followed by binary element data.

The important detail is that PLY is property-driven. The header declares the elements, their counts, and the properties stored for each element. The binary body then stores those declared properties in order. A complete PLY reader should therefore parse the element/property layout and read or skip fields according to the header.

For this article, we will use a deliberately small subset of binary little-endian PLY: vertices containing only float x, float y, and float z, followed by faces containing only property list uchar int vertex_indices.

A simplified binary PLY header for that subset might look like this:

ply
format binary_little_endian 1.0
element vertex 3
property float x
property float y
property float z
element face 1
property list uchar int vertex_indices
end_header

Then the binary body follows.

For that header, the body contains three vertices, each with three 32-bit floats:

x y z
x y z
x y z

Then one face:

uchar count
int index0
int index1
int index2

A small model type:

public readonly record struct Vertex(float X, float Y, float Z);

public sealed class PlyMesh
{
    public List<Vertex> Vertices { get; } = new List<Vertex>();
    public List<int[]> Faces { get; } = new List<int[]>();
}

A simplified binary PLY reader for exactly this layout can be written as:

public static PlyMesh ReadBinaryLittleEndianPly(string path)
{
    ImmutableByteArrayReader data = ImmutableByteArrayReader.FromFile(path, ByteArrayEndianness.LittleEndian, Encoding.ASCII);

    data = ReadPlyHeader(data, out int vertexCount, out int faceCount);

    var mesh = new PlyMesh();

    for (int i = 0; i < vertexCount; i++)
    {
        data = data
            .ReadFloat(out float x)
            .ReadFloat(out float y)
            .ReadFloat(out float z);

        mesh.Vertices.Add(new Vertex(x, y, z));
    }

    for (int i = 0; i < faceCount; i++)
    {
        data = data.ReadByte(out byte indexCount);

        int[] indices = new int[indexCount];

        for (int j = 0; j < indexCount; j++)
            data = data.ReadInt(out indices[j]);

        mesh.Faces.Add(indices);
    }

    return mesh;
}

The header reader can remain text-oriented:

private static ImmutableByteArrayReader ReadPlyHeader(ImmutableByteArrayReader data, out int vertexCount, out int faceCount)
{
    vertexCount = 0;
    faceCount = 0;

    var lines = new List<string>();

    while (true)
    {
        data = ReadAsciiLine(data, out string line);
        lines.Add(line);

        if (line == "end_header")
            break;
    }

    foreach (string line in lines)
    {
        string[] parts = line.Split(' ', StringSplitOptions.RemoveEmptyEntries);

        if (parts.Length == 3 && parts[0] == "element" && parts[1] == "vertex")
            vertexCount = int.Parse(parts[2]);

        if (parts.Length == 3 && parts[0] == "element" && parts[1] == "face")
            faceCount = int.Parse(parts[2]);
    }

    return data;
}

private static ImmutableByteArrayReader ReadAsciiLine(ImmutableByteArrayReader data, out string line)
{
    int count = 0;

    while (count < data.Length && data[count] != (byte)'\n')
        count++;

    line = Encoding.ASCII.GetString(data.AsSpan(0, count)).TrimEnd('\r');

    if (count < data.Length)
        count++;

    return data.Skip(count);
}

Again, the binary body parser is clean because the cursor is implicit in the returned ImmutableByteArrayReader.

This reader is not a general-purpose PLY parser. It assumes the exact layout shown above: three float properties for each vertex and one uchar/int list property for each face. Real PLY files often include additional vertex properties such as normals, colors, texture coordinates, opacity, or Gaussian Splatting attributes. They may also use different scalar names or different element layouts. A complete reader would parse the full header schema, then read or skip each declared property in order.

Example: writing a binary PLY file

Writing a simple triangle mesh to binary little-endian PLY is similarly direct. This writer emits the same restricted layout used by the reader: each vertex has three 32-bit floats, and each face has a uchar count followed by 32-bit integer vertex indices.

public static void WriteBinaryLittleEndianPly(string path, IReadOnlyList<Vertex> vertices, IReadOnlyList<int[]> faces)
{
    var current = new MutableByteArrayWriter(ByteArrayEndianness.LittleEndian, Encoding.ASCII)
        .WriteStringFixedSize("ply\n")
        .WriteStringFixedSize("format binary_little_endian 1.0\n")
        .WriteStringFixedSize($"element vertex {vertices.Count}\n")
        .WriteStringFixedSize("property float x\n")
        .WriteStringFixedSize("property float y\n")
        .WriteStringFixedSize("property float z\n")
        .WriteStringFixedSize($"element face {faces.Count}\n")
        .WriteStringFixedSize("property list uchar int vertex_indices\n")
        .WriteStringFixedSize("end_header\n");

    foreach (Vertex vertex in vertices)
    {
        current = current
            .WriteFloat(vertex.X)
            .WriteFloat(vertex.Y)
            .WriteFloat(vertex.Z);
    }

    foreach (int[] face in faces)
    {
        if (face.Length > byte.MaxValue)
            throw new InvalidDataException("PLY face has too many indices for uchar list count.");

        current = current.WriteByte((byte)face.Length);

        for (int i = 0; i < face.Length; i++)
            current = current.WriteInt(face[i]);
    }

    current.Save(path);
    current.Dispose();
}

A triangle can then be written like this:

var vertices = new[]
{
    new Vertex(0, 0, 0),
    new Vertex(1, 0, 0),
    new Vertex(0, 1, 0),
};

var faces = new[]
{
    new[] { 0, 1, 2 },
};

WriteBinaryLittleEndianPly("Triangle.ply", vertices, faces);

The code reads as the layout of the file, not as a sequence of stream or array mutations.

Below is what the code would look like with traditional BinaryWriter:

public static void WriteBinaryLittleEndianPly(string path, IReadOnlyList<Vertex> vertices, IReadOnlyList<int[]> faces)
{
    using FileStream stream = File.Create(path);
    using BinaryWriter writer = new BinaryWriter(stream, Encoding.ASCII, leaveOpen: false);

    writer.Write(Encoding.ASCII.GetBytes("ply\n"));
    writer.Write(Encoding.ASCII.GetBytes("format binary_little_endian 1.0\n"));
    writer.Write(Encoding.ASCII.GetBytes($"element vertex {vertices.Count}\n"));
    writer.Write(Encoding.ASCII.GetBytes("property float x\n"));
    writer.Write(Encoding.ASCII.GetBytes("property float y\n"));
    writer.Write(Encoding.ASCII.GetBytes("property float z\n"));
    writer.Write(Encoding.ASCII.GetBytes($"element face {faces.Count}\n"));
    writer.Write(Encoding.ASCII.GetBytes("property list uchar int vertex_indices\n"));
    writer.Write(Encoding.ASCII.GetBytes("end_header\n"));

    foreach (Vertex vertex in vertices)
    {
        writer.Write(vertex.X);
        writer.Write(vertex.Y);
        writer.Write(vertex.Z);
    }

    foreach (int[] face in faces)
    {
        if (face.Length > byte.MaxValue)
            throw new InvalidDataException("PLY face has too many indices for uchar list count.");

        writer.Write((byte)face.Length);

        for (int i = 0; i < face.Length; i++)
            writer.Write(face[i]);
    }
}

The PLY writer is still fairly readable, but it becomes more procedural - the stream owns the cursor, and the code is expressed as side effects against that stream.

A Reflection on the Design

The reader and writer APIs are intentionally symmetrical.

Reader:

ReadInt(out int value)
ReadFloat(out float value)
ReadString(...)
ReadBytes(...)

Writer:

WriteInt(int value)
WriteFloat(float value)
WriteString...
WriteBytes...

The reader consumes and returns remaining data. The writer appends and returns the current or new builder.

The result is a high-level binary workflow:

var data = ImmutableByteArrayReader.FromFile("Input.bin");

data = data
    .ReadString(4, out string magic)
    .ReadInt(out int version)
    .ReadBytes(32, out ImmutableByteArrayReader header);

and:

var output = new MutableByteArrayWriter()
    .WriteStringFixedSize(magic)
    .WriteInt(version)
    .WriteBytes(header);

This makes binary code easier to inspect, easier to test, and easier to refactor.

Procedural vs Dataflow Use: Mutable vs Immutable Construction

There are two writer types because they solve different problems.

MutableByteArrayWriter is for ordinary construction. It is mutable, append-only, efficient, and can be saved multiple times.

var data = new MutableByteArrayWriter()
    .WriteStringFixedSize("FILE")
    .WriteInt(1);

data.Save("A.bin");
data.Save("B.bin");
data.Dispose();

ImmutableByteArrayWriter is for branching construction.

var common = new ImmutableByteArrayWriter()
    .WriteStringFixedSize("FILE")
    .WriteInt(1);

var a = common.WriteStringZeroTerminated("A");
var b = common.WriteStringZeroTerminated("B");

The immutable writer is not meant to replace the mutable one for high-throughput output. It exists for safety, experimentation, and forkable construction.

Future Improvements

The API can be improved in several directions.

A schema layer could sit on top of these primitives. Instead of manually writing every field, a format could define named fields, block sizes, validations, and version-specific layouts.

The reader could gain richer parsing helpers, such as ReadAsciiToken, ReadAsciiLine, ReadUntil, TryRead, and Peek variants. These would make mixed text/binary formats like PPM and PLY even cleaner.

The writer could support reservation and backpatching. Many binary formats write a length or offset before the final value is known. A controlled API for placeholders would make this safe:

var lengthPosition = current.ReserveInt();

...

current.PatchInt(lengthPosition, payloadLength);

For very large files, both reader and writer could have stream-backed variants. ImmutableByteArrayReader is ideal for in-memory data, but some workflows need lazy reading, memory-mapped files, or chunked output.

The immutable writer could also use a rope-like internal representation instead of copying the whole byte array on every append. That would preserve functional semantics while making branching construction much more efficient.

The core idea, though, should stay the same: binary data should be worked with as a fluent sequence of explicit operations. The API should make the structure of the format visible, while hiding the repetitive mechanics of offset movement, byte ordering, padding, and raw byte appending.

A Soft Introduction to EasyShell

Charles Zhang — Tue, 05 May 2026 02:30:47 +0000

"Can it be simpler?" - A recurring thought I've had while working on build automation.

EasyShell (command: easy) is a minimal shell scripting language designed from the ground up for simplicity and cross-platform build/process automation. If you’ve ever felt that PowerShell’s syntax is powerful but easy to forget, or that traditional shell scripts get messy across operating systems, EasyShell aims to strike a cleaner balance.

It's implemented in C# and runs on .NET, giving you natural access to the entire .NET ecosystem while keeping the scripting experience lightweight and approachable.

Design Principles

One command per line (shell-like flow)
Very small set of core concepts
Strongly-typed global variables
Seamless .NET interop via reflection
Expressions in parentheses for inline evaluation
Easy to read, write, and remember

Version 0.1.0 is now available — functional for everyday automation tasks.

Core Language Features

Variables

All variables are declared with an explicit type and live in global scope:

INTVAR Count 42
BOOLVAR Debug TRUE
DOUBLEVAR Ratio 3.14
STRINGVAR Message "Hello from EasyShell"
HANDLEVAR Now System.DateTime.Now   # stores object instances

Variable names are case-insensitive
Reference with $VarName
Re-assign with $VarName = value (or expressions)

Expressions (The Power Feature)

Wrap sub-commands in parentheses to evaluate them inline:

STRINGVAR Formatted (System.String.Format "Count = {0}" $Count)
BOOLVAR IsBig (> $Count 100)
STRINGVAR Today (format "{0:yyyy-MM-dd}" (GetDate))

Calling .NET

Static members (fully qualified):

  System.Console.WriteLine "Hello World!"
  System.IO.File.WriteAllText "output.txt" $Message

Instance methods via HANDLE:

  HANDLEVAR Now System.DateTime.Now
  STRINGVAR Stamp (CALL $Now ToString)

Control Flow

IF (== $Count 42)
    print "The answer!"
ELSEIF (> $Count 50)
    print "Too high"
ELSE
    print "Something else"
END

INTVAR I 0
WHILE (< $I 5)
    System.Console.WriteLine $I
    $I = (+ $I 1)   # arithmetic helpers coming soon
END

Functions

Simple named blocks (no parameters — use globals):

FUNC BuildProject
    print "Building..."
    dotnet build
END

CALL BuildProject

External Commands

Any command that isn’t a keyword or .NET call falls back to executing an external process (with stdout capture):

git status
dotnet publish ...

Real-World Example

Check out the full build script used by the project itself:

BuildEasyShell.easy

It demonstrates:

Path handling and folder creation
Running dotnet publish
Conditional logic for OS/architecture
Creating a dated zip package

This script is self-contained and shows how EasyShell can manage non-trivial automation tasks.

Quick Start

# REPL mode
easy

# Run a script
easy path/to/script.easy

# Help
easy --help

A dedicated VS Code syntax highlighting extension is available: Methodox.easyshell

Who Is It For?

EasyShell is ideal for:

Build automation scripts
Simple CI/CD glue
Daily developer tooling
Anyone who wants .NET power without heavy dependency

It's intentionally minimal — no advanced Bash-style features, just the essentials done in a way that’s hard to forget.

Give it a try and let me know what you think!

DevLog 20251214: Yet Another Shell Script – Keeping Build Automation Simple with EasyShell

Charles Zhang — Tue, 05 May 2026 02:23:04 +0000

As we roll out more tools, both internal and public, there has been a growing need for easy-to-maintain shell scripting and build automation. Build automation is complex enough without all the syntax burden - my favorite is to use PowerShell, but often it feels like wrestling with the tool itself. PowerShell is powerful, sure, but its depth often means hunting down syntax I know I've used a dozen times before. Bash has its quirks across platforms, and honestly I don't know good ways of using it outside MinGW, Git Bash, or WSL - none of which felt quite "right".

I wanted something lighter: a shell scripting tool that's easy to pick up, cross-platform, and hard to forget once you start using it.

So I made EasyShell (or just easy): a minimal shell scripting language implemented in C# that focuses on process automation with a very small set of concepts.

Motivation and Design

EasyShell is for "lazy" developers (like me) who just want to automate common tasks - calling .NET APIs, running external tools, handling simple logic - without a steep syntax curve or platform-specific headaches. It combines a shell-like one-command-per-line flow with strong typing and easy .NET interop. No advanced Bash-style wizardry; just straightforward scripting.

It could also serve as a nice companion alongside other tools in the long-term Divooka ecosystem.

Quick Taste of the Syntax

Files typically use the .easy extension, with syntax highlighting available via the VS Code extension.

Here's a small sample from the repo:

# Comments start with #
HANDLEVAR NOW System.DateTime.Now

# Instance method via CALL
STRINGVAR DATE (CALL $NOW ToString)

# Static .NET call with expression
STRINGVAR VALUE (System.String.Format "Current time: {0}" $DATE)

STRINGVAR PATH "C:/temp/greeting.txt"
System.IO.File.WriteAllText $PATH $VALUE

Variables are declared with their type (INTVAR, STRINGVAR, BOOLVAR, DOUBLEVAR, HANDLEVAR), names are case-insensitive, and everything lives in global scope for simplicity. Expressions are wrapped in parentheses for inline evaluation, like (== $X 10) or sub-commands.

Control flow sticks to the basics:

IF ... ELSEIF ... ELSE ... END
WHILE ... END
Simple FUNC ... END / CALL (globals make "returns" easy via variables)

You can call external executables naturally, and non-built-in commands fall through to process execution (stdout capture included).

Early Days

This is version 0.1.0 territory - functional for everyday build tasks, with room to grow (arithmetic helpers, more examples, etc.). You can run it in REPL mode (easy) or point it at a script. Builds and packages are straightforward with the included scripts.

If you've ever wished for something between a full PowerShell script and a quick batch file that "just works" across machines, maybe give EasyShell a try. The GitHub repo has the full language overview, examples, and build details: MethodoxTech/EasyShell.

DevLog 20260426: Divooka Mandelbrot Benchmark – Putting Our Scripting Language to the Test

Charles Zhang — Mon, 27 Apr 2026 03:31:48 +0000

Today we released the first public version of DivookaBenchmark_Mandelbrot — a standardized benchmark suite built specifically to measure the real-world performance of Divooka against a wide range of languages and runtimes.

The benchmark computes the Mandelbrot set at 2000 × 2000 resolution with a maximum of 1000 iterations per pixel, then verifies correctness using a 32-bit checksum (target: 689833081). We run each implementation five times and record average time, min/max, peak memory, and distribution size.

Why This Benchmark Matters

One of our core beliefs is that a modern scripting language needs a "decent (high) performance". This benchmark was designed to prove that point in a reproducible way.

It exercises heavy integer and floating-point math, tight loops, branches, and memory writes — exactly the kind of workload where interpretation overhead shows up quickly. This particular benchmark doesn't test function calls directly.

The goal is not to produce the an optimized Mandelbrot renderer, but to compare a simple, fixed algorithm across different languages and runtimes, then use the result to understand where Divooka currently stands.

We included implementations (or equivalent ports) for:

C++
C# (.NET 10, including AoT/trimmed)
JavaScript (multiple browsers + Node.js)
Go, Java, Julia, Python 3.13, Ruby, Prolog, GNU Octave
And of course, multiple execution modes of Divooka 0.75.2 (compiled, Aviator, Neo Editor, Stewer)

We even tested AI-generated versions from ChatGPT, Gemini, Grok, and Kimi to see how reliable and performant LLM-produced result is in practice.

Key Results (on Windows 11, i7-13700KF)

Fastest overall: JavaScript in Edge/Chrome/Brave (~1,296 ms, very low memory)😲
Fastest native: C++ (~1,308 ms)👍
Strong managed contender: C# AoT (~1,355 ms)
Divooka compiled: 3,639 ms — comfortably beating pure interpreters like Python (~47 s) and Ruby (~49 s) ⚡
Divooka Aviator: 6,711 ms 🥰
Divooka Neo Editor: significantly higher overhead (estimated multi-hour range for full runs) 🥹

The gap between Divooka's compiled mode and the top-tier JITs (especially V8) is still noticeable, but the improvement over classic interpreted scripting languages is clear. This reinforces why we’ve been investing heavily in our compilation pipeline and runtime optimizations.

AI-generated implementations varied wildly — some produced correct checksums but took 26 seconds to several minutes, while others failed entirely or fell back to calling Python under the hood. Deterministic engineering still wins.

What We Learned

JIT is not optional for competitive scripting performance.
Tooling and editor overhead can dominate if not carefully managed (something we're actively addressing).
Even simple, well-defined tasks like Mandelbrot reveal meaningful differences in language/runtime design.

The full repository is now public:

https://github.com/MethodoxTech/DivookaBenchmark_Mandelbrot

It includes all source implementations, PowerShell automation scripts, result tables, and artifacts. Feel free to clone, run it yourself, or contribute additional language ports.

This benchmark will become part of our regular performance regression suite as Divooka evolves. Future runs should show steady gains as we refine the compiler and reduce runtime overhead.

Current Results

Results from best runs of respective platform:

Rank	Language / Runtime	Size	Best Time
1	JavaScript Web, Edge / Chrome / Brave	3 KB	1295.80–1302.80 ms
2	C++	15 KB	1308.00 ms
3	C# AoT	911 KB	1355.35 ms
4	C# .NET 10	16.5 MB	1357.47 ms
5	JavaScript Node.js	2 KB + 98.2 MB	1406.20 ms
6	Go	2 KB + 224 MB	1425.01 ms
7	Julia	2 KB + 1 GB	1511.20 ms
8	JavaScript Web, Firefox	3 KB	1513.00 ms
9	Java OpenJDK 17.0.11	301 MB + small files	1587.79 ms
10	Divooka 0.75.2, Compiled	71.914 MB	3639.24 ms
11	Divooka 0.75.2, Aviator Run	8 KB + 2.16 GB + 776 MB	6710.84 ms
12	Python 3.13.5	2 KB + 139 MB	47127.70 ms
13	Ruby 3.2.2	1 KB + 907 MB	49489.82 ms
14	Prolog SWI, optimized	2 KB + 42.8 MB	314687.84 ms
15	GNU Octave 7.3.0	2 KB + 2.07 GB	2464913.29 ms
16	Divooka 0.75.2, Neo Editor estimate	8 KB + 2.67 GB	~95.8 hr

Limitations

This benchmark only tests a narrow case.

It does not test UI programming, data manipulation, graph execution, external libraries, async workloads, recursion-heavy workloads, or large real-world applications.

It also does not fully normalize warm-up behavior. Browser JavaScript likely benefits from highly optimized JIT behavior, and other runtimes may have different startup / warm-up costs.

GNU Octave is probably optimized for matrix-oriented workloads, not naive scalar loops.

Python is rarely used this way in performance-sensitive numerical code; normally people use NumPy, Numba, Cython, PyPy, or native extensions.

English is The Worst Programming Language

Charles Zhang — Sun, 26 Apr 2026 03:47:34 +0000

In the world of software engineering, we obsess over programming languages: their syntax, their type systems, their performance characteristics, their paradigms. We debate Rust versus Go, Python's readability versus C++'s control, Haskell's purity versus JavaScript's chaos. Yet we rarely acknowledge the elephant in the room — or rather, the language we all use every day that makes every other language look like a model of crystalline precision: English.

English is, without question, the worst programming language ever created. It is not merely flawed; it is fundamentally unsuited for the reliable transmission of complex ideas. Anyone who has ever tried to communicate a non-trivial technical concept to another human being knows this instinctively. The ambiguities, the contextual dependencies, the endless opportunities for misinterpretation — English excels at all of them.

If you have spent any time in meetings, code reviews, specification documents, or even casual Slack threads, you have felt the pain. And if you have any background in mathematics, physics, or formal logic, the contrast becomes almost comically stark.

Precision: The Foundation of Reliable Computation (and Communication)

At its core, a good programming language is a formal system designed for unambiguous execution. Every valid program has exactly one meaning under the language's semantics. A compiler or interpreter will produce the same behavior every time, assuming the same inputs and environment. This is not an accident; it is the entire point.

Mathematics and physics adopted formal languages for the same reason. When Newton or Leibniz developed calculus, they didn't just wave their hands and say "the rate of change, you know, kinda like speed but for curves." They created notation — symbols, rules of manipulation, axioms — that allowed precise statements like:

This expression has one, and only one, interpretation among those who understand the formal system. There is no room for "well, depending on what you mean by derivative" or "in my experience, sometimes it's 2x plus or minus a bit."

Physics follows suit. Maxwell's equations in differential form are not poetic suggestions:

These are not open to "opinions-based" interpretation. Misunderstand a sign or a vector component, and your electromagnetic device will quite literally fail to function. Engineers and physicists spend years learning to think within these formalisms precisely because natural language is too sloppy for the phenomena they describe.

Formal languages exist because human natural languages are terrible at edge cases, scope, and unintended interpretations. We invented predicate logic, set theory, lambda calculus, and programming languages to escape the swamp of ambiguity.

English, by contrast, is the swamp.

The Many Ways English Fails as a Specification Language

Consider something as seemingly simple as a requirement: "The system shall process transactions quickly."

What does "quickly" mean? Under 100ms? Under 500ms? Does it depend on load? On hardware? On network conditions? Is this a hard guarantee or a soft target? English offers no mechanism to distinguish these.

Now imagine trying to implement a sorting algorithm based on an English description:

"Sort the list in ascending order, but put the most important items first, unless they're duplicates, in which case keep the original order for those."

Good luck. Is "important" defined? What constitutes a duplicate? Does "original order" refer to stable sort semantics? English leaves all of this to intuition, shared context, and — inevitably — arguments in code review.

Real-world examples abound in software projects:

"Handle errors gracefully" — Does this mean log them? Retry? Notify the user? Crash the process? Return a default value?
"Make the UI intuitive" — Intuitive to whom? A power user? A complete novice? Someone from a different cultural background?
"The cache should be consistent" — Eventual consistency? Strong consistency? What about partition tolerance?

These are not edge cases. They are the norm. Experienced engineers learn to translate vague English requirements into precise specifications, often using formal tools (user stories with acceptance criteria, UML, TLA+, property-based testing) precisely because English alone is insufficient.

Ambiguity at Every Level

English is ambiguous at the lexical, syntactic, semantic, and pragmatic levels.

Lexical ambiguity (multiple meanings for the same word): "Bank" can mean a financial institution, the side of a river, or to rely on something. Context usually helps, but in technical documents, context can itself be contested.

Syntactic ambiguity (parsing issues): Classic example — "I saw the man with the telescope." Did I use the telescope to see the man, or did the man have the telescope? Programming languages avoid this with strict grammar rules and operator precedence.

Semantic ambiguity: "The function should return the largest value." Largest by what metric? In what ordering? For floating-point numbers, what about NaN or signed zeros?

Pragmatic ambiguity: What is left unsaid. In a conversation between colleagues who have worked together for years, massive amounts of information are implied. New team members, or an AI trying to implement from a spec, have no access to that shared mental model.

Compare this to Python, often praised for readability:

def process_data(data: List[float]) -> Optional[float]:
    if not data:
        return None
    return max(data)

Even without types, the behavior is unambiguous to anyone who knows Python's semantics. max([]) raises an exception, but here we explicitly handle the empty case. The return type hint further constrains expectations.

English has no equivalent of type hints, no compiler to catch inconsistencies, no unit tests for prose.

Why We Put Up With It (And Why We Shouldn't)

English has undeniable strengths. It is expressive, flexible, and culturally rich. It can convey emotion, nuance, humor, and poetry in ways that formal languages cannot. Shakespeare didn't write in lambda calculus for a reason.

But when the goal is reliable transmission of executable ideas — specifications, APIs, requirements, designs — those strengths become liabilities. Flexibility is another word for underspecification.

Anyone with real experience communicating complex ideas knows the pattern:

Write what seems like a clear English description.
Send it to a colleague.
Receive back an implementation that is technically correct but completely misses the intent.
Spend hours in discussion clarifying what was "obviously" meant.
Repeat.

This is why mature software organizations invest heavily in:

Precise requirements documents with measurable acceptance criteria
Formal methods (where the cost justifies it — e.g., aerospace, finance, medical devices)
Contract testing, property-based testing, and exhaustive specification
Code as the single source of truth, with comments used sparingly

The very existence of these practices is an admission that English is inadequate.

In physics and mathematics, we don't tolerate "it's approximately true, in the usual sense." We define terms rigorously. We prove theorems. We build models whose predictions can be falsified experimentally. The precision of the language enables the precision of thought and the reliability of results.

Programming aspires to the same rigor. That's why we have static type systems, formal verification tools like Coq or Lean, and languages with strong guarantees (memory safety, data-race freedom, etc.).

English remains the worst because it resists all such discipline. It evolves organically, embraces exceptions, and thrives on interpretation. It is a living, messy, human thing — wonderful for literature, conversation, and persuasion; disastrous for programming.

A Humble Remark

We don't need to abandon English. We need to recognize its limitations and use better tools where precision matters.

Next time you write a technical specification, ask yourself: Could this be misinterpreted in a way that leads to incorrect behavior? If the answer is yes (and it almost always is), add precision — through examples, edge cases, invariants, or even pseudocode.

Treat English as a high-level, lossy compilation target rather than the final executable specification.

Because in the end, the computer doesn't care about your opinions, your intent, or what "everyone knows" you meant. It executes precisely what you told it — in a real programming language.

And humans, despite our intelligence, are not much better than computers when the specification is written in the worst programming language of all: English.

We just hide our bugs better, and argue about them longer.

DEV Community: Charles Zhang

Building Multilingualism with Claude and Divooka App Platform

Background

Motivation

Building with Claude and Divooka

Building the Translation Dataset

A Website Without a Backend

Accuracy and Open Contributions

Final Thoughts

DevLog: 2026-10-15 A Detective Story - Making It to The Release.

Overview

Development Experience

Reception

Revival of Effort

The Things I Am Still Not Satisfied With

Remarks

References

Fantasy Planet Painter 2.0 Is Here!

The Basics: From a Sketch to a World

A New Physical Planet

More Ways to Create Your World

Painting, Layers, and More Space to Experiment

Build a Fantasy World to Suit Your Terrain

A World with Many Styles

Save and Share Your Worlds

Flat Worlds and Familiar Favourites

Experimental Steam Achievements

World to Beyond: A Rebuilt Map Studio

Availability

References

DevLog 20261007: A Detective Story - First Satisfying Fully Playable Build

Overview

Motivation

On a Reusable, Configuration-Based Detective Story Game Engine

The Development of A Detective Story

Plot Work

Release

References

DevLog 20261002: Desktop Automation Toolbox and Mouse Emulation

DevLog 20260919: Upcoming Fantasy Planet Painter 2.0 and the Making of It

Fantasy Planet Painter

The Beginning

The Start

The Road Map

Feedback and Improvements

Version 2.0

The W2B Project

Going Forward

References

DevLog 20260731: FPP v1.4.0 and Divooka Explore Demo Updates

Overview

Procedural Terrain Generation in Divooka

The Fantasy Planet Painter v1.4.0 Update

Conclusion

Designing a Binary Data API for Divooka with PPM and PLY Examples

Design Motivation

Reading Binary Data

Binary Buffer Reader: ImmutableByteArrayReader

Reading blocks

Strings

Writing Binary Data

Binary Buffer Writer: MutableByteArrayWriter

Immutable writer: ImmutableByteArrayWriter

Writing fixed-size blocks

Examples

Example: reading a PPM image

Example: writing a PPM image

Example: reading a PLY file

Example: writing a binary PLY file

A Reflection on the Design

Procedural vs Dataflow Use: Mutable vs Immutable Construction

Future Improvements

A Soft Introduction to EasyShell

Design Principles

Core Language Features

Variables

Expressions (The Power Feature)

Calling .NET

Control Flow

Functions

Binary Buffer Reader: `ImmutableByteArrayReader`

Binary Buffer Writer: `MutableByteArrayWriter`

Immutable writer: `ImmutableByteArrayWriter`