Karl2D

In the previous newsletter I announced the beta of my Karl2D game creation library.

Since then, I have been hard at work with adding audio support. I’m proud to finally have shipped the Beta 3: Audio support release!

A lot of different kind of work went into that release. The first thing was to play basic sounds and write a software mixer. I wrote a blog post about how I created the software mixer.

Other things I had to add to the library was:

• Audio streaming

• Possibility to play several sounds simultaneously

• Backends for Windows, Linux, Mac and Web

• Support for both mono and stereo audio

• Smooth volume changes to avoid cracks and pops

I think making my own software mixer was worth it: The audio backends for each platform are very small. They just give the samples to the audio API for that platform, and the way the audio sounds is identical on all platforms.

Sponsor Karl2D

Want to help me develop Karl2D faster? Sponsor me on GitHub or Patreon — You don’t have to be a sponsor forever! If you just want to sponsor for a few months in order to help during this period of rapid development, then that is super helpful! 💖

Book update

Since the last newsletter, I’ve done two updates of my book “Understanding the Odin Programming Language”: Version 1.9 and 1.10. You’ll find the change list for both updates here.

Version 1.9 addressed changes due to core:os/os2 becoming the new core:os package. Version 1.10 addressed changes due to Small_Array becoming [dynamic; N]T.

A return to YouTube

Those who watch my YouTube channel may have been sad that I didn’t post much during the last few months… That is now changing! I am again trying to make more videos and host more live streams. Here are two recent videos.

A video on my Karl2D audio support:

A video with Odin release highlights (I’m going to do one of these for every Odin release!)

Gamejam

This is an announcement of an announcement™. I am going to host a Karl2D gamejam sometime soon. I don’t have the complete details ready yet, but follow me on any of these platforms to make sure you don’t miss the announcement! More details within just a week or two!

• YouTube

• Discord server

• X

• Bluesky

Have a nice day!

/Karl Zylinski

It’s a 2D game creation library written in Odin that tries to be beginner friendly while also minimizing the number of dependencies. The focus is “easy to get started with, easy to ship the game”.

“easy to ship” actually never happens… Shipping games is always hard. What I mean is: Less problems due to the library you use, and easier to fix the problems when they do occur!

You’ll find the library here: https://github.com/karl-zylinski/karl2d

In the beta version that I just released, the feature set is as follows:

• Rendering of shapes, textures and text with automatic batching

• Support for shaders and cameras

• Windows support (D3D11 and OpenGL)

• Mac support (OpenGL)

• Linux support (OpenGL)

• Web support (WebGL, no emscripten needed!)

• Input: Mouse, keyboard, gamepad

Ok, that’s cool. Show me some examples!

A basic “hellope world” example would be this:

package hello_world

import k2 "karl2d"

main :: proc() {
	k2.init(1280, 720, "Greetings from Karl2D!")

	for k2.update() {
		k2.clear(k2.LIGHT_BLUE)
		k2.draw_text("Hellope!", {50, 50}, 100, k2.DARK_BLUE)
		k2.present()
	}

	k2.shutdown()
}

And it would look like this:

Or you can see it running in a browser here.

That’s not all that fun though. It’s just a piece of text, nothing interactive! Here are some more advanced live web examples, with their source code linked:

Basics example — Source here (draw textures and simple movement code)

Camera example — Source here (movable and rotatable camera, thank you to a contributor for making this example)

In the library’s README I show how to make these web builds. You can make both ordinary desktop games as well as web builds. The web builds will be very handy for game jam creations and such. The fact that they do not need emscripten makes the whole process a lot smoother, compared to creating Raylib web builds.

If you try the library out and want to show what you made, do please join my Discord server and post a video or web build link! :)

Platform architecture shenanigans

In previous newsletters I’ve talked about avoiding extra dependencies in order to make things more understandable and easily modifiable for you, the game dev!

I have some new fresh examples of this in this beta version. The current platforms are Windows, Linux, Mac and Web.

The Windows platform code you can see in platform_windows.odin — That one implements the windowing, events and gamepad support. It’s plain win32 API code without any other library in-between. If you have a Windows-only bug and you are stressed because you need to ship your game soon, then don’t worry. You can just go in and poke in that Windows platform code without affecting any other platform. No need to recompile some additional C library in debug mode and look for bugs in there. Odin libraries come as source, so you just make changes in the Karl2D source and recompile your game. Easy as PI.

The Linux platform code is quite different. You can see it in platform_linux.odin — There is no windowing code in there! The reason for this is that Linux doesn’t have a single windowing system. These days people use both X11 and Wayland. So instead of throwing in some bindings to some C library that talks to both, me and a contributor have added support for both! In platform_linux_window_x11.odin and platform_linux_window_wayland.odin you see the windowing code that the Linux platform layer calls into, depending on which is currently used.

Adding Wayland support wasn’t all that easy because Wayland is strange. It’s the new fancy Linux thing for managing windows that is supposed to replace X11. In order to talk to it we had to make bindings for something called libwayland.

libwayland isn’t much of a library: It’s just a client that can throw things to the Wayland server using the Wayland protocol. In order to figure out what is possible to communicate using the protocol you parse XML files that tell you what is available… Yes… Parse XML files, to generate code, in order to use a protocol, in order to open a window… 🙀

A much better idea would have been a plain C library!! They could make an extension mechanism for it and adding versioning of APIs wouldn’t be hard either.

I was literally laughing while working on the Wayland windowing. It was like a parody YouTube video about over-engineering. But it’s the new thing!! The thing that is going to save Linux and start The Year of Linux on the Desktop!!! AAAAAAAAAAAAaaaa

Wayland really is the worst windowing API I’ve ever used. Win32 and even X11 feels like a refreshing day in the sun in comparison.

Anyways. We managed to tame the Wayland beast. Phew.

You may say: “But if you used SDL or GLFW then you would just have 1 library to talk to!! Now you have Win32, Wayland, X11 and more. Isn’t that adding dependencies? You wanted to avoid dependencies!! But you are ADDING MORE!!!”

In my opinion, the “quote” above is the wrong way to think about this. If you think about it, SDL and GLFW has dependencies on Win32, X11, Wayland etc. So if you use for example GLFW, then you still have dependencies on Win32, X11 and Wayland, but with another another layer in-between. That extra layer is another dependency. And that layer is annoying to change, because it is written in C, and it does lots of things I do not need.

Anyways, I am happy with how the platform code has turned out. With the help of some contributors, we’ve been able to also build gamepad support for Mac and Linux. On Linux it goes straight to udev/evdev and talks to the gamepads that way. It’s pretty cool! It currently supports XBox and PlayStation controllers; give it a go! Here’s a web version of the gamepad example (the web version does not have vibration currently, I’ve put that off for some reason).

On Mac we’ve used the Cocoa framework for windowing and GameController + CoreHaptics for gamepads + vibration. Those are native OS libraries that are included on Mac. They seem to be at a reasonable abstraction level. Thanks to contributors for figuring that stuff out; I don’t have a recent enough mac to get that work done.

What’s missing?

This beta (known as Beta 2) does not have the follow features, but they are planned in the order stated:

• Sound

• System for cross-compiling shaders between different backends (HLSL, GLSL, GLSL ES, MSL etc)

• Metal rendering backend for Mac (OpenGL already works)

I have a few small tasks to do before starting on sound. My idea for sound is to write a software mixer and then output the audio directly to the low-level audio interfaces of each platform.

Support the development of Karl2D

If you want to support the development financially, then I’d be very grateful! You can do so by becoming a sponsor on either GitHub or Patreon. The money will be used to make me able to spend more hours on this project.

Wanna do open-source contributions to odin-c-bindgen?

My C library binding generator needs help! I don’t have time to fix bugs for it currently. If you want to help then please check out the section called Contributing on its GitHub page. Thank you to all past contributors!

Bye bye, have a nice day!

/Karl Zylinski

odin-c-bindgen 2.0 released!

I spent most of October rewriting my binding generator from scratch. Why did I do that? Because the code had gotten too messy, it was hard to fix bugs without stacking hacks upon hacks.

odin-c-bindgen takes C library headers and generates Odin bindings. The generator is meant to be easy to configure and produce nice-looking bindings that are easy to navigate while retaining comments.

One problem with the old implementation was that it used libclang things here and there all over the code. There wasn’t a clear “pipeline”. The base design for bindgen 2.0 is that I first fetch everything I need from the C headers using libclang. After that stage libclang isn’t used at all. From there on, it’s a lot of processing of the data until it’s all finally outputted.

I wanted the generator to be possible to use for two things:

1. Quickly testing out a C library within an existing Odin code base.

2. Using configuration options to make the bindings as close to production-ready as possible.

(1) is important because there may be 3 different libraries that don’t have Odin bindings, and you want to quickly see how those libraries would integrate with an existing Odin code base. Then you’d want to make quick & dirty bindings, just to try things out. If you have to create bindings for each library by hand, then you are actually likely to settle for the wrong library, due to not having the energy to hand-author all those bindings.

In order to prove that (2) was possible, I decide to try to make Raylib bindings that were as close as possible to the Odin vendor bindings. As I did that, I had to add a few features here and there. You can see the generated Raylib bindings here.

One feature that was important was the “footer feature”. Say that you are generating bindings based on the C header raylib.h. In order to make the bindings really nice to use, you may need to do a few custom Odin things. For example, perhaps you want to add a custom Odin allocator that is compatible with the library. I made it so that you can put a raylib_footer.odin file next to the raylib.h file. The stuff in the footer will simply be pasted at the end of the generated bindings. Simple, but effective.

See the release notes for the new version here.

Karl2D progress

The Karl2D library is coming along nicely. I have slightly less time to spend on side-projects recently, due to a part-time contracting job. Nonetheless, some great progress has been made!

OpenGL backend

I’ve made an OpenGL backend, meaning that you can now use D3D11 or OpenGL on Windows. Soon I will also add Linux windowing, and on that platform use the OpenGL backend for rendering.

By “backend” graphics programmers often refer to the part of their renderer that takes care of talking to the GPU using an rendering API such as OpenGL, Direct3D, Vulkan etc. A library that has multiple backends must be written in such as a way that the shared parts of the library don’t directly use things from specific rendering APIs. The backend is abstracted away, so that the shared parts of the renderer work no matter which backend is used.

I realized one important thing when making the OpenGL backend. It is a lot nicer to first write a D3D11 backend and then move on to OpenGL. I think D3D11 is the best API for learning graphics programming. It has reasonable amount of features while being very discoverable. If you want to understand a certain feature of the API you can often just look at an API function and then look at any structs that the function refers to. With OpenGL things are not so simple. OpenGL uses lots of generic constants that can be used in very arbitrary ways. It is hard to guess how to do the right thing.

When implementing the OpenGL backend, a lot of my time was spent on staring at my D3D11 code and trying to come up with something similar in OpenGL. I often did it step-by-step. For example, when setting up the rendering of a draw call, I first got my data uploaded to the GPU. Before writing any more code, I used RenderDoc to check that the data had arrived to the GPU correctly. Then I added code for setting OpenG shaders, uniforms etc. At each step I tried to verify what I had done using RenderDoc. This made graphics programming a lot more fun! No more was it “write a lot of code and then debug it for 5 hours”. Instead it became: “Try to make your GPU do a bunch of tiny tasks and verify each step, if possible”. This made the code better. It often worked on first try.

Creating the OpenGL context

Many people use libraries like GLFW in order to create the OpenGL context. The OpenGL context is platform-specific. It’s the bridge between your OS window and OpenGL.

I try to minimize the number of dependencies, so naturally I wanted to try without anything like GLFW.

Bear in mind that I also do the windowing myself. On Windows I use the win32 API to create and manage windows. So there is platform-specific windowing code, and then there is a tiny bit of platform-specific OpenGL code that creates the context.

On Windows, creating the context is a lot about picking a compatible “pixel format”. You can see the file that implements my Windows OpenGL context here. It’s not a lot of code, so I’m happy I didn’t give up and use GLFW.

There are a few peculiar things however: In order to get RenderDoc to work with GL I had to use the win32.wglChoosePixelFormatARB procs to help me choose pixel format. Funny thing is: That procedure is an extension, and in order to fetch extensions, you have to already have a valid OpenGL context. So first I have to create an OpenGL context using the “old school” way that is incompatible with RenderDoc. Then I have to use that “dummy context” to create the context I actually want to use. Silly!

Render Textures

I added support for drawing into textures, as opposed to drawing to the screen. You can see how that feature works in the render_texture example.

I still need to implement render textures in the GL backend.

Pre-multiplied alpha

In order to make blending look better you often have to use pre-multiplied alpha. This means that you multiply the alpha value of a texture’s pixels into the RGB values of each pixel. Then you modify how the blending is set up so that it takes this into consideration.

Pre-multiplied alpha can sometimes make your rendering look better. If you notice black fringes around your half-transparent pixels, then chances are that using pre-multiplied alpha would help you.

Many projects start out with using “normal alpha blending”, because they don’t have a pipeline to do the pre-multiplication yet. In my premultiplied_alpha example I show how you can easily get going with pre-multiplied alpha by telling the texture loading procedure to pre-multiply the alpha for you:

tex := k2.load_texture_from_file(”plop.png”, options = { .Premultiply_Alpha })

To make it correct use these pre-multiplied textures, you just have to change the blend mode from .Alpha to .Premultiplied_Alpha:

k2.set_blend_mode(.Premultiplied_Alpha)

Setting texture sampling mode

When the GPU draws pixels from a texture, it’s said that it samples them. You can specify sample mode, for example you can use “point sampling” to preserve the pixlyness of an image. You can use “linear sampling” to smooth the texture when it is has been scaled up.

Point sampling is the default in Karl2D as many people make pixel art games, or just find smoothed textures ugly. I’ve added so you can set the filtering on a per-texture basis by writing:

k2.set_texture_filter(tex, .Linear)

In OpenGL this was fairly simple to implement: For each texture in an GLSL shader, there is a single sampler. So it’s easy to associate a sampling method with a specific texture.

In D3D11 however, you create samplers and textures separately in the shader. This means that you can have 1 sampler used by 2 textures. And you can only set the sampling method to a single value… So now, if someone makes a custom shader, then they could easily end up with a configuration that does not work with per-texture texture filtering configuration: A sampler can’t be in two states at once!

I went back and forth a lot on what to do about this. In the end, I decided to implement some verification code in the procedure that loads HLSL shaders: If you have a texture in HLSL texture register 1, then there must be a sampler in HLSL sampler register 1. This makes D3D11 behave a bit more like OpenGL.

I don’t enforce a single shader programming language. Instead I use the shader language that is native to each rendering API. I will provide default shaders for each shader language. However, if you want to write your own shaders, then you may have to write multiple versions of it.

However, I do plan to add a cross-compiler toolkit that you can use. But that is a later problem. That cross-compiler will sit outside of Karl2D and Karl2D will accept the result of such a cross-compilation. This makes sure that Karl2D avoids weird assumptions about shader languages and enforces fewer dependencies.

Another thing to consider is what happens when you need to finally ship a game. Then the idea of having shaders that you can “write once, run everywhere” sometimes bites you in the foot. You may very well need to write custom shaders for some platform, in the shading language native to the rendering API it uses. With my solution you can do that when the need arises. This follows my main design idea for Karl2D: “Easy to get started with, helpful when you need to actually ship a game.” — Many “easy-to-use” libraries end up being troublesome when you need to ship. I’m trying to avoid that.

The future

I’m tinkering with something I haven’t announced yet. More about that next year.

I also have a contract job for a few months, so my open-source projects and YouTube productivity has taken a hit. I’ll be back!

In the coming months I’ll try to get Karl2D to a state where I feel comfortable with doing a first big round of tests.

Have a nice December and happy holidays!

/Karl Zylinski

We’ll start with news regarding my book Understanding the Odin Programming Language, then some updates on my 2D game library Karl2D and finally some future plans for my binding generator.

Book update: Strings chapter overhaul, and a sale!

One big thing that happened in the September release of Odin was native UTF-16 support using the string16 and cstring16 types. Odin doesn’t use these types a lot, since it focuses on UTF-8. The UTF-16 types are mainly for interfacing with Windows code (and any other library that needs UTF-16). Nevertheless, I did have a section in my book Understanding the Odin Programming Language where I showed how to interface with the Windows API. Now the code in that chapter no longer compiled, so the book needed to be updated!

Having a native UTF-16 type in the language made me treat UTF-16 a bit more rigorously. As I tried to rewrite those sections, I also noticed that my discussion around the interplay between Unicode and UTF-8 was a bit lacking.

So I started doing a major overhaul of the Strings chapter of the book! It needed more details on what Unicode actually is, and how UTF-8 is used to encode/decode Unicode. That way I could extend that discussion to UTF-16 in the later parts of the chapter.

I also added a section on how to manually decode UTF-8. That specific section is freely available on my blog and also as a YouTube video:

This update, including some other small fixes, took almost two weeks to complete. The updated Strings chapter (chapter 11) has several almost completely rewritten sections, as well as a few new sections.

The update is live, with release notes here.

I am running a sale of the book on store.zylinski.se — 25% off until October 9!

Karl2D progress

Since the last newsletter I’ve been doing good progress on my “Karl2D” library! It’s a 2D game creation library. The API is based on Raylib, but meant to be written in native Odin, using as few dependencies as possible.

It is not yet ready for use, but here follows some highlights.

Follow the development of the library on GitHub.

More efficient rendering

I ported the “bunnymark” Raylib demo.

When running the ported demo, I ran into some errors in how I handle batching. After fix that I could spawn around 160000 bunnies while staying at 60 fps. This is not meant to be a benchmark, as I haven’t really optimized anything yet. But it’s looking OK!

The port is available here (original here).

The batching works by building a vertex buffer that can be up to 1 megabyte large. If it hits the limit, then it does a draw call and then empties the buffer and continues drawing. It’s similar to what Raylib does. However, I also have the possibility to customize vertex inputs. In Raylib that is hard-coded. This way, you can add extra vertex inputs in the shader and set their value while drawing, without modifying the library.

Gamepad support

The basic gamepad support uses XInput. I’ll make sure to get PlayStation controllers to work as well. Later, when I add more platforms, I’ll use that platform’s native API to do gamepad support on it.

Basic text rendering (work in progress)

I use stb_truetype to generate bitmap fonts. Similar to how raylib does it. The offsets and line heights are still a bit wrong in this image, but I’ll get there. I am thinking if I perhaps should have some fancier way to process fonts, such as dynamically building bitmap atlases. We shall see!

stb_truetype is one of few non-OS / non-rendering APIs that I’ve used. We shall see if it stays in the long run, but it’s a simple enough library that I would be OK with the dependency.

People may wonder what the philosophy is here: Why are some libraries OK while others are not? For example, why am I not just using SDL_GPU for the rendering?

The answer lies on how heavily your project becomes dependent on the library. Something like stb_truetype is easy to swap out if the need arises. However, if I use SDL_GPU everywhere and don’t even make any graphics API abstractions, then I am heavily dependent on it. The day I want a platform where I can’t use SDL_GPU, then I’m in deep trouble.

So I only use libraries that I’m forced to use (OS APIs, rendering APIs) and libraries that I can easily swap out (stb_truetype).

Also, I ended up watching this informative and soothing video by Sebastian Lague. Perhaps trying to do some curve-based approach to text rendering is interesting, but as you can see in the video, it is a huge can of worms. We shall see!

Karl2D API documentation

Creating APIs that are easily overviewable isn’t one of Odin’s strengths. In C you use headers for that. But I don’t want any header-like things! But I also don’t want to force people to use a web-based documentation file.

What I’ve come up with instead is to use core:odin/parser to parse the source files and create a karl2d.doc.odin file that contains a good, programmer friendly overview (essentially stripping out the procedure bodies). The file is not meant to be compiled (it has #+build ignore at the top). It’s there for documentation while at the same time being as close to real code as possible.

You can see the generated file here: https://github.com/karl-zylinski/karl2d/blob/master/karl2d.doc.odin

The source of the program that creates the file is available in the api_doc_builder folder of the repository.

Binding generator rewrite

Recently, odin-c-bindgen got a big update: We switched from using the clang executable to directly using libclang. This was due to great help from the contributor Xandaron.

What this means is that we use libclang to analyze the C headers. And from the information we get out of libclang we can generate the bindings. This is more tidy and less error-prone than using the clang executable, ouputting JSON and then parsing that JSON.

Since all that happened, I’ve been putting off doing some maintenance work on the generator. The code has gotten a bit messy! So… I am going to use the great work that Xandaron did as a reference, and do a “bindgen 2.0” rewrite.

My idea is to have a clearer separation between different “stages” of generation:

• Collect: Use libclang to build an intermediate representation of the C headers.

• Process: Take any extra configuration options and use that to transform the collected representation. For example, this is where “bit setification” of enums would happen. The output of this stage is a “final representation”.

• Output: Take the final representation and prettily output it as Odin files. An important aspect, in order to keep the messiness down, is to make sure that the outputter knows nothing about libclang. So the two stages before this one must prepare the data in an orderly fashion. One of the big issues with the old version was that clang things seeped into the output stage. This give me a hard hard time when trying to fix bugs, because there is clang-related things happening just about anywhere.

The one thing I like less about libclang vs parsing JSON from clang is that libclang uses “visitors” to iterate children. So for example, to get all the fields of a struct definition, you pass libclang a callback that it will call for each child of the struct.

This makes the code so much more messy. It’s must better to just iterate an array. So what I do in the rewrite is that I just use the visitor to make an array of children, return that array and then loop through it. The code then becomes much easier to read.

Join my Discord community

If you want to chat about my book, Karl2D or the binding generator, then why don’t you join my Discord community? It’s a friendly place where you can also talk about your projects, be it gamedev- or Odin-related.

Here’s the invite: https://discord.gg/4FsHgtBmFK

Until next time, happy programming!

/Karl

My vacation was four weeks long. I barely used computers at all during that time, except for playing Stardew Valley in splitscreen for very many hours. Coming back to the computer I felt strangely curious about some old projects.

During my last newsletter I did some philosophizing about game engines. The newsletter included a link to a repository with some sketches on a plugin-based architecture for an Odin engine.

I haven’t done much more on that specific project, due to it feeling too unbounded, to unconstrained. Instead, what has happened is this: When I came back from the vacation I opened up my old “Metroidvaniaish” project. It’s a prototype I worked on last year that looks like this:

I dusted it off and easily got it running, thanks to Odin not having changed much. However, after that something else happened. I started thinking: What if I want to work on this project again; how would I want to do go about it?

The project used Raylib. While I managed to ship CAT & ONION using Raylib, I thought it would also be nice to have something “native” written in Odin that I also have more ownership of.

With that in mind I started making an Odin wrapper for Raylib. The long-term goal being to replace the Raylib parts (that are written in C), with native Odin code. The project-dusting-off followed by the start of this wrapping can be seen in this stream:

Since then I have worked a lot on it. My aim is this:

• Make a native, Raylib-like library for creating video games.

• The library doesn’t have to be identical to Raylib, the initial API is just inspired by Raylib because I like it. But I can also correct things that I don’t like about Raylib. I know the library very well, even how the internal C code works.

• Use as little dependencies as possible. Use the “most native” APIs on each platform. Currently I’m working on a Windows version that uses win32 for windowing and d3d11 for rendering. I will not use GLFW, SDL, Sokol or any abstract thing like that. Hopefully I can get very far with just some core libraries and a few rendering libraries in vendor.

One big technical difference from Raylib will thus be support for multiple rendering backends. A big benefit of this is that I’ll eventually be able to make a WebGL or WebGPU backend that has no need for emscripten. It’s quite exciting!

Raylib uses OpenGL on all platforms. In order to make it work on web it uses emscripten to “translate” the OpenGL into WebGL. It’s a huge amount of magic that comes with many limitation and possible issues.

I have given the library the name “karl2d”, and you can find the repository here: https://github.com/karl-zylinski/karl2d — Note that it is not ready for any kind of use and missing lots of features. At the moment of writing I’m working on making a proper “rendering backend” interface.

I have already gotten rid of the Raylib wrapper. Right now only a Win32/D3D version exists. Somewhere down the line I’ll hop into Linux and try to figure out the most suitable rendering backend and windowing solution.

My current biggest issue is choosing a shader language. I’m trying to figure out which shader infrastructure that comes with the least number dependencies. Remember: I want to minimize strange library dependencies. However, for shading compilation I may be forced to use some dependency.

I might use the new slang language. But then I cannot use OpenGL on Linux: I’ll be forced to use Vulkan. Vulkan is quite overkill and overcomplicated for this kind of thing. But I’ll do what makes most sense.

If I make a Vulkan backend, then perhaps I’ll use it on Windows too, we’ll see. As noted, I still need multiple backends for web, mac and possible consoles.

There are more shader language alternatives: I might use GLSL and some cross-compiler, I might use HLSL and some cross-compiler. I’m gonna try my best to find a low-friction pipeline.

Another alternative is to just use the format of whatever rendering API you run on right now and provide a separate “cross-compilation library”, so that the karl2d library stays simple. That’s good for actually shipping games, since you don’t have this weird cross compiler smack in the middle of it all.

We shall see how it goes. I’ll do more streams on YouTube where I work on the library.

I recently tried Jai

Just after the vacation ended, I did two live streams where I tried the Jai language, which is currently in closed beta. The two live streams are here:

People naturally want me to provide comparisons of Jai and Odin. Pros and cons. Which is best? etc

I haven’t used Jai enough to say anything definite. What I can say is this:

• Jai works. I had no trouble with compiling my first program.

• I was able to make a small 2D game thingy quite easily: https://github.com/karl-zylinski/learning-jai-by-making-a-game

• The package system in Jai is more relaxed than Odin. This may or may not be a good thing. You can do a bit more whatever you want and load separate files into a package. It is not as bound to a specific folder as Odin is.

• I didn’t really try any of the famous Jai meta-programming, because I don’t find meta-programming that interesting. When I need meta-programming in Odin I just generate .odin files. That has filled all my needs so far.

I’m not planning on doing any more Jai in the near future. It seems like an OK language. But it is less polished than Odin and none of the additional features interest me that much.

odin-c-bindgen: A big update

The odin-c-bindgen, which generates Odin bindings for C libraries, now uses libclang instead of the clang executable. This means that it no longer has to write a JSON file to disk and read it back. Instead it just uses libclang to process the C headers, directly in the code.

Almost all this work was done by Xandaron, who I now see as “co-author” of the program, because he has done so much work on it. Huge thanks! You can read more about the release here: https://github.com/karl-zylinski/odin-c-bindgen/releases/tag/1.1

Odin gamedev architecture

I’m thinking of making a video or blog that is a bit more in-depth on how to do the architecture of a video game in Odin. It’s a huge topic where I need to limit myself. So I’m thinking: “Architecture for small, 2D, single-threaded games, probably using Raylib for simplicity”. If you have anything you’d like to see in such a video or blog, then let me know in the comments.

Thanks for reading

Have a great September! If you enjoyed this newsletter, then perhaps you want to subscribe? You’ll get roughly one newsletter, similar to this one, per month.

Have a nice day!

/Karl Zylinski

Make your game!

I tend to say that if you want to make a game from scratch (not using a any existing game engine), then you need to focus on making the game.

Do not try to first make a general purpose engine and then, when you are done with that engine, make your game on top.

Only solve the problem you actually have. Don’t dream about “what if I need X in the future”. Only write the code that gets you closer to shipping the game.

If you are on a bigger team, then you may need to think a bit more about “what if we need X in the future”. The smaller the team, the more you are usually able to focus on The Now. In small teams its easier to do crazy restructuring of the code. The more people, the scarier it is to break things.

But I want to make an engine!

That’s fine! Make an engine. You just need to be honest with yourself: Are you making a game, or making an engine?

When I say engine in this newsletter, I mean “general purpose game engine”, something like Unity or Godot. If you make 3 games and some kind of engine fall out as a bi-product over time, then that’s not really what I refer to in this case.

One thing you should keep in mind, is that that making an engine is a huge task. Let’s say that you want to make a general purpose game engine that other people can use. What is biggest amount of work? Fancy rendering code? An entity system? No: Tools. If you want to make an engine then you must be prepared to spend a lot of your time making tools. You must care about the user experience of those tools.

This may sound obvious, but here is a funny thing I’ve noticed with people who make game engines as a hobby: Many start with some 3D rendering code, perhaps they make some Physically Based Rendering pipeline, etc etc. And then when they’ve spent months on that, then they suddenly realize they need to make some tools. Many give it a go, don’t find it fun and then the project dies.

So here’s an idea: If you want to make a game engine, then you should probably start with these things:

• UI rendering

• Some way to store / load data

Then make some tiny toy tool using the UI rendering and go on from there.

Eventually, you can add some basic 2D / 3D rendering and experiment with some ideas of how to edit levels. Over time, you can add more rendering and perhaps an entity concept etc.

This way you’ll have a more holistic approach to game engine development. You’ve already started with the most important part: The tools.

So why are you writing about this?

I’m an experienced tools and engine programmer. So I thought it would be interesting to try the approach above. More specifically, what I would like is:

• A general purpose game engine written in Odin

• Odin is also used for gameplay programming

• I focus on getting the tools programming up to speed first. If I can’t get anywhere with the tools, then I might just as well not continue.

• Plugin-based: Make the engine modular. Have hot reloadable plugins.

• Low-level: Does not use any graphics API wrapper. Instead I want to use the “most native” graphics API for each platform. On Windows that’d be Direct3D. On Mac Metal. On Linux…. Vulkan I guess.

I haven’t gotten far yet. But I’ve spent some time in June tinkering with these things.

I’ve written some rendering code in Direct3D 12 that can draw some rectangles in a single draw call. This will be the foundation of the Immediate Mode UI.

Then I’ve gotten started on the plugin system. It’s not 100% working yet, but I have my Direct3D 12 code as a plugin that is loaded dynamically.

Thinking about code organization

When making something modular and plugin-based, where the plugins are possible to dynamically load and hot reload, then each plugin probably becomes a separate package.

Using many small packages in Odin is usually a problem. You’ll compartmentalize incorrectly and you can’t have circular dependencies.

However, I envision my plugins to be quite big. At least the plugins of the core engine and the tools. The whole D3D12 renderer is one plugin etc. The IMUI rendering code is probably another plugin. A level editor may be another plugin.

So what I do is the following: In the D3D12 plugin I introduce an `@api` attribute. I mark procedures with it like so:

@api
buffer_create :: proc(blabla) -> Buffer_Handle {
	// do things
}

When I compile the plugin I use the parser in `core:odin` to find those procs marked with `@api`. I add their signature to an API struct. That’s the API the user of the plugin has to use.

The API file for the D3D12 plugin currently looks like so:

package renderer_d3d12

import hm "kzg:base/handle_map"
import "kzg:base"

Shader_Handle :: distinct hm.Handle
Buffer_Handle :: distinct hm.Handle
Swapchain_Handle :: distinct hm.Handle
Pipeline_Handle :: distinct hm.Handle

State :: struct {}
Command_List :: struct {}

API :: struct {
	create: proc(allocator := context.allocator, loc := #caller_location) -> ^State,
	destroy: proc(s: ^State),
	create_swapchain: proc(s: ^State, hwnd: u64, width: int, height: int) -> Swapchain_Handle,
	destroy_swapchain: proc(s: ^State, sh: Swapchain_Handle),
	create_pipeline: proc(s: ^State, shader_handle: Shader_Handle) -> Pipeline_Handle,
	destroy_pipeline: proc(rs: ^State, ph: Pipeline_Handle),
	flush: proc(s: ^State, sh: Swapchain_Handle),
	begin_frame: proc(s: ^State, sh: Swapchain_Handle),
	draw: proc(s: ^State, cmd: ^Command_List, index_buffer: Buffer_Handle, n: int),
	create_command_list: proc(s: ^State, ph: Pipeline_Handle, sh: Swapchain_Handle) -> ^Command_List,
	destroy_command_list: proc(rs: ^State, cmd: ^Command_List),
	set_buffer: proc(rs: ^State, ph: Pipeline_Handle, name: string, h: Buffer_Handle),
	begin_render_pass: proc(s: ^State, cmd: ^Command_List),
	execute_command_list: proc(s: ^State, cmd: ^Command_List),
	present: proc(s: ^State, sh: Swapchain_Handle),
	shader_create: proc(s: ^State, shader_source: string) -> Shader_Handle,
	shader_destroy: proc(s: ^State, h: Shader_Handle),
	buffer_create: proc(s: ^State, num_elements: int, element_size: int) -> Buffer_Handle,
	buffer_destroy: proc(s: ^State, h: Buffer_Handle),
	buffer_map: proc(s: ^State, h: Buffer_Handle) -> rawptr,
	buffer_unmap: proc(s: ^State, h: Buffer_Handle),
	swapchain_size: proc(s: ^State, sh: Swapchain_Handle) -> base.Vec2i,
}

The procs inside that API struct are matched up with the actual procs in the DLL when the plugin is loaded.

So the plugin is, from the viewpoint of the running game engine just two things: This API definition file and the DLL that contains the code. In order to avoid circular dependencies the API file should only import things from `core`, `base` and my own `kzg:base` package.

However, inside the code in the DLL, behind the “API wall”, it can import any other plugin. That’s fine, it’s not going to create a circular dependency from the viewpoint of the Odin compiler. So this way we get simple APIs and arbitrarily complicated code behind those APIs.

The code

You can look at the code here: https://github.com/karl-zylinski/kzg — Keep in mind that currently it just renders some rectangles and does some plugin stuff. But it’s going to be fun to the the plugin stuff a bit more going and then go back and try to get the editor things off the ground.

Well, I’m off to vacation for a month!

Thanks for reading! Have a nice July!

/Karl

A blog post that blew up on Hacker News

I wrote this blog post in which I shared my personal story of how I used to program in C and how I stumbled onto Odin, and how it fit my specific needs.

It wrote it partially because my book says “Odin point-for-point addresses many of the issues I've had with C, while also incorporating some of my favorite C best practices, straight into the language”. But it doesn’t elaborate much more than that. So the blog post fills in that blank!

It ended up Hacker News, on the front page! It is fun to see that Odin-related things tend to find their way to Hacker News so often.

Organic and paid marketing

Let’s talk a bit about marketing! The best kind of marketing is called “organic”. It means that people are excited enough about your product that they talk about it for you. They repost your social media posts, etc.

Even better is when the content wasn’t even created to be marketing. Perhaps you were just excited to share something. But it blew up. These kind of things can happen when one least expects it. It’s hard to “make it happen”. Because then you’re kind of “faking it”. Just make sure you’re making something you’re honestly excited about, and share interesting things about it!

I have never tried paid marketing before, until last month. During May I tried running ads for my book on Reddit. My idea was this: I put in $10 of ads per day. If I manage to sell 1 extra book per day then I’ve made $10 (since the book cost roughly $20). It felt like a good, non-risky way to approach it.

Did it work? I’m not 100% sure, since the Hacker News stuff happened at roughly the same time. But it seems like I’ve sold 1-2 more copies per day, even after the Hacker News exposure died down.

Why Reddit? Because it’s so easy to specifically target niche programming subreddits. That way I could get the maximum value for my daily $10. You can of course do targeted ads on other platforms as well, but it just feels easier to set up on Reddit. You can just choose to target some subreddit that you know you enjoy yourself.

Note: I did not target the Odinlang subreddit, since I’m the moderator of that one! Running ads on platforms where you’re supposed to be a neutral moderator may not look very good.

Small book update

Just before writing this, I also released a small book update. You can read the change log on itch. It’s nothing big, just a few typo fixes.

What happens now?

I wish I knew!

I’ve been trying to make a new game. It hasn’t gone very well. The book money is coming in, but I don’t think I’ll make enough to last me more than a few months. Doing these things is my main income.

I’ll still poke around with some projects and see if anything interesting pops up. But I do feel a bit deflated and stressed. As you may have noted, I’ve made less videos and blog posts than usual.

I’m sure I’ll get through it, but perhaps some bigger change will be needed soon. We’ll see! I’ll try to figure these things out during June. And then have a proper summer vacation in July.

Have a nice day!

/Karl Zylinski

I wanted to give people some insights on memory arenas. So wrote about that. Then there was a bunch of blogging related to libraries and software I’ve made. I summarize it all below.

At the end of this newsletter I also show a sneak peek of my latest gamedev experiments, along with some reflections on Odin, Sokol and Raylib.

Memory arenas and handle-based maps

A thing I often see is people trying to combine arena allocators with dynamic arrays. You can sometimes do that, but you need to be aware of a bunch of potential pitfalls. There are also a bunch of cool tricks you can use to your benefit. With that in mind I wrote a blog post and also made a video on the topic:

Some of the ideas in that blog post actually made me re-design my “handle-based map” package.

A handle-based map is used to associate array items with robust identifiers. The handle is essentially an index plus a generation counter.

In particular, I made that package use virtual memory arenas in smarter ways. I wrote a whole post about that as well! In it I explain three different approaches of implementing a handle-based map. The updated source code can be found on GitHub.

I made a video about this as well:

I’ve chosen to write about handle-based maps because it’s something that many game developers run into. But there are lots of small nuances related to how one implements it. When making CAT & ONION I rewrote my handle-based map several times and figured things out as I went. I hope I can save people some of that time.

My Odin C Binding generator

At the start of April I wrote a blog post that explains how to use my Odin C binding generator and what the benefits of a generator can be.

This binding generator takes C headers and tries to output Odin bindings that utilize Odin features such as bit_set. It also tries to generate bindings that actually look good and are easy on the eye. I think that bindings should be as easy to learn from as the original headers. With that in mind, it also makes sure to bring along comments and documentation.

If you try to use it and run into any problem, then please post an issue on GitHub! I’ve also recieved a bunch of Pull Requests that have added features and fixed bugs. Thanks a lot to those who helped me!

No-engine gamedev using Odin + Raylib

I realize that some people may find “making games from scratch” daunting. By “from scratch” I mean not using any big engine.

Exactly what “from scratch” means varies from person to person. Some may say that it means building everything on top of Operating System APIs and rendering APIs such as Vulkan. To me it just means that you use a programing language and some kind of basic library, such as Odin + Raylib. But you don’t have any big engine such as Unity or Godot.

Recently, I’ve also tried to use the term “no-engine gamedev”. But that also confuses some. Then people debate about what an engine is instead! By engine, I again mean a big engine like Unity. So “no-engine gamdev” means making a game without such software.

In any case, I wrote a blog post called “No-engine gamedev using Odin + Raylib” that attempts to be a quick crash course on the super basics of Odin + Raylib. Those basics are followed up by some pointers on how to manage entities and how I approach making level editors. I hope it can make the idea of no-engine gamedev less daunting. The post is almost like a little “summary post” of all the different things I’ve done in this area, with links to videos, blog posts and articles where you can learn more about specific things.

The Zylinskiverse

I’ve made it so you can buy my Odin book on the domain store.zylinski.se — My own store, so profesh! I’ve also made it so that this newsletter is hosted on news.zylinski.se. Welcome to the Zylinskiverse!

In the future, perhaps I’ll also start selling CAT & ONION on my store.

Some thoughts on Sokol and Raylib

The last few days me and my partner have been poking around with some little video game experiments. I don’t have much to show other than the strange image above.

But I do have some technical notes to share. Initially, I started doing it in Sokol, using my sokol-hot-reload-template. I was trying to do a 3D game with flat, paper-like characters and trees and stuff.

I went with Sokol because I did have some trouble using 3D in Raylib before. In what way? The 2D support in Raylib is great. But the 3D support often forces you to go into the C code of Raylib and port some functions over to Odin, so that you can modify them. This is because Raylib’s 3D code makes a bit too many assumptions about how you want to set things up. For example, I didn’t like how `rl.DrawMeshInstanced()` worked internally. So I ported it to Odin and adapted it to my own needs.

Initially everything went great with Sokol! I got shadowmapping working and managed to create flat, paper-like characters that used my partner’s art. Sokol is more low-level than Raylib (it’s more like a rendering API and less like a “game creation library”), so none of the annoying assumptions bit me.

But then I wanted to make an editor. For CAT & ONION I had a very fun time making editors using Raylib’s 2D drawing features. A button was just a rectangle with some text in it. I got a lot done, very quickly! Without any extra IMGUI library or anything.

Sokol didn’t have such things built in. Naturally. It’s more low-level! Less assumptions! But I also didn’t want to pull in Dear IMGUI or something like that. So I started making my own “rectangle drawer” procs, similar to rl.DrawRectangle etc. Quite quickly I was totally lost in the sauce of making utility procs, when what I really wanted to do was to make my editor. I wanted to just quickly layout some panels with some buttons on them to spawn some graphics!

People may scream at me “well, then, just put in Dear IMGUI or something!!”. But I don’t want to! I like writing my own IMGUI stuff, because I come from a tools programming background. I just don’t want to write the code that draws the rectangles and a million different variations of such procedures.

Also, I was actually missing some of the basic collision detection features of Raylib. Not that it’s very hard to implement them. But I was just starting to feel tired from having to implement so many small things. I got side-tracked every time I tried to implement something for the game.

At this point it dawned on me: I wasn’t having fun. I love when the level at which you’re programming is such that you feel like you can easily do the part that is “most fun” to you. For some people perhaps the graphics programming is most fun. But for me the most fun part is bolting together gameplay, shaders, making editors, thinking about data formats. Making it all work together. But I also love the “from scratch” feeling of not using a big game engine. I love when my game is just a program that uses a library. I want it to be as simple as possible, but still give me a suitable amount of features.

In any case, since I wasn’t having fun and just wanted all my good old Raylib stuff, I just re-wrote it all using Raylib. I know there may be some issues down the road regarding the assumptions in Raylib 3D, but I think I can work around them. It’ll be OK!

By all this, I don’t mean to tell anyone what libraries to use. The important thing here is that you find something that makes it possible for you to quickly get to the parts that are most fun for you. Find that sweet spot!

Thanks for reading!

If you want to hang out and discuss Odin or game development, then join my Discord server: https://discord.gg/4FsHgtBmFK — It’s a friendly place!

/Karl Zylinski

Updates to my book and the future of it

My book "Understanding the Odin Programming Language" got a 1.6 update. It was mostly about updating a few things that had changed in the language. I also added some new sections, such as how to break cyclic package imports using callbacks and interfaces. You can read the whole change log here: https://zylinski.itch.io/odinbook/devlog/909629/version-16-keeping-the-book-up-to-date

I also want to talk about the future of the book.

My aim is to keep it up-to-date. This means that I'll update it if important things change in the language. These updates will be free for those who have already bought the book, just like past updates.

I have also decided to not make a physical version of the book. Sorry anyone who was waiting for that! My reasoning is like follows: When I wrote the book I wanted to create a semi-interactive work. It does explain many things in great detail, but I also don't shy away from linking to articles, videos, documentation and code. I do it in a kind of informal way, without footnotes. Changing all that for a physical version is a lot of work. Frankly I just don't think it'll work very well in physical format. A second reason is that I just didn't find the energy to work on the physical version. So I just won't.

A huge thanks to everyone who has bought the book and said such nice things about it. It's my first independent work that has sold well enough in order to sustain me for a while. Everything I currently do is funded by book sales.

I told my programming life story on a podcast

I was a guest on the Wookash Podcast (previously known as the "Game Engineering Podcast"). You can listen / watch here:

It was very fun! The front part of it ended up being me talking about all the twists and turns that can lead to one's current occupation. The second half is more specific about game development and Odin. Thanks to Łukasz for hosting and having me on!

Handle-based map blog posts and library

It's often important to store references to objects within your code. However, many of us have probably had problems with dangling pointers etc.

A common remedy is to store handles instead of pointers. A few days ago I made a blog post about that: https://zylinski.se/posts/handle-based-arrays/

Towards the end of the blog post I talked about some further ideas regarding how to use virtual memory arenas in order to make the code more robust. My curiosity resulted in the following odin-handle-map library: https://github.com/karl-zylinski/odin-handle-map

Note: I say handle-based array, handle-based map and handle map interchangeably.

In many ways my blog post was meant as a follow-up to Andre Weissflog's 2018 article named "Handles are the better pointers".

I made a Sokol + Hot Reload template

Speaking of Andre Weissflog. He's also the creator of Sokol. It is a library that, among other things, lets you talk to the GPU through an abstract interface. This means that you write the code once, but it will use Direct3D, OpenGL or Metal depending on the platform.

I'm well known for my Odin + Raylib hot reload template. But I also wanted hot reload capabilities when working with Sokol. So I created a template for that: https://github.com/karl-zylinski/odin-sokol-hot-reload-template

When comparing this template to my Raylib Hot reload template, you may note a major difference: This template has a build script written in Python. So instead of several batch / bash scripts, there is a single Python script for all platforms and build modes. There is a thing that tipped the scale towards writing a Python script for this template: I wanted to automate the download and build of the Sokol bindings and libraries.

I was also considering writing the script in Odin itself, but since Odin has no bundled HTTP client yet, I decide to go with Python.

Here's a technical overview and demo of the template:

I hosted the Odin 7 Day Jam

The game jam I hosted March 8 - 15 was a big success! In the end we had 62 games submitted. The winner was decided by the participants voting. The result is here: https://itch.io/jam/odin-7-day-jam/results

Let's talk about four of the games!

The winner was "Pass Whales", a very nice and cozy little puzzle game: https://gordonshamway23.itch.io/pass-whales

The second place was "Voidcrawl", which is a 3D dungeon crawler with an amazing atmosphere! https://lucypero.itch.io/voidcrawl

Third place was "Slice Slash", which was a cleverly designed puzzle game: https://tacohej.itch.io/slimeslash

Those three games are playable in the browser.

But I also want to mention another game: Barry's Revenge! It's a Hotline Miami-meets-"western movie" game. It's absolutely spectacular. It has nice graphics, tight and challenging gameplay and even voice acting. I was floored that it was made in 7 days! It didn't make the top 10 because it does not have a web build, so it didn't get enough votes. But I encourage you to check it out here: https://blunderguru.itch.io/barrys-revenge

All-in-all, a huge thanks to everyone who participated! You're all an amazingly creative bunch.

My future

Personally, I had a bit of trouble making a game during the game jam. I think the pressure of hosting and being creative got to me. I might host jams in the future, but in that case I'd probably have a more “tutor role”: Answer questions on stream, show how to do specific game development things, hang out in Discord voice chat rooms and help people with their problems, etc! I'm actually quite excited about that idea; I really like teaching and helping.

But also, I've realized something else about my game making: I've tried to make another game for about a year and it hasn't gone that well. I ended up making a book instead, which was great fun. But the idea that I "should" make another game has been looming.

After the jam I came to a realization: I made CAT & ONION as a solo developer. It a great experience and I learned a lot! But I actually don't think I should make games alone, I should have at least one more person to work with. The most important aspect for me is to have someone who is deeply involved in the game. That way we can collaborate on the game design.

So I won't try to make another game alone unless some magical inspiration comes around. But I might do it in a group. We'll see!

Other than that I'm excited to continue making educational content such as videos and blog posts as well as open source libraries and host game jams.

Support me

If you like the videos, blog posts and libraries that I make, then you can support me by:

• Buying my book: https://odinbook.com

• Becoming a patron: https://www.patreon.com/karl_zylinski

• Sponsoring me on GitHub: https://github.com/sponsors/karl-zylinski

• Buying my game CAT & ONION: Itch / Steam

• Saying something nice on my Discord server: https://discord.com/invite/4FsHgtBmFK

Thanks for reading!

/Karl Zylinski
March 29, 2025

Over the last few years I’ve been making a lot of different things related to programming and game development. I’ve written a book about the Odin Programming Language. I made my own video game, CAT & ONION. I’ve run a YouTube channel, I’ve written blog posts, I’ve published open source software.

Yet, there has been no central place to get a digest of what I’m currently up to.

That’s why I’m starting this newsletter!

If you register, you’ll get roughly one e-mail per month. In it you’ll get updates about past projects, announcements of new projects and also links to any blog posts or videos I’ve made since the last newsletter. Some letters may also contain additional insights on programming or game development.

Have a nice day!

/Karl Zylinski