The lie was implicit. It wasn’t intentional, but it was there nonetheless: You can make anything you want [with these engines].

Can you travel through your voxel world at 7,400km/h in real-time?

Can you “simply” carve a tunnel through a world built entirely from mathematical equations?

Most programmers never find out. They optimise for shipping quickly, take the common path, and never notice the walls.

These aren’t theoretical examples, these are games that exist right now, built by programmers who went a different way.

Engines don’t remove the hard problems—they only bury them. If you want to grow as a programmer, you must eventually run the gauntlet.

By the end of this article, you’ll see why:

• Understanding lets you go where engines can’t follow

• Your tools define your possibility space

• The constraint isn’t only technical, it’s creative

Understanding Lets You Go Where Engines Can’t Follow

A Flock of Meese has been sharing his Minecraft-like game engine for the Gamecube and Dreamcast:

The Dreamcast is a console from 1998. It has a 200MHz CPU, 16MB of RAM, 8MB of VRAM and a 100MHz GPU.

The difference between the Dreamcast and a typical gaming PC in 2009, the year Minecraft was created is orders of magnitude.

The Dreamcast peaked at ~7 million polygons/sec. An average 2009 PC: 775 million/sec—110x more.

This Dreamcast example is only possible because the programmer understands the hardware and the problem space at a deep level.

It also means that Minecraft could have launched in 1998. There was no technical reason that it did not exist yet, only one of human ingenuity.

We must assume that right now there are game concepts waiting to be discovered, that use the constraints of our current hardware to their maximum, and likely won’t be discovered for decades.

Your Tools Define Your Possibility Space

Here is the PC version of the same engine. Movement at 7,400km/h with a 1KM draw distance, in real-time with no frame dips, at 60FPS:

So far the developer has been quiet about his methods, but I can say for certain that you don’t get these kinds of results without deeply understanding the problem space, and the hardware.

Contrast this with the industry standard high-performance game engine: Unreal Engine 5. With typical cell sizes of 256m^3, and loading ranges around 768m radius, you can’t sustain that speed without FPS drops (called “hitches” in their documentation).

With the engine A Flock of Meese has created, game design ideas that aren’t even possible in other engines are unlocked.

Want to create a game about an immortal cat piloting ICBMs across a vast voxel world in real-time? You can’t do that in just any engine.

The Constraint Isn’t Only Technical, It’s Creative

Mike Turitzin has been sharing his SDF-based game engine, and the results are something else:

A gun that opens a traversable tunnel through arbitrary geometry in real time, and then closes it again.

Mike calls it simple, because he built the tools that made it natural to think about this type of operation.

The engine-dependent programmer never arrives at this idea because nothing in their toolchain points towards it.

The limitations shape the imagination before the developer even sits down to design the game.

Conclusion

The programmers in this article didn’t find a shortcut. They worked through the hard problems and came out the other side with the capability to explore spaces other programmers cannot.

They researched how programs work, the hardware, the mathematics, and created their own unique possibility space.

That’s the gauntlet. It’s harder. It’s slower. But what’s waiting through the fire isn’t just better code, it’s a possibility space that’s uniquely yours.

Fire is the test of gold; adversity, of strong men,
— Seneca

There are many reasons I build my own engines from scratch, and one that’s not what you think... It has to do with the collapse of civilisation.

But first, let’s talk about the obvious stuff that made me quit game engines.

The Obvious

Why do most people stick with big engines like Unity even when they’re frustrated? I speak to developers that have successful games published that *hate* working in their engine.

For them, dealing with frustration feels safer than starting over, and much safer than going engine-free. But here’s the thing: much of what they are protecting is engine-specific trivia that never transfers anywhere else anyway.

I used to think that serialisation was difficult, because it was, back when I used Unity as my main engine.

Nowadays, with my knowledge of building custom engines, it’s not only trivial, but fun to write serialisation code for my games.

One of the reasons that serialisation was such a chore back in those days was because of Unity’s version control tool. It was rudimentary and had merge conflicts constantly that lost us hours or days of work.

And that’s not even to mention the compile times of these engines. Sitting around for tens of seconds, or sometimes minutes just to test a change is insane considering how powerful modern computers are.

When I’m writing my own game engine, 2D or 3D, if the compile time is greater than 1 second - something’s wrong.

Control

Beyond the day-to-day minutiae, it’s also about control.

What happens when something breaks in a 3rd party engine? You’re stuck waiting for a patch or workaround, and praying the patch doesn’t add more bugs.

In my world? I can dive in and fix it myself immediately - and, that forces higher quality. No excuses, no finger-pointing, because I’ll just be pointing in the mirror in that case.

I take full responsibility for any low-quality outcome.

My stat distribution heavily weighted toward programming. I care about software craftsmanship. This is my way to lead by example - proving you don’t need massive tools to make something great.

3rd Party Risks

If you want to take game development seriously and treat it like a business, you have to manage your risk profile. Using a 3rd party engine is a non-trivial liability. If at any point the incentives of you and the company that makes your game engine don’t align, they can cause serious damage. Here are some real stories to prove it.

Unity Runtime Fee Fiasco 2023

Back in 2023, Unity was the go-to engine for indies. That market share has been significantly eaten into by Godot since then - and this is one reason why.

If you somehow haven’t heard of the runtime fee fiasco, let me lay it out for you.

Unity announced a pricing change - adding a $0.20 fee, after a threshold, for the developer to pay to Unity *per installation* of their game. The kicker? It applied to games that were already published *and* to every instance of an installation - even the same user installing your game again after deleting it would incur a $0.20 fee.

As you can imagine, the game developer community was very upset about this - and, rightfully so. Many studios faced potential bankruptcy due to the way their games were priced.

Your free to play game that gets millions of installs per year, but makes no money? Pretty soon, you’d owe Unity 6-figures.

After massive backlash, Unity scrapped the per-install fee entirely in 2024, but the damage was done.

Many devs had their trust broken, and left Unity for other engines, or went engine-free.

Our Machinery License Termination 2022

Our Machinery was a game engine being developed by two ex-Autodesk developers starting in 2021. It was a promising extensible engine written in C.

It seemed like a reliable up-and-coming alternative without the bloat of engines like Unity or Unreal.

In 2022, the company shut down and terminated all licenses overnight, demanding that all studios using the engine delete their source code and binaries *within 14 days*.

There was no path for migration, and we still aren’t sure what happened.

One Hacker News user commented1 that a friend had been building a game using Our Machinery, and had started the painful process of porting it to Godot.

Arrowhead and Fatshark, the creators of the Helldivers franchise and Warhammer: 40K Darktide, respectively had invested financially into Our Machinery2. The engine’s failure meant that investment was wasted, though they weren’t developing games in it that we know of.

Unity Security Vulnerability 2025

Using new technology is generally riskier, but what about using something that’s been around for ages? Let’s take another look at a recent security vulnerability with Unity games published since 2017.

As indie game developers, we don’t want to have to understand everything about cyber security - so, we offload the responsibility to the authors of the tools we use.

But what happens when the people making the tools make a mistake? Everyone using them pays the price.

Any game made with Unity 2017.1 up until October 2025 - that’s 8 years - had to patch this vulnerability. Fortunately, Unity provided binary patch tools to apply the fix without doing full rebuilds and there is no evidence the exploit was used.

These aren’t hypotheticals that may *one day* happen. They have happened and will continue to happen.

With a custom engine? You don’t have that kind of risk.

Fun and Ease

Programming games from scratch is made out to be this Herculean task that only a few can accomplish. Maybe that’s true, maybe not. All I know is that if your stat distribution is over-indexed into programming, or you *want it to be*, then this path is not just possible, but *can be* easier.

I enjoy “low level” programming. Bit flipping, data packing, pointer abuse, memory management, all that kind of stuff. For me, it’s easier to create a small game engine that fits my needs than to learn and fight with a big game engine.

If you don’t want to start from scratch, working in a systems language like Odin or C means you can use pretty much any library out there easily.

From something like raylib, which handles windowing, input, sound, rendering, and even some collision detection, to something more bare-bones like SDL3 or Sokol.

I have no editor overhead. What I type is what compiles. And, it takes me less than 1 second to compile my game. My game, which, by the way, has a play test available on Steam, and also a web build playable on itch.io right now. If you are into Zachtronics style games, you’ll like LANE-4.

The Collapse of Civilisation

Finally, we get to the reason that may seem outlandish, but makes total sense - The Collapse of Civilisation.

As we move into this LLM-powered future, more and more developers are outsourcing not just their programming, but their critical thinking to idiot machines. Machines that are not conscious, cannot think, but can produce a simulacrum of what a human can.

The effect of offloading these skills is that less people understand how computers work at a fundamental level. This is an issue since almost all our infrastructure is built with computers of some kind - be that the tiny microcontroller in your air conditioner, or the high-powered CPU in your phone or computer.

It follows that if less people understand how to fix our infrastructure, that will create a skill-supply shortage. Increasingly, situations will arise in which nobody is available to fix the problem, and part of our civilisational infrastructure is left to degrade.

Knowledge is not automatically propagated forward, otherwise we would have a crystal clear understanding of the Ancient Egyptians, or the Mayans and Aztecs, or the Mesopotamians.

Instead, we have fragments to piece together a puzzle which can never be completely solved.

This loss of knowledge has happened in the distant past, and the very recent past. There are a couple of good talks on this, already, so I’d recommend you watch these if you are interested:

One is “Preventing the Collapse of Civilization” by Jonathan Blow

Another is “1177 BC: The Year Civilization Collapsed” by Eric Cline

Enjoyed this? I made Program Video Games for you.
Game Ideas -> Working Systems using first principles.

In this newsletter:

1. Why the compile-restart destroys your productivity

2. How to hot reload in Odin + Raylib without losing state

3. The affordance that’s unlocked when you use hot reloading

1. The Manual Feedback Loop Tax

Every second between “I have a cool idea” and having the implementation working in your game to see if it works is friction.

Whether you’re tweaking the main character’s jump height, or modifying the colours of a background piece of art, or modifying the pitch of a sound effect, one thing is clear: You want to observe the change as quickly as possible.

With the default setup, you tweak, compile, get back to the correct state, then you can test. This can take from seconds to minutes, depending on your game and what you’re testing. And then, you have to do it again because the first change is invariably not the last.

One of the most common reasons cited for embedding slow scripting languages into most game engines is to be able to change things while the game is running. But, what if you don’t want to, or aren’t using a scripting language?

2. Dynamic Libraries to the Rescue

Odin can compile your code as a dynamic library (.dll/.so/.dylib) that loads at runtime

The trick: split your code into two parts. The terminology is borrowed from Casey Muratori’s excellent Handmade Hero series.

1. The Cradle: This part of the program handles OS and platform code. It owns all the memory, and it calls into the dynamic library.

2. The Game: A dynamic library that contains only game code. Any state that is required across reloads must live in the memory that’s passed from the Cradle.

For this example, I have a third component: A raylib_api package that provides runtime procedure bindings for raylib. This keeps the build process simple - less moving parts.

The code below is to get the gist, full source code is linked at the end.

// main.odin - The Cradle
main :: proc() {
    rl_api := raylib_api.init()
    game_api: Game_API
    game_api_reload(&game_api)
    
    rl.InitWindow(800, 600, “Hot Reloading”)
    defer rl.CloseWindow()
    
    // Ask the Game how much memory it needs
    game_memory_buffer := make([]u8, game_api.game_memory_size())
    game_memory_pointer := raw_data(game_memory_buffer)
    
    game_api.game_init(game_memory_pointer, &rl_api)
    
    for !rl.WindowShouldClose() {
        // Check if the DLL changed on disk
        if dll_write_time, err := os.last_write_time_by_name(DLL_PATH_FULL); err == nil {
            if dll_write_time != game_api.last_write_time {
                game_api_reload(&game_api)  // Hot reload!
            }
        }
        
        game_api.game_update(game_memory_pointer, &rl_api)
        
        rl.BeginDrawing()
        game_api.game_render(game_memory_pointer, &rl_api)
        rl.EndDrawing()
    }
}

// game.odin - The Game

import rl "vendor:raylib"
import "raylib_api"

// Types and constants from raylib are safe to use
Vec2 :: rl.Vector2

Game_State :: struct {
	positions: [dynamic]Vec2,
	sizes: [dynamic]Vec2,
	colors: [dynamic]rl.Color,
}

@export
game_memory_size :: proc() -> int {
	return size_of(Game_State)
}

@export
game_init :: proc(gs: ^Game_State, rl: ^raylib_api.Raylib_API) { // ...

// other procedures follow the same structure ...

The Cradle is compiled as your main application - your .exe on Windows. It then loads the Game at runtime and binds the procedures to an API that can be called. Once bound, the Cradle can then call into the loaded procedures, passing in the required memory to keep the game running.

Recompiling the Game will trigger a reload and rebind the procedures - changing gameplay code in real time.

3. The Affordances Hot Reloading Unlocks

Hot reloading doesn’t just save time. It changes the possibility space.

With instant feedback, you entirely remove the friction of making changes, and avoid the tendency to batch a bunch of small changes together. Bonus points if you put a build hotkey in your code editor.

You can sculpt the game feel in real-time, for example:

Tune character feel in real time: Adjust jump heights, animation lengths, sound effects, damage numbers.

Design levels live: Move platforms, resize enemies or hitboxes, adjust spawns.

Iterate on juice: Modify screen shake, particle effects, camera movement - until it feels great.

I don’t know about you, but I’ve found myself getting distracted if I have to wait more than a couple of seconds. That means that every compile-restart cycle is a potential distraction point in the day.

Plus, without the cost of restarting each time, you can have the confidence to tweak anything and everything. No more hesitation and doing math in your head to calculate if you’ve changed enough lines to justify a restart.

You unlock designer mode. As a programmer, I find it very appealing to be able to expand into that other mode without friction and go from Change -> Compile -> Test to Observe -> Adjust -> Observe.

Key Insights

1. Less Friction Means More Focus - Focus is about removing distractions. Every time you wait for a compile, your brain will start to look for other things to do - even if it’s just a couple of seconds.

2. Dynamic Libraries let you reload code without restarting - Split into Cradle (persistent memory/platform) and Game (hot-reloadable logic).

3. Enable Designer Mode - With hot reloading, you get to switch into designer mode and tweak -> observe -> tweak -> observe. No break of flow getting back to the same state.

P.S. Want structured guidance on building games from first principles? Program Video Games gives you the full system - Odin + Raylib, no engines, complete control.

Code: GitHub Gist (click here)

That's where event systems shine. Keep your systems separate, and keep communication open.

What you'll learn:

• Events decouple systems

• Every major game uses them

• How to build one in 25 lines of code

Events Decouple Systems

An event system is a mail service between systems. One system sends a message, others receive it and respond. The response is a procedure - a callback - that consumes the event state and produces side-effects. Without this mail service, your code risks becoming 99% spaghetti, making you want to quit programming forever.

Imagine you're playing a game, running around, picking up items, and you pick up a gemstone. You receive a notification: Quest Started - The Missing Link (1/20 collected). Without events, you'd have either every item checked on pick-up if it should start a quest. Every sword, shield and bow dropped by bandits would have a bunch of code to check whether they are quest starters. With events, you have the item system announce "Special Gem Collected" and the quest system responds - no coupling required. The quest system doesn't even have to know the item system exists.

// Without events
on_item_pickup :: proc(item: Item) {
	if item.type == .Special_Gem {
		if !quest_is_active(.Collect_Special_Gems) {
			quest_start(.Collect_Special_Gems)
		}
		
		quest_progress_increment(.Collect_Special_Gems)
	}
}

// With events
on_item_pickup :: proc(item: Item) {
	event_publish(.Item_Collected, ItemCollectedPayload{item})
}

At first glance, the example without events looks better. It's explicit about what's going on. The version with events is abstract. The trade-off is that now any system can listen for the Item_Collected event and respond. The UI system can show a little notification, the quest system can update/start a quest, the sound system can play the "pick up item" sound, etc.

This is why major studios rely on event systems - they scale with your systems. Let's look at how Fallout used event systems.

Major Games Use Them

I've been using these [event systems] for decades in my games... designers like it, programmers like it, my guess is artists like it too

• Timothy Cain, Lead Designer of Fallout1

Timothy Cain has a video about event systems on his YouTube channel. He describes how in Fallout, when a player picks a lock, the Skill System publishes an event and the AI System checks if nearby guards "saw" anything. The AI System and Skill System communicate without being coupled - they don't know about each other.

Another example covered is that a follower may get angry when the player kills too many "cystypigs" (a gross looking pig in the world of Fallout). This demonstrates the Companion System and Combat System working together without being coupled.

Simple Implementation

A simple event system may have types setup something like this:

EventType :: enum {
	Invalid,
	TextUpdate,
	PositionChange,
}

EventPayloadTextUpdate :: struct {
	text: string,
	// some relevant data..
}

EventPayloadPositionChange :: struct {
	pos: [2]f32,
}

EventPayload :: union {
	EventPayloadTextUpdate,
	EventPayloadPositionChange,
}

Event :: struct {
	type: EventType,
	payload: EventPayload,
}

To put the types into context, you'll want some variables - stored here as globals to make things simple:

// Event callback type
EventCallbackProc :: proc(event: Event)

event_listeners: map[EventType][dynamic]EventCallbackProc
event_queue: queue.Queue(Event)

To push an event onto the queue, you'll want to create a wrapper so you don't pollute your call-sites with implementation details:

event_publish :: proc(type: EventType, payload: EventPayload) {
	queue.enqueue(&event_queue, Event{
		type = type,
		payload = payload,
	})
}

To subscribe to an event, you can link a callback procedure with an event type:

event_type_subscribe :: proc(type: EventType, callback: EventCallbackProc) {
	if type not_in event_listeners {
		event_listeners[type] = make([dynamic]EventCallbackProc)
	}

	append(&event_listeners[type], callback)
}

In your main loop, you can add a call to something like this:

process_events :: proc() {
	for queue.len(event_queue) > 0 {
		event := queue.dequeue(&event_queue)

		if listeners, ok := event_listeners[event.type]; ok {
			for callback in listeners {
				callback(event)
			}
		}
	}
}

This is a very simple event system that takes events off the queue every update and has no conditions to determine whether the event is "ready".

I've included an example with timed events in the code2. There are other types of conditions that may be useful, such as:

• Priority Events: Events have a priority score, higher priority are always checked first, low priority can be checked every so often

• Conditional Events: Attach a callback to an event that returns a boolean. If the callback returns true - which could be a game state lookup - consume the event.

• Filters: Location, Specific Entities, Game Modes - basically anything can be a filter.

• Persistent: Events that need to be saved and loaded when the game is saved and loaded.

• Sequences: Events that publish events when conditions are met.
  ... and much more!

Key Takeaways

• Use events to keep systems decoupled, where performance is not the priority

• Events are used in major games, and written the same way or similar, for decades

• Events can be extended for increased capabilities

Enjoyed this? I made Program Video Games for you.
Game Ideas -> Working Systems using first principles.

Most developers treat input as an afterthought - just slap some IsKeyPressed(<hardcoded_key>) calls and call it a day. Input is the interface for player interaction. Get it wrong and it can ruin a game.

Spend less than 15 minutes and less than 100 lines of code to write a proper input system that your players will thank you for

After reading this article, you'll never have the excuse that it's too hard to implement key rebinding.

What you'll learn:

• How to abstract input states from raw keyboard events

• Why configuration files beat hard-coded bindings every time

• How to create a custom config file that auto-generates when invalid or missing

Input Abstraction

Raw input is messy. A key can be up, pressed (this frame), held down or released (this frame). Most input bugs come from confusing these states.

I use a Colemak keyboard layout with a split keyboard at home. I usually remap WASD to FRST as that's what's comfortable for my keyboard.

When I first played Cyberpunk 2077, the in-game menu did not allow rebinding the "pick up" key - it was stuck to T, which is the same as "Strafe Right" with my layout.

Many times during combat, I'd be fighting and strafing, my crosshair would go onto a corpse while I'm strafing right, and my character would do the pick-up-this-guy animation, leaving me totally vulnerable in the middle of combat.

It was infuriating. and made me quit playing the game for a while until I bothered to learn how to edit the config file manually. You don't want your players to experience that kind of thing - many of them won't come back.

Here's the input states for keys/buttons:

InputState :: enum {
	Up,
	Pressed,
	Down,
	Released,
}

Something I've found useful is to map actions to key bindings. Just like the player rebinds "pick up" to T, we are creating games with certain actions.

For our example game, we'll have four actions:

GameBinding :: enum {
	Jump,
	Sprint,
	Left,
	Right,
}

Now we can easily separate our actions from keys by using a map (or an enum array):

// Assuming we use raylib, this could be win32's VK_KEY type, or SDL3, or GLFW, or whatever
input_map: [GameBinding]rl.KeyboardKey
input_state: [GameBinding]InputState

We have two mappings. One for the binding, and one for the current state.

We'll create a procedure to update the state every frame:

input_update :: proc() {
	for key, binding in input_map {
		if rl.IsKeyPressed(key) {
			input_state[binding] = .Pressed
		} else if rl.IsKeyDown(key) {
			input_state[binding] = .Down
		} else if rl.IsKeyReleased(key) {
			input_state[binding] = .Released
	 	} else {
			input_state[binding] = .Up
	 	}
	}
}

Raylib makes this easy because it has the same states: Pressed, Down, Up, Released.

Something like SDL3 would be a bit different:

event_update_sdl3 :: proc() {
	event: sdl.Event
	for sdl.PollEvent(&event) {
		#partial switch event.type {
		case .KEY_DOWN:
			// Check if key was previously up, etc
		case .KEY_UP:
			// ...
		// ... other event types ...
		}
	}
}

Config Files

Config files exist because we need a way to store the settings between launches of the game. Imagine if every time the player restarted the game they had to rebind the keys!

Let's say we want a config.ini file like this:

[bindings]
Jump = SPACE
Sprint = LEFT_SHIFT
Left = A
Right = D

We can create a simple default string that serves as our config file if none is present:

config_default_fmt :: `
[bindings]
Jump = %s
Sprint = %s
Left = %s
Right = %s
`

// later

config_default := fmt.tprintf(
	config_default_fmt[1:],
	string_from_key(.SPACE),
	string_from_key(.LEFT_SHIFT),
	string_from_key(.A),
	string_from_key(.D),
)

The key values for different platforms and frameworks will probably be different. So, you may need to create a couple of conversion procedures, such as these:

string_from_key :: proc(key: rl.KeyboardKey, scratch := context.temp_allocator) -> string {
	if key >= .A && key <= .Z {
		return fmt.aprintf("%c", u8(key), allocator = scratch)
	}

	#partial switch key {
	case .SPACE: return "SPACE"
	case .LEFT_SHIFT: return "LEFT_SHIFT"
	// ...
	}

	return "NULL"
}

key_from_string :: proc(s: string) -> rl.KeyboardKey {
	if len(s) == 1 {
		return rl.KeyboardKey(u8(s[0]))
	}

	switch s {
	case "SPACE": return .SPACE
	case "LEFT_SHIFT": return .LEFT_SHIFT
	// ...
	}

	return .KEY_NULL
}

Creating and Loading the Config File

For this example game, we'll use a simple config.ini file, which Odin conveniently has a parser for in core:encoding/ini.

config_load_and_apply :: proc(input_map: ^[GameBinding]rl.KeyboardKey) {
    is_config_valid := false
    m: ini.Map
    
    // Load existing config file
    if os.exists(CONFIG_PATH) {
        ini_map, err, ok := ini.load_map_from_path(CONFIG_PATH, context.temp_allocator)
        if err == .None && ok {
            is_config_valid = true
            m = ini_map
        }
    }

    // Rewrite default config file if invalid
    if !is_config_valid {
        // Generate defaults and save...
    }

    // Apply the config
    input_map[.Jump] = key_from_string(m["bindings"]["Jump"])
    // etc...
}

Generating the default config may look something like this:

config_default := fmt.tprintf(
	config_default_fmt[1:], // remove the newline at the top
	string_from_key(.SPACE),
	string_from_key(.LEFT_SHIFT),
	string_from_key(.A),
	string_from_key(.D),
)
os.write_entire_file(CONFIG_PATH, transmute([]u8)config_default)

ini_map, err := ini.load_map_from_string(config_default, context.temp_allocator)
if err == .None {
	m = ini_map
}

The generated config.ini:

[bindings]
Jump = SPACE
Sprint = LEFT_SHIFT
Left = A
Right = D

You would need to validate the config file based on your specific game's needs. For example, if some bindings are missing, that may be an invalid file and a new one will be generated.

The Usage

In your gameplay code, you can now refer to the actions your game cares about, rather than arbitrary keys:

if input_state[.Jump] == .Pressed && player.is_grounded {
	// Jump
}

Key Takeaways

This system is simple, easy to implement, and configurable by the player.

Even if you don't have the budget to create a menu, players can change the bindings in the config file directly.

The entire thing comes to less than 100 lines of code.

It goes without saying that accessibility is another major consideration when designing input systems.

By mapping actions <-> keys, your gameplay code stays clear of nasty bugs due to hard-coded key bindings, and your players get to play how they want.

Full source code

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.

Have you ever worked on a project where it was clear the user experience was being sacrificed to serve the developers? Where technology choices were made not based on performance requirements, but based on language X being the cool new thing?

People think the language choice matters more than it does. The choice only matters so far as you can finish the project and deliver a good user experience. Bonus points if you can skill-up, and though this is ultimately the most important thing, prioritising it can be unwise.

Your technical choices reveal more about your priorities than your skills.

What's discussed below:

• How ego influences our technical decisions

• The impact of our tool choices on users

• Aligning technology choices with long-term growth

The Ego Check

Ask yourself: "If nobody would ever see my code or know what tools I used, would I still make the same choice?"

I do all my marketing on social media. It's probably how you found this newsletter.

I've had to learn what works and what doesn't. One thing that works is being divisive - picking a side, and importantly, picking an enemy.

"C++ sucks, use C instead"

"Rust is superior, only brainlets use C"

It's just like picking a sports team. People start to identify with their language/toolchain choice, and get defensive when it's criticised.

People get positive social signals by cheering on their favoured programming language in the right circles.

And then, when it comes time to make a decision about a project, they have chosen their team and are obligated to stick with it.

In reality, the best thing to do is remove ego from the equation, as difficult as that can be sometimes.

I look around and see people having arguments about languages. It reminds me of this tweet:

Tsoding is right on the money. I know because I was guilty of this exact thing - learning languages rather than fundamentals, thinking the language was the problem. In reality, every language I was looking at had the performance characteristics I needed - I didn’t need to change.

In 2018, I started writing a game engine in JavaScript because I thought the language was "beautiful". I fantasised about having some game engine in JS and all the JS people being impressed. I knew the performance was bad by default, but didn't really consider the implications.

I know game engines and games have been written in JS. The point is, the decision was ego-driven, not based in rationality.

I integrated pixiJS (a rendering engine), built an ECS entity system, and was getting horrible performance. I didn't, and couldn't understand why - because I didn't know programming.

My mindset today is very different. For example, recently when looking at building a digital signal processing application with a friend, I considered first the performance, second the user experience.

I decided on C++, as that's what he uses and it works fine. But, also there are important libraries: miniaudio, and imnodes. An audio processing library, and a graphical node plugin for dear imgui.two

If I let my ego make the decision... It would have been Odin, or C. It would have been no libraries, no standard library. I doubt it would have gone anywhere.

User Impact

That brings me to the next question: "Am I prioritising development convenience at the expense of my users' time and resources?"

Have you looked at your target market and what their median specs are? Do you know how many cores their computers have, at what speeds, and how much RAM they have?

if you are a PC game developer, have you looked at the latest Steam Hardware Survey?1

Since this is not social media, I can allow myself a bit of nuance and say that there are always trade-offs. You may not be able to do the best thing for performance (user experience) because it'll cost you too much time (project runway) and so you have to choose between having no product, or one that eats the battery of people's laptops.

You can patch it later... If it's up to you.

Here's an example from today. I tried the new note-taking software called Kortex, and it uses 1.4 GB of memory without me doing anything.

I'm not willing to use it right now, and that's a direct result of their choice to write bloated software. When the global average PC has 12 GB of RAM, and the OS takes up so much of that nowadays, I can't be the only potential customer that is pushed away by this.

The Decade Test

Finally, and most importantly, ask this: "Will mastering this approach teach me principles that will remain valuable for decades to come?"

My journey into systems programming languages started in 2019. The improvement in my skill as a programmer is astronomical. I put this down to being forced to learn fundamentals - especially about memory.

The difference is so stark that I wonder how I ever had a job in web development in the first place. The answer, I think, is that I was tech savvy and knew how to read documentation.

Rather than focusing entirely on frameworks, which are constantly changing, I found value in implementing things from scratch. Things I can tailor specifically to the project.

Now, when utilising libraries in my code, I can understand the building blocks and make better decisions, not just look at the API.

The biggest unlock for me came by learning a bit about memory allocation and how CPUs work. I can make reasonable decisions about how to approach certain problems with just a few simple techniques2.

Key Takeaways

• Rather than choosing tools based on identity, instead ask yourself what's best for the project.

• Every tool choice is a trade-off for you and your users - they are the ones you are building for, so don't forget them.

• The most valuable long-term investment is principles/foundational skills. Invest in yourself to compound long term gains.

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.

2

The Bytes Beneath

Software is the Platform - Programming Lies

I feel the cursor move sluggishly as I type into VSCode on my high-end desktop computer. It drives me nuts. Not so much because of the delay, but because I know that software doesn't have to be like this…

Read more

a year ago · 4 likes · 2 comments · Dylan Falconer

I feel the cursor move sluggishly as I type into VSCode on my high-end desktop computer. It drives me nuts. Not so much because of the delay, but because I know that software doesn't have to be like this.

Microsoft can't even conceive that their applications should open instantly, putting the smallest option in a survey about expected load time as "less than 10 seconds"1.

Applications that have an entire web browser under the hood plague our systems, eating up our RAM. This is a screenshot from my laptop as I type this.

Windows uses an ungodly amount of memory these days, and these web applications on top are doing me no favours.

My laptop is intentionally low-end (Lenovo T480s). I write software to run fast on this thing and know it'll run fast on most devices.

For reference, the global average computer has 12 GB ram, and this has 8 GB.

Most people struggle with less than 16 GB these days, it's absurd.

I haven't even talked about games, as it's not the focus of this article, but the issue is huge in the game development space too. AAA developers tell their customers to "just buy better hardware".

Being willfully ignorant about the hardware isn't cool. It's unprofessional.

Disregarding the user's time is vampiric. You are trading your time for theirs, in a real sense.

By the end of this article, you'll have three key concepts to keep in mind that'll help you avoid being a digital vampire:

• Plain old data

• Data locality

• Access patterns

Plain Old Data

Code is code. Data is data. Objects aren't real. It's all a psyop.

Treating instances of datum as if they are singular pieces with agency is something all too common. A Message class that has a send(User to) method is one such example.

Take these two ways to write that functionality:

message.send(recipient)
// vs
message_send(message_data, recipient)

The difference may seem trivial, but one frames your thinking in a deceptive way.

When you call message.send, the message isn't "sending itself". A function is being called, and a pointer to the message is being passed as the first argument implicitly.

The second example more accurately reflects the reality of programs: all programs are about transforming data.

When you consider programs as fractal data transformation tools, you come to sane conclusions about how to structure them.

For example, if we wanted to send 100 different messages to 100 recipients... Let's do it a way that would be common with the first version:

messages = [100]MessageData{...}
recipients = [100]Recipient

for message, i in messages {
    message.send(recipients, recipients[i])
}

Do you see what's wrong with this? Maybe the compiler will be smart enough to catch it in this contrived example, but compilers are not magic. They are notoriously capricious when it comes to good code generation.

The issue is that we are dispatching a function call for every message, setting up the stack for calling into the function, then sending a message, then tearing it down, repeat 100 times.

What about the other method?

messages = [100]MessageData{...}
recipients = [100]Recipient

send_messages_batch(messages, recipients)

Here we are passing entire arrays of data to be processed at once.

This function wasn't outlined in the contrived example description - but, here's the thing: It can't exist with the mind-state of the first style.

If a message is a singular object, then how can it have a method that sends it and 99 others to 100 recipients? It seems absurd due to the thought patterns of thinking about individuals vs collections.

Treating data as data and programs as data transformers unlocks performance by default, especially when taking the next two points into account.

Data Locality

Keeping data close together in memory allows the CPU to use it efficiently.

This is because all modern CPUs have caches. The CPU pulls in data it thinks your program is about to use and stores it in the cache. Then, when correct, it grabs it from the cache instead of RAM.

These are L1, L2, and sometimes L3. Each cache increases in size and thus increases in real-world distance from where the work is done.

The time required to get the data is much higher in the L3 cache, and significantly higher in RAM, than in L1.

Rough averages. Time based on 3.5-5 GHz CPU

There is a lot more to this picture. The thing to keep in mind is to try and fit the data for your transformation in the L1 or L2 where possible, and try to go out to RAM rarely.

Another thing to note, is the L1 and L2 are per core caches. That means you can multiply the cache size you have access to by learning how to use threads effectively.

Access Patterns

Finally, there are access patterns. This goes hand in hand with data locality.

The CPU will try to predict what data your program needs and prefetch it into the caches. If you choose an algorithm that jumps around a lot in memory, the CPU may prefetch the wrong data. This is called a cache miss, and it's a performance killer.

Since going to memory is so slow, if every iteration of an algorithm is causing a cache miss, the algorithm may take 100x longer than it could have.

Let's look at a classic example, and how to fix it without changing data structures. The Linked List.

LinkedListNode {
    LinkedListNode *next
    int data
}

head = new LinkedListNode
head.data = 32

node1 = new LinkedListNode
node1.data = 42

linked_list_append(head, node1)

// some time later in the program

node2 = new LinkedListNode
node2.data = 42

linked_list_append(head, node2)

// etc, repeat however many times

We have this linked list with individually allocated nodes.

Each node has no guarantee about its location in memory due to using the default allocator (new).

This could be disastrous for performance as the memory may be scattered around and each time you walk the list, you may have cache misses on every next lookup.

The mistake people make in the Linked List vs Arrays argument is assuming this is the only way to make a linked list.

Let's look at another way to make a linked list, but keep the memory close together.

LinkedListNode {
    LinkedListNode *next
    int data
}

MAX_REQUIRED_NODES = 100

nodes = new [MAX_REQUIRED_NODES]LinkedListNode
nextNode = 0

alloc_node() -> LinkedListNode * {
    node = &nodes[nextNode]
    nextNode += 1
    return node
}

head = alloc_node()
head.data = 32

node1 = alloc_node()
node1.data = 42

linked_list_append(head, node1)

// some time later in the program

node2 = alloc_node()
node2.data = 42

linked_list_append(head, node2)

// etc, repeat however many times

A few extra lines, some thinking about limits, and we have a linked list that will perform nearly as well as an array.

There are a bunch of different ways you could achieve something similar, here are two methods to use without having to define a maximum:

• Use indices instead of next pointers, and a backing array

• Use a growable arena allocator

By thinking about how data is stored and accessed, you unlock hundreds of times faster programs without much, or in some cases zero extra code.

Conclusion

Software runs on hardware. Hardware is the platform. Hardware has physical constraints and considerations. Abstracting away the hardware is not possible.

When writing code that needs to run fast, consider these simple questions:

• Am I treating data as data, or pretending objects have agency?

• Is related data stored close together in memory?

• Are my access patterns using close-together data?

These questions force you to think about the reality of computers. You'll write code that performs better without huge refactoring efforts.

Understanding these basics isn't just for systems programmers or game developers. Every professional programmer has a responsibility to have at least a shallow understanding of these concepts.

Don't be the programmer who drains users' lifeblood one sluggish interaction at a time, when you could easily write code that respects it.

Sound familiar?

Let's outline an example of how this may go down. To make the example simpler, we'll only focus on is_jumping, is_dashing and is_falling, though this problem gets worse the more boolean flags we add.

Player_State :: struct {
  is_running: bool,
  is_jumping: bool,
  is_falling: bool,
  is_dashing: bool,
  is_grounded: bool,

  pos: Vec2,
  vel: Vec2,
}

player_update :: proc(ps: ^Player_State) {
  // Jump
  if input.jump && !ps.is_jumping && ps.is_grounded {
    ps.is_jumping = true
    ps.is_grounded = false
    ps.vel.y = JUMP_VEL
  }

  if input.dash && !ps.is_dashing {
    ps.is_jumping = false
    ps.is_dashing = true
  }

  // Dashing keeps current vertical position
  if ps.is_dashing {
    ps.vel.y = 0
  }

  // Fall (+Y is often 'down' in 2D games)
  if ps.is_falling {
    ps.vel.y += GRAVITY
    ps.vel.y = max(ps.vel.y, TERMINAL_VEL)
  }

  // ...
}

Do you see the bug? Even with this small amount of code, it may be difficult to spot!

The is_falling flag is not set to false when a dash is started. Therefore, if the player starts dashing on the way up their jump, everything seems fine. However, if they start just at the apex, or on the way down, the dash will have gravity applied.

This is a small example, but you can imagine how complex these controllers get in a full game. You may have dozens of booleans.

Another thing to point out is that bugs can occur not just because a boolean is set or unset, but also the order in which they are checked.

Finite State Machines

Enter finite state machines (FSMs). They provide a way to define a finite number of valid states for our character.

Not all the booleans fit into the FSM. For example, we can be dashing but not jumping (these fit, and are hence orthogonal states). However, we may be grounded and running at the same time.

Player_Movement_State :: enum {
  Idle,
  Running,
  Jumping,
  Falling,
  Dashing,
}

Player_State :: struct {
  movement_state: Player_Movement_State,
  is_grounded: bool,

  pos: Vec2,
  vel: Vec2,
}

player_update :: proc(ps: ^Player_State) {
  switch ps.movement_state {
  case Idle:
    if input.left || input.right {
      ps.movement_state = .Running
    }
    if input.jump {
      ps.movement_state = .Jumping
      ps.is_grounded = false
    }
  case Running:
    if input.jump {
      ps.movement_state = .Jumping
      ps.is_grounded = false
    }
  case Jumping:
    ps.vel.y = JUMP_VEL
    // Somehow determine when jump finished (up to implementation)
    if jump_apex_reached {
      ps.movement_state = .Falling
    }
  case Falling:
    ps.vel.y += GRAVITY
    ps.vel.y = max(ps.vel.y, TERMINAL_VEL)
  case Dashing:
    // Somehow determine dash finished (up to implementation)
    if dash_finished {
      if ps.is_grounded {
        ps.movement_state = .Idle
      } else {
        ps.movement_state = .Falling
      }
    }
  }
}

Now you can see exactly what code is running depending on orthogonal states. Some code is duplicated, and wherever necessary, you can easily pull that out:

player_try_jump :: proc(ps: ^Player_State) {
  if input.jump {
    ps.movement_state = .Jumping
    ps.is_grounded = false
  }
}

It's common to want to use state machines everywhere, but I'd caution against that. I would suggest using these in places where it's clear there are orthogonal states and you definitely do not want overlapping behaviours.

In some cases, you may want overlapping behaviours - I'll write about that in a future newsletter.

The trade-off of FSMs is inherent in it's structure: it creates N number of code paths for you to now consider, and perhaps even more.

player_update -> [N]Player_Movement_State -> [M]player_try_xxx.

More Examples

You've already seen the character controller example, let's briefly touch on a couple more.

Enemy AI

Consider an enemy in your game. You may want it to patrol randomly, or following some waypoints. Then, when the player comes into a certain range, you want the enemy to start chasing the player. If the enemy gets within striking distance, it should throw out an attack. If the player gets lost somehow (invisibility, running too fast, etc) - then the enemy may walk back to it's post and continue patrolling.

[Patrolling]
player detected --> [Chasing]

[Chasing]
player within range --> [Attacking]
player lost --> [Searching]

[Searching]
search timer ended --> [Returning]

[Returning]
returning finished --> [Patrolling]

UI Screens

Usually, we don't want multiple menus open at the same time. For example, when the player is loading a saved game, they don't want to look at the settings menu.

[Main Menu]
'continue' selected --> [Load Game Menu]
'settings' selected --> [Settings Menu]

Hierarchical State Machines

State machines can be nested into a hierarchy in multiple ways.

One way is to use the standard enum approach I showed and have a particular set of states, making up their own orthogonal set, that are only accessible via one state.

However, that can be confusing as the amount of states that are unrelated pile up.

Another approach is to simple create a separate state machine.

Imagine an old-school JRPG game.

Primary State: [Exploration, Combat, Menu]

Exploration States: [Walking, Running, Swimming, Climbing]
Combat States: [Attacking, Blocking, Dodging, Casting]
Menu States: [Inventory, Skills, Map, Dialogue]

With this kind of setup, the map cannot be opened during combat, for example.

You can't accidentally start climbing while in the middle of casting.

Event Based State Changes

So far, the only way we've seen to change states is by putting some conditions right into the active code path.

However, you may want to allow events to update states. This decouples state change from the code path and could get messy quickly, but is very powerful.

For example, imagine a scenario where an enemy is chasing the player, so it's in the [Chasing] state. The player is crafty, though, and throws a smoke bomb - obscuring the enemy's vision and making it lose the player.

// Perhaps the smoke bomb has some code like this
entity_ids := gather_entities_nearby(pos, radius)

for entity_id in entity_ids {
  event_emit(entity_id, "vision_obscured")
}

Now the enemy can react to this dynamic event without having it coded in the state machine itself:

event_listen(entity_id, "vision_obscured", proc() {
  entity.state = .Searching
})

This approach allows us to keep the code that handles vision and detection separate from the AI state machine itself. Any system that affects visibility may emit an event and the AI will respond in kind.

Conclusion

State machines keep orthogonal states in design orthogonal in the code.

An escape hatch can be added with something like an event system (for example) - but without caution, this will soon turn into hard to debug spaghetti code once again.

As usual, there’s no silver bullet - just trade-offs.

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.

The Beginning: Canvas2D and JavaScript

When I started making games as a hobby back in 2013, I was only familiar with JavaScript, Perl, Ruby, and PHP. I was a 23 year old web developer who had gone from high school into the industry, skipping university.

Naturally, I used web technology to make games. Enter Canvas2D.

Canvas is pretty easy to use. You create a <canvas> HTML element, use a function to get a context object, and call methods, like: ctx.fillRect(130, 190, 40, 60);

So, I thought I'd make a game like Snake, but with the ambience of something like flOw.

My game featured a "snake" similar to the one above, but much less beautiful. You would grow tail segments when collecting food.

From the sides of the screen, enemies would fly into view - enemies you can't kill.

There were squares, moving in a straight line across the screen (horizontally or vertically). There were circles, which curved towards the snake but not fast enough to be seeking-missiles. There were hexagons, which would move in random directions, then pause and shoot out 6 triangles (one from each side).

Naturally, the game got more difficult as time went on. As such, the screen filled up with shapes to render. The enemies, the food, and the growing "snake" all taking up valuable compute and rendering time.

JavaScript is a garbage collected language. I was having large slow-downs whenever the garbage collector kicked in.

The way to fix this was to implement pool allocators - ways to re-use memory. Such that the garbage collector didn't clean up the objects. I thought the issue was Canvas being slow - but really it was my understanding. Regardless, I decided to ditch it and move to Unity.

Recreating the game in Unity, I ran into the same issues. C# is also a garbage collected language, and maybe the way I programmed just wasn't up to snuff - I programmed in Unity as if it was JavaScript (that was an option back then, not just C#).

I decided to put the game on ice for a while. I made a different game using Canvas2D again about riding a motorbike to the right, and dodging obstacles. I sent this to a local technical college with an email and was accepted into the Diploma of Game Programming course, despite applications being closed (thanks Marek).

I'm going to skip ahead here, as there's not much to say besides that I got experience in Unity and UE3.

I'd recommend Canvas2D if you are already familiar with web programming and want to get your feet wet with a very simple API. It's missing many features, and although some game engines have been built on it, such as ImpactJS (heavily modified for the game CrossCode), I think we have better web options nowadays.

Diving into the Deep End: OpenGL

I finished my course, started and failed to complete a couple of games with an artist friend I met there, but something was still bugging me. I made so many prototypes in Unity, but I was always fighting with the engine. I could never figure out how to get the look or feel I wanted. And, don't get me started on ScriptableObjects... Plus, I had to implement object pooling in Unity as well to get performance under control.

In 2019 I had the thought that I didn't actually know how to program, so I decided to learn C and OpenGL. This was tough.

To learn OpenGL, I used the fantastic https://learnopengl.com resource. I spent a week at the local university library, all day every day, working through it.

By the end, I could draw very simple things in OpenGL, but still had to work through that first second another five times over the next few years to really understand it.

I watched some videos by TheCherno. I was specifically interested in batch rendering. I didn't realise then that this concept is basically the same as a command buffer, and also conceptually similar to a linear allocator.

I was able to render basically any 2D game I could think of at full FPS using just this small amount of OpenGL (one quad batch renderer). The fact I was only interested in pixel art games at this time made a big difference.

A Focus on Productivity: raylib

Some time later, I decided that all this graphics programming was getting in the way of making things. I didn't know about RenderDoc, NVIDIA NSight, or how to add debug logging to OpenGL. Many days were spent looking at a blank screen or totally incomprehensible shapes and colours flashing across the window.

I chose raylib because it seemed simple and vaguely familiar due to the way rendering works. You first call BeginDrawing then write various draw calls DrawRectangle.. and then EndDrawing. It's essentially immediate-mode graphics - similar to Canvas2D, and similar to batch rendering quads.

I worked on various small projects in raylib and enjoyed the experience immensely. It got out of the way and allowed me to develop gameplay systems rather than spending all my time debugging the renderer.

Eventually, though, I ran into a few issues:

1. raylib is built with OpenGL 3.3 by default, I wanted to use compute shaders, which means I had to rebuild the program in 4.3 mode

2. raylib doesn't include fences - which are a CPU<->GPU synchronisation mechanism. These are pretty required to know when compute shaders have finished task

These were minor issues as by this point I was very familiar with build systems and modifying existing projects. raylib's source code is very straightforward, so I added the wrapped functions and recompiled from source.

raylib has a fantastic set of samples which you can view on the website. It supports both 2D and 3D, and is more of a framework for interactive applications due to it's other features: audio, input, image loading, and more.

raylib has been used to make commercial games, such as Cat & Onion by Karl Zylinski, though the creator of raylib, Ray, does caution against using it for commercial endeavours.

The Middle Road: Sokol and SDL3

I tried Sokol at some point between OpenGL and raylib. It confused me as there was no concept of a "render pass" or "pipeline" in OpenGL. Of course there is the graphics pipeline - but in OpenGL it's fixed. My experience was: vertex stage -> fragment stage -> done or compute stage -> done. Pretty simple.

I didn't use Sokol recently because it didn't have compute shader support. However, as of writing this, it seems it will be added soon.

Looking at Sokol now, it's very easy to understand - but that's because I've already moved onto Vulkan and therefore must have an idea about these concepts. Unfortunately, the jump from OpenGL to Vulkan is large.

What helped me was actually the recently released SDL3's GPU API. Plus a particular page of their documentation. This page walks through step by step what one may do to setup a rendering pipeline using the API. This was the missing link I needed to make the jump to Vulkan.

I think the SDL3 GPU API would be sufficient for most games. The only reason I'm not using it is because I believe Vulkan will be the API I use for the next 20+ years, so I decided to invest in it.

The Present: Vulkan

I am whittling away at the final boss of graphics APIs - Vulkan. It's been a huge learning experience - but the SDL3 GPU API helped reduce confusion.

Besides future investment, I'm interested in creating custom worlds and custom rendering techniques that may be difficult or impossible with APIs besides OpenGL, DirectX or Vulkan.

The control of every aspect of rendering is something I believe will be invaluable.

If you are interested in seeing my progress, I actually implemented this chain of things on-stream recently:

• C99 + DX11 Software Renderer

• C99 + DX11 Hardware Renderer

• Odin + OpenGL Compute Shader Marching Cubes Terrain Generation

• Odin + SDL3 GPU API rasterised renderer, model loading, 3D lighting

• Odin + Vulkan rasterised renderer (on par with SDL3 one)

• Odin + Vulkan raymarching + rasterised renderer

As you can see, I was working with DX11 - similar in difficulty to OpenGL.

I switched to Odin + OpenGL to have more parity with my course material. I teach game programming using Odin + raylib at https://programvideogames.com.

The reason we use raylib is similar to what I stated above - we are focusing on gameplay and systems programming, not graphics programming.

I stayed with Odin, and eventually progressed to Vulkan - where I'm focusing my energy now.

If you are struggling with graphics programming - you are not alone. Nearly everyone I know who has started in the field has struggled. Especially if, like me, their mathematics knowledge unused since high school.

Conclusion

If you are just getting started in graphics programming and are more interested in the end-result (I.E. making a game), then I'd recommend raylib.

For something more advanced, I think SDL3 GPU API or Sokol are the best choices.

The final boss, Vulkan, is not to be undertaken lightly. I did 5 1000+ line hello-triangles before grasping what was going on.

I haven't mentioned wgpu or Metal - I don't have direct experience with them. I have heard good things about wgpu and I know notch is using it for his new game "Levers and Chests". I have read that wgpu is similar to Vulkan, but easier.

So, my order of learning would look like this:

• Canvas2D/P5.js

• raylib

• OpenGL/DX11

• Sokol/SDL3 GPU/webgpu

• Vulkan/DX12

Obviously, you can skip straight to any API you want - this is just what I think makes sense in order of difficulty to learn and building on previous steps.

I’ll assume you have done your research and decided against it.

So then, what is an Entity System and how do we build one?

Keeping things simple, we’ll put data required for all entities onto an Entity type.

This is often referred to as a “mega-struct”.

Entity :: struct {
	pos, vel:                   Vec2,
	collider_size:              Vec2,
	sprite_size, sprite_offset: Vec2,
	health, max_health:         int,
	flags:                      bit_set[Entity_Flags],
}

We can store a bunch of boolean values inside a bit_set.

Entity_Flags :: enum {
	Is_Dead,
	Is_Flipped,
	// etc...
}

We’ll store our entities in a simple dynamic array.

entities: [dynamic]Entity

Then, if you language allows it, I recommend creating a distinct type for your entity IDs.

Entity_Id :: distinct int

Why a distinct type?

Imagine we use a simple int.

Then imagine we also create another system that uses int as IDs.

other_system_id := other_system_create()
entity := entity_get(other_system_id)

Obviously that is contrived, but you can get into situations where you pass the wrong ID in because they are all int.

With distinct types, you’ll get a type error at compile time if you pass anything other than Entity_Id in.

Let’s build out the entity system procs:

entity_get :: proc(id: Entity_Id) -> ^Entity {
	if int(id) < len(entities) {
		return &entities[int(id)]
	}
	return nil
}

entity_create :: proc(entity: Entity) -> Entity_Id {
	for &e, i in entities {
		if .Is_Dead in e.flags {
			e = entity
			e.flags -= {.Is_Dead}
			return Entity_Id(i)
		}
	}

	index := len(entities)
	append(&entities, entity)

	return Entity_Id(index)
}

entity_kill :: proc(id: Entity_Id) -> bool {
	if int(id) < len(entities) {
		entities[int(id)].flags += {.Is_Dead}
		return true
	}
	return false
}

You should not keep Entity pointers across calls of entity_create. If the array is full and a reallocation is required, pointers will be invalidated.

These are almost the simplest versions I have used across various projects.

There may be a problem, though, depending on your game’s design.

For example:

• Given two Entities A and B

• B is following A

• A gets killed

• C gets created in A’s slot

• B will now incorrectly follow C

To counter this issue, we can introduce the concept of a “generation” to the entities.

Entity :: struct {
	generation: int,
	// other fields remain unchanged
}

Now when you assign an Entity to follow another, you also include the generation.

Something like this, (just one way of many)

Follow :: struct {
	id: Entity_Id,
	generation: int,
}

following: map[Entity_Id]Follow

Then in your update code, you’d make sure the generation matches:

if follow, ok := following[id]; ok {
	other := entity_get(other_id)
	if other.generation == follow.generation {
		// follow code goes here
	} else {
		delete_key(id)
	}
}

The generation is set when an entity slot is reused:

entity_create :: proc(entity: Entity) -> Entity_Id {
	for &e, i in entities {
		if .Is_Dead in e.flags {
			gen := e.generation + 1 // Save generation before overwriting
			e = entity
			e.flags -= {.Is_Dead}
			e.generation = gen // Set to new generation
			return Entity_Id(i)
		}
	}

	index := len(entities)
	append(&entities, entity)

	return Entity_Id(index)
}

Here’s the rest of a very simple program I wrote that uses the first style:

entity_update :: proc(dt: f32) {
	for &e in entities {
		if .Is_Dead in e.flags do continue

		e.pos += e.vel * dt
	}
}

main :: proc() {
	id := entity_create({pos = 100, vel = 200})

	dt :: 1.0 / 60.0

	for i in 0 ..< 4 {
		entity_update(dt)
		fmt.println(entity_get(id).pos)
	}
}

It prints out:

[103.333336, 103.333336]
[106.66667, 106.66667]
[110.000008, 110.000008]
[113.33334, 113.33334]

Alright, that’s it!

Those are my two simple entity systems to get you going without having to create complex ECS queries.

If you enjoyed this post, please consider joining the mailing list. Thank you for reading!

Subscribe now

• Deepen your understanding of programming concepts.

• Help write more efficient code.

I share a bit of my story and the insights I have gleaned from taking this path.

Reading time is about 6 minutes.

First, a little story

I was in my mid twenties. I didn't have a proper Computer Science education. I hadn't even finished high school.

Spending half a decade in the web industry taught me surprisingly little about programming.

I was a "glue-coder". I received praise and more money for being a good glue-coder. I wasn't satisfied.

For you, the paycheque may be enough to stay a glue-coder. For me, it wasn't about the money.

So, I quit my web dev job and went to get a Diploma of Video Game Programming.

Unfortunately, we only learnt how to use Unreal Engine 3 Visual Scripting.

I went to University to learn Computer Science. In year 1, we only learnt about ethics of IT and some basic Linux stuff I already knew by that point.

I dropped out. I went back into the web industry and continued gluing.

I decided to teach myself C to gain more understanding of what was going on. That was five years ago.

Now I can see how little I knew and how little I needed to know. I could build front-end web applications that were "good enough".

If any of that resonates with you, I wrote this for you.

I hope this helps get you up that first hill.

Manual memory management

Have you ever tried to write some high-performance code in JavaScript?

A little game or animation using Canvas?

You may have noticed that performance sucks.

If you go deep enough, you may find yourself implementing an Object Pool.

An Object Pool is a strategy to prevent the Garbage Collector from deleting your objects.

This way, there won't be those sawtooth spike patterns in your memory usage that cause lag.

Let's say you are making a simple video game with a space ship flying through space.

Enemies appear from the top of the screen. You have a ship flying "up". I'm sure you've seen games like this.

When ships and missiles explode, they create particles. These particles vary in colour, size, lifetime, and velocity.

You find that when many enemies explode all at once the game lags.

You profile the game. The particles spawning and the Garbage Collector cleaning them up is causing lag.

"What if they didn't get cleaned up and instead we reuse them?"

The answer to that question is an Object Pool.

One field of a particle could be `isActive` or you could keep a separate free-list.

Regardless of the details, you have now implemented a memory allocator.

Perhaps memory management is not as scary as many would have you believe.

Pointers

You already use them in JavaScript. Sort of.

When you pass an Object or an Array to a function in JavaScript, you don't get a copy, you get a reference.

There is a difference between references and pointers.

In JavaScript, you can't pass an array to a function then read outside the memory of that array.

You can extend the array, even using negative indices, but let's not go there.

C doesn't have such bounds checking. That means by writing off the end of an array, you corrupt other memory. You can even corrupt the call-stack, causing all kinds of unpredictable behaviour.

In practice, there are tools to prevent these bugs, but it's important to know.

In either case, mutating the reference will mutate the value passed in at the call-site.

Types and Structs

I suspect this is less of a problem nowadays. A lot of JavaScript developers use TypeScript.

Regardless, I'll cover what I would have liked to have known about C's types when getting into it.

Types are a way to tell the compiler the size of the data you are using. This doesn't come up in JavaScript, but it's very important in C and how to think about memory.

When you define a `struct` in C, it's easy to start thinking in weird abstract ways again.

Think about it like this:

A struct is a way to bundle values together and refer to them as one "thing".

They are not objects, though you may hear C programmers refer to them as objects. It's not the same - there are no methods and modification is not possible.

I'll refer to a struct value as an "instance".

An instance of a struct is a block of memory with enough bytes to store the fields in order. They may sometimes have padding between fields or at the end, but I'll skip over that.

In C, the size of types vary depending on platform. For most things we use 64-bit architecture and have been for over a decade.

That means `int` and `float` are 4 bytes and `char` is a single byte.

As I said earlier, types are kind of telling the compiler the size of things.

If you cast an `int` pointer to a `char` pointer then read the value, you will get only a single byte.

If the number happens to be less than 128, you'll see no problem. If it's higher, you may get a negative number instead as a single `char` represents -127 to 127.

A working example

Here's a working program that shows what I'm talking about, with extensive comments.

It includes a new concept called "casting". This allows you to refer to one pointer type as another type. It's very important to know this.

Why is it useful to think of them as block of memory with byte offsets?

It keeps you thinking of the program in a practical way.

For example, let's say you have a library that needs the float values but nothing else.

The library can't understand your type, but it can understand byte offsets.

Libraries will often have built in the concept of "stride". That is, how many bytes are between each value it wants to operate on.

If you pass in an array of `float` to the function, you can use a stride of 0.

Pass in an array of struct instances and then you'll need to tell the library the size of your type.

The lack of runtime type information is why thinking in sizes and offsets is important.

Arrays are fixed size

In C, arrays are always a fixed length.

This may sound limiting, but in practice it's usual to know the required capacity of your data.

I would recommend, if you need dynamic arrays, to use one of the thousands of libraries that exist. Or, learn how to create your own.

Iterators

There are no iterators or syntactic sugar for looping over stuff.

Since there are no methods, there's nothing like `my_array.forEach`.

You will have to get used to writing plain loops.

Strings

Strings are Arrays of `char` in C with a null-value to denote the end `\0`.

Personally, I don't like the way they work by default, so I use my own implementation.

I wrote it to be compatible with normal null-terminated strings for library interfaces.

As with Dynamic Arrays, I recommend using a library or learning how to create your own.

Of course, you'll have to learn how to do Unicode to have proper language support. It is quite fun from what I've read - I haven't added it myself.

The biggest change is mindset

We can go over the language differences all day, but it won't matter much if you keep the JavaScript mindset.

I'm speaking from experience here. My mindset had to change to get better at C and programming in general.

I've never spoken to anyone about this before, but I used to think of programs in very fuzzy ways.

In my mind's eye I'd visualise graphs of objects all talking to each other.

I'd obsess about code cleanliness.

I'd comment every line with useless comments.

I went down the OOP SOLID rabbit hole and tried very hard to follow those rules.

None of that stuff made programming easier.

What actually helped was a talk by Mike Acton that I'm sure many people in this sphere are familiar with.

"Programs are for data transformation"

You have X. You want Y. The program (or subset) is how you convert X to Y.

All that's in a program: plain old data and instructions that operate on that data.

Adding layers of complexity should not be the norm. Yet it is - especially in JavaScript land.

You are better off only adding complexity after careful consideration of the trade-offs.

How this mindset change helps

These are examples of web based work I've done recently that benefited from a new mindset.

A recent SaaS project

Over the past little while I've been working on a web app.

In the past, I would have looked up what the hot JavaScript framework of the month is and used that.

I would have found some bleeding edge stuff to add to it that breaks the bundler... and spent days fixing build issues.

What did I do differently? I thought about what I actually need to get done and what the most practical approach was.

I made a back-end in Golang. I made a front-end in HTML, CSS, JS with htmx.

I added a websocket connection to send htmx events from the server to the client for dynamic updates.

There's more stuff around auth and whatever else that you'd have to do regardless, but the point is:

I was able to focus on the data transformations required to give the user the experience I wanted.

I chose the stack based on efficiency and requirements, not because it's flavour of the month.

I didn't have to think about React hooks or component lifetimes.

I didn't have to mess with webpack or vite - my build system is a few lines in a bash file.

A recent web client

I had a website client a few months ago who wanted a very simple site.

She needed a home page with some static information, a photo, and a booking form.

She wanted to be able to update some of the booking form content:

• Available days

• Text and images of a few sections

• Turn on or off a few fields

And she refused to pay a monthly fee to somewhere like Jotform.

How would you have created this? Wordpress? A service like Wix or Squarespace?

Once again, I used Go and htmx with HTML, CSS, JS.

It took only a few lines of code to add this functionality.

The site is fast, has good SEO, and it's easy for the client to update it.

Conclusion

Learning how to think about programming in a different manner has been invaluable.

I can now consider and create programs that would have become tangled spaghetti code if my past self tried.

I'm sure a lot of that I owe to general experience.

OOP did not help with this problem.

Notes

• C isn't simple. I'm sure I've said it is simple in the past, but I was wrong. Unfortunately there is a lot of unexpected and unintuitive behaviour.

• In case you thought I was insulting you for being a "glue-coder". I wasn't.

Tools already exist to catch memory errors.

There are multiple sanitisers available in Clang, GCC, and MSVC: Address, Memory, Thread, Undefined Behavior.

Today I’m going to show you how and why you want to use the Address Sanitiser (ASan).

By utilising this tool you will:

• Prevent difficult to find bugs.

• Create more robust software.

Unfortunately, it seems that most programmers are not aware of these tools. I didn’t know about them for the first 4 years of programming in C.

Ignoring ASan is like driving blindfolded: reckless and bound to crash.

Using ASan while developing will reduce the likelihood of a whole host of bugs.

• Catch out of bounds access on heap, stack and globals.

• Never have a use-after-free or double-free again.

• Detect leaked memory.

If you have been bitten by these problems in the past, read on.

Catch Out-of-bounds errors

Consider the following C program:

#include <stdio.h>

int main(void) {
  int arr[10];
  for (int i = 0; i <= 10; i += 1) {
    arr[i] = i;
  }
  printf("Done!\\n");
  return 0;
}

The mistake is obvious due to the tiny surface area of the program.

Loop limits are often calculated based on some dynamic data that makes this error harder to catch.

This program will compile and seemingly execute with no issues.

> cl /Zi oob.c
> oob
Done!

When running it from the command line that “Done!” is printed, so all good, right?

If you compiled and ran this program, you would have noticed that it takes a second or two to exit.

Running it in a debugger shows an error when the program exits.

Let’s see what compiling with ASan turned on tells us when we run it.

> cl /Zi /fsanitize=address oob.c
> oob

A simple explanation of how ASan works

Okay, that’s a pretty crazy looking message. Let’s go over what ASan is.

This is in no way a comprehensive explanation.

Usually when your program allocates memory on the stack or the heap, it’s reasonably close together.

ASan spreads out allocations and adds a bunch of “poison bytes” surrounding them.

When one of these poison bytes is written to or read from, ASan reports that as an error.

The “shadow bytes” seen above is like a minimap of the poisoned bytes.

It’s how ASan knows which memory is poisoned and what kind of poison is there.

Never have a use-after-free or double-free again

Consider this simple C program:

#include <stdlib.h>
#include <stdio.h>

int main(void) {
    int *nums = malloc(32);
    free(nums);
    printf("%d\\n", nums[0]);
    return 0;
}

When I compile and run this, I get 0.

> cl /Zi uaf.c
> uaf
0

There’s no guarantee that it will print the correct value, and perhaps the page that was allocated is no longer readable, crashing the program.

Compiled with ASan and I get a helpful error.

The first line: heap-use-after free … followed by a location uaf.c:7

You can dangle pointers all day long. Not that I advise that kind of rash memory allocation.

Detect memory leaks

For some reason this is not working on my Windows whether I compile with Clang or CL.

It’s disappointing, but I don’t get memory leaks in my own code anyway due to using custom memory allocators.

So, for this example I’ll be firing up the old WSL2 Ubuntu and using Clang.

Our program with a simple memory leak:

#include <stdlib.h>

int main(void) {
    char *buf = malloc(512);
    return 0;
}

Compiling and running the program:

$ clang -g -fsanitize=address leak.c -o leak
$ ./leak

ASan successfully caught this memory leak.

Tthis kind of memory leak can be a false positive as there’s no need to free memory when closing the program normally.

Perhaps using some kind of macro to turn on clean-up code when running ASan is called for.

Takeaways

• ASan is simple to use. Just add the parameter to your compile command.

• It will detect a whole host of memory errors so you can ship robust programs.

• On my Windows machine it’s iffy with leaked memory. Test on Linux with Clang if cross-compilation is easy.

  Want more tactical programming content in your inbox each week? Subscribe for free.

Thanks for reading!

See you next week,
— Dylan

I’ve been showing you you a lot of the how, but nothing about why you should care.

How-tos are pointless without a why.

This week I'm going to share a bit about my journey in the hopes that you find something useful.

Early Programming

My first encounter with “programming” was selecting “view source”. I was looking at people’s GeoCities websites and trying to figure out how it all worked.

I’d save .html files to my machine, then change the code and see what happened.

I even came up with a genius idea of renaming all the tags to custom ones that “made more sense”.

My first “real” programming was making Final Fantasy fan sites with PHP. PHP allowed me to keep the header and footer consistent by using PHP Includes.

I started with JavaScript, Ruby and Perl at my first job (front-end web developer).

My initial thoughts were amazement, like I was learning some hidden knowledge.

The Journey

I went deep into (OOP) Object Oriented Programming. I used all the things like Dependency Injection, Encapsulation, Polymorphism by Inheritance. I even implemented Classes with Inheritance in JavaScript before ES6.

I was a big JavaScript fan.

Everything I made was a rats nest.

I learnt about Object Pools because the Garbage Collector was too slow. This was my first hint that something was wrong.

I found myself wondering… “Why am I fighting with the language feature that’s meant to help me?”

Deciding to learn C in 2020 was a big change. That’s when I actually started learning how to program.

Passion

There's nothing quite like this feeling... I'd bash my head against the wall for hours or days. And then when doing something unrelated... Eureka!

Sometimes it happens in sleep, sometimes on a walk, sometimes in the shower.

Anywhere it happens, I rush back to my home or pull out my laptop and start implementing.

Many people think that programming is not creative. I am not sure where they get this idea - but it’s completely false.

The truth is that much of the time I’m engaged in what you’d call “exploratory” programming.

I need to write some stuff to see whether it all fits together and solves what needs solving.

If not, I’ll scrap it or change it and start in another direction.

Being able to program has allowed me to do things that other people need to use a service for.

I can do specific things that are difficult otherwise.

For example, I once scraped the Steam top 200 for 12 months to see if I could identify any trends.

I never ended up using the data, but can you imagine doing that without programming? It would take hours each day as the data captured included things like discounts, tags, all sorts of stuff.

Nowadays we have AI that can create scripts. It's pretty useful, and getting better, but still wrong a lot of the time.

Plus, in the Steam example, I needed to figure out which CSS targets are the right ones for the data.

Lessons Learned Along the Way

People will go to great lengths to justify their beliefs.

In programming culture, this translates to dogmatic views about "unsafe" programming language features.

Some programmers demand that everyone adhere to their "safe" language.

Some demand that everyone must use their madness inducing paradigm.

I'm speaking of Rust and OOP/SOLID.

A little side-note:

I've been studying marketing recently. It seems that people don't make rational choices at all. At least not to do with buying products. It would not surprise me if all choices are irrational and justified to the self afterwards.

Back to programming.

Insurmountable seeming problems are best tackled by first breaking them down. Once problems are small enough to fit in one's head, progress by application of effort will be swift.

I try to apply this lesson learnt from programming to everything in my life.

The Bigger Picture

Programming will be important so long as we use digital technology.

I'm not convinced that advancements in LLMs will make programming obsolete.

Compilers didn't. No-code builders didn't. Visual scripting didn't.

For programming to become obsolete, we’d have to have a superior replacement. What most people are focusing on is "low skill" programming jobs.

Jobs like front-end web development should be on the decline already. So far, people have managed to secure job security through obfuscation and complication.

The web job collapse will come - if it hasn't already started. Look at the layoffs in 2023/2024.

That does not mean programming as a skill will go away any time soon. It means it won’t be so easy to get those $100K 2-year-experience front-end web jobs.

Why It Matters

Programming is my favourite creative outlet.

There is nothing quite like it. Think of some idea, load up my editor, write code until it compiles, observe the result of creation.

Artisanal programming is more important than ever.

Why? The industry is bursting with people using ChatGPT to write their code. They do not understand how to fix the AI's nor their mistakes.

Customers don’t care about how hard we work or what languages we use. But, they do care about their experience.

If the customer has a worse experience because we use AI and don't know how to fix stuff, that's bad for business.

Microsoft recently bragged about reducing their Teams startup time to “only” 9 seconds. Can you believe that?

The largest corporation in the world thinks that is something to be proud of. The bar is on the floor.

If you are on the fence about programming because you think it may be too difficult, consider what I just wrote... The level of incompetence to make a chat application start in 9 seconds is astounding.

If you are already a programmer - what are your reasons for caring? Do you care?

Conclusion

In summary, I care about programming for these reasons:

• It gives me a creative outlet (yes, it’s creative)

• It allows me to create cool and/or useful things that other people can’t

• It helped me to problem solve in other domains

• It’s fun (recreational programming is a thing!)

Thank you for your time and engagement.

If you got this far, please share this with someone that will enjoy it.

Share your own reasons for enjoying (or hating) programming in the comment section.

Until next week,
Dylan

Subscribe now

This week’s newsletter is about being able to recompile and reload code to see the changes in real-time - without restarting the application.

The way I learnt to develop software was using the compile-link-execute cycle. Depending on your setup, this may be more or less ergonomic.

In my setup, I used to:

1. Edit and save the file.

2. Press Alt-M to run my build (compile & link) script.

3. Win-2 to switch to my debugger, press F10 to start stepping through my program or F5 to just run it.

4. Do whatever in the program, set break points, analyse variables, etc.

5. Close the program.

6. Make changes to the code.

7. Start the process again.

It’s pretty inefficient.

Now, I do this:

1. Edit and save the file.

2. Press Alt-M to run my build script.

3. Alt-Tab back to the program, that was still running, and has all the state from before I made changes.

4. That’s it - the code has been updated in the background!

My Journey to Discovering Hot Reloading

I knew about “hot module reloading” from my career as a front end web developer. It was amazing to have instant changes in real-time after updating some code.

What I didn’t know, is that this functionality has been available since the 1980s for compiled programs!

On Windows, we can load .dll (Dynamic Link Library) files. On Linux they are called .so (Shared Object) files.

These files can be loaded at run-time of a program and contain code and data, like an executable.

Join me on this adventure to figure out how to get hot reloading working in a simple Win32 C program. If you don’t use Windows, don’t fret - the code is simple and the structure will apply to Linux/MacOS just as well.

Understanding Hot Reloading: Application Code and Cradle

Hot reloading is a concept used in software development that allows programmers to immediately see changes made in the code without closing and re-opening the running program.

This is exactly the functionality we need to reduce the time between idea and execution.

How this can be done for our purposes is we split the code into two sections - the application code and the cradle.

Our application code is the dynamically linked code. The code we are updating. In the case of games - it’s our gameplay and perhaps a lot of the engine code, too.

Our cradle is the compiled executable that loads the application code and provides it with memory. It is important that the memory we use comes from the cradle as when the DLL is reloaded, the DLL’s memory is refreshed.

Implementing Hot Reloading: A Step-by-Step Guide

Now that we know what we are doing, let’s look at how to actually do it.

On Windows, there is a function called LoadLibrary, on Unix-like systems the equivalent is dlopen .

Let’s write a simple win32 layer that achieves the goal of hot reloading.

main.c

Our cradle will be a simple program that loops every second, reloading the DLL regardless of whether it has been changed or not.

In my experience, reloading every second is good enough for a long time during development.

#include <windows.h>
#include <stdio.h>
#include <string.h>

#define MEMORY_SIZE 256

typedef void (*HotReloadedFunction)(char *memory, size_t *size);

int main(void) {
    HINSTANCE dll = 0;
    HotReloadedFunction fn;
    char memory[MEMORY_SIZE] = {0};

    while (1) {
        if (dll) {
            FreeLibrary(dll);
        }

        CopyFile("application.dll", "_application.dll", 0);
        dll = LoadLibrary("_application.dll");
        if (!dll) {
            printf("Failed to load DLL.\\n");
            return 1;
        }

        fn = (HotReloadedFunction)GetProcAddress(dll, "hot_reloaded_function");
        if (!fn) {
            printf("Failed to find function in DLL.\\n");
            return 1;
        }

        fn(memory, MEMORY_SIZE);

        Sleep(1000);
    }

    return 0;
}

We are copying our application.dll file to a new _application.dll file so that the file isn’t in use when we try to compile a new one.

We provide some memory to our function - this would be where you’d store all your game state in a game, or all your application state in some other application.

We then load the copied DLL file and use GetProcAddress. GetProcAddress gets the procedure (function) address of a function. This function will de defined in the application code.

Then we call the function, passing in the memory and memory size.

Finally, we just sleep for a second. In a game this could be waiting until you hit 16.67 ms (for 60 FPS).

In most real-time cases, you probably want to use either a timer or watch the file for changes to reload the DLL.

application.c

Our application is dynamically loaded at run-time.

We must be careful about what kind of data we store in it.

In this case whatever_string is a static string that will be stored in the DLL and not changed.

However, counter is incremented in the hot_reloaded_function . Let’s see what happens.

#include <windows.h>
#include <string.h>
#include <stdio.h>

char *whatever_string = "This can change at run time, even though the memory address doesn't!";
int counter = 0;

__declspec(dllexport) void hot_reloaded_function(char *memory, size_t size) {
    printf("memory size: %zu, address: %p\\n", size, memory);
    sprintf(memory, "%s", whatever_string);
    printf("%s\\n", memory);
    printf("counter: %d\\n", counter);
    counter += 1;
}

BOOL WINAPI DllMain(HMODULE inst, DWORD reason, LPVOID reserved) {
    (void)inst; (void)reason; (void)reserved;
    return 1;
}

build.bat

@echo off
cl /c /Zi /nologo application.c /Foapplication.obj
link /nologo /DLL /DEBUG /OUT:application.dll application.obj

build_exe.bat

@echo off
cl /Zi /nologo main.c

output

We’ll assume we managed to change the contents of whatever_string between runs to “For example, here!”.

memory size: 256, address: 00000097917DFC00
This can change at run time, even though the memory address doesn't!
counter: 0
memory size: 256, address: 00000097917DFC00
For example, here!
counter: 0

• Memory address is unchanged - that’s good!

• String is updated successfully - that’s good!

• Counter is not incrementing! Why? …

The answer is what I was alluding to earlier.

Each time the DLL is recompiled and reloaded, the memory of any variables inside the DLL are reset.

That’s why passing in memory that you want to persist from the cradle is so important.

Pass in memory you need to for your entire application from the cradle, then it will keep state across DLL reloads.

The Impact of Hot Reloading on Your Programming Efficiency

Using hot reloading allows the programmer to reduce the time between idea and execution.

You can press jump in your game, see how it feels, then change some values in the program, compile - press jump again.

It removes the (sometimes very lengthy) process of opening the program and getting back to the state you were in before.

Imagine you are testing some boss battle and you have to run back to the boss between each tweak of it’s attributes.

If closing your game, compiling, running, and getting back to the same state takes let’s say 3.6 seconds…

And, you may want to tweak things hundreds or thousands of times in one day...

360 / 60 = 6 minutes
* 10 for 1000 is 1 hour

That’s a saving of between 6 minutes and one hour per day.

What could you do with an extra 260 hours per year? Probably, a lot of neat stuff.

Hot Loading in the Future?

Once I saw how easy it was to implement, I wondered why we don’t all use hot reloading all the time.

In the future, I think we may see this built in to languages and IDEs.

However, given it’s been essentially this easy for going on 40 years now... I can’t be certain of that.

I can be certain that I’ll be using it for the rest of my career, and I hope to have helped you decide to give it a try.

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.

Memory management is typically taught in ways that cause many issues. Let’s go over the 4 most common issues: Fragmentation, Allocation Speed, Lack of Control, and Lifetimes.

Fragmentation

Using malloc and free for individual objects inevitably cause fragmentation of the heap.

The locality of similar objects is not guaranteed when different types are allocated in an unpredictable order.

The general purpose memory allocator provided by the language (the thing behind the malloc call) does it’s best to make sure there are not too many gaps. But, it doesn’t know anything about the usage and lifetimes of your objects.

As a result, you can easily end up with bad performance by jumping around in the heap.

Performance

There’s a common idea that memory allocation on a per-frame basis is a quick way to slow down your application. I focus on games and real-time applications, so I’ll use “frames”, but you could replace this with any high frequency loop.

The idea is that malloc and free are either too slow or too unpredictable to be able to be used in high-frequency code paths.

The common remedy is to malloc and free before and after these code paths are executed. To ensure the program does not crash, one of two things must occur. Either a fine-tuning of the memory footprint, or an over-allocation at the outset.

If the data changes, and the code paths are not updated to fit the new data, crashes may occur.

Lack of Control

malloc does not allow you to control the memory allocation strategy. You don’t know where you are getting memory from or how it’s doing it. It’s a black box. Need memory? Call malloc . That’s it.

Lifetimes

The cognitive overhead of trying to manage object lifetimes in the programmer’s head is a cause of many bugs. When the common wisdom is to dynamically allocate each instance of an object and release the memory individually, there is a large surface area for mistakes.

For example, when individually allocating a bunch of nodes for a tree, performing some data transformations, then walking the tree again to release each node. It could easily be the case that some of the nodes have been detached during the transformation and are no longer accessible.

You can get around this issue by pre-allocating an array of nodes and grabbing from the pool of them - then releasing the node array all together. This is a custom memory allocator - called a Pool Allocator.

Today, however, we’ll be talking about a more versatile allocator - the Arena.

The Arena

The Arena Allocator is quite simple, and extremely useful. Since using Arenas, I have rarely needed to think about memory management at all. I have written about them before, but I wasn’t satisfied with that article’s definition as it misses some important implementation details.

Arenas work by allocating a large buffer of memory up-front and then handing out pieces of the buffer. The amount of used memory is usually tracked with an offset number.

For example, the Arena is 4096 bytes (in reality they are usually much larger) and the program allocates 2 1024 byte chunks - now the offset will be 2048. The calculated available space is the offset - size. Actually, it’s a bit more complicated due to memory alignment, but for the sake of explaining the concept, this will do. We get into the nitty gritty later on.

Performance and Lifetimes

Let’s say we are working on a game. We know there’s a bunch of allocations that need to happen at startup. Things like copying files into buffers (shaders, images) to upload them to the GPU and then throw them away.

In the main loop, there may be things that need to be allocated each frame and then thrown away, too - debug strings, collision data, the possibilities are endless.

Rather than creating set pools for all of these things, or trying to guess how many we need and using arrays, we can create a single Transient Arena Allocator.

// Start up code:
String my_shader_code = io_read_entire_file("my_shader.glsl", &transient_allocator);
// Link the shader
// We don't care about it after this, so do nothing

// Main loop:
{
    // Some entity loop or something:
    {
        Hit hit = physics_hit(e, target, &transient_allocator);
        if (hit.did_hit) {
            // do something with hit
        }
    }

    // Reset the Arena each frame
    arena_free_all(transient_allocator.context);
}

With this transient allocator, we have chosen to clear it at the end of each frame.

The cost of freeing the memory? Two assignment operations:

arena_free_all(Arena *a) {
    a->offset = 0;
    a->committed = 0;
}

What about the cost of allocating all this memory on each frame?

It’s a little more expensive, but not by much. Certainly much less expensive than malloc . It’s basically a couple of add and compare instructions - see more in the implementation below.

The simplicity of these allocation and deallocation calls means that we don’t have to fear allocating and freeing memory during frames.

It’s so cheap that we can do it whenever we want.

Fragmentation and Lack of Control

Another side-effect of using an Arena is eliminating or greatly reducing fragmentation.

If we know that we need to both dynamically allocate and use together a few different types of objects - we can put them into a separate Arena.

Say we have a bunch of Hits and a bunch of Particles, but we are unsure how many we need (if any) per frame, but we are sure that we’ll use data from the Hit for each Particle.

We could create another Arena Allocator called hit_allocator that just stores Hits and Particles. Granted, this is probably not necessary and the transient_allocator would more than suffice, but for the sake of example - we’ll say we have so many Hits and Particles that we really want them to be memory local.

// Main loop:
{
    // Some entity loop or something:
    {
        Hit *hit = physics_hit(e, target, &hit_allocator);
        if (hit->did_hit) {
	    // do something with hit
            Particle *p = particle_spawn(hit.position, &hit_allocator);
        }
    }

    // Reset the Arenas each frame
    arena_free_all(transient_allocator.context);
    arena_free_all(hit_allocator.context);
}

Something you have probably noticed is that we are now thinking about collections of objects and their lifetimes, rather than individual objects. This is a big mental switch and extremely powerful if you are used to malloc and free -ing objects one at a time.

Since all our Hits and Particles are in the same Arena, we know they are probably somewhere pretty close in memory. It’s not 100% optimal, but we don’t need a 100% optimal solution to get a 300x speed-up. We just need our data to be in the L1, L2, or L3 caches and avoid going back to main memory.

Using different Arenas for objects that have the same lifetime reduces cognitive overhead, freeing up your mind for the multitude of other problems that need solving when developing complex software.

Who Actually Uses Arenas?

The concept of Arenas is so useful that it’s a built-in feature in new programming languages like Odin and Jai.

I first heard about them during a stream in which Casey Muratori and Jonathan Blow were speaking about game architecture. Jonathan said, in an off-handed way, “just put them in an Arena and you’re done”. The conversation moved on, but I was now very curious. What is this “Arena” that they are speaking of as if every programmer just knows what it is?

Soon, I found a great resource by the creator of the Odin language and started messing around with my own implementations.

After a short time, I was hooked. My programs (which were all game prototypes) were much easier to reason about - I haven’t seen the word “segfault” show up in my terminal since.

Implementation

I like to wrap my Arenas in an Allocator interface so that all my functions that require memory allocation can take any type of Allocator.

typedef struct {
    void *(*alloc)(size_t size, void *context);
    void (*free)(size_t size, void *ptr, void *context);
    void *context;
} Allocator;

For convenience, I like to define a couple of macros:

#define make(T, n, a) ((T *)((a).alloc(sizeof(T) * n, (a).context)))
#define release(s, p, a) ((a).free(s, p, (a).context))

The Arena code is fully outlined below:

#define DEFAULT_ALIGNMENT (2 * sizeof(void *))

typedef struct {
    void *base;
    size_t size;
    size_t offset;
    size_t committed;
} Arena;

#define arena_alloc_init(a) (Allocator){arena_alloc, arena_free, a}

#define is_power_of_two(x) ((x != 0) && ((x & (x - 1)) == 0))

uintptr_t align_forward(uintptr_t ptr, size_t alignment) {
    uintptr_t p, a, modulo;
    if (!is_power_of_two(alignment)) {
        return 0;
    }

    p = ptr;
    a = (uintptr_t)alignment;
    modulo = p & (a - 1);

    if (modulo) {
        p += a - modulo;
    }

    return p;
}

void *arena_alloc_aligned(Arena *a, size_t size, size_t alignment) {
    uintptr_t curr_ptr = (uintptr_t)a->base + (uintptr_t)a->offset;
    uintptr_t offset = align_forward(curr_ptr, alignment);
    offset -= (uintptr_t)a->base;
		
    if (offset + size > a->size) {
        return 0;
    }

    a->committed += size;
    void *ptr = (uint8_t *)a->base + offset;
    a->offset = offset + size;

    return ptr;
}

void *arena_alloc(size_t size, void *context) {
    if (!size) {
        return 0;
    }
    return arena_alloc_aligned((Arena *)context, size, DEFAULT_ALIGNMENT);
}

// Does nothing.
void arena_free(size_t size, void *ptr, void *context) {
    (void)ptr; (void)size; (void)context;
}

void arena_free_all(void *context) {
    Arena *a = context;
    a->offset = 0;
    a->committed = 0;
}

Arena arena_init(void *buffer, size_t size) {
    return (Arena){.base = buffer, .size = size};
}

Given this sample code below, we can inspect the memory of the program and see how our data ends up:

size_t size = 1024 * 1024 * 64;
void *buffer = malloc(size);
Arena arena = arena_init(buffer, size);
Allocator allocator = arena_alloc_init(&arena);

int *x = make(int, 420, allocator);
size_t *y = make(size_t, 23, allocator);
char *z = make(char, 69, allocator);

for (int i = 0; i < 420; i += 1) x[i] = i;
for (int i = 0; i < 23; i += 1)  y[i] = (size_t)i;
for (int i = 0; i < 69; i += 1)  z[i] = (char)i + '!';

As you can see, our data is nicely located in a predictable way - good for the CPU and good for us.

Note: I am in the process of experimenting with adding realloc to my Allocator interface. It seems like it could be a pretty handy thing to have.

If you decide to or already do use Arenas in your projects, I’d love to hear about it.

If you think my implementation can be improved, please leave a comment below!

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.

Problem: Always Checking For ‘\0’

I won’t go into depth on this one. You can imagine that having to check for the terminating character adds unwanted complexity to any functions dealing with strings in C.

Problem: Buffer Overruns

Buffer overruns are possible due to C’s direct memory access. Let’s look at a small example program:

#include <stdio.h>

static struct {
    char str[10];
    int num;
} values;

int main(void) {
    values.num = 420;
    sprintf(values.str, "%s", "0123456789abcd");
    printf("%d\n", values.num);
    return 0;
}

I put two variables into a struct so they don’t get re-ordered by the compiler.

The integer num will appear at least 10 bytes from the start of the char array str. Due to alignment, num most likely appear 12 bytes after the start of str.

In the image below, I have placed labels above the memory. a401 in hexadecimal is 420 in decimal:

When “0123456789abcd” is is placed at the position str, we get this result:

As you can see, we have clobbered the first 2 bytes of num. We have inadvertently modified the value to be 6364 in hexadecimal which is 25699 in decimal.

This can happen with any pointer, though it’s a more common bug with regular strings due to the way we use textual data. In inserting into and formatting strings, we increase the likelihood of this class of bug.

This program doesn’t give any warnings, by the way. Even on the most strict warning settings (-Wall -Wextra -pedantic).

To Microsoft’s credit, they do warn the user about using sprintf. The MSVC compiler will recommend using sprintf_s. sprintf_s has the buffer length as one of the parameters. There is also snprintf, which provides the same protection - though differs in the return type.

This memory overwriting issue is not solved by just using these functions. For example, what about if we want to iterate through some data and add something from it to a string? I’ll show a brief example:

char *my_str = malloc(10);
char *my_data = malloc(5);
sprintf(my_data, "%s", "012345");

for (int i = 0; i < 100; i += 1) {
    my_str[i] = 0x77;
}

In my testing, my_str appears in memory shortly before my_data.

As with the sprintf example, my_str is overwritten with bytes of 0x77.

Solution: The Custom String Type

The String type is defined as such:

typedef struct {
    size_t len;
    char *data;
} String;

In my version, we keep the null-terminator, and we also store the length. This allows us to create String functions that are compatible with:
- C Standard Library
- Any 3rd Party libraries that expect a null-terminated char array.

Before we dive into the implementation, let’s review some usage code:

Allocator a = ...;

String s1 = String("This is my cool string.");
String s2 = String("And here is another one.");

String cs = str_concat(s1, s1, &a); 

printf("'%s'\n", cs.data);
// => 'This is my cool string.And here is another one.'

String *split = str_split(s1, String(" "), &a);

size_t len = array_length(split);
for (size_t i = 0; i < len; i += 1) {
    printf("'%s'\n", split[i].data);
}
// => 'This'
// => 'is'
// => 'my'
// => 'cool'
// => 'string.'

String joined = str_join(split, String(","), &a);
printf("'%s'\n", joined.data);
// => 'This,is,my,cool,string.'

String view = str_substring_view(s1, String("my"), &a);
printf("'%s'\n", view.data);
// => 'my cool string.'
// As views don't alter or clone, the printf will not terminate correctly.

There’s much more you can do, but we’ll leave it there for now.

As you can see, our string usage is much simpler than the standard C string functions.

No weird strtok loop to split a string. Easily join strings together. Great.

Below is a simple and not necessarily great (it’s a first-pass) implementation:

typedef struct {
    size_t len;
    char *data;
} String;

#define String(x) (String){strlen(x), x}

String str_init(size_t len, Allocator *a) {
    String s = {
        .len = len,
        .data = a->alloc(len + 1, a->context),
    };
    s.data[len] = 0;
    return s;
}

String str_concat(String s1, String s2, Allocator *a) {
    size_t len = s1.len + s2.len;
    String s = str_init(len, a);
    memcpy(s.data, s1.data, s1.len);
    memcpy(&s.data[s1.len], s2.data, s2.len);
    return s;
}

String str_substring(String s, size_t start, size_t end, Allocator *a) {
    String r = {0};
    if (end <= s.len && start < end) {
        r = str_init(end - start, a);
        memcpy(r.data, &s.data[start], r.len);
    }
    return r;
}

bool str_contains(String haystack, String needle) {
    bool found = false;
    for (size_t i = 0, j = 0; i < haystack.len && !found; i += 1) {
        while (haystack.data[i] == needle.data[j]) {
            j += 1;
            i += 1;
            if (j == needle.len) {
                found = true;
                break;
            }
        }
    }
    return found;
}

size_t str_index_of(String haystack, String needle) {
    for (size_t i = 0; i < haystack.len; i += 1) {
        size_t j = 0;
        size_t start = i;
        while (haystack.data[i] == needle.data[j]) {
            j += 1;
            i += 1;
            if (j == needle.len) {
                return start;
            }
        }
    }
    return (size_t)-1;
}

// NOTE: this does not terminate the string with a 0 as that would destroy the original string.
String str_substring_view(String haystack, String needle) {
    String r = {0};
    size_t start_index = str_index_of(haystack, needle);
    if (start_index < haystack.len) {
        r.data = &haystack.data[start_index];
        r.len = needle.len;
    }
    return r;
}

bool str_equal(String a, String b) {
    if (a.len != b.len) {
        return false;
    }
    return memcmp(a.data, b.data, a.len) == 0;
}

String str_replace(String s, String match, String replacement, Allocator *a) {
    String r = {0};
    // TODO
    return r;
}

String str_view(String s, size_t start, size_t end) {
    if (end < start || end - start > s.len) {
        return (String){0};
    }
    return (String){end - start, s.data + start};
}

String str_clone(String s, Allocator *a) {
    String r = {0};
    if (s.len) {
        r.data = a->alloc(s.len, a->context);
        r.len = s.len;
        memcpy(r.data, s.data, s.len);
    }
    return r;
}

String *str_split(String s, String delimiter, Allocator *a) {
    String *arr = 0;
    size_t start = 0;
    for (size_t i = 0; i < s.len; i += 1) {
        if (s.data[i] != delimiter.data[0]) {
            continue;
        }

        if (memcmp(&s.data[i], delimiter.data, delimiter.len) == 0) {
            // Allocate array if we haven't yet.
            if (!arr) {
                arr = array(String, a);
            }

            // Clone the substring before the delimiter.
            size_t end = i;
            String cloned = str_substring(s, start, end, a);
            array_append(arr, cloned);
            start = end + delimiter.len;
        }
    }
    // Get the last segment.
    if (start + delimiter.len < s.len) {
        String cloned = str_substring(s, start, s.len, a);
        array_append(arr, cloned);
    }
    return arr;
}

String *str_split_view(String s, String delimiter, Allocator *a) {
    String *arr = 0;
    size_t start = 0;
    for (size_t i = 0; i < s.len; i += 1) {
        if (s.data[i] != delimiter.data[0]) {
            continue;
        }

        if (memcmp(&s.data[i], delimiter.data, delimiter.len) == 0) {
            if (!arr) {
                arr = array(String, a);
            }

            size_t end = i;
            String view = str_view(s, start, end);
            array_append(arr, view);
            start = end + delimiter.len;
        }
    }
    if (start + delimiter.len < s.len) {
        String view = str_view(s, start, s.len);
        array_append(arr, view);
    }
    return arr;
}

String str_join(String *s, String join, Allocator *a) {
    ArrayHeader *h = array_header(s);

    size_t total_length = s->len * join.len;
    for (size_t i = 0; i < h->len; i += 1) {
        total_length += s[i].len;
    }

    char *mem = a->alloc(total_length + 1, a->context);
    size_t offset = 0;
    for (size_t i = 0; i < h->len; i += 1) {
        memcpy(&mem[offset], s[i].data, s[i].len);
        offset += s[i].len;

        if (i == h->len - 1) {
            break;
        }

        memcpy(&mem[offset], join.data, join.len);
        offset += join.len;
    }

    mem[total_length] = 0;

    return (String){total_length, mem};
}

Hello there, dear reader. I’ll write about tools like ASan and UBSan in the future.

Subscribe now

Some algorithms require an unknown number of values to be stored, either temporarily during the running of algorithm, or as the result. In cases like this, the caller of the algorithm must either know the upper bound and allocate an array with enough space, or use a dynamic array that can grow in size as required.

More recent languages almost universally deal with this problem for the programmer. Some implementations are more egregious than others. Here are just two examples of ones you may have seen.

JavaScript:

// Declare an array
const my_array = []

// Assign a value to any index
my_array[69] = 420

// Now the array has a length of 70
// The first 69 items are empty

C++:

std::vector<int> my_array;

for (int i = 0; i < 70; i += 1) {
    my_array.push_back(i);
}

// [0,1,2,3,4,5..69]

As you can see, in both these examples, we did not have to specify the size of the array. In C, however, something like this is not a language feature nor part of the standard library. There is a concept called a Variable Length Array, however these are not quite the same and as of C11 are only optionally included in the spec, so they are not recommended.

Implementation

I'll skip the cruft and get straight to how to implement one in C. We'll use a a combination of a trick I learnt from Sean Barrett, the creator of the stb libraries, and custom memory allocators.

The trick is that we allocate space for the array plus some metadata. In our case, we'll define a header struct to store the metadata.

typedef struct {
    size_t length;
    size_t capacity;
    size_t padding_or_something; // prefer 16-byte alignment
    Allocator *a;
} Array_Header;

The padding field here is added so that the size of the header is 32 bytes. This is important because unaligned data causes the CPU to do more work to read from and write to the memory.

On x64, we want mostly 16-byte aligned data. There are some exceptions to this: SIMD (Single Instruction Multiple Data) types - specifically any SIMD types that are larger than 128 bits.

We won’t go into more details here, but I have confidence that if you are looking to exploit SIMD, then forward-aligning your dynamic array through either the allocator or the header definition should be no problem for you.

The Allocator type is quite simple, and will be expanded upon in further articles. For now, I'll show the structure and suggested values to get started without worrying too much.

typedef struct {
    void *(*alloc)(size_t bytes, void *context);
    void *(*free)(size_t bytes, void *ptr, void *context);
    void *context;
} Allocator;

A simple setup without custom allocators:

void *my_alloc(size_t bytes, void *context) {
    (void)context;
    return malloc(bytes);
}

void *my_free(size_t bytes, void *ptr, void *context) {
    (void)ptr; (void)context;
    free(ptr);
}

Allocator my_allocator = {my_alloc, my_free, 0};

This may all seem a bit redundant when you can just stick a malloc directly into the code we're about to write - but custom allocators are one of the most powerful concepts that a programmer can learn. As our machines are generally cache-bound, using the correct memory allocation strategy for the problem is very important. At the very least, we can simply make our code not slow, and it'll beat 99% of the stuff out there.

First, I'll show you the usage code:

int *my_array = array(int, my_allocator);
array_append(my_array, 69);
array_append(my_array, 420);
// ...

That looks pretty simple - and we get an array type back (a pointer to a type in C) so we can pass it to any functions that expect that - nice.

We'll need some way to initialise a dynamic array. Since C doesn’t have a type type, we’ll have to use a macro here.

#define ARRAY_INITIAL_CAPACITY 16

#define array(T, a) array_init(sizeof(T), ARRAY_INITIAL_CAPACITY, a)

void *array_init(size_t item_size, size_t capacity, Allocator *a) {
    void *ptr = 0;
    size_t size = item_size * capacity + sizeof(Array_Header);
    Array_Header *h = a->alloc(size);

    if (h) {
        h->capacity = capacity;
        h->length = 0;
        h->a = a;
        ptr = h + 1;
    }

    return ptr;
}

What we have done here is allocate enough space for our initial array size plus the metadata Array_Header. We then increment h by 1 which gives the address the array items start at.

Now we have our array, how can we add items to it? Well, we know it has space for 16 items, so we could just use the subscript operator directly:

my_array[0] = 23;

However, in this case the metadata is not updated - so the length is still 0. Let’s add a macro to append items.

#define array_append(a, v) ( \
    (a) = array_ensure_capacity(a, 1, sizeof(v)), \
    (a)[array_header(a)->length] = (v), \
    &(a)[array_header(a)->length++])

Admittedly, this is a bit tough to follow, so let’s break it down.

The parameters a and v refer to the array and the value (not pointers), respectively.

We wrap the entire macro in parentheses with statements separated by commas. This is intentional, and a little (as far as I’ve seen) used language feature of C. The comma operator will evaluate each item separated by commas from left to right and resolve to the rightmost one. All but the result of the final expression will be discarded.

There’s a lot of parentheses in these macros because I have been burnt by not using them enough. It may be overkill, but since there’s no type checking and you can’t really step through the C in a debugger unless you do a partial compilation, I prefer to err on the side of caution.

So in our code above, we assign the array variable a to the result of array_ensure_capacity (we will fill this out shortly). Then, we assign the value using another macro we have yet to define: array_header. Using this macro we get a pointer to the metadata and then get the length field. That gives us the next available slot in the array which we assign v to.

Finally, we get a pointer to the place we just put v and postfix increment the length at the same time. So our macro does 3 things:

1. Ensure there is enough space to put the value.

2. Set the value.

3. Increment the length.

Returning a pointer to the new item is nice when you want to do something with the inserted value right away.

Ensuring the capacity is quite a long function (not a macro this time!). I’ll present it in its entirety:

void *array_ensure_capacity(void *a, size_t item_count, size_t item_size) {
    Array_Header *h = array_header(a);
    size_t desired_capacity = h->length + item_count;

    if (h->capacity < desired_capacity) {
        size_t new_capacity = h->capacity * 2;
        while (new_capacity < desired_capacity) {
            new_capacity *= 2;
        }

        size_t new_size = sizeof(Array_Header) + new_capacity * item_size;
        Array_Header *new_h = h->a->alloc(new_size, h->a->context);

        if (new_h) {
            size_t old_size = sizeof(*h) + h->length * item_size;
            memcpy(new_h, h, old_size);

            if (h->a->free) {
                h->a->free(old_size, h, h->a->context);
            }

            new_h->capacity = new_capacity;
            h = new_h + 1;
        } else {
            h = 0;
        }
    } else { h += 1; }

    return h;
}

Despite the fact that this function is named “ensure capacity”, if the memory allocation fails, we assign the array to 0 and assume this is a critical error. In the array_append macro, the next line will cause a crash when we try to write to 0x0[array_header→length].

Here are some convenience macros:

#define array_header(a) ((Array_Header *)(a) - 1)
#define array_length(a) (array_header(a)->length)
#define array_capacity(a) (array_header(a)->capacity)

I rarely use remove, and even even more rarely use something like pop_back, but for the sake of completion I’ll add the implementations below:

#define array_remove(a, i) do { \
    Array_Header *h = array_header(a); \
    if (i == h->length - 1) { \
        h->length -= 1; \
    } else if (h->length > 1) { \
        void *ptr = &a[i]; \
        void *last = &a[h->length - 1]; \
        h->length -= 1; \
        memcpy(ptr, last, sizeof(*a)); \
    } \
} while (0);

#define array_pop_back(a) (array_header(a)->length -= 1)

That’s it - if there’s something you would like to add, please do so in the comments!

2024/01/24:

• Fixed Array_Header struct definition so that it is 32-bytes. This will fix alignment issues.

• Added small section on alignment.

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.

The Passion Trap

Indie game developers are largely driven by passion - this is a double-edged sword. Due to this passion, we fail to consider that what we are doing by creating and (hopefully) releasing a game which people will pay money for is starting a business.

It seems as though Unity has relied on this passion and their arguably intuitive game engine to gain a very strong position in the market. They are now abusing this position to extort their user-base.

This is not the first time something like this has happened, and it won’t be the last. To understand the potential consequences of Unity's decision, let's look back at another dominant platform: Adobe's Flash.

The Rise and Fall of Flash

In 1998, Adobe’s Flash was the go-to choice for website builders wanting to add some flair - standard web capabilities were pretty limited back then. Entire interactive websites were made in Flash and pretty soon the Newgrounds website would give birth to the Flash games scene.

Newgrounds boasted 18 million unique visitors a month at its peak and was a major hub for Flash games and animations. By 2005, top Flash game developers could earn up to six figures in sponsorship deals for a single game.

In 2010, Steve Jobs wrote an open letter criticising Flash for multiple reasons, one of which being that it didn’t port well to mobile devices.

In 2011, Adobe pivoted to HTML5, though it would still take almost a decade before browsers started dropping support for Flash entirely.

Though it took a long time for the sun to set on Flash, there were web designers with careers built on this proprietary tool that could no longer find work. Businesses stopped using Flash, afraid that anything made in it would be unusable within a few years.

The Real Cost of Free

I don’t think anybody expected that this kind of pricing change would happen - but people did expect something to change with Unity’s pricing model. The argument that Unity may one day be unavailable and all the Unity-based game developers would be in a position of having skills in something that isn’t easily transferred seemed hyperbolic just a couple of weeks ago. That is, unless you looked at previous examples of things like this happening - such as The Machinery game engine - a game engine that revoked their license to all developers using it and gave them 14 days to delete all source code (including their in-progress games).

The situations are different, and the mechanism is the same: updating the EULA to the detriment of the user-base. Whether this is legal is a matter for the courts - the message is clear: “we don’t give a damn about our users”.

Some developers have spent a decade learning the ins and outs of Unity and are now looking at migrating to another tool. Some developers with games in development are considering full rewrites in other engines like Godot.

Unfortunately, most people don’t think about these scenarios until they are forced to - the result is, unfortunately, some pretty dire circumstances.

Everything is a Trade-off

There is always a trade-off with every decision - by doing X, you cannot do anything that isn’t X. By learning Unity, you cannot spend that time learning how to create your own tools, or how to use other tools.

In the vast expanse of software development, the allure of pre-made solutions often blinds us to the pitfalls of becoming too comfortable. Unity's recent shock move only underscores a fundamental principle: Relying heavily on a single tool, no matter its reputation, can backfire spectacularly. The pitfalls of proprietary platforms remind us to spread our dependencies and stay adaptable in our craft.

Doing a bit of research into the plethora of free (as in liberty) software libraries and tools out there may save you and your business from ruinous circumstances.

I have a video that touches on how one may go about doing this available here: Unity Game Ends Themselves - A different take.

The Take-Away

Remember, if your business (game dev is a business) is reliant on a 3rd party and you have no contingency plan then your business is at that 3rd party’s mercy. If something happens to them, or they decide not to work with you anymore, your business could be ruined overnight.

If you enjoyed this post, please consider subscribing. Thank you for reading!

Subscribe now

As you may or may not know, I offer a free game engine programming course on my YouTube channel: C Game + Engine from Scratch. The most common question I get in the comments is “Why not C++?” followed by “Why reinvent the wheel?” or “Why not use Unity?” etc. I have outlined my reasons a couple of times in videos, but let’s add some more context.

Introduction

A myriad of confused programmers - either through poor education, lack of experience, or indoctrination into one or more of the various gratuitous acronym-based programming cults - find themselves believing misconceptions about their chosen vocation.

An ostensible pearl of wisdom proffered by thought-leaders and cult-leaders alike is the phrase “don’t reinvent the wheel”. Occasionally, one may have the inclination to investigate the bytes beneath the tortuous tower-of-abstractions - the very tower upon which so much of our modern day programs are built upon - the “tech stack”.

The curious programmer, upon further investigation, may decide to delve into the labyrinthine halls of the tower, perhaps glimpsing a peek of the vaults below. He may experiment there - probing and perhaps even modifying some of the code.

"Don't reinvent the wheel!" exclaims the indoctrinated programmer, compelled as if he was a CPU executing a stream of instructions.

Ridiculed and covered in bile, the curious programmer must be restored to their place on the assembly line of programmed automatons produced by modern “educational” institutions.

The supposition of the phrase makes clear, whether directly or by common inference, certain demonstrably false assumptions about programming.

1. The wheel is perfect.

2. Problem X already has a wheel.

The Wheel Is Perfect

The wheel, as we know it at in the present, is an incredible device that appears to be perfect at converting torque into linear motion. However, this depends on the context in which it’s applied.

For variations of context, we have variations of wheels. If the wheel was already perfect, we may still be using the solid stone wheels invented in Mesopotamia over 6000 years ago.

The design of a wheel suitable for smooth asphalt is different from one designed for rugged mountain trails. If you need to go through the snow, snow chains or studded tires are required to provide extra traction. In deserts, wide wheels are used to prevent vehicles from sinking into the sand.

There’s functional aspects to consider as well. Truck wheels are larger and more robust because of the weight they carry.

I won’t belabour the point - wheels have been reinvented for different contexts for thousands of years.

Problem X Already Has a Wheel

Let’s talk about game engines. Unity, Unreal, and Godot are the big 3 game engines. They have advanced toolkits that make them appear to be the ideal solution for most games that you may want to make - and that’s true.

However, these game engines are certainly not the best solutions for all problems. Any game design that falls outside their general use-case will have the programmers and designers fighting the engine trying to get things to work.

Look at Oxygen Not Included as an example. It’s one of my favourite games of all time. It has horrible performance issues if you play one save file for too long. The trade-off for Klei choosing Unity is that the world size has to be small to mitigate the lag - and they still can’t mitigate the lag.

For a new game developer, the big 3 may seem like the only viable options. They are popular and have extensive resources available to learn them. As I always say, this may be true for you and your games - but it’s not true for everyone.

Someone has to create the next Unity. Someone has to create something bespoke that the big 3 just cannot do well enough. That someone may be you.

When The Big 3 Don’t Fit

The big 3 are designed to fit the general case - they must cater to a wide variety of genres and platforms. This is fantastic if your game fits within the scopes of these engines, and this broad scope means that they are inherently generic. For some projects, overheads of these engines - in terms of memory usage, performance costs, or even learning curve - can be too much.

Moreover, when you use a pre-built engine, you're also confined to its architecture and limitations. While these engines provide flexibility, there's a ceiling to how much you can modify or extend their core. For games requiring a unique mechanic, more simulation computation - as with Oxygen Not Included - or a different approach to rendering, this can become a significant barrier.

You Don’t Have to Build Everything

There are many battle-tested libraries available in a swathe of languages. If you cannot find something native to the language you choose - you can probably find a C version and most common languages have C interoperability.

Rendering engines like Magnum and bgfx allow you to draw complex scenes with all the features you could want. Physics libraries like Bullet and qu3e have most of the features you could want. These are just 2 examples of 2 areas that make up a game engine - there are many.

What’s the difference between using an engine and using a bunch of libraries? You control how these systems talk to each other. If you really need to, you can create custom solutions for the missing pieces - if nothing you find fits.

Conclusion

The phrase “don’t reinvent the wheel” holds merit in many scenarios. However, as I hope to have demonstrated by this article, there are many situations in which the wheel required reinvention. The context is vitally important.

I have been talking about games and game engines because that is what most interest me. However, you can extend this logic to all of programming. I don’t think we are close to finding a wheel in nearly any programming domain.

The next time someone questions the decision to build something from scratch - remember that without understanding, there can be no innovation. If we always stuck with the status quo, we’d still be riding on stone wheels.

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.

There are multi-decade projects built specifically to obscure the memory from the programmer - most commonly used programming languages use garbage collection rather than allow the programmer direct control of memory allocations. It’s understandable that the first instinct is to disallow certain actions - similar to how when there are small children in the house you would lock away the knives and cover the power points.

However, unlike with children, programmers are told not to grow and learn to take their own risks - they are kept wrapped in bubble wrap, unable to hurt themselves, severely limiting their movement and retarding their development.

The Teaching Problem

When learning about data structures such as linked lists, you were probably taught to allocate and free using malloc and free directly. Whether learning from a textbook or online, the examples commonly found are something akin to this:

Node* push(LinkedList* list, int data) {
    Node* new_node = (Node*)malloc(sizeof(Node));
    new_node->data = new_data;
    new_node->next = (list->head);
    list->head = new_node;
    return new_node;
}

malloc is seen as a mystical operation that provides memory when either the stack won’t suffice or control over the memory’s lifetime is required. Depending on the path you have taken on your programming journey, this may be the extent of your understanding.

As with all things, there are trade-offs to this way of teaching. On the one hand, it's easier to teach about the data structure itself without delving into the intricacies of how malloc works or considering alternative memory allocation methods. On the other hand, linked lists are often criticised as slow and fragmented because proper memory allocation wasn't utilised from the start. Ironically, malloc/free's internal implementation uses a linked list to denote free blocks of memory.

Carrying It Forward

Due to the aforementioned learning process, many programmers reach for malloc early and often. This leads to bugs as the lifetimes of data are ignored or thought of in fragmented ways. Human error is a reasonable assumption when creating complex systems. As a result, manual memory management is blamed, rather than the lack of any process that would mitigate the bugs.

Enter garbage collection, smart pointers, reference counting, etc. - all designed to prevent programmers shooting themselves in the foot. And, all with overhead that means more CPU cycles used, which means more money spent and more electricity wasted.

Garbage Collection

The two reasons most often given for using a garbage collected language are: program safety and programmer productivity. One of these claims is false and the other is hard to quantify and also probably false.

Program Safety

One commonly cited program safety issue that arises with manual memory management is dangling pointers - they are pointers that no longer point to valid memory blocks.

There are a few ways to create a dangling pointer, but for the sake of simplicity, here is a classic use after free error.

#include <stdio.h>
#include <stdlib.h>

int main() {
    int* ptr = (int *)malloc(sizeof(int));
    *ptr = 69;
    free(ptr); // Memory is deallocated here.
    *ptr = 420; // Use after free error: accessing memory that has been deallocated.
    printf("value: %d\n", *ptr);
    return 0;
}

The thing that makes this type of bug so insidious is that it’s not a compile error - it’s undefined behaviour, and that means it’s up to the compiler implementation to decide what happens. You will only get a warning if you have the correct warning level turned on for your C compiler. In this case, using GCC 12.1, the program works as expected, though it’s not guaranteed to do so.

You may be wondering why I’m explaining dangling pointers, their insidiousness, and then still recommending manual memory management. It’s because GC languages have exactly the same problems, just inversed.

In a GC language, rather than having a dangling pointer, you can easily create a memory leak using the very tool that is meant to replace malloc and make it safe - new.

var myThing = new MyThing();
myList.Add(myThing);

• The MyThing instance resides in the heap memory, and it has at least two references pointing to it: the local variable myThing and the reference inside the list myList.

• If the scope of myThing (e.g., a method or block where it's declared) ends, the local reference myThing will go out of scope and be removed. However, the MyThing instance won't be garbage collected because the myList still holds a reference to it.

• Only when there are no more references pointing to the MyThing instance (for instance, if the item is removed from myList and no other references exist) will it be eligible for garbage collection. Until then, it remains in memory.

You as the programmer can easily spot the potential issue in this case - it’s contrived, after all.

The point here is not that you can create other types of memory issues using GC’d languages, but that you are simply trading thinking about malloc/free for thinking about object references instead.

Let’s just show one more simple C# example to see how easy it is to make a memory leak.

public class MyThing {
    public MyThing() {
        GlobalEvents.SomeEvent += HandleEvent;
    }

    private void HandleEvent(object sender, EventArgs e) {
        // Do something.
    }
}

In the above code, GlobalEvents.SomeEvent holds a reference to each instance of MyThing until unsubscribed. This is, once again, the same type of cognitive burden that causes mistakes as malloc/free.

Programmer Productivity

Programmer productivity seems to be almost impossible to quantify properly. It’s certainly not X lines of code written in Y time, commit frequency, or test coverage. Perhaps something like “frequency of difficult problems solved with robust solutions” - but even then, how do we score different problems?

Rather than trying to quantify what makes programmers productive, we can simply compare garbage collection vs manual memory mental overhead and call-site code requirements.

As stated above, the GC promise of not having to worry about memory is not true in practice. The programmer must still consider object lifetimes and keep track of object references. If the argument is that manual memory allocation takes more lines of code, that may be true in the naive case - where each allocation has a free, but the argument falls apart once custom memory allocators are involved.

The Solution: Memory Allocators

Memory allocators allow programmers to group together object lifetimes and think about them much more easily than the usual malloc/free or new.

Rather than tracking individual object lifetimes in your head, you can decide which one of your memory allocators you’d like to use up-front and then not have to worry about it. This is the panacea to the fragmented way of thinking we have been discussing thus far.

The Arena Allocator

The arena allocator is an extremely simple and powerful tool to have in your arsenal. The way it works is memory is allocated sequentially and must be freed all at once.

The implementation of an arena allocator can be as simple as:

size_t current_position = 0;
size_t arena_size = 4096;
u8 *arena_memory = malloc(arena_size);

u8 *arena_alloc(size_t bytes) {
    if (current_position + bytes <= arena_size) {
        u8 *ptr = &arena_memory[current_position];
        current_position += bytes;
        return ptr;
    }
    return 0;
}

void arena_free() {
    current_position = 0;
}

This implementation will not do for any serious use-cases, but the concept remains the same.

With this one simple tool, the programmer is enabled to allocate a variety of objects with entirely different types and sizes, but the same lifetime. This is much more akin to how we actually use memory in the first place.

During the initialisation phase of your program, you can allocate permanent resources using your permanent arena allocator that you never have to free or worry about. Then, each update of your program, you may want to construct some strings and log them to a file - you can have an arena that gets cleared at the end of each update cycle.

The lifetimes of your objects are now dependent on the memory allocator you decide to use and the burden of keeping individual lifetimes in the programmer’s head is lifted.

Memory allocation techniques are often covered in advanced C/C++, systems, or OS programming materials, so many programmers are unfamiliar with them.

I believe that if this concept was taught much earlier in the programming journey, it would lead to better quality software and less confusion about how memory works.

Conclusion

The main challenges arising from manual memory management stem from how programming is taught, leading many programmers to find it difficult.

Garbage collection, though not a problem in and of itself, is lauded as the solution to memory bugs. However, it fails to live up to that reputation and obfuscates another class of memory bugs by default.

Custom memory allocators can be simple to implement, easy to understand, and have no hidden functionality.

Understanding memory management is essential to creating efficient and robust software. The hardware does not disappear when we try to abstract it away.

Knowing just a little bit more about how the hardware works can save CPU cycles, reducing costs and conserving energy.

Whether you are a novice or experienced, I recommend looking into custom memory allocators if you haven’t already - they are a game-changer.

Continual learning is part of the programming journey - embrace it. Every year I feel like I was a fool the year before.

I hope that in the future we will teach memory management the right way sooner. New systems languages like Zig and Odin have incorporated memory allocators as core features - this is a step in the right direction.

Golang recently added an arena allocator that works in tandem with its GC. I'm quite interested to see how that pans out.

If you’d like to learn more about arenas, I recommend these great resources: gingerBill, Ryan Fleury.

I encourage you to share your experiences, thoughts, or questions below.

If you enjoy this newsletter and want to go deeper, with more structure, I made Program Video Games for you. Transform your game ideas into working systems from first principles.