DEV Community: Charles Zhang

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.

DevLog 20260319: Metaprogramming (Teaser)

Charles Zhang — Thu, 19 Mar 2026 20:16:19 +0000

Quick Comment

Following Document-Level Main Module, the possibility really opens up...

This is very different from our earlier hard-coded "Stats" node.

DevLog 20260319: Towards OOP - Document-Level Default Module and Module-Level Members and Behaviors

Charles Zhang — Thu, 19 Mar 2026 20:16:08 +0000

Revisiting Flappy Bird – The Pain Point

Remember our Flappy Bird example from mid-2025?

The long chain of variable initializations was needed for two main reasons:

No way to declare variables before using them
More critically - no way to define custom data structures that could group related values together and be instantiated with a single node.

In retrospective it seems obvious: we just need proper structured data containers. But building the scaffolding to support this properly in a visual, node-based system is a bit more involved.

Searching for a Solution

I spent a long time trying to bring OOP concepts into Divooka. A huge amount of effort went into DiOS (Divooka Open Standards), with the hope that a complete standard would naturally solve these kinds of problems. But standardization work is slow and deep - just like making Divooka itself feature-complete.

Then, while working on something completely unrelated and taking a short break from this topic, it suddenly clicked.

The key insight: start simple and approach it from a functional/declarative angle first, before jumping into inheritance, encapsulation, polymorphism, and all those good stuff.

I'm really excited - we finally have meaningful progress.

The Divooka Way

To claim our goal as "everything is a node" is a bit too strong, but I strongly prefer keeping almost everything on the graph.

This aligns with how we already handle structured primitives - direct value setting of compound inputs. That way, there's still hope that users can drop down to raw node programming when they need full control (and thus keep everything programmable).

Traditional property panels (like Unreal Blueprints' object definition GUIs) are out - they break the pure graph paradigm.

Instead, the solution is declarative, similar to how TerraGen works: the mere presence and connection of certain nodes defines meaning.

This feels awesome for several reasons:

We can make full use of the 2D graph layout - place things exactly where we want them visually
It stays completely coherent with Divooka's graphical paradigm
No need for separate "class editor" UIs

What's Been Implemented So Far

Current working pieces:

Graphs can now act as modules
Support for module-level data members and behavior members
A main module tied to the document, with existing graphs serving as associated behaviors

Module-scoped instance node – in Events context

Module-scoped instance node – in Dataflow context

Top-level module behavior graphs

This immediately unlocks:

Clean access to (top-level) module instances
Shared event and dataflow instance data
A unified programming and document model for subgraphs (still a work-in-progress)
In procedural contexts (Glaze! especially): we now have proper data containers - no more awkward giant variable lists or forced tuples! (Compare to the old Flappy Bird screenshot)
Much simpler and more natural state storage/access in Glaze! and procedural graphs

This is a big deal - for a system that's gearing up for real production use, it feels like crossing a major milestone in usefulness and core abstractions.

Current Limitations & Remaining Work

Still plenty to fix/polish:

A bunch of bugs and edge cases
Proper serialization support
Smooth context switching between graphs
Subgraph consolidation / better nesting UX

Looking Ahead

This is a solid foundation, but there's still a long road:

Full modularization support
Modules inside modules (nesting)
Module inheritance / composition patterns / polymorphism
Base DOM exposed as the "main module" for metaprogramming API
Detailed documentation: how it all fits together, recommended usage patterns, expected behaviors, pitfalls
Module-level scoped instances (deeper/finer control)

Overall - I am very happy with the direction. It feels like Divooka is finally getting the abstraction power it deserves while staying true to its visual, graph-first philosophy.

I am hyped for what we will achieve.

References

A Detective Story: The Case of The Dead Office Guy (Upcoming Game Release)

Charles Zhang — Fri, 06 Mar 2026 19:29:11 +0000

Overview

In the quiet town of Baytown, an unremarkable man lies dead under suspicious circumstances. Rumors ripple through the streets. Secrets long buried begin to surface. The whole community is buzzing - some in dread, others gripped by dark fascination.

A Detective Story is a compact detective simulator that brings generative AI to the heart of interactive fiction.

Step into the role of detective in this small-scale murder investigation. Interrogate a cast of AI-powered townsfolk, each with their own motives, fragmented memories, and the potential to lie or mislead. Explore the map to uncover physical evidence and hidden clues. Piece it all together before time runs out.

Game Guide

Your mission: Solve the murder as efficiently as possible - minimize days elapsed and questions spent.
Bringing suspects to the station costs valuable time (days). Choose your interviews with care.
These are informal interrogations - no formal oaths, no truth serum. Witnesses and suspects may deceive, omit, or hide the truth.
You have only 3 questions per interview. Make every one count.
Stay in character for maximum immersion: Ask about alibis, relationships, timelines, strange sightings, and contradictions.
Cross-check stories, hunt inconsistencies, and link conversations to evidence found on the map.

Hardware Requirements

A Detective Story is lightweight and runs smoothly on modest hardware. It requires at least 10 GB of system RAM (DRAM) - with no heavy VRAM demands.

DevLog 20260225: Divooka Visual Programming - Direct Value Setting of Compound Inputs

Charles Zhang — Wed, 25 Feb 2026 17:46:45 +0000

Finally, it arrived! Well, not exactly here yet, but getting closer.

Overview

Divooka intends to make visual programming simple and accessible - the accessible part is achieved both through wide availability and the general-purpose nature of the programming system, but the simple part is what we spend lots of effort thinking hard trying to improve.

In the past, dealing with complex configuration takes the form of either "explosion" of arguments or dedicated Make XXX construction functions:

The problem arises due to the direct exposure of all input arguments in visual programming. Both approach makes the canvas look busy, with the former a common approach in existing systems - using a struct sounds good on paper but still requires a complex looking construction node. This is a common problem in visual programming systems, below shows how it's done in Blender and ComfyUI.

You do get used to it after a while, but a busy looking canvas remains a busy-looking canvas. In Blender, you can sort of "collapse" a node:

As Blender is constantly improving, we can also now collapse property groups as shown in the earlier screenshot.

As a syntax purist and (unfortunately) very conscious about my working space, my eyes can't tolerate messiness. I kind of like how Houdini approaches this.

Essentially they offload all the complexity to the properties panel - this has the huge benefit of making everything look very clean. But the downside is Houdini rely heavily on scripting expressions (like Excel).

TerraGen and World Machine mixes the approach:

In both cases, connections represent flow of terrain data only and additional configurations are offloaded to property panels. In TerraGen especially, this allows those properties to be animated. The downside, once again, is whatever is offloaded to property panels are no longer programmable using nodes.

Our Approach

Our proposed solution for Divooka looks like this: fundamentally all properties remain as node inputs, but compound values (especially value types) should just allow "editing in place" through a property panel. If more complex programming is needed, one can easily fall back to Make XXX nodes again.

Future Work

There is still remaining work on type check, hierarchical compound types, arrays, and serialization, and also node rendering.

Conclusion

As usual with all the exciting language features of Divooka we intend to introduce, there are lots of details to take care of here.

DEV Community: Charles Zhang

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

External Commands

Real-World Example

Quick Start

Who Is It For?

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

Motivation and Design

Quick Taste of the Syntax

Early Days

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

Why This Benchmark Matters

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

What We Learned

Current Results

Limitations

English is The Worst Programming Language

Precision: The Foundation of Reliable Computation (and Communication)

The Many Ways English Fails as a Specification Language

Ambiguity at Every Level

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

A Humble Remark

DevLog 20260319: Metaprogramming (Teaser)

Quick Comment

DevLog 20260319: Towards OOP - Document-Level Default Module and Module-Level Members and Behaviors

Revisiting Flappy Bird – The Pain Point

Searching for a Solution

The Divooka Way

What's Been Implemented So Far

Current Limitations & Remaining Work

Looking Ahead

References

A Detective Story: The Case of The Dead Office Guy (Upcoming Game Release)

Overview

Game Guide

Hardware Requirements

DevLog 20260225: Divooka Visual Programming - Direct Value Setting of Compound Inputs

Overview

Our Approach

Binary Buffer Reader: `ImmutableByteArrayReader`

Binary Buffer Writer: `MutableByteArrayWriter`

Immutable writer: `ImmutableByteArrayWriter`