Games

Solar Storm

Steam

My first commercial game, and the first game I realeased on Steam. I made it in 4 months in a custom game engine built with Odin and Sokol.

Hyper Heist

itch.io

Hardcore fast-paced cyberpunk platformer. Submission to SpeedJam 1 organized by ScoreSpace, ended up #3rd overall and #1 organizers choice.

No-Gun Shotgun

itch.io

This is a 2d tower defense platformer. Submission to Mini Jam 117: Ghosts, the first game jam I ever attented. Made in Godot 3.5.

Dungeon of Quake

itch.io Github

A retro FPS game written from scratch in Odin and Raylib. Comes with a very simple level editor.

Voxel Caves

itch.io

A small 3d game prototype, where you explore procedurally generated infinite cave system. The terrain is generated with the marching cubes algorithm in a compute shader on the GPU.

Jump Prince

Simple Jump King clone made with raylib, in <700 lines of C code.

Github

FRAGILE: handle with care

Top-down game set in a sci-fi warehouse, where you use boxes to fight off enemies. Submission to Ludum Dare 53.

itch.io

Github

Open-source projects

VMem

Github

STB-style single-header C library for cross platform virtual memory management.

3d ISCP software renderer

Github

Simple 3d rasterizer based on fgeisen’s blog Triangle rasterization in practice, written in ISPC.

Odin bindings

• odin-steamworks
• odin-ldtk
• odin-fmod
• odin-lz4
• odin-mimalloc

About

Solar Storm is a turn-based scifi artillery game, inspired by 90s local-multiplayer games like Scorched Earth and Worms.

Solar Storm releases on Steam April 3rd 2024 with Windows support.

Fully Destructible Procedural Maps

Each battle takes place in an unique, procedurally generated arena. There are a number of Biomes, where each one of them has unique characteristics.

Powerful Weapons of Mass Destruction

There is a wide arsenal of powerful weapons, which can help you out in any circumstances.

• Weapon Powerups which significantly change the weapon
• You can choose a Weapon Mode each turn. This impacts whether a projectile explodes on impact, bounces, or drills through the terrain.

Disasters

Watch out for disaster! Meteorites might be falling from the sky out of nowhere!

Key Features, Summarized:

• 30+ Biomes, each with unique procedural maps
• Deep weapon system with 40+ powerful Weapons
• Local Multiplayer against players or bots
• Free for All and Team Deatchmatch game modes
• Unexpected Disasters

Supported Languages

• English
• Simplified Chinese - 简体中文
• Spanish - Deutsch
• German - Čeština
• Czech - Español
• Greek - Ελληνικά
• Russian - Русский
• Swedish - Svenska
• Croatian - Hrvatski
• Portuguese - Português
• Finnish - Suomi
• Turkish - Türkçe
• Dutch - Nederlands

Price

• $6.99
• €6,89
• £5.89
• 170 CZK

Contact and Links

• Business Inquiries: jakubtomsu@proton.me
• Steam
• Discord Server
• YouTube
• Dev Twitter
• Handmade Network

Credits

Jakub Tomšů - Game Design, Programming and Art

Dylan Siebert - Soundtrack

Technology

The entire game is written in the Odin programming language and uses a custom game engine built on Sokol and FMOD

The goal is to ensure high quality and good performance, even on low power devices.

Videos

Demo Trailer

Logos

Gifs

Screenshots

The usual way to implement the slot-reuse mechanism is to store some kind of a list of currently unused slots. There are a bunch of different ways to implement this list, from a dumb array with slot indices, an intrusive/non-intrusive singly-linked-list. They essentially do the same, except minor memory overhead differences.

Here’s how the datastructure internals could look like:

1Pool :: struct($N: int, $T: typeid) {
2    data:   [N]T,
3    next:   [N]u32, // per-item free list 'next'
4    free:   u32, // free list head
5    max:    u32, // max used slot
6}

But I have been using a very different approach lately, which is NOT based on any kind of free-list-like system. It has a few nice performance properties:

• only ~1 bit overhead per slot
• significantly better slot allocation strategy with improved memory locality

My approach is inspired by the TLSF memory allocator, though it should be a lot simpler to understand and implement from scratch.

Demo

free-list-based pools have an weird property people don't talk about - at some point the slot allocation pattern becomes almost random.

But there are alternative approaches, which don't use free lists at all. Lately I've been using a multi-level bit pool: pic.twitter.com/zx1zaoT0un

— Jakub Tomšů (@jakubtomsu_) February 23, 2026

Bits

The idea is to just store a single bit, which determines whether a slot is in use or not. Let’s start with this, though we will improve it a lot later:

1Pool :: struct($N: int, $T: typeid)
2    where N % 64 == 0
3{
4    data:   [N]T,
5    used:   [N/64]u64,
6}

For the rest of this article we assume all pools store a multiple of 64 elements.

This of course has a fatal flaw - once you have thousands of items, you need to search through all the individual bits.

tzcnt is your friend

It’s wasteful to search the 64 bits of each used field individually with something like a loop of shr+mask+branch.

There is tzcnt, which stands for trailing zero count. It’s an x64 instruction which has been supported on all consumer chips for many years. It’s exposed to the programmer in the form of compiler intrinsics, and it lets you find the index of a lowest binary 1 in essentially a single cycle.

And while a smart optimizing compiler could convert a tiny loop into a single tzcnt call, using it yourself explicitly makes it clearer what’s going on and it will be fast even in debug builds.

In Odin, I use a procedure called count_trailing_zeros from the base:intrinsics package, which implements this in a cross-platform way.

Searching slots with tzcnt

All you need to do to find an empty slot in a single u64 is to call count_trailing_zeros(~used[index]). We’re negating the used mask to actually count trailing ones (used slots) to find the first zero (unused) bit index.

The code could look like this:

 1find_empty_slot :: proc(pool: $T/$Pool($N, $V)) -> (result: int, ok: bool) {
 2    for i in 0..<N/64 {
 3        bit := int(intrinsics.count_trailing_zeros(~pool.used[i]))
 4        // check for full block
 5        if bit != 64 {
 6            return i * 64 + bit
 7        }
 8    }
 9    // Pool is full
10    return 0, false
11}

Okay, this is quite a nice improvement, but you still have to search N/64 u64s in the worst case. Can we improve this? Can we somehow quickly search among all those u64s and find one that isn’t full?

2-level bit arrays

The answer is yes. The solution is another, but smaller bit array. While the original bit array stores 0/1 for each slot, we can add another array to store bit per each block, which is 1 when a block is full.

The actual struct ends up something like this. I’ll only implement the bit pool part without the actual data, since that’s how I use it in my code.

1Bit_Pool :: struct($N: int)
2    where N % 64 == 0
3{
4    // round up div by 64*64
5    l1: [(N + 4095) / 4096]u64,
6    // 'used' array from before
7    l0: [N / 64]u64,
8}

Each field in the L1 array stores info about 64 fields in L0. This way each tzcnt instruction effectively searches 4096 slots.

The arrows in this illustration show the implicit mappings between the data:

data             L0               L1
┌──────────┐   ┌──────┐      ┌────────┐
│0..63     │◄──┤0     │◄─────┤0       │
├──────────┤   ├──────┤      ├────────┤
│64..127   │◄──┤1     │   ┌──┤1       │
└──────────┘   ├──────┤   │  ├────────┤
               │...   │   │  │...     │
┌──────────┐   ├──────┤   │  │────────│
│4032..4095│◄──┤63    │   │  │N/4096-1│
└──────────┘   └──────┘   │  └────────┘
┌──────────┐   ┌───────┐  │
│4096..8191│◄──┤64..127│◄─┘
└──────────┘   └───────┘

Search

This is how the code looks like. There is a loop so while the “theoretical asymptotic complexity” is still based on N. In practice, the N is either quite small so this loop is taken only a few times, or you add more levels, which scales logarithmically in memory footprint and with a tiny constant overhead at each additional level.

 1find_0 :: proc(bp: Bit_Pool($N)) -> (index: int, ok: bool) {
 2    l0_index := N > 64 ? -1 : 0 // ignore the L1 in small pools
 3    // Find suitable L0 block by searching L1
 4    for used, i in bp.l1 {
 5        l1_slot := int(intrinsics.count_trailing_zeros(~used))
 6        if l1_slot != 64 {
 7            l0_index = 64 * i + l1_slot
 8            break
 9        }
10    }
11
12    if l0_index == -1 || l0_index >= (N / 64) {
13        return -1, false // Pool is full
14    }
15
16    // Find the actual slot within the L0 block
17    l0_slot := int(intrinsics.count_trailing_zeros(~bp.l0[l0_index]))
18    if l0_slot != 64 {
19        return l0_index * 64 + l0_slot, true
20    }
21
22    return -1, false // Pool is full
23}

As you can see this has a nice “front loading” property, where it always allocates slots with the lowest index first. This is great for memory locality, especially in burst-like slot allocation patterns. A regular list-based pool would scatter the values all across the pool!

The generated code also looks reasonably nice, LLVM can unroll the loop in many cases and even collapse it. Check out this Godbolt example where N = 8192.

Code

A full implementation is on Github, as a part of my Raven engine. It includes procedures for actually setting bits and lookups.

More levels

If your N gets significantly larger than 4096, you could trivially add more levels. It’s still all O(1) in every case. The only reason I don’t do this is because my pools tend to be relatively small, tens of thousands of items at most.

For example, if you added l2 bit array, a single tzcnt instruction would effectively search 64^3 (262144) slots. That is a lot of slots.

AoSoA

This block-based approach lends itself to SIMD AoSoA (arrays of structures of arrays).

The L0 mask is the “ground truth” determining free slots, but since it’s a bitmask of packed elements it’s exactly the layout you would use as a SIMD op mask or something similar.

I quite enjoy keeping datastructures simple, instead of wrapping everything in multiple levels of generic containers. Here’s an example of AoSoA combined with Bit_Pool, for something like a particle system:

 1MAX_FOOS :: 1024 * 16
 2
 3Foo_Batch :: struct {
 4    pos:    [3]#simd[64]f32, // xyz 64 times
 5    vel:    [3]#simd[64]f32, // xyz 64 times
 6    timer:  #simd[64]f32,
 7    flags:  #simd[64]u16,
 8}
 9
10// Each value in used.l0 corresponds to one batch
11Foos :: struct {
12    used:       Bit_Pool(MAX_FOOS),
13    batches:    [MAX_FOOS / 64]Foo_Batch,
14}

Explaining this in more detail is out of scope for this article, but I’ll leave this here just as a vague idea for inspiration.

Possibly atomic?

I haven’t really looked into this yet, but I wonder if insertion/removal could be completely lockless using atomics. It seems relatively trivial in the one-level case, maybe I could order the insertion and removal memory writes to eliminate data races?

In case you figure something out, please do let me know! I would be very interested in experiments and also correctness proof.

Conclusion

This approach is a bit more complicated than a dumb free slot array, but I really like the fact it’s just a basic bit array, no super complicated metadata to take care of.

I’m not necessarily trying to convince anyone to use this approach, however I think these kinds of algorithms are still relatively uncommon, so it was worth writing about. It’s certainly nothing novel, but I hope it’s valuable!

Thank you for reading!

Jakub

2026-02-22: Minor updates, correct free list memory overhead

2026-02-23: Typo fixes, demo

So what can we do to compile Odin programs faster? Here I’ll try to explain some ways of troubleshooting Odin compile times and ways to improve them.

TL;DR

• Use faster linkers
• There is a -show-debug-messages flag to dump things like LOC/s and total parsed lines/tokens/packages, plus a lot of debug info.
• -o:minimal and -microarch:native is essentially free

Small programs

Compilation speed of large projects is probably the most important thing when measuring compiler performance.

However in Odin, I often write many small utility “scripts” instead of using shell/batch/python. It’s very convenient, I get access to the core libraries running is simple as odin run my_tool.

So let’s consider the following program. It’s just a simple hello world, but all small tools need to print to console so it’s at least a little representative of the real world.

1import "core:fmt"
2
3main :: proc() {
4    fmt.printfln("Hello %s %i!", "World", 123)
5}

To get the compilation speed, we can run odin build with the -show-timings. On my machine, result is something like this:

Total Time                         -   270.198 ms - 100.00%
initialization                     -     7.618 ms -   2.81%
parse files                        -    12.968 ms -   4.79%
type check                         -    66.492 ms -  24.60%
LLVM API Code Gen (   54 modules ) -    82.512 ms -  30.53%
msvc-link                          -   100.602 ms -  37.23%

This is not too bad! But interestingly, compiling some of my projects (with tens of thousands lines of code, and a lot more in dependencies) don’t compile that much slower.

So can we do better?

Linker

In the example above, almost 40% of the time is spent in the linker. So let’s try a different one.

Using -linker:radlink gets it down to about 15% on my machine. If you’re on linux you can also try mold.

In general, a faster linker can also improve compile times when the binary gets large (e.g. large dependencies, or big #load files).

More Timings

There is a -show-more-timings which lists timings for all the internal compilation stages.

In most cases it doesn’t tell you that much (it’s mostly valuable for compiler developers), and most time is spent in LLVM Object Generation stage.

However, you still might want to look at the results if you need to debug why something is compiling slower than expected - sometimes you hit a slow path.

For example, I ran into a case parsing a file with gigantic embedded arrays of integer constants generated by sokol shader compiler was adding ~3 seconds to my compile time.

Always profile, especially when things go wrong.

Internal Flags

You can often find interesting hidden flags in the compiler source code. Let’s look at some of them.

Debug Messages

There is a flag called -show-debug-messages, and while it’s not intended for regular users, it’s extremely useful. It dumps a LOT of good statistics to stderr useful for debugging and profiling.

So let’s measure Hello World again:

odin build hello -show-timings -linker:radlink -show-more-timings -show-debug-messages

When you scroll a bit past the LOC/s sections (which are also extremely useful!), you’ll see something like this:

Peak Memory Size: 271.000 MiB

Total Lines     - 80727
Total Tokens    - 395951
Total Files     - 162
Total Packages  - 26
Total File Size - 2572637

This is an overview of all the things the compiler had to parse to compile your program.

But 26 packages and 80k lines of code seems like a lot for a Hello World. All of that was pulled in by core:fmt and it’s dependencies. Let’s see if we can do something about it.

Build Diagnostics

When you call odin build with the -build-diagnostics flag it’s going to generate big tables from LLVM backend information.

Currently this includes two primary kinds of tables:

• parapoly instatiation statistics
• module diagnostics

The parapoly tables just list the generic procedures with the most instantiations, plus their instruction counts.

The module diagnostics list per-module total instruction count as well as other info, which can be useful for determining which module is the slowest to compile by LLVM.

Dependencies

A good way to diagnose the dependencies is to add a -keep-temp-files flag to the build command, and look at what .ll IR files are generated. The list of files tells you which packages got actually included in the build. And the file size roughly reflects the compile time.

base:runtime only

We can do something like the following to write data directly to stderr. The base:runtime is always included by default as it contains builtin implementations and other required features, so there’s not much better we could do.

1import "base:runtime"
2
3main :: proc() {
4    runtime.print_string("Hello World 123!")
5}

The results look a lot nicer:

Peak Memory Size: 76.703 MiB

Total Lines     - 9211
Total Tokens    - 59321
Total Files     - 31
Total Packages  - 3
Total File Size - 290122

Total Time                         -    58.230 ms - 100.00%
initialization                     -     7.189 ms -  12.34%
parse files                        -     2.853 ms -   4.90%
type check                         -     5.993 ms -  10.29%
LLVM API Code Gen (   31 modules ) -    14.681 ms -  25.21%
rad-link                           -    27.510 ms -  47.24%

Only 9k LOC, 3 packages, and 60 milliseconds to compile the entire program! That’s really nice.

But there’s a problem: we lost all the nice core:fmt’s formatting functionality. This is a big issue, because it’s very cumbersome to do all the formatting by hand.

μ-fmt experiment

This lead me to write an experimental ufmt (micro-fmt) package. It does only the bare minimum, but it covers 90% of my own core:fmt use-cases.

1import "ufmt"
2
3main :: proc() {
4    ufmt.printfln("Hello %s %i!", "World", 123)
5}

The entire implementation is <200 lines of code and depends only on base:runtime. It also compiles in 60 milliseconds and includes only 9k LOC.

There is only tprintf, printf and printfln. Only supported format qualifiers are the following:

• %s: string and cstring, no cstring16
• %i: all integer types
• %x: all integer types in hexadecimal, always zero padded
• %f: 16, 32 and 64 bit floats, with basic NaN/Inf detection
• %%: to print literal % characters

Here’s the initial ufmt version as a github gist.

Update: I expanded the initial version and now it lives in the source tree of my game engine. I added very lightweight RTTI crawl for printing any values including structs, arrays, etc automatically. It’s not 100% complete, but it’s reasonably usable and I’ll continue to improve it. Here’s the link.

Of course, using this has no effect if you import a package which depends on core:fmt. This is pretty annoying, currently there is no good way to see what exactly is your program importing and why, apart of looking at temp obj files.

On my branch of the compiler I experimented with printing a graphviz graph of all the packages with their includes, but that’s not official. Update: see this PR for the graph generator, and a userspace solution using core:odin/parser.

LLVM

In general the slowest part of the compilaton pipeline is the LLVM backend. Even with all optimizations disabled it takes quite a while.

Odin already codegen’s each package independently to utilize all the CPU threads (LLVM cannot be multithreaded with better granularity). And as a general rule, LLVM scales very poorly with the codegen amount. For example -disable-assert and -no-bounds-check can help by a very tiny bit because it’s slightly less things to generate (so I don’t think it’s worth it for debug builds).

On the other hand, -debug has a HUGE impact. Generating the PDB is no small feat, and it can make compile times take 20-80% longer in my experience.

Optimization

Obviously, it’s not a good idea to compile with -o:speed/size/aggressive if you want good compilation speed. But I still want debug builds that run fast!

However -o:minimal is almost completely free, all it does is enable inlining of #force_inline procedures. It’s the default when NOT compiling with -debug.

Similarly, using -microarch:native adds no overhead. I’m pretty sure it just triggers a slightly different code path in the LLVM lowering passes, but could possibly yield some runtime perf benefits.

Parapoly Variants

Another issue which can appear in larger codebases is a duplicate explosion from parametric-polymorphism variants.

For example if you have code like this:

1some_large_procedure :: proc($N: int, ...) {
2    // ... lot of code
3}

The compiler will literally need to generate the code for each N separately. So while the parsing cost is paid once, the type checker and the backend has to work extra hard.

The overhead is totally negligible even with hundreds of variants when the procedure body is small. But once the codegen amount gets larger you start running into all kinds of bottlenecks, one of them being LLVM (as always).

What to do about this

Update: there is now a -build-diagnostics flag. But the following approach also works.

There isn’t any kind of diagnostics in the Odin compiler itself to check if this is happening. What you can do however is compile your code and check the symbols. For example like this on Windows:

odin build my_program -build-mode:lib
dumpbin /SYMBOLS my_program.lib > symbols.txt

Or with objdump on Linux. You’re looking for a long list of repeated procedure symbols, something like: my_package::my_procedure:proc(my_param:$$value, ...).

To help mitigate this issue, you could try putting all the common code into a non-parapoly procedure and calling it indirectly. Or, if you don’t actually need the parapoly specialization and only use it for “optimization”, just get rid of it.

Conclusion

GingerBill says the Odin compiler can still be a lot faster. And while there’s plenty of room for optimization, it’s not too bad in the current state.

For a simple hello world, we got nearly 5x faster compile times by compiling with the right flags and being careful about dependencies. Of course, it’s different in real, bigger projects but I hope I shed some light on the various ways you could debug these issues, and some general rules to follow.

I recomment the following command as a reasonable default for compiling lightweight tools:

odin build my_tool -linker:radlink -microarch:native

Thank you for reading!

Also big thanks to all my Patrons! <3

• Voodoo51
• p1xelHer0
• Coedo
• Filip Aničić
• Moritz Falk
• Lion Schitik
• Ondřej Jamriška
• Alastair Marshall

Edit 2026-01-22: Added a section about parapoly, and more -o:minimal info.

Edit 2026-01-23: A small section about checking dependency IR

Edit 2026-02-10: Linked graph generator and new ufmt version

Edit 2026-04-11: Build Diagnostics flag

 1// Imagine this is for a tile-based 2D game or something
 2generate_level :: proc(some_params: ...) {
 3    some_temp_state_1, some_temp_state_2: int
 4    for i in 0..<N {
 5        // generate land tiles ...
 6    }
 7    for iter in 0..<4 {
 8        // run cellular automata ...
 9    }
10    for x in 0..<SIZE do for y in 0..<SIZE {
11        // spawn entity ...
12    }
13}

All the logic being contained within one big procedure (possibly with a few helpers) is quite nice, especially for prototyping.

But, what if something goes wrong, and the debugger, logging or 2D/3D visuals don’t help?

You might want to inspect what the actual iterations are doing.

The usual solution

If you’re using a managed language with coroutines, you can just yield from the procedure.

In other cases, you likely need to completely refactor your state management, put in a state machine, and split up the code a lot. I really don’t want to do that.

No-refactoring approach

So here’s my 1-million-IQ solution.

What if you just re-ran the entire procedure, stopping at a different point each time? The observable effect is just like with coroutines.

So let’s try that! Here’s a helper proc to mark each “step” of the algorithm:

1max_iter: int
2curr_iter: int
3
4_iter :: proc(n := 1) -> (ok: bool) {
5    ok = curr_iter < max_iter
6    curr_iter += n
7    return ok
8}

Now all you need is to instrument your generate_level procedure:

 1generate_level :: proc(some_params: ...) {
 2    some_temp_state_1, some_temp_state_2: int
 3    for i in 0..<N {
 4        // generate land tiles ...
 5        _iter() or_return
 6    }
 7    for iter in 0..<4 {
 8        // run cellular automata ...
 9        _iter() or_return
10    }
11    for x in 0..<SIZE do for y in 0..<SIZE {
12        // spawn entity ...
13        _iter() or_return
14    }
15}

In case you’re not using Odin, you can use if (!_iter()) return or another equivalent instead of or_return

And a way to control max_iter:

1max_iter = 0
2for app_main_loop_running {
3    max_iter += 1
4    generate_level(...)
5    debug_draw_level()
6}

And that’s it. Of course it works only if generate_level is reasonably fast, otherwise you’d have use other methods.

Thanks for reading, I hope it saves you some refactoring time.

Often, those problems are straightforward to solve: it’s just a forgotten zero-check before dividing, normalizing zero-length vector, etc. I almost always find it immediately by looking through my most recent changes. But this time I had no idea!

So I came up with a simple way to help catching these bugs in general (in fact, it’s so simple it’s probably the first thing you would think of too). But it’s a nice pattern, so I thought I would share it anyway.

Gameplay testing in general

Testing games can be really complicated, since the final output is just pixels and audio. I have few “real unit tests” in my codebase, mostly for things like file formats. Those usually look like this:

1. Setup state
2. Execute some logic
3. Assert correct results

That’s just not useful for most gameplay code.

Most of the bugs happen when the setup gets complex enough and the multiple systems interact together. And the expected results change all the time as you’re iterating on your game design.

So, what if instead of writing isolated tests, I just inserted the correctness validation (step 3) throughout the codebase? It limits what you can do, but IMO it’s still useful.

Validation

First I created validation procedures for common data types, e.g. a float:

1validate_f32 :: proc(x: f32) {
2    assert(!math.is_nan(x))
3    assert(!math.is_inf(x))
4}

Then it’s easy to use this for validating other data:

1validate_vec :: proc(v: [$N]f32) {
2    for f in v {
3        validate_f32(f)
4    }
5}

And then validating actual entities:

1validate_entity :: proc(ent: ^Entity) {
2    validate_vec(ent.position)
3    validate_vec(ent.velocity)
4    // arbitrary limits depending on what's reasonable for the game
5    assert(ent.position.y > -1000)
6    assert(linalg.length(ent.position) < 10000)
7    assert(linalg.length(ent.velocity) < 10000)
8}

The validation procedure asserts the data isn’t in a completely unreasonable state.

I also add a @(disabled = !DEV_BUILD) to all those procedures since I don’t really need validation in release mode.

Instrumenting code with validation

Now, let’s just slap the validation in the most important parts of the codebase. I know this is really grug-brained, but just a few calls in the right places got me a lot of coverage!

The point is to reliably catch possible errors soon after they happen, rather than letting them propagate for multiple frames before the issue becomes visible. This is about debuggability - not necessarily 100% correctness.

Here is a pattern I use a lot: validate every entity at the start and the end of interface procs like entity_tick, entity_damage, entity_interact etc. The defer makes sure it’s called on every return.

1entity_tick :: proc(ent: ^Entity, delta: f32) {
2    validate_entity(ent^)
3    defer validate_entity(ent^)
4
5    // gameplay logic...
6}

This is kinda like the “assert everywhere” advice, just in a slightly different form.

With this in place, I’m significantly more confident I can debug issues with NaN etc much easier.

Failed approach: catching FP exceptions

Before this approach I also tried to catch FP exceptions directly at the source. Turns out this isn’t really viable due to SIMD codegen of modern compilers (I won’t go into details here…)

But in case you wanna try it yourself, here is a Github gist for enabling the exceptions on win32 with Odin.

The general idea is this: the game would keep an accumulator timer and only simulate steps with a constant delta time, which is great for stability and predictability.

This was mostly inspired by server code for multiplayer games, so I naturally also implemented game state interpolation, which multiplayer games use as well. However I have some issues with regular interpolation, it adds unnecessary latency and it’s also annoying to implement.

Turns out there are other ways to do it! It’s possible to use the game tick to “predict” the render game state without explicitly writing any interpolation code. That’s what this post is about.

I also made a Demo program which implements all of the different methods mentioned.

The “old” way

Here is what the old game loop looked like. The game kept track of the game state from the previous tick, and then used this for interpolation with the time remainder.

 1DELTA :: 1.0 / 60.0
 2
 3accumulator: f32
 4game: Game
 5prev_game: Game
 6prev_time := time.tick_now()
 7
 8for !quit {
 9    frame_duration := f32(time.duration_seconds(time.tick_since(prev_time)))
10    prev_time = time.tick_now()
11    accumulator += frame_duration
12    for ;accumulator > DELTA; accumulator -= DELTA {
13        runtime.mem_copy_non_overlapping(&prev_game, &game, size_of(Game))
14        game_tick(&game, DELTA)
15    }
16    // Remainder to go from fixed time to real time.
17    // Always in 0..1 range.
18    alpha := accumulator / DELTA
19    // Interpolates between previous and current game state with the alpha factor.
20    game_draw(game, prev_game, alpha)
21}

Can we do better?

The fundamental issue is that the fixed timestep simulation does as many timesteps as possible, however because the frame-rate is variable, the real time doesn’t always match the fixed time.

So the solution is very simple, after the fixed timestep simulation is done, we need to simulate one more additional tick with the remaining time. However this additional tick could mess up our game state, because the time step is no longer fixed - this is a problem especially for things like physics.

Render Tick

For this reason we duplicate the entire game state into a new, temporary render-only game state, and simulate the tick on this one. That way the fixed timestep game state stays untouched. So we “predict” what’s gonna happen at a particular point in time between current fixed tick and the next one.

 1DELTA :: 1.0 / 60.0
 2
 3accumulator: f32
 4game: Game
 5temp_game: Game
 6prev_time := time.tick_now()
 7
 8for !quit {
 9    frame_duration := f32(time.duration_seconds(time.tick_since(prev_time)))
10    prev_time = time.tick_now()
11    accumulator += frame_duration
12    for ;accumulator > DELTA; accumulator -= DELTA {
13        // Simulate the game state (without keeping previous game state!)
14        game_tick(&game, DELTA)
15    }
16    // Remainder to go from fixed time to real time.
17    // Always in 0..DELTA range.
18    alpha := accumulator
19    // "Create" a duplicate version of the game state so our
20    // "render tick" doesn't affect the real game state.
21    runtime.mem_copy_non_overlapping(&temp_game, &game, size_of(Game))
22    // Simulate the temp state forward in time to match reality.
23    game_tick(&temp_game, alpha)
24    // No need to do any interpolation now, just render the game state as it is.
25    // It matches real time pretty much perfectly.
26    game_draw(temp_game)
27}

Note: This method probably won’t work very well in cases when game_tick can take a very significant amount of time, or the game state is gigantic, e.g. in a big AAA game which needs to run the physics engine and whatnot.

Game state duplication

In a more traditional system with individually dynamically allocated objects this might be a bit of an issue. Even if your language can do a deep copy of an object which holds the game state, the individual allocations could take a long time or it could make the GC sad.

In my case the entire game state is trivially copyable, because:

1. I never store any pointers. ever. Only integer indexes or handles.
2. All of the datastructures are fixed size, no dynamic allocations.

That means I can easily do memcpy and get a duplicate game state without any issues. This setup makes things a whole lot easier to deal with.

What about input?

Just like the last time, the game_tick needs to get the input from somewhere. This is easy, because the main update loop is pretty much the same like in the interpolation case! So the solution from my original post still applies, you can just use a separate frame_input and a tick_input.

But what about the temp render tick?

But I found re-applying the tick_input in exactly the same way as in the fixed update loop works decently well. You also want to clear the “pressed” and “released” flags from the input, because those were already applied in the fixed update loop. If you use my implementation from previous article you don’t need to do this directly, the fixed update loop does this on it’s own anyway.

So here is how to accumulate the input states every frame:

1tick_input.cursor = frame_input.cursor
2// _accumulate_ temp flags instead of overwriting
3for flags, action in frame_input.actions {
4    // Bitwise OR the bit flags
5    tick_input.actions[action] += flags
6}

And this is how to apply it. Note how the temp flags are cleared after every tick, and all flags are cleared at the end of a frame when any tick happened.

1any_tick := accumulator > delta
2for ;accumulator > delta; accumulator -= delta {
3    game_tick(&game, tick_input, delta)
4    input_clear_temp(&tick_input)
5}
6runtime.mem_copy_non_overlapping(&temp_game, &game, size_of(Game))
7game_tick(&temp_game, tick_input, accumulator)
8game_draw(temp_game)
9if any_tick do tick_input = {}

(see the Demo source code for the full implementation)

Different TPS is a fundamentally different problem

Something I’ve realized while working on this post and the Demo is how different the problem you’re trying to solve is, depending on your TPS. So here is what I think is a good way to roughly categorize it:

• ~10 TPS: Here the way you render the in-between game states matters a lot. Latency from interpolation is huge but the predicted render ticks can be jittery because of different simulation results. And the exact way you accumulate inputs and how you pass them in the game matters a lot as well. This is completely unusable for any kind of real time action game.

• 30-60 TPS: This is the most common for regular games. In this case the render tick method works really well, because there is almost no jitter due to input sampling inaccuracies. But the smoothing is still very visible. The added latency from interpolation is not that noticeable. However if you’re making a fast-paced action game, you probably want to eliminate every millisecond of unnecessary latency.

• ~120+ TPS: At this point any kind of interpolation accounts for only a tiny fraction of a second. The only reason you might want to use it to remove some jitter, but it’s just not very significant.

Accumulated render tick

In case you wanted to run only a very small number of fixed update ticks per second, the basic render tick method described above has some limitations. The temporary render tick always uses the last fixed tick, which means as your fixed delta increases your render tick might be doing a single, very large time step.

This is not an issue in most singleplayer PC games. That’s because you probably want to simulate >30 ticks per second anyway, for stability reasons and just because there’s no reason to push TPS lower.

The solution is to copy game state into temp game state only if you simulated a fixed tick that frame. Otherwise you keep simulating the old temp game state. This also means you need to keep another separate remainder timer, because alpha is no longer valid for each render tick.

This is similar to client-side prediction in real-time multiplayer games.

One issue is jitter, the difference in frequency of input between fixed and predicted ticks is so significant the render game state can get out of sync. One solution is to interpolate to sync the game states instead of doing that instantly. Alternatively you could modify the render tick inputs to eliminate high frequency inputs, and maybe even completely disable “pressed” and “released” key events.

I don’t do this in my game, simply because I didn’t run into issues with the current, simpler approach. But I thought I should mention it anyway.

Demo

I wrote a small demo game in Odin and Raylib to demonstrate the different fixed timestep rendering methods.

See the Github Repository for source code.

Here is how the various simulation modes look like when running at 4 ticks per second. This is a very low TPS only for demonstration purposes.

Without any kind of smoothing at all the game is very choppy:

The regular interpolation looks smooth but it’s a bit delayed (the “onion skinning” shows the current game state drawn as green, previous as red):

This is the regular render tick method, it looks fairly smooth and importantly there is no lag:

Here is a very high TPS simulation just for comparison:

Overview

Let’s summarize the all the different methods from the demo and how they compare to each other. There is no clear winner, it depends on your engine, game and your circumstances.

• Interpolation: Always smooth. Needs a way to interpolate two game states, this can be a pain to implement. Always lags one tick behind - this means worse latency, especially with low TPS.

• Render Tick: No added latency, matches real time “perfectly”. Very easy to implement, especially if your game state and tick is set up in a nice way. However the single render tick can get inaccurate with low TPS because each update step is linear.

• Accumulated Render Tick: More accurate in low TPS simulations, however because of the input frequency is so different between the predicted and the fixed ticks it can get out of sync.

In my case, I’m making a fast paced singleplayer game and I have no issue setting the TPS to 30 or even 60. For this reason the Render Tick is by far the best fit.

Tangent: determinism and replay

This isn’t related to the main topic of this post, because it applies to any kind of gameplay where the timestep is fixed (it doesn’t matter whether you use prediction or interpolation). But if your gameplay is deterministic, meaning you always get the same game state T+1 by simulating game state T with the same input, there is a neat trick to do game replay.

Regular replay systems would have to periodically store the game state, which ends up consuming a lot of memory, even if you try to compress it. But if your game is deterministic you only need to store the starting game state (or even just the starting settings to generate the game state), and then inputs for all the fixed timesteps. Then when you can just simulate the original game state N times to get any tick you want, once you need to do the replay.

By the way, this is what Media Molecule does in Dreams. The Trackmania racing games do this as well, to verify runs and make sure people aren’t cheating. Even their 3d physics engine is fully deterministic! very cool stuff.

Notes:

1. You need to make sure entities are always updated in the same order. This means deterministic O(1) datastructures like pools are your friend.
2. If you use random numbers then you need to make sure the seeds match at the start of every tick as well. You can probably get by storing only one seed along with the first
3. The stored replay gets invalidated once you change your gameplay logic, so this method is generally useful for debugging only.

That’s all!

Thank you for reading, I hope this can be useful in your engine/game project! Also let me know if you have any feedback, if you know how to improve any of the methods I explained here, or you know of an even better method:)

Credit

After I published the original blog post, a number of people messaged me it helped them with use fixed timestep update loops in their game/engine as well. However some people complained specifically about the interpolation step, it can be kinda cumbersome to do, especially if you want to interpolate more properties than just the entity transform.

I was told about the render tick method by Radek Jurga on discord, a fellow handmade programmer. He uses it in his engine as well! And he found out about it from an old Jonathan Blow Q&A stream which is a much more in-depth explanation of this entire topic.

Note: this was initially supposed to be my first supporter-only Patreon post. But their tools for writing posts kinda suck so I thought hey, let’s just release it for free.

Anyway it would mean a lot to me if you decided to support me anyway! Here is my Patreon link

This is an behind-the-scenes look at my design process for the first iteration of a logo for my new game, BEHEADER.

I use Krita, it’s a pretty good and free photoshop alternative. It doesn’t have all of the fancy features but there are enough filters for me to do all I need.

Basic Shape

I started with a basic text with gothic font (Old English Text MT). This serves as a base for everything else. I duplicated the layer and “flattened” it so I can work with the pixels instead of the vector representation.

Then I added distortions using the transform tool. First I added a bit of perspective to make the bottom larger, then I used the warp tool to make the center curve up a bit. And then I used the liquify tool as a brush to distort it even more and add those spiky details.

Here is what it looks like after all those distortions:

Shading

Now the shape looks good, let’s add the colors. I wanted the reflective chrome effect with lighting etc, so I started by generating a normal map.

But the default normal map is kinda flat, so let’s just use the Gaussian Blur filter to smoothen it out a bit.

And since I only care about the “Y-axis normal”, I removed the red and blue channels, and then desaturated it to get this black and white texture:

Okay, that’s all we need to start doing the shading. I used a Gradient Map filter to map specific brightness to some cool colors.

I also used dithering with a grunge texture instead of the default linear interpolation. This depends on the style you’re going for.

Pro tip: you can click the “Create Filter Mask” button in the filter settings to create a non-destructive filter layer.

And here is what it looks like with the gradient:

Finishing

But because the normal map and blur filters changed the text borders, we need to somehow mask it to make the edges crisp again. I did this by duplicating the original white texture and inverting the alpha (with color curves). Then you place this layer above all other layers and it clips everything correctly.

And this is the final result! I’m happy with it, especially since it’s the first iteration of the logo. I still plan on improving it before I launch the Steam Page. I think I would like to make it all caps instead, and also improve the readability a bit.

Alternative shading method: blinn Phong lights

Here is anoter color combination I made. Instead of gradient map I used the phong shading filter which lets you set up lights from various directions.

I used the following settings to sort of a metal material.

And here is the settings for light sources, many possibilities here

But it seems like it’s mostly targeted at physics simulations, and it doesn’t cover a few things you need to make your entire game run on fixed timesteps. For example, how to handle input polling properly! That’s what I’ll try to cover today, as well as some reasoning behind this game architecture.

I use a slightly modified version of the update loop from Gaffer’s article, here is a simplified version in Odin:

 1DELTA :: 1.0 / 60.0
 2
 3accumulator: f32
 4game: Game
 5prev_game: Game
 6prev_time := time.tick_now()
 7
 8for !quit {
 9    frame_duration := f32(time.duration_seconds(time.tick_since(prev_time)))
10    prev_time = time.tick_now()
11    accumulator += frame_duration
12    num_ticks := int(floor(accumulator / DELTA))
13    accumulator -= f32(num_ticks) * DELTA
14    for tick_index in 0 ..< num_ticks {
15        runtime.mem_copy_non_overlapping(&prev_game, &game, size_of(Game))
16        game_tick(&game, prev_game, input, DELTA)
17    }
18    alpha = accumulator / DELTA
19    game_draw(game, prev_game, alpha)
20}

The main difference is that I calculate number of ticks from the accumulator, instead of running a while loop and subtracting delta from the accumulator directly. I find this a bit nicer but there isn’t much difference.

Note: if you use floating point numbers you might run into float cancellation precision issues. An alternative is to use 64 bit ints to store nanoseconds directly and do all computations with those. And then convert the delta to float later once you need it. Thanks to Graphite for telling me about this!

How engines separate update and physics ticks

It’s fairly common for game engines to separate regular ticks and physics ticks. For example, unity components have an Update function which runs every frame and FixedUpdate function which runs 50 times a second (by default) during physics tick.

I really don’t like this separation.

It often makes gameplay code which interacts with physics much more convoluted, because it forces you to split your update logic into two places. It can be very confusing for beginner programmers. And in general setting up your simulation this way makes it easier to write frame-rate dependent and less stable gameplay code.

A single fixed timestep tick for both gameplay and physics

So what’s the alternative?

To have one big tick procedure which updates everything in the game, including gameplay, physics, etc. And then run this tick in a fixed update loop.

This way the game simulation is completely independent from “frames” and rendering.

It could be complicated to do this in an already existing engine, or if you use one of the common rigidbody physics engines. But I have a custom engine and custom collision system, so I can set it up however I like :P

Interpolating everything

Okay, what about rendering then?

You could just run your ticks in a fixed update loop, and then rendered the final game state every frame. However the “tick time” and “frame time” doesn’t match perfectly. And in cases when the frame rate is much higher than tick rate, the game could look very laggy.

The solution is interpolation.

Now game_draw takes two game states, and interpolates between them based on the alpha factor. Here is an example of interpolating the camera and enemies:

 1game_draw :: proc(game, prev_game: Game, alpha: f32) {
 2    camera := Camera{
 3        pos = lerp(prev_game.camera.pos, game.camera.pos, alpha),
 4        rot = slerp(prev_game.camera.rot, game.camera.rot, alpha),
 5    }
 6
 7    for curr_enemy, i in game.enemies {
 8        prev_enemy := prev_game.enemies[i]
 9        enemy := curr_enemy
10        enemy.transform = lerp_transform(
11            prev_enemy.transform, enemy.transform, alpha)
12        draw_model(.Grunt_Enemy, enemy.transform, COLOR_RED)
13    }
14}

The same concept applies to everything else, you can interpolate whatever properties you need. You could probably even automate it in a proper entity system, or if you use a scripting language.

Double-buffered game state

As you can see there are two copies of entire game state. This makes it easy to do interpolation, and you can also use the previous game state for many things in gameplay code as well.

I initially got this idea from Dreams by Media Molecule. It’s a really smart engine architecture, which Alex Evans explained in one of their streams.

If you use fixed size datastructures and never dynamically allocate memory like I do, copying the game state is just a single big memcpy once per tick. But in case you want to use dynamic memory, you could use arena allocators or some kind of memory pools to make copying game state trivial as well.

What about input?

As you can see the game_tick procedure takes an input parameter, but where did that come from? Glenn’s article doesn’t cover this, probably because he’s mostly concerned with physics simulations. But in our case it’s crucial to get the correct results.

Just for context, here is how my (simplified) input state looks like. This isn’t very important, but note I don’t use an “input event queue” in gameplay code. I just use procedures like input_is_key_down(inp, .Left_Shift) etc.

 1Input :: struct {
 2    cursor_pos:    Vec2,
 3    cursor_delta:  Vec2,
 4    scroll_delta:  f32,
 5    mouse_buttons: [Input_Mouse_Button]bit_set[Input_Digital_Flags],
 6    keys:          [Input_Key]bit_set[Input_Digital_Flags],
 7}
 8
 9Input_Digital_Flags :: enum u8 {
10    Down,
11    Changed_This_Frame,
12    Repeated,
13    Multiple_Changes_This_Frame,
14}

Okay, now let’s see how to pass the inputs into the game_tick procedure.

The naive solution is to just pass your regular input state like you would normally:

 1frame_input: Input
 2// ...
 3
 4for !quit {
 5    for event in events {
 6    case .Key_Down:
 7        input_add_key_down(&frame_input, key)
 8    // handle other (input) events...
 9    }
10
11    // ...
12        game_tick(&game, prev_game, frame_input, DELTA)
13    // ...
14
15    // Clear input flags for things like "pressed", "released" etc.
16    // but keep "down" states
17    input_clear_temp(&frame_input)
18}

But, this has a number of problems:

1. Inputs are lost when there are no ticks to run for few frames.
2. Mouse delta is applied multiple times
3. Key states which should only be valid for one frame (like Pressed and Released) are passed into game_tick multiple times.

Solution 1: Poll inputs every tick

This might technically be the “best” solution to this problem, because you also get the most accurate results this way. However it might not be practical because your app only has one event loop, and you need regular frame inputs too. You could probably poll events and then “save” non-input ones for later, but IMO it’s probably unnecessary for many games.

Solution 2: Accumulate tick inputs separately

This is what I went with, because it’s simple and the accuracy loss from not polling inputs every tick isn’t noticeable.

The idea is to keep two separate input states, one for “per frame” stuff and the other one for ticks. Both are updated with the same events at the start of your frame, but the state is updated in a different way during the frame.

First idea is to discard temporary key flags (like Pressed and Released) after every tick, so they aren’t applied multiple times.

Then, we can also divide the mouse delta by number of ticks to apply it over time. Alternatively you could skip this and set the delta to zero after every tick, but I think splitting the delta over multiple ticks is nicer. Finally, you clear the rest of temporary input data once you ran all your ticks.

Here is the update loop example code:

 1DELTA :: 1.0 / 60.0
 2
 3frame_input: Input
 4tick_input: Input
 5
 6accumulator: f32
 7game: Game
 8prev_game: Game
 9prev_time := time.tick_now()
10
11for !quit {
12    // Accumulates the input events to both frame and tick input states
13    for event in events {
14    case .Key_Down:
15        input_add_key_down(&frame_input, event.key)
16        input_add_key_down(&tick_input, eveny.key)
17    case .Key_Up:
18        input_add_key_up(&frame_input, event.key)
19        input_add_key_up(&tick_input, event.key)
20    // case ...
21        // handle other (input) events, as well as mouse buttons and mouse move...
22    }
23
24    frame_duration := f32(time.duration_seconds(time.tick_since(prev_time)))
25    prev_time = time.tick_now()
26    accumulator += frame_duration
27    num_ticks := int(floor(accumulator / DELTA))
28    accumulator -= f32(num_ticks) * DELTA
29
30    if num_ticks > 0 {
31        tick_input.cursor_delta /= f32(num_ticks)
32        tick_input.scroll_delta /= f32(num_ticks)
33
34        for tick_index in 0 ..< num_ticks {
35            runtime.mem_copy_non_overlapping(&prev_game, &game, size_of(Game))
36            game_tick(&game, prev_game, tick_input, DELTA)
37            // Clear temporary flags
38            for &flags in tick_input.keys do flags &= {.Down}
39            for &flags in tick_input.mouse_buttons do flags &= {.Down}
40        }
41
42        // Now clear the rest of the input state
43        tick_input.cursor_delta = {}
44        tick_input.scroll_delta = {}
45    }
46
47    alpha = accumulator / DELTA
48    game_draw(game, prev_game, alpha)
49}

And that’s it! This is the solution I currently use in my engine and works well so far. Let me know if you run into any problems or if you have a better solution in mind :)

Thanks for reading!

A few weeks ago I started working on a new project, it’s a 3D FPS game inspired by Quake and other ’90s shooters. The world is a 16x16x16 uniform grid of blocks, and it loops infinitely. Here is a clip of the game prototype:

This is a small boomer shooter prototype I've been working on lately. The world is 16x16x16 blocks and it infinitely repeats itself.#gamedev pic.twitter.com/ONrkzmf5t2

— Jakub Tomšů (@jakubtomsu_) May 24, 2024

This clip uses procedurally generated levels. Those are cool, but don’t have that much structure and interesting stuff going on. So I quickly decided I need to hand-craft levels for them to reach the full potential.

So I wrote a simple level editor. It was surprisingly quick, I had all of the basic functionality implemented within a few hours. One of the problems I had to solve was undo/redo system, which seems very challenging but doesn’t have to be. I found a very simple way to structure the code to make the implementation trivial.

My implementation is inspired by rxi’s Simple Undo System and Dennis Gustaffson’s Undo for Lazy Programmers

Level Representation

First, let’s define the data for our level. In my case it’s very simple, but it’s easy to extend if necessary.

 1Level :: struct {
 2    using info:   Level_Info,
 3    cells:        Level_Cells,
 4    detail_cells: Level_Detail_Cells,
 5}
 6
 7Level_Cells :: [LEVEL_BOUNDS_X][LEVEL_BOUNDS_Y][LEVEL_BOUNDS_Z]Cell // Cell is a u8 enum
 8
 9Level_Detail_Cells :: [LEVEL_BOUNDS_X][LEVEL_BOUNDS_Y][LEVEL_BOUNDS_Z]Detail_Cell
10
11Level_Info :: struct {
12    size:      IVec3,
13    fog_color: Vec3,
14}

The goal here is to organize the level representation into a bunch of “chunks” (mostly by size and importance). All miscellaneous level metadata goes into Level_Info but other big chunks of data are a separate member.

Note: this assumes all of your level data is statically allocated and trivially copyable. I do this for all of my data anyway, I think there isn’t a reason to use any dynamic allocation for the use cases I care about. I might write a blog about this another time, it’s a very useful way to think about data and not many people talk about it. It’s always borrow checker/RAII/Arenas/Custom Allocators…

Save Points

Now, let’s define a way to store a single “change” to the data. This acts as a save point the user can go back to.

1Editor_Undo_Item :: union {
2    Level_Info,
3    Level_Cells,
4    Level_Detail_Cells,
5}

This stores a change to a part of a level. It’s a tagged union, so the total size is the size of the largest item.

This allows me to easily store a change to any part of a level. That’s why I separated the level into chunks in the previous step, it makes it easier to organize changes into groups. In theory you could save the entire level on every change. But this is almost as simple and can save a lot of memory.

This way every change takes up memory for the “worst-case”, which might seem bad at first but it’s actually completely fine. In my case one undo item is 4 kilobytes, which is almost nothing these days. This system also scales really well in cases where you modify most or all of the cells, and doesn’t create unexpected spikes. But the reasons for focusing on worst-case computation is a big topic, let’s leave that for another blog post :)

History Buffers

Let’s define a way to store the actual edits within our editor state.

1Editor :: struct {
2    level: Level, // current level data
3    undo:  Queue(2048, Editor_Undo_Item),
4    redo:  Queue(2048, Editor_Undo_Item),
5    // other editor state...
6}

The editor stores two queues (ring buffers) of edits, one for Undo and one for Redo. The reason why I use a queue is to have the ability to “force push” an edit at the end. If I used a regular array/stack, I would need to shift all other items down by one slot. The queue I use comes from my own small library for static datastructures, but you could use something like core:container/queue as well.

1editor_undo_push :: proc(ed: ^Editor, item: Editor_Undo_Item) {
2    // Makes sure the item is always pushed back into the queue, even if it's full.
3    queue_push_back_force(&ed.undo, item)
4}

This is the procedure for pushing save points before any edits. I pass the state which will be changed, and then perform the change. Here is an example of placing wall blocks on a mouse click:

1if input_pressed(.Mouse_Left) {
2    editor_undo_push(ed, ed.level.cells)
3    // Do any modifications to level.cells...
4    ed.level.cells[cursor.x][cursor.y][cursor.z] = .Wall
5}

Ctrl+Z and Ctrl+Shift+Z

This is all I need to implement the actual undo/redo functionality. This logic is the same as in rxi’s article. Pop from one buffer, and before applying the data push the current state to the other buffer.

 1block: if input_pressed(inp, .Z) || input_repeated(inp, .Z) {
 2    modifiers: bit_set[Input_Modifier] = input_modifiers_down(inp)
 3
 4    // Pop the data from a change buffer depending on the operation
 5    // Breaks out of this entire scope if it's empty
 6    change: Editor_Undo_Item
 7    switch modifiers {
 8    case {.Left_Control}:
 9        change = queue_pop_back_safe(&ed.undo) or_break block
10    case {.Left_Control, .Left_Shift}:
11        change = queue_pop_back_safe(&ed.redo) or_break block
12    case:
13        break block
14    }
15
16    // Prepare a save point for the current data
17    // Write the change to the current state
18    prev: Editor_Undo_Item
19    switch v in change {
20    case Level_Info:
21        prev = ed.level.info
22        ed.level.info = v
23    case Level_Cells:
24        prev = ed.level.cells
25        ed.level.cells = v
26    case Level_Detail_Cells
27        prev = ed.level.detail_cells
28        ed.level.detail_cells = v
29    }
30
31    // Push the current data into the _other_ buffer
32    switch modifiers {
33    case {.Left_Control}:
34        queue_push_back_force(&ed.redo, prev)
35    case {.Left_Control, .Left_Shift}:
36        queue_push_back_force(&ed.undo, prev)
37    }
38}

And that’s it! Turns out this entire system is not many lines of code at all, and is efficient even when you use worst-case-sized statically allocated data structures. That said, it’s not a one-size-fits-all method. If you have gigantic scenes you probably need to look into other approaches (maybe XOR and RLE compressed delta states? LZ4? idk).

But this is fine for basically anything an indie developer might need in 99% of cases. Hope this helps, thank you for reading!

Solar Storm is an upcoming tactical sci-fi artillery game. It’s a solo project I’ve been writing in a custom engine for the last ~4 months. It’s inspired by local multiplayer games from the 90s like Scorched Earth (1991) and Worms (1995). The entire game is written from scratch in the Odin programming language.

Play Solar Storm on Steam and Join our Discord!

The game engine is built with the help of Sokol. It’s a set of STB-style cross-platform libraries for C/C++, with an official support for Odin as well as some other languages. In particular, I use sokol_app for windowing and interfacing with the OS, and sokol_gfx as an rendering API abstraction.

Similar to libraries like SDL2 or GLFW, sokol_app provides a cross-platform API for interacting with the OS. But like all other sokol modules, it’s just a single, lightweight C/C++ header file, which makes it really nice to work with.

So let’s talk about the Solar Storm rendering a bit. The entire renderer is built on sokol_gfx, with custom shaders, render passes, and all that fun stuff.

Here is a sneak peek at the different steps of the rendering process:

Shaders

The shaders are written in Sokol’s flavor of GLSL, which has a cross-platform shader compiler called sokol-shdc. Usually writing shaders for multiple rendering APIs is a lot of pain. But sokol-shdc uses libraries like GLSLang, SPIRV-Tools, SPIRV-Cross to transpile them for the appropriate platform.

Another nice aspect is that the compiler can generate source code and boilerplate for any language supported by Sokol. Here is an example command of compiling shaders with sokol-shdc:

sokol-shdc.exe -i shaders.glsl -o shaders.odin -l hlsl5:glsl330 -f sokol_odin

And here is how a simple sokol-style GLSL looks like:

 1@vs vs
 2uniform vs_params {
 3    mat4 mvp; // transformation matrix for current mesh
 4};
 5in vec4 position;
 6in vec2 texcoord0;
 7out vec2 uv;
 8
 9void main() {
10    gl_Position = mvp * position; // transform vertex position
11    uv = texcoord0; // pass mesh UVs to fragment shader
12}
13@end
14
15@fs fs
16uniform texture2D tex; // Note the texture and the sampler is separated
17uniform sampler smp;
18in vec2 uv;
19out vec4 frag_color; // pixel color
20
21void main() {
22    frag_color = texture(sampler2D(tex, smp), uv);
23}
24@end
25
26@program foo vs fs

Immediate-mode APIs are amazing

A core philosophy of the renderer is to do as much as possible with immediate-mode APIs, and group rendering operations so Instancing is trivial.

Immediate-mode APIs are well known for UIs, but the core idea can actually be applied to almost any context. In games, where you often do an action every frame, the idea is incredibly powerful. I use it many places in the engine, for things like collision, physics, drawing shapes and text, UI, debug gizmos, localization and particle effects.

The game uses immediate mode API exposed by the renderer for all drawing operations. Each frame game calls draw_shape, draw_text, draw_sprite and draw_ui_rect to draw everything. That includes players, particle effects, ImGui system, projectiles and explosions. This way it becomes much easier to do dynamic effects, since there is no state at all that needs to be managed. Here is an example of drawing simple animated octagon which rotates over time:

1draw_shape(
2   pos = {0, 0},
3   scale = 10,
4   rot = time_passed(),
5   color = COLOR_RED,
6   z = 0.1,
7   shape = .Octagon)

Immediate-mode text drawing has an interesting benefit of dynamic animations. The draw_text procedure returns a slice of the text character instances, so you can do any modifications yourself. Here is a simple example:

1chars := draw_text({100, 200}, "Hello world!")
2for &ch, i in chars {
3    ch.pos.y += sin(time_passed() + f32(i)) // animate up and down
4}

This code runs every frame, and updates the character instances right before being submitted to the GPU and displayed. There is state in the background, but the API is fully immediate-mode. immediate-mode != stateless

World pass

The terrain is drawn as a single quad. A shader which reads from the terrain SDF texture and a color texture and does the shading. Explaining the terrain in-depth is out of scope for this article, let’s do that another time…

There is also a shader for rendering the background and another one for wind. The background shader draws stars using perlin noise raised to a very high power. The wind is also just perlin noise, but this time it’s stretched horizontally and has some distortion to add some wiggle.

All world-space elements are rendered into a custom render target. It’s a texture with single channel per pixel in the R8_UNORM format. This pass also uses a depth buffer for ordering objects instead of sorting. It’s essentially free on modern hardware and it makes things easier.

Shapes

All of the other things in the game are rendered using primitive shapes. Every frame, the game pushes shape instances to instance buffers, which then get uploaded to the GPU memory once it’s time to render them. This uses an immediate API in the form of draw_shape procedure.

There is one instance buffer per shape type. It’s a simple fixed array of a shape instance struct, which has a memory layout the GPU can feed to the vertex shader in the form of per-instance parameters.

Here is the full list of supported shapes in the game as of now.

1Renderer_Shape :: enum u8 {
2    Triangle,
3    Rectangle,
4    Rhombus,
5    Pentagon,
6    Hexagon,
7    Octagon,
8}

Fun fact: the reason there is both rectangle and a rhombus is because they have different properties when doing non-uniform scaling. Rhombus is primarily used for sparks and other particle effects.

More complex shapes like tanks are made up of multiple shapes.

This is the shape instance struct, as it is handled both on the CPU and the GPU side. It’s 32 bytes with alignment, which could be significantly reduced but probably isn’t worth the effort. The right and up vectors have baked in rotation and scale, so they work like a 2x2 rotation matrix.

1Renderer_Shape_Instance :: struct {
2    pos:   Vec3, // world-space position
3    right: Vec2, // local-space vector pointing to the right. 
4    up:    Vec2, // local-space vector pointing up
5    color: Color8, // RGBA8_UNORM color
6}

Here is all the state renderer keeps for shapes. The pipeline is shared for all shape types, and the buffers are created at load time. shape_instance_bufs are filled with instances from shape_instances prior to rendering. Array is just struct { data: [N]T, len: int }, it’s a custom version of odin’s core:container/small_array.

1shape_pipeline:      sg.Pipeline, // shader for all shapes
2shape_vertex_bufs:   [Renderer_Shape]sg.Buffer, // mesh vertices for each shape type
3shape_index_bufs:    [Renderer_Shape]sg.Buffer, // mesh indicies for each shape type
4shape_instance_bufs: [Renderer_Shape]sg.Buffer, // GPU buffer for instance data
5shape_instances:     [Renderer_Shape]Array(BUDGET_MAX_RENDERER_SHAPE_INSTANCES, Renderer_Shape_Instance),

All shapes of certain type are rendered using GPU instancing, this means it takes only about 6 drawcalls to render all shapes in the worst case. Here is how the game dispatches draw calls. Note: this code is a heavily simplified for the sake of clarity.

 1sg.apply_pipeline(renderer.shape_pipeline)
 2// Apply projection matrix
 3sg.apply_uniforms(.VS, shaders.SLOT_shape_vs_params, sg_range(&shaders.Shape_Vs_Params{mvp = mvp}))
 4// For each shape type...
 5for &arr, shape in renderer.shape_instances {
 6    // Clear the instances when done, since it's immediate-mode
 7    defer clear(&arr)
 8    
 9    // Upload the instance data for a particular type to the GPU
10    sg.update_buffer(
11        renderer.shape_instance_bufs[shape],
12        {ptr = &arr[0], size = u64(size_of(Renderer_Shape_Instance) * len(arr))})
13    
14    // Bind the mesh
15    sg.apply_bindings({
16        vertex_buffers = {
17            0 = renderer.shape_vertex_bufs[shape],
18            1 = renderer.shape_instance_bufs[shape]},
19        index_buffer = renderer.shape_index_bufs[shape]})
20
21    // Dispatch the drawcall for all instances of a shape.
22    // Single 'DrawIndexed' call when using D3D11
23    sg.draw(
24        base_element = 0,
25        num_elements = shape_num_elems[shape],
26        num_instances = len(arr))
27}

Here is an example of one drawcall, in this case hexagons:

That’s it for the world render pass, here is the result so far:

Postprocess pass

In the post processing pass, a shader takes the single channel world texture and does all post processing. That includes water reflections, palettization and outlines (in order).

The water relections involve calculating the UV coordinate from the reflected world-space coordinate, which is then sample the world texture again. So this is completely done in screenspace. The UV coordinate is also distorted with 1D and 2D perlin noise to make the surface look like actual water waves. The reflected color is also darkened the further from the water surface it is, and a soft vignette is applied around screen edges to make the transition smoother. The reflection is then blended with the world behind the water.

The palettization is there to convert the single-channel value to a RGB color. The value is used as an UV coordinate for looking up a color from a palette texture. Each biome in the game has a combination of colors to make it look more unique. The palette texture uses Nearest sampling mode, which is a stylistic choice.

Finally, the outlines are applied. Each pixel compares the depth value to it’s neighbors in a 5x5 block, and calculates outline weight based on that. The outline is applied to the already palettized color, to make it go towards pure black instead of the darkest palette color. It improves clarity, especially in biomes with a palette without much contrast.

Screenspace pass

Then all text character, icons, sprites and UI rectangles get drawn on top of the postprocessed image. There is nothing fancy about this step, but again, everything is drawn with just a couple of draw calls. This pass uses the depth buffer for ordering UI and text elements.

The UI, icons and text rendering are a big topic on their own, so I’ll leave that for later. I’m also considering switching from my own custom text rendeing to FontStash.

Display pass

And that’s it for the rendering! The last render pass just draws the final image to the actual swapchain texture, which gets displayed on your monitor.

Conclusion

The renderer spends up to 50 microseconds on the CPU submitting the commands. At the time of writing, it takes around 100 microseconds on a RTX2060 to actually draw everything.

This is CPU profiler trace using Spall:

Here is another profiler trace, this time from the GPU using PIX:

And here is the entire renderdoc capture of the game. The entire thing is just a couple of draw calls and buffer uploads.

github

DoQ is currently in Alpha version - there are still a lot of bugs to fix and features to add. The initial development took ~1 month.

screenshots

dqmake

DQMake is a super-simple tool for editing DoQ maps.

accessing source code

For a game, all of the gameplay source code is stored in \SomeGame\SomeGame_Data\Managed\Assembly-CSharp.dll. This is a dll (dynamically-linked library), which is generated from source files when the game is built. To get the original source code, you need to decompile this dll. Fortunately, C# is quite easy to decompile, and there are many free and open-source tools on the internet.
I personally really like dnSpy, since it’s also capable of compiling C# code (this means you can just change code from the original game)

injecting custom code

It is of course possible to develop an entire mod by editing the Assembly-CSharp.dll, but it’s easier to just create it separately and load it at startup time. This way your game can support multiple mods at the same time, because games can have one common loader for all mods.

If you want to inject the code yourself, here is a simple example how to load and run a C# dll:

 1using System.Reflection; // loading dll's at runtime
 2
 3// just loop all types and find the entry point method
 4// there are probably much better ways of doing this, but this worked for me
 5foreach(Type type in Assembly.LoadFile("some dll path").GetTypes()) {
 6	MethodInfo method = type.GetMethod("some method with unique name");
 7	if (!(method == null)) {
 8		object obj = Activator.CreateInstance(type);
 9		method.Invoke(obj, new object[0]);
10	}
11}

This code sould be ideally placed in some method that runs as early as possible. Probably Awake function on a component somewhere on the first loading screen, main menu, etc. is good enough.

inspecting the renderer

With tools like NVIDIA Nsight, RenderDoc, etc. you can easily inspect what your GPU is doing, and how the game actually renders each frame. You can also take a look at all kinds of resources in the game - shaders, textures, models, …

Here is a screenshot from Shady Knight when using RenderDoc: as you can see, it shows everything you might need