multidimensional code - Blog

Lua bindings with Zig reflection

Antonio Caggiano — Sun, 21 Jun 2026 00:00:00 +0000

I am building a small game engine in Zig, and at a certain point I had to ask myself a question: do I keep writing gameplay in the same language as the engine, recompiling everything to move a cube, or do I add a scripting layer? I went with the scripting layer, and I picked Lua for it. It is tiny, fast, easy to embed, and games have used it for decades.

Adding Lua is the easy part. The work is in how the engine and Lua talk to each other. A script is useless unless it can reach into the engine: read the input, move a node, ask the scene for its camera. That bridge is called a binding, and writing bindings by hand is some of the most repetitive code you will ever produce.

So this post is about generating that bridge instead of typing it out. I'll start from the bottom, with what a binding really is at the level of the Lua stack, then write a couple by hand to show why that does not scale, and finally let Zig's compile-time reflection do the rest. The part I like is that by the end one description of my API is enough to both bind the functions and generate the autocompletion stubs my editor reads.

Let's start.

As I mentioned, the engine is written in Zig, which is statically typed and compiled, and a Node is a struct with a fixed layout in memory. Lua is dynamically typed and interpreted, and it knows nothing about that struct. The two meet across the Lua C API, and the first thing to understand about that API is that everything goes through a stack.

You do not call a C function from Lua by passing arguments the way you would in C. Lua gives you a small virtual stack. When Lua calls your function, the arguments are already sitting on it. You read them off, do your work, push your return values back, and return one integer: how many values you left up there. That is the whole protocol.

In zlua, the Zig binding library I use, I write that function in a Zig-friendly shape, fn (lua: *Lua) i32, and zlua.wrap turns it into the C-callable function pointer (CFn) that Lua actually expects:

fn myFunction(lua: *Lua) i32 {
    // 1. read arguments off the stack (index 1, 2, 3, ...)
    // 2. do the work
    // 3. push results onto the stack
    return n; // I left n results on the stack
}

Index 1 is the first argument, 2 the second, and so on. Negative indices count from the top, so -1 is whatever is on top right now. Say a script calls node:translate(10, 20, 30). Inside your function the stack looks like this:

index    1       2     3     4      <- count from the bottom
        node    10    20    30
index   -4      -3    -2    -1      <- count from the top

So node is at index 1, the first real argument 10 is at index 2, and the same 10 is at index -3. Reading slot 2 and reading slot -3 give you the same value. Once that clicks, the rest is detail.

A binding is mechanical work on top of this. You pull the Zig-typed arguments out of the stack, call the real Zig function, then push the result back. Converting values between Lua's stack and Zig's types like this has a name: marshalling. A binding is mostly marshalling, and marshalling is the kind of mechanical work a computer should be doing instead of us.

Making a Zig pointer look like an object

Before a script can call methods, Lua needs something to call them on. When a script writes scene:get_name(), what is scene? It cannot be a plain Lua table, because the real scene lives in engine memory and Zig owns it. Lua has to hold a reference to it.

Lua's tool for that is userdata: a block of memory that Lua owns and garbage-collects, but whose contents are opaque to Lua. I do not store the scene itself in there. The engine owns the scene, and its lifetime has nothing to do with Lua's garbage collector. Instead, I store a pointer to it. The userdata is an 8-byte box holding a borrowed *Scene:

fn pushScene(lua: *Lua, scene: *model.Scene) void {
    const ud = lua.newUserdata(*model.Scene, 0); // Lua owns an 8-byte slot
    ud.* = scene;                                 // store the borrowed pointer
    lua.setMetatableRegistry("Scene");            // attach the "Scene" behaviour
}

That last line does the interesting work. A userdata on its own is inert. You cannot index it or call methods on it. A metatable gives it behaviour. When Lua evaluates scene:get_name(), it does not find get_name on the userdata, because there is nothing there. So it looks at the userdata's metatable for a special key called __index. If __index is a table, Lua searches that table for get_name. This is how objects work in Lua. The metatable plays the role a vtable plays in C++.

So binding a class to Lua comes down to this: create a metatable, register some functions into it under their Lua names, and point __index at the metatable itself so method lookup finds them. Here it is for a Scene:

// Create a fresh table, store it in Lua's registry under the name "Scene",
// and leave it on the stack.
try lua.newMetatable("Scene"); // stack: [ mt ]

// Copy the value at index -1 (the metatable we just made) onto the top.
lua.pushValue(-1);             // stack: [ mt, mt ]

// Pop the top value and store it as mt["__index"]; the table is at index -2.
lua.setField(-2, "__index");  // mt.__index = mt   ->  stack: [ mt ]

// ... register each method into mt, then pop mt off the stack ...

Three stack operations happen here, and the same three turn up all over Lua binding code, so they are worth understanding.

newMetatable("Scene") creates a fresh table, registers it under the name "Scene" so I can find it again later, and leaves it on top of the stack. After this line the stack holds one value: the metatable, at index -1.

pushValue(-1) does not invent a value. It copies an existing stack slot to the top. To put a brand-new value on the stack you call a typed push like pushString or pushInteger; pushValue is specifically "duplicate whatever is at this index". I pass -1, the top, so now two copies of the metatable sit on the stack.

Why two? Because the next call eats one. setField(index, key) does t[key] = v, where t is the value at index, v is the value on top, and v is popped afterwards. I want mt.__index = mt, so the metatable has to play both parts: the table t and the value v. After the duplicate, the table is the second slot from the top, which is index -2, and the value to assign is on top. So setField(-2, "__index") pops the top copy and leaves the original metatable behind, now pointing its __index back at itself.

With that, the metatable is wired up.

The honest, painful way

I will write a binding by hand first, because you should feel the problem before automating it away. Here is Scene:get_name():

fn sceneGetName(lua: *Lua) i32 {
    // arg 1 must be a "Scene" userdata
    const scene_ud = lua.checkUserdata(*model.Scene, 1, "Scene");
    
    // unwrap to the borrowed *Scene
    const scene: *model.Scene = scene_ud.*;
    
    // push the name as the result
    _ = lua.pushString(scene.name);
    
    // one value left on the stack
    return 1;
}

Read it against the protocol from before. Argument 1 is the self userdata. checkUserdata pulls it off the stack and also checks that it really carries the "Scene" metatable, so a script that passes the wrong object gets a clean error instead of corrupting memory. We dereference to the real *Scene, push its name, and return 1 because we left one value on the stack.

The code is correct, and it is also ten lines that do almost nothing. I have to write a near-identical ten for get_camera_node, and again for every field of every struct, and again for every method of every type I want to expose. Each one is a place to slip up: read argument 2 instead of 1, forget the return, push an integer where Lua wanted a number. This is plumbing the type system already knows how to write. So I will bring in reflection.

What reflection means in Zig

If you come from C++, the word "reflection" might suggest runtime cost, RTTI, and a bit of magic. In Zig it is none of that. Zig runs ordinary Zig code at compile time, and during that compile-time execution it can inspect types. There is no runtime cost, because by the time the program runs the inspection is long over and only the generated code is left.

I lean on two tools. The first is @typeInfo(T), which returns a value that describes a type: for a struct it lists the fields, for a function it gives the parameter types and the return type, for an integer it gives the bit width. You switch on it like any other tagged union. The second is std.meta, which adds convenience helpers on top, such as std.meta.fields(T) and std.meta.ArgsTuple(F).

An example makes it concrete. Take a small struct and a small function:

// a plain struct with two scalar fields
const Mouse = struct { x: f32, y: f32 };

// a plain function with two arguments
fn add(a: i64, b: i64) i64 { return a + b; }

@typeInfo(Mouse) comes back tagged .@"struct" (the tag is quoted because struct is a keyword), and inside it carries a .fields array. Each field knows its .name ("x", then "y") and its .type (f32). std.meta.fields(Mouse) is just a shortcut to that .fields array, which I can loop over:

inline for (std.meta.fields(Mouse)) |f| {
    // f.name is "x" then "y";  f.type is f32
}

A function reflects the same way. @typeInfo(@TypeOf(add)) is tagged .@"fn", and it gives me .params (each with a .type, here i64 and i64) and .return_type (i64). On top of that, std.meta.ArgsTuple(@TypeOf(add)) turns the parameter list into a tuple type I can fill in and then call:

// a tuple shaped like .{ i64, i64 }
var args: std.meta.ArgsTuple(@TypeOf(add)) = undefined;

args[0] = 2; // first parameter
args[1] = 3; // second parameter

// calls add(2, 3); r == 5
const r = @call(.auto, add, args);

That last move, building an argument tuple from a function's type and calling the function with it, is the trick behind binding functions automatically.

The keyword that ties all this together is inline for. A normal for loops at runtime. An inline for is unrolled at compile time, and its loop variable is a comptime value, so inside the loop you can use it where Zig needs a compile-time constant: a field name, or a type. That is what lets me walk a struct's fields and generate one branch per field.

With that, the hand-written boilerplate can go.

Structs for free

Most of what a script wants from the engine is plain data. Read input.mouse.x, set input.key.w. There is no real method here, only field access. So instead of one getter per field, I write one generic __index that works for any struct T by reflecting over its fields:

fn metaIndex(comptime T: type) zlua.CFn {
    // wrap a plain Zig fn as a Lua-callable CFn
    return zlua.wrap(struct {
        fn index(lua: *Lua) i32 {
            // arg 1: the object, resolved to *T
            const self = lua.checkUserdata(*T, 1, @typeName(T)).*;
            
            // arg 2: the field name Lua asked for
            const key = lua.checkString(2);
            
            inline for (std.meta.fields(T)) |f| {
                // skip "private" fields
                if (comptime f.name[0] == '_') continue;

                if (std.mem.eql(u8, key, f.name)) {
                    // push that one field, by pointer
                    pushFieldValue(lua, f.name, &@field(self.*, f.name));
                    
                    // one value returned to Lua
                    return 1;
                }
            }
            return 0;
        }
    }.index);
}

There are two phases here. The inline for runs at compile time and unrolls into one if per field, so a struct with x, y, z produces three comparisons in the generated code. The std.mem.eql comparison runs at runtime, against the key the script actually asked for. The result is a dispatcher of the same quality I would have written by hand, except I did not write it.

Two details I like. Fields whose name starts with _ are skipped, which is my convention for a private field that Lua should not see. And an unknown key returns 0, meaning "I pushed nothing", which Lua reads as nil. That is exactly the Lua behaviour you would want.

Writing a field needs the mirror image, __newindex, which Lua calls on assignment. It pulls the value off the stack and writes it back into the struct. It has one extra rule: only leaf fields, like a number or a bool, are writable. A whole nested struct is not a writable leaf, so __newindex skips it and the assignment is quietly ignored, the same as writing to an unknown key.

How do we push a field once we have found it? We reflect on the field's type and pick the matching Lua push function:

fn pushFieldValue(lua: *Lua, comptime field_name: []const u8, field_ptr: anytype) void {
    // the field's Zig type
    const F = @TypeOf(field_ptr.*);
    
    // choose a Lua push based on that type
    switch (@typeInfo(F)) {
        .bool => lua.pushBoolean(field_ptr.*),
        .int => lua.pushInteger(@intCast(field_ptr.*)),
        .float => lua.pushNumber(@floatCast(field_ptr.*)),
        .@"struct" => pushStruct(lua, field_ptr),
        else => @compileError("unsupported field type"),
    }
}

Look at the .@"struct" branch. A nested struct is not copied into Lua. It gets wrapped as its own userdata pointing at the sub-struct, with its own metatable. So input.mouse returns a Mouse userdata, and input.mouse.x then indexes into that. The recursion in the data structure becomes recursion in the binding, for free.

The else branch matters too. If I ever add a field of a type the bridge cannot marshal, say an enum or a tagged union, the program does not compile, and the error names the exact field and type. A hand-written binding would have crashed at runtime months later. Here the failure shows up today, at the line. Reflection saves typing, but moving a class of bugs from runtime to compile time is the part I care about more.

Walking the whole type tree

If input.mouse is going to return a Mouse userdata with a working metatable, then Mouse needs a registered metatable too. And Mouse might contain a Position, which needs one as well. So registering a type means registering every struct it contains, all the way down. That is a recursive walk over the type tree, again with inline for:

fn registerStructTree(lua: *Lua, comptime T: type) !void {
    // give T a metatable with the generic __index/__newindex
    try registerStruct(lua, T);
    
    // look at each field of T at compile time
    inline for (std.meta.fields(T)) |f| {
        // skip "private" fields
        if (comptime f.name[0] == '_') continue;
        
        switch (@typeInfo(f.type)) {
            // a struct field: recurse into it
            .@"struct" => try registerStructTree(lua, f.type),
            
            // a scalar field: nothing to register
            else => {},
        }
    }
}

One call, registerStructTree(lua, Input), makes my whole input struct readable and writable from Lua, however deeply it nests. When I add a field to Input in the engine, the script sees it on the next run, and I touch no binding code. The binding follows the types instead of duplicating them, which is what I was after.

Functions for free

At this point, the data side is done. Calling real Zig functions like node:translate(dx, dy, dz) is the part that looks harder: each one has its own arguments and its own return type, so this looks like where I finally have to write the code by hand.

It is not. A function's signature is type information too, and @typeInfo of a function gives me its parameter types and return type. So I can generate the adapter automatically from the function value alone. I keep calling that adapter a marshalling shim. A shim is a thin layer that sits between two sides so they fit together, and this one does the marshalling we named earlier: it reads Lua values off the stack, converts them to Zig types, calls the function, and converts the result back. One small shim per function, written by the compiler.

We already met std.meta.ArgsTuple in the reflection section: it turns a function type into a tuple holding exactly that function's arguments. Here it earns its keep. I declare one of those tuples, fill each slot by pulling the matching value off the Lua stack, then call the function with @call:

fn methodCFn(comptime f: anytype, comptime pullSelf: anytype) zlua.CFn {
    return zlua.wrap(struct {
        fn call(lua: *Lua) i32 {
            // A tuple shaped exactly like f's argument list
            // e.g. .{ *Node, f32, f32, f32 }.
            var args: std.meta.ArgsTuple(@TypeOf(f)) = undefined;

            // A free function passes null here.
            // A method passes a pullSelf, so it has one leading arg.
            const self_count = if (@TypeOf(pullSelf) == @TypeOf(null)) 0 else 1;
            
            // fill slot 0 with the receiver
            if (self_count == 1) args[0] = pullSelf(lua);

            // reflect on f's signature
            const fi = @typeInfo(@TypeOf(f)).@"fn";
            
            inline for (fi.params[self_count..], self_count..) |param, i| {
                // read Lua stack slot i+1 as param.type
                args[i] = pullArg(lua, param.type.?, i + 1);
            }

            if (fi.return_type.? == void) {
                // call f(args...) and return nothing to Lua
                @call(.auto, f, args);
                return 0;
            } else {
                // call f and push its result
                pushReturnValue(lua, @call(.auto, f, args));
                return 1;
            }
        }
    }.call);
}

This is the function the rest of the binding leans on. The inline for walks the function's parameter list at compile time. For each parameter it emits a pullArg call that reads stack slot i + 1 and converts it to that parameter's exact Zig type. Then @call invokes the real function with the assembled tuple. The void versus non-void check decides whether we return 0 or 1 values to Lua. That is the protocol from the first section, derived from the return type instead of typed out.

pullArg is the inverse of pushFieldValue. It reflects on the wanted type and reads it from the stack:

fn pullArg(lua: *Lua, comptime A: type, idx: i32) A {
    // dispatch on the wanted Zig type
    return switch (@typeInfo(A)) {
        .float => @floatCast(lua.checkNumber(idx)),
        .int => @intCast(lua.checkInteger(idx)),
        .bool => lua.toBoolean(idx),
        // []const u8 <- Lua string
        .pointer => |p| if (p.size == .slice and p.child == u8) lua.checkString(idx),
        else => @compileError("Lua arg unsupported: `" ++ @typeName(A) ++ "`"),
    };
}

To expose Node.translate, a normal Zig method I wrote for the engine that knows nothing about Lua, I write zero lines of marshalling. I point the generator at it and I am done.

The self problem

There is one wrinkle you may already have spotted. A method is called on an object, and that object is called the receiver: in node:translate(...), node is the receiver, the thing the method acts on. A free function like add(x, y) has no receiver; it is just called with its arguments. In Lua the colon is what makes the difference. Writing node:translate(...) passes node as a hidden first argument, so on the stack argument 1 is the receiver and the real arguments start at slot 2. The dot form, node.translate(node, ...), is the same call with the receiver written out by hand.

That is what the pullSelf parameter handles. For a free function I pass null, self_count is 0, and every parameter is pulled as a normal argument. For a method I pass a small function that unwraps the receiver from slot 1 into the right pointer type. For a simple Zig-owned struct that is a one-liner:

fn pullPtrSelf(comptime T: type, comptime name: [:0]const u8) fn (lua: *Lua) *T {
    // an anonymous struct, used only as a namespace
    return struct {
        fn pull(lua: *Lua) *T {
            // arg 1 must be a `name` userdata -> *T
            return lua.checkUserdata(*T, 1, name).*;
        }
    }.pull; // hand back the function itself
}

That struct { fn pull ... }.pull shape deserves a full walk-through, because it looks odd the first time and it shows up all over this code. metaIndex and methodCFn use it too.

Here is the problem it solves. I want pullPtrSelf to return a function, and that returned function needs to know T and name. But Zig functions are not closures: a plain nested function cannot capture the T and name from around it. What Zig does give me is comptime parameters and the fact that a struct is a value I can define on the spot.

So I define an anonymous struct type inside pullPtrSelf, put a function called pull inside it, and return .pull, a reference to that function. The struct holds no data here. It is only a namespace for the function. The point is that T and name are comptime parameters of pullPtrSelf, so when the compiler builds the struct it bakes their concrete values straight into pull. Calling pullPtrSelf(Gui, "Gui") and pullPtrSelf(Probe, "Probe") produces two different struct types, and therefore two different pull functions, each with its own T and name already filled in. Returning .pull hands back one of those concrete functions, ready to be used as an ingredient of a CFn. It is Zig's idiom for a function generated from comptime arguments, the same comptime machinery that powers generic types, and once you recognise it you will spot the same move in metaIndex and methodCFn.

Why make pullSelf a pluggable function instead of hard-coding "grab the pointer from slot 1"? Because not every receiver is a raw pointer.

Store handles, not pointers

For Scene and Input I stored a borrowed *Scene inside the userdata. That is fine for them, because they live as long as the game does. A Node is different. Nodes live in a pool inside the scene, they are created and destroyed during play, and I reload the scene while developing. The moment I reload, every pointer a script is holding dangles. Lua has no idea. It will happily call translate on freed memory, and I get the worst kind of bug, the one that corrupts silently and crashes somewhere unrelated.

A raw pointer is the wrong thing to hand across the scripting boundary. The script outlives the things it points at, and it has no way to know when one has gone away.

The fix is to not store a pointer at all. I store a handle that can tell when it has gone stale. I follow the same approach as Handles are the better pointers by Andre Weissflog: hand out an integer that packs an array index plus a generation tag, keep the real objects in arrays the system owns, and resolve a handle to a pointer only at the moment of use, checking the tag as you go.

My node pool is built on zig-gamedev's zpool, which does exactly that. Every Handle(Node) is an array index plus a cycle counter, and when a slot is freed and reused the cycle bumps, so a handle to the old occupant no longer resolves. The scene then carries one more counter of its own, an epoch that bumps every time the whole scene reloads. The userdata I give Lua bundles all three together:

fn RichHandle(comptime T: type) type {
    return struct {
        // zpool handle: array index + cycle counter
        handle: model.Handle(T),
        
        // the scene this handle belongs to
        scene: *model.Scene,
        
        // the scene's reload counter when we handed this out
        epoch: u32 = 0,
    };
}

Why both a cycle counter and an epoch? They catch different mistakes. zpool's cycle counter catches a single node being destroyed and its slot reused mid-game. The epoch catches a coarser case: when I reload a scene I throw the whole pool away and build a new one, and the fresh pool could hand out the same index and cycle the old one used. Bumping the epoch once per reload makes a handle from the previous scene fail to match.

Every access from Lua goes through one resolver, and that resolver is where the safety lives:

fn resolveNode(node_handle: RichHandle(Node)) !*Node {
    if (node_handle.epoch != node_handle.scene.epoch) {
        // the scene was reloaded since we handed this out
        return error.StaleHandle;
    }
    // zpool resolves index+cycle to a live pointer, or errors if the slot was reused.
    return try node_handle.scene.nodes.getColumnPtr(node_handle.handle, .node);
}

The two checks stack. First the epoch comparison rejects handles from a reloaded scene. Then the try lets zpool run its own cycle check inside getColumnPtr and return an error if the slot was reused. Either way the script gets a clean error instead of a dangling dereference. This is why pullSelf is pluggable: a Node's receiver is not userdata.*, it is "validate the handle, then resolve it to a live pointer, or raise a Lua error". And because pullSelf is just a parameter, the same methodCFn machinery binds both kinds of type without a separate code path: the permanent ones like Scene, where it takes the pointer directly, and the validated ones like Node, where it checks the handle first.

The rule I took away, after it cost me real debugging: a scripting layer must never hold a raw pointer to something whose lifetime it does not control. Hand it a handle it can validate, and validate on every access. The cost is one integer comparison. The other option is a crash you cannot reproduce.

One manifest, one source of truth

All the pieces are here. The last step is to describe the API in one place. I use a small data structure, a list of classes, each with a list of methods, plus a couple of helpers to build each entry. This list is the single description everything else comes from:

const MANIFEST = [_]Class{
    .{ .name = "Node", .methods = &.{
        // rawMethod: I supply both the CFn and the signature string by hand.
        rawMethod("is_valid", zlua.wrap(nodeIsValid), "fun(self: Node): boolean"),
        rawMethod("get_name", zlua.wrap(nodeGetName), "fun(self: Node): string"),
        // autoMethod: the CFn and the signature are both derived from the Zig function.
        autoMethod("translate", model.Node.translate, pullNodeSelf),
        autoMethod("get_child_count", model.Node.getChildCount, pullNodeSelf),
    } },
    // ... Game, Scene, Gui ...
};

Look at the two kinds of entry next to each other, because the contrast is the design. autoMethod takes a real Zig function and derives two things from it by reflection: the marshalling shim, through methodCFn as we built above, and a human-readable signature string, through a small helper called luaSig. We have not used that second thing yet. It describes the function in the notation an editor understands, and it is the subject of the next section. rawMethod is the escape hatch. When a binding needs something reflection cannot express, like the handle validation in nodeIsValid or returning nil for an optional, I hand-write the CFn and supply its signature string myself. Most of the API is autoMethod. The few genuinely special cases are rawMethod. If the generator only automated and gave me no way out, the first irregular function would be a wall; keeping rawMethod a first-class peer of autoMethod means I never hit it.

Binding the whole thing at startup is then a single loop over the manifest that builds each metatable and registers its methods. Add a class, add a line. Add a method, add a line.

The payoff: the editor learns my API

This is the reason the manifest is shaped the way it is.

When you write Lua against an engine, the editor has no idea what node: can do. No autocompletion, no type checking, nothing, because Lua is dynamically typed and your API is invisible to the tooling. The Lua ecosystem's answer is LuaCATS: annotation comments that describe your classes and signatures, which the language server reads to give you completion and diagnostics. They look like this:

---@class Node
---@field translate fun(self: Node, arg1: number, arg2: number, arg3: number)
---@field get_child_count fun(self: Node): number

Normally you write these by hand, and then you have two descriptions of your API, the bindings and the annotations, drifting apart the moment you forget to update one. I am not going to maintain the same thing twice.

So I generate the annotations from the same manifest. Each autoMethod already carries the signature string that luaSig produced. luaSig walks the function's parameter and return types and emits LuaCATS type names: bool becomes boolean, []const u8 becomes string, ?*Node becomes Node?. The same @typeInfo walk that builds the runtime shim builds the documentation. Then a comptime string-concatenation pass turns the whole manifest into one .lua stub file:

fn classesDefs(comptime classes: []const Class) []const u8 {
    // the whole stub, built at compile time
    comptime var s: []const u8 = "";
    
    inline for (classes) |c| {
        // one class header per manifest entry
        s = s ++ "---@class " ++ c.name ++ "\n";
        
        // one ---@field line per method: its Lua name and its luaSig signature
        inline for (c.methods) |m| {
            s = s ++ "---@field " ++ m.lua_name ++ " " ++ m.sig ++ "\n";
        }
        s = s ++ "\n";
    }
    return s;
}

The engine writes this file out, the language server picks it up, and my game scripts get autocompletion and type checking for an API that exists only inside my Zig source. Change a Zig function's signature and the stub changes with it on the next build. There is one source of truth, and it is the Zig code.

That is the real reward of doing bindings through reflection. I wrote less plumbing, yes. But the better part is that the binding, the safety checks, and the editor tooling are all projections of the same types. They cannot drift apart, because there is nothing to keep in sync.

What I would tell myself before starting

Three things, if you are about to do this:

Learn the stack protocol first. Every binding, by hand or generated, is "pull arguments off the stack, call the function, push results back". Once that is second nature, the generator is just code that writes the pattern for you. The Lua C API reference documents what every call pushes and pops.
Reflect over types, do not duplicate them. @typeInfo, std.meta, and inline for let the compiler write the marshalling, and they turn an unsupported type into a compile error instead of a runtime surprise.
Never let a script hold a raw pointer to engine-owned, short-lived data. Hand it a handle it can validate, and check on every access. Handles are the better pointers makes the full case, and zpool is a ready-made implementation.

The engine is still small and the API keeps growing, but the binding layer has stopped being a chore. I add a Zig function, drop one line in the manifest, and it is callable from Lua and autocompleted in the editor.

You tell me what to bind next.

Integrating Vulkan Ray Tracing in Godot

Antonio Caggiano — Sat, 30 May 2026 00:00:00 +0000

Note: This blog post is a transcript of my talk at GodotCon. The conversational tone reflects the original presentation, aimed at walking through the work of bringing hardware ray tracing into the Godot engine.

During the pandemic I went deep into ray tracing. I wrote a software renderer from scratch, implemented a path tracer, and learned about techniques like importance sampling and multiple importance sampling. With these I was able to render really cool images, like the Stanford dragon below.

Why ray tracing

With ray tracing you can render beautiful pictures. The technique simulates the physics of light accurately, so you get effects that are difficult to fake: soft shadows, global illumination, reflections, and refractions.

At a certain point I wanted to share this with more people, but my code was just a prototype, and nobody would care about my prototype. This is where Godot comes in.

Why Godot

Godot is a game engine, and a lot of friends and colleagues use it. It ticks many boxes for me:

It is popular.
It is open source under the MIT license.
It is multiplatform.
It does not require royalties for publishing your game.
It is just a single file that you put on your desktop. You double-click, and it works.
And most importantly, it compiles in a few minutes on my machine. If you have ever compiled other game engines, you know what that means for productivity.

A couple of years ago, however, Godot had no support for hardware ray tracing. I thought I could help with that. How cool would it be to have something like this in Godot?

The picture shows a technique called ray traced ambient occlusion, which tries to estimate where light struggles to reach. You get nice soft shadows below a cube, or behind curtains, where the light cannot easily get in.

Adding Vulkan ray tracing to Godot. How hard could it be?

That was the challenge. I had a bunch of Vulkan code in my prototype, which was the result of following the NVIDIA ray tracing tutorial. You cannot just take that code and drop it into Godot, it does not work like that.

At a high level, to do ray tracing you need to do four things:

Create a bounding volume hierarchy.
Create a ray tracing pipeline.
Create the shader binding table.
Trace rays.

Let me go into a bit more detail on each.

Bounding volume hierarchies

A bounding volume hierarchy is boxes containing boxes containing geometries. What problem does it solve?

When you want to ray trace something, you shoot a ray and look for an intersection. Your scene may contain many geometries, and naively you would iterate through all of them looking for an intersection with the ray. That is a linear algorithm, and it does not scale.

Instead, you can subdivide the space. You check for intersection on each cell of your space, and if you hit a cell, you go down and look for the geometries inside it. The algorithm becomes logarithmic.

You can also subdivide the space within the space. You create a top level acceleration structure (TLAS) at the top, and bottom level acceleration structures (BLAS) underneath. Geometries live inside the BLAS, and instances of those BLAS are referenced from the TLAS.

In pseudocode, you iterate through all the pixels in your framebuffer. You generate a ray and look for an intersection by traversing the bounding volume hierarchy. You either get an index of the geometry you hit, or you do not hit anything, which is a miss. If you hit a geometry, you can shade it: pick the material and, according to the lighting model, get a pixel colour on the screen.

for pixel in framebuffer:
    ray = generate_ray(pixel)
    i = intersects(ray, bvh)
    pixel.color = shade(ray, geometries[i])

Ray tracing pipeline

The ray tracing pipeline is tied to the GPU, and there are hardware modules for it.

You generate a ray and trace it by looking for intersections in the bounding volume hierarchy. Inside the GPU this is a data structure, and the traversal is accelerated by the hardware. That is why we call it an acceleration structure.

If we have an intersection, we ask: is this the closest geometry to the origin of the ray? If so, we have a closest hit, and we run a shader to compute the colour. If there is no hit, we have a miss, and we still want to do something, for example return the colour of the sky. For that we use a miss shader.


flowchart TD
    RG[Ray Generation]
    AST[Acceleration Structure Traversal]
    RG -->|Trace Ray| AST

    INT[Intersection]
    AH[Any Hit]
    AST --> INT
    INT --> AH
    AH --> AST

    MISS[Miss]
    CH[Closest Hit]
    AST -->|Hit? No| MISS
    AST -->|Hit? Yes| CH

Fitting ray tracing into Godot

I have this Vulkan code, I want to put it in Godot, but I cannot just drop it in. There are constraints:

I should not break the engine.
It should fit Godot's rendering abstractions.
It should perform automatic synchronisation via the render graph.
I need to expose this new ray tracing API to the user via scripting.
It should be multi-backend friendly. Godot does not only have Vulkan, it also supports Direct3D 12 and Metal. The interface should be unified.

The end goal

Brace yourself, I am going to show you some code. This is what I would like the final API to look like. If you are familiar with GDScript and the RenderingDevice object, you probably already use the parts at the top. The functions highlighted below are new and exposed to you.

var rd = RenderingServer.create_local_rendering_device()

# New: create a bottom level acceleration structure for the scene geometries.
var blas = rd.acceleration_structure_create_bottom_level(geometries)

# New: create a top level acceleration structure with one or more instances.
var tlas = rd.acceleration_structure_create_top_level(instances)

# Record commands.
var rtl = rd.raytracing_list_begin()
rd.raytracing_list_bind_pipeline(rtl, pipeline)
rd.raytracing_list_bind_uniform_set(rtl, uniform_set, 0)
rd.raytracing_list_trace_rays(rtl, width, height)
rd.raytracing_list_end()

Where GPU rendering lives in the engine

So, what code do I touch? I came up with the following picture. There are a few classes in the Godot source that matter:

RenderingDevice
RenderingDeviceGraph
RenderingDeviceDriver


---
config:
  class:
    hideEmptyMembersBox: true
  layout: elk
  elk:
    nodePlacementStrategy: SIMPLE
---
classDiagram
    class RenderingDevice["RenderingDevice (RD)"]
    class RenderingDeviceGraph["RenderingDeviceGraph (RDG)"]
    class RenderingDeviceDriver["RenderingDeviceDriver (RDD)"]
    class RDDVulkan
    class RDDD3D12
    class RDDMetal

    RenderingDevice *-- RenderingDeviceGraph
    RenderingDevice *-- RenderingDeviceDriver
    RenderingDeviceGraph *-- RenderingDeviceDriver
    RenderingDeviceDriver <|-- RDDVulkan
    RenderingDeviceDriver <|-- RDDD3D12
    RenderingDeviceDriver <|-- RDDMetal

The RenderingDeviceDriver is a polymorphic type. It is a unified interface over the graphics APIs available to us, with concrete implementations for Vulkan, Direct3D 12, and Metal.

In the middle is the RenderingDeviceGraph. I really like this class. It is the authority on synchronisation. It is responsible for recording commands and tracking resource usages, and it generates barriers automatically based on those usages, which is incredibly useful.

What are barriers?

The GPU is highly parallel hardware. It tries to do everything at once if it can. Sometimes, though, you do not want that: you want to do something first, then something after that finishes. A GPU barrier is the way to tell the GPU "please wait for this operation to finish before starting the next one".

I do not need to issue these barriers myself. The render graph generates them for me. That is why I like this class.

How the graph works

The graph is a directed acyclic graph. Nodes represent GPU operations such as uploading data to a buffer, running a render pass, or running a compute pass. Edges between nodes are resource usages: do I read from the resource, do I write to it, do I use it for a specific reason?

With this information, the RenderingDeviceGraph detects dependencies between operations and resources, and generates barriers for me. There is a nice blog post on the Godot Engine website by DarioSamo, GPU synchronisation in Godot 4.3 is getting a major upgrade, that I recommend if you want a better understanding of the topic.


flowchart TD
    a((a))
    b((b))
    c((c))
    d((d))
    e((e))

    a --> b
    a --> c
    a --> d
    a --> e
    b --> d
    c --> d
    c --> e
    d --> e

The Rendering Device

At the very top is the RenderingDevice. This is the GPU API exposed to Godot developers. It is responsible for creating GPU resources and recording commands, which it does by delegating to the classes on the right. Anything that involves command recording and synchronisation goes through the RenderingDeviceGraph. Anything related to resource management goes through the RenderingDeviceDriver.

Ray tracing hello world

The idea is to do the ray tracing hello world: one triangle, one ray per pixel. What is the minimum set of changes needed to get a ray-traced triangle on the screen?

Here is the road map I ended up with:

Extensions and properties.
New types and APIs available to the user.
Acceleration structures.
Ray tracing shaders.
Recording commands.

Vulkan requirements

Not every GPU supports ray tracing. These features are quite new in the industry, and in Vulkan the ray tracing API is an extension, which means it is not enabled by default. I need to query the GPU: do you support acceleration structures? Do you support the ray tracing pipeline? Do you have all the requirements I need?

If yes, the new Godot APIs become available. Otherwise, they do not. There are also a few properties I need to query for the size of objects, alignments in memory, and similar details, which the user will not have to care about. I take care of those.

A new pipeline type

So far Godot had two pipelines: rasterisation for drawing things on the screen, and compute for generic computation. Now we have a new one for ray tracing.

Together with the pipeline come new shader stages:

raygen shader: how we generate rays. Typically you generate rays at the camera position, shooting in the camera's view direction.
miss shader: what happens when the ray does not hit any geometry. Maybe you want the colour of the sky.
closest hit shader: what happens when the ray hits the closest geometry.
any hit shader: invoked every time the ray hits something, not necessarily the closest. Useful for things like transparency.
intersection shader: by default the GPU has a hardware module to accelerate ray-triangle intersection, which is super fast. If you want a different geometry, for example a signed distance function, you can provide your own intersection shader. I think that would be very cool.

I create the shader stages, group the closest hit and any hit shaders, and together they form a ray tracing pipeline.

Where to store the objects

At this point I have a question: where do I put my objects? I have all these Vulkan objects I created, and I need to specify their lifetime. Who creates them, who destroys them?

There is a nice pattern in the Godot source code: the concept of an owner. The owner is an object that holds GPU resources. You put your object into the owner and you get back a lightweight ID, an RID, which is just an access key you can use later to retrieve the object.

I ended up creating an owner for acceleration structures and an owner for ray tracing pipelines.

New engine APIs

These are the new functions available via the RenderingDevice. This is the part that you care about. The API is still experimental: the function names may change, the parameters may change. But so far we have functions for:

Creating BLAS and building them.
Creating TLAS and building them.
Creating the ray tracing pipeline.
Recording commands, which I will show in a moment.

The instances buffer

The instances buffer is an interesting object. It is the way we build the TLAS.

To build a BLAS we just need a collection of geometries, and we put those into the BLAS. The TLAS is different: we cannot just put a BLAS into a TLAS directly. We may want to use the same BLAS several times, instanced at different positions in space.

This is done via the instances buffer: a reference to a BLAS plus a Transform3D so we can place it in the world.


flowchart TD
    BLAS[BLAS]
    T3D[Transform3D]
    IB[InstancesBuffer]
    TLAS[TLAS]

    BLAS -->|*| IB
    T3D -->|*| IB
    IB --> TLAS

The scratch buffer

The scratch buffer is needed when we build acceleration structures. The GPU tells us: "I need some memory where I can do my computation while building the acceleration structure, please give it to me." You ask, "Can you not figure that out yourself?" and the answer is no. You specify it, and the GPU can build the acceleration structure.

You, the user, never have to care about this. I take care of it for you.

Resource usages

Earlier I mentioned that the render graph tracks operations and resource usages. For ray tracing the operations are:

Building acceleration structures.
Tracing rays.

The resource usages are things like:

When building a TLAS, the BLAS is used as a build input.
When tracing rays, we read from the memory representing the TLAS.

From these, the render graph generates the appropriate Vulkan barriers for me. Very cool.

Ray tracing shaders

This is the part where I introduced new markers in source files: markers for raygen, miss, closest hit, any hit, and intersection. Below is an example of a single source file containing three shaders: a raygen shader, a miss shader, and a closest hit shader.

#[raygen]
#version 460
#extension GL_EXT_ray_tracing : require

layout(set = 0, binding = 0) uniform accelerationStructureEXT tlas;
layout(set = 0, binding = 1, rgba8) uniform image2D output_image;

layout(location = 0) rayPayloadEXT vec3 payload;

void main() {
    vec3 origin = vec3(0.0);
    vec3 direction = vec3(0.0, 0.0, 1.0);
    traceRayEXT(tlas, gl_RayFlagsOpaqueEXT, 0xFF,
                0, 0, 0, origin, 0.001, direction, 10000.0, 0);
    imageStore(output_image, ivec2(gl_LaunchIDEXT.xy), vec4(payload, 1.0));
}

#[miss]
#version 460
#extension GL_EXT_ray_tracing : require

layout(location = 0) rayPayloadInEXT vec3 payload;

void main() {
    payload = vec3(1.0, 0.0, 0.0); // red on miss
}

#[closest_hit]
#version 460
#extension GL_EXT_ray_tracing : require

layout(location = 0) rayPayloadInEXT vec3 payload;

void main() {
    payload = vec3(0.0, 1.0, 0.0); // green on hit
}

The raygen shader generates a ray at the origin pointing along the z-axis. There is probably a bug somewhere in there. The miss shader returns red when the ray hits nothing. The closest hit shader returns green when the ray hits something.

The shader binding table

The shader binding table was a headache for me. It is an object the GPU wants when you build your ray tracing pipeline. It does not contain shaders directly, it contains shader group handles. When you build it, you also have to handle the size of the handles, their alignment in memory, and the strides of each region. It is complicated stuff that you, the user, should never have to care about.

Command list

This is how Godot records commands: they are pushed into a list. There is a draw list for the rasterisation pipeline, a compute list for the compute pipeline, and now a ray tracing list for the ray tracing pipeline.

In practice that is just a bunch of new functions on the RenderingDevice, all available from GDScript. We have raytracing_list_begin and raytracing_list_end. Between those two, you bind objects, push data, and trace rays.

The minimal sample, in full

Going back to our minimal sample, this time with the full picture:

var rd = RenderingDevice.new()
assert(rd.has_feature(RenderingDevice.SUPPORTS_RAYTRACING_PIPELINE))

# Create BLAS and TLAS for a mesh.
var blas = rd.blas_create(
    [geometry],
    RenderingDevice.ACCELERATION_STRUCTURE_GEOMETRY_OPAQUE_BIT)
var tlas = rd.tlas_create(1)

# Build acceleration structures.
rd.blas_build(blas)

var instance = RDAccelerationStructureInstance.new()
instance.blas = blas
rd.tlas_build(tlas, [instance])

var raylist = rd.raytracing_list_begin()

# Bind pipeline and uniforms.
rd.raytracing_list_bind_raytracing_pipeline(raylist, raytracing_pipeline)
rd.raytracing_list_bind_uniform_set(raylist, uniform_set, 0)

# Trace rays.
var width = get_viewport().size.x
var height = get_viewport().size.y
var depth = 1
rd.raytracing_list_trace_rays(raylist, 0, sbt, width, height, depth)

rd.raytracing_list_end()

Creating the ray tracing pipeline

How do you create the pipeline object? You take a GLSL shader, compile it to SPIR-V, create a shader object from the SPIR-V, group the resulting stages into hit groups, and call the pipeline create function. It looks convoluted, but you will figure it out.

func _initialize_raytracing_pipeline():
    # Load shaders and create raytracing pipeline
    var shader_file = load("res://ray.glsl")
    var shader_spirv = shader_file.get_spirv()
    var shader = rd.shader_create_from_spirv(shader_spirv)

    var pipeline_shader = RDPipelineShader.new()
    pipeline_shader.shader = shader

    var hit_group = RDHitGroup.new()
    hit_group.closest_hit_shader = pipeline_shader

    var raytracing_pipeline = rd.raytracing_pipeline_create(
        [pipeline_shader],
        [pipeline_shader],
        [hit_group],
        1)

Creating uniforms

Uniforms are how we push data to the GPU. In my sample I have two: one for the output image, and one for the TLAS, which is the object I use to traverse the hierarchy and look for intersections.

And here we have our nice triangle. The triangle is green, meaning the ray hit the geometry. Red means the ray missed.

func _initialize_uniforms():
    # Storage image uniform
    var image_uniform = RDUniform.new()
    image_uniform.uniform_type = RenderingDevice.UNIFORM_TYPE_IMAGE
    image_uniform.binding = 0
    image_uniform.add_id(output_image)

    # Acceleration structure uniform
    var as_uniform = RDUniform.new()
    as_uniform.uniform_type = RenderingDevice.UNIFORM_TYPE_ACCELERATION_STRUCTURE
    as_uniform.binding = 1
    as_uniform.add_id(tlas)

    uniform_set = rd.uniform_set_create([image_uniform, as_uniform], shader, 0)

The pull request

At this point I felt the implementation had enough code to call it done. I did not want to keep adding more. I wanted to open a pull request that was the minimum set of changes needed to implement this feature, because otherwise it would have been difficult for Godot maintainers to review and difficult for me to iterate on.

Even so, the PR is around 3000 lines of code and accumulated 174 comments, mostly asking for changes. I opened it on November 12, 2024, and it was merged on January 27, 2025. I want to thank the reviewers: Calinou, Mickeon, AThousandShips, DarioSamo, clayjohn, and reduz. Thank you very much for reviewing my code.

Going beyond the minimum: Sponza

On a separate branch, which is not a pull request, I went further. I wanted to take the geometry from a real scene and forward it to the ray tracing pipeline.

I rendered Sponza, but only half of it. Some geometries were missing. I started asking myself: where have those geometries gone? Why are some present and others not? I needed to debug it.

I noticed a weird cube in the middle of the scene. It was not really a cube, there were things inside it.

I opened it in a profiler and saw that there were indeed many geometries inside, but the vertex positions were all between zero and one. I scratched my head. Maybe there is some compression going on here?

Indeed, Godot compresses vertex attributes when you import a model. I disabled that behaviour, and boom: Sponza was rendered nicely through the ray tracing pipeline.

Ray traced ambient occlusion

In that screenshot you can also see ray traced ambient occlusion in action. I noticed that Godot has a nice node called WorldEnvironment, and I realised I could use it to add a post-processing step that does ray traced occlusion and composites the result with the default forward-plus pipeline.

So this is forward-plus without ray traced ambient occlusion.

This is forward-plus with it. Look at the difference, especially below the cube, where you can see a nice soft shadow, and behind the curtains, where you now see dark areas where the light struggles to reach. I think it is so nice.

What is next

With this in place, we can do other interesting things:

Ray traced reflections.
Custom visibility queries accelerated by the GPU's ray tracing hardware module.
A hybrid renderer.
Cinematic rendering.

You tell me.

Computer Graphics: Follow The Light

Antonio Caggiano — Tue, 03 Sep 2024 00:00:00 +0000

Note: This blog post is a transcript of my talk at the Archaeological Park of Paestum for Paestum Tech Days. The conversational tone and simplified explanations reflect the original presentation style, aimed at making computer graphics concepts accessible to everyone, regardless of their technical background.

Okay, let's start with a nice question: How do we see? With the eyes. The eyes are a marvel of nature. They are light sensors. They capture light and send a signal to the brain, which we interpret as our internal representation of the reality around us. Wonderful.

What is light? This second question is a bit more difficult. A didactic definition would be: a collection of photons. It is electromagnetic radiation — a variation of the electric and magnetic fields in space and time. It is a flow of particles and waves. The particles are photons. It has a dual nature: it has both a particle nature and a wave nature. Let's say it bounces like a ball, but it waves like the sea. It is energy that travels, so much so that we can capture it with solar panels to power our homes.

Yes, it's difficult. In fact, you need to be Einstein to have the genius idea to define light as a flow of photons, which are packets of energy. For example, a 60-watt light bulb emits 800 billion photons per second. And that's a lot. But what is the main source of photons that reaches planet Earth? The sun. How many photons does the sun emit per second? Many. It's such a large number that it's unimaginable.

How Does Light Work?

Okay, but if we want to simulate light with a computer, we need to understand it a bit more. It behaves like particles, so we can use the concepts of particle and wave physics, but we should also observe some phenomena that are typical of light.

For example, the phenomenon of transmission. Light passes from one medium to another, for instance, from space into the Earth's atmosphere. It arrives with a certain direction, intensity, and frequency, and continues in the same direction, with the same intensity and frequency.

There's the phenomenon of reflection, which happens with a mirror; a ray is reflected by the mirror and changes direction.

The phenomenon of refraction is typical of water when a ray changes direction making it seem like a straw is broken, but it is not. It's just the optical effect of light refraction changing direction.

The phenomenon of diffraction. Here we have a ray that splits into many other rays of different intensities or frequencies. A clear example is a prism, which is also a beautiful album by a musical group. The ray enters the left side of the prism and is split into other rays of different intensities. It exits on the right side but at different frequencies, and different frequencies correspond to different colors. We perceive a different color if the frequency changes, and our eye can capture certain frequencies of electromagnetic radiation. There is a range that we see, but outside this range, there are frequencies we cannot see, such as infrared and ultraviolet.

The phenomenon of absorption. Light is completely captured by an object and disappears, but it cannot disappear. No, because we know from the principle of conservation of energy that "Nothing is created, nothing is destroyed, but everything is transformed", so this ray becomes something else, presumably it could become heat.

The phenomenon of scattering happens in clouds. The ray splits into many other rays and goes everywhere. It also happens in fog. I don't know if you've ever seen streetlights in the fog; you see this halo.

In reality, all these light phenomena do not occur distinctly and separately but all happen together, everywhere, simultaneously. For example, there are materials that can reflect more, absorb more, or transmit/refract light more. But the other phenomena still occur, even if only to a small extent.

Light Simulation

Finally, we get hands-on. Let's delve into the technical issue of real-time light simulation.

What does real-time mean? I looked it up in the dictionary because I didn't know either. So, it means a duration corresponding to the real one, thus very quickly, almost immediately. Well, at least to give us the optical illusion of continuity. Our eye can perceive something as continuous if I update it every 16 milliseconds. Every 16 milliseconds a new image, so we perceive it as continuous. 16 milliseconds allow us to make 60 images per second.

Okay, so 16 milliseconds, but we have to do a lot of calculations here. I talked about billions and billions of photons. I can't simulate all these photons because I only have 16 milliseconds. So, are we interested in all the photons? No, maybe I can focus on a reduced number of photons. Okay, and which ones interest me? Those that hit the eye. These are the ones that contribute to the image. These are the ones that actually interest me.

In computer graphics, we use the term viewpoint or the term camera, from camera or video camera. So I will use camera and eye interchangeably. How can photons reach the eye? They can arrive directly. They start from a point source and reach our eye. Or they can also be emitted by objects that have a certain volume, like LED panels. They can bounce and reach our eye. In this case, it is called indirect light. And they can bounce more and more times, an indefinite number of times.

So how do I know which photons reach my eye? This is an important question because there are photons that do not reach the eye that I want to ignore. So, it's time to talk about practical methodologies. In computer science, we call these algorithms, which in the world of cooking are called recipes.

Whitted-style Raytracing

Step number one: what do I see? I know where I am, I want to understand what is in front of me. I trace a ray, what do I hit? Maybe I hit something. Yes, I found something. Okay, let's trace more rays. Maybe I continue along this path. I trace a ray in the reflected direction and then trace other rays to reach the lights in my scene. How many lights are there? I trace as many rays as there are lights.

Okay, so I trace a reverse path. This way, I make sure to trace paths that reach the camera, so I focus only on those photons, right? Clearly, it doesn't end here, because light bounces, so the reflected ray bounces on a new object. For the new object, I can trace other rays: a reflected ray and other rays to find the light recursively, repetitively.

Great, this algorithm was created in 1980 by Turner Whitted. It's called Whitted-Style Ray Tracing. Turner Whitted was a scientist at Bell Labs. According to Americans, Bell is the inventor of the telephone, but according to us, it's Meucci. At that time, Bell Labs was part of the American Telephone and Telegraph Company.

I hope that's clear. For each bounce of light, a reflected ray and other rays towards the lights in the scene. But there's a small flaw in this algorithm. What happens if my scene has thousands and thousands of lights? My electrician went crazy and created a lot of LEDs in my room. Can I simulate them all? I could spend a lot of time tracing rays for all these lights, so I need to find a better solution. I need an algorithm that scales better with the complexity of the scene.

So, let's try a new algorithm.

Path Tracing

Let's start from scratch. What do I see? I trace a ray. This remains common, alright? I found something, but at this point, I don't trace a ray following the previous steps; instead, I trace only one, but randomly. I find something. Okay, I continue. I trace another ray in a random direction. Oh, I was lucky. I found a light along the way. But I was very lucky. This is a path, let's remember that.

However, there are rays that I choose randomly that might not hit anything in my scene; they might get lost in the void, they might miss the light. The ray is sad.

I mentioned Path, in fact, this algorithm is called Path Tracing. It was created in 1986 by Jim Kajiya. At that time, he was a professor at the California Institute of Technology, and since 1994, he is a researcher at Microsoft.

How beautiful. This is an image created with the Path Tracing algorithm. It is a scene called Cornell Box. Cornell Boxes are a family of 3D scenes that can vary in wall color or objects in the scene. I can vary them a bit as I like, but fundamentally they are 3D scenes created by academics at Cornell University. Cornell University is located in Ithaca, which is a college town in the state of New York.

These are examples of paths that light can take. Let's look at path number one. A bounce on the metal sphere and then it reaches the camera. Path number three bounces on the wall, the ceiling, and then reaches the camera. But path number two is more interesting because of the glass sphere, so we have the phenomenon of refraction. The ray is bent, passes through the sphere, and then reaches the camera.

In this image, we can see how the final result improves as the number of paths I consider increases. Let's focus on image number one. You see, it's very noisy. There are many black pixels. Here, for each pixel, I made only one path, but some pixels are black. Why are they black?

I'll tell you: because, as I mentioned before, there are random paths that do not find any light along the way, so it's as if it's dark. That's why. But I can do something: maybe, for each pixel, I don't make just one path but try to make another one, and I might be luckier. This way, I increase the chances of finding the light.

In mathematics, we call these "samples", using the technical term "samples per pixel". I increase the number of samples per pixel to 2, 4, 8, 16, 32, 64, 128, and I get a more beautiful, more defined, clearer image. I found the light with a higher probability.

However, I have to consider more paths, so I have to do more calculations, which means I might exceed the budget of 16 milliseconds. I always have to be careful not to overdo it. Maybe I can focus only on some paths; I can use some techniques. Indeed, Turner Whitted had somewhat guessed right in trying to find the light as soon as possible in order to reduce the number of samples to obtain a well-defined image.

From 1986 onwards, however, algorithms have been improved, and I can achieve better results with fewer samples compared to naive ray tracing.

Maths

In short, I talked about Whitted-Style Ray Tracing, I talked about Path Tracing, which are algorithms in the Ray Tracing family. What I really mean is: Maths.

Maths. In fact, I can represent a ray with a point and a vector. The point is the origin, the vector is the direction of my ray. I represent geometries with points and indices to connect these points, like that puzzle game. For transformations, I can use matrix multiplications to enlarge, resize, rotate, and translate objects. I solve intersections between rays and geometries with systems of equations, the ray equation and the triangle equation, in this case.

Light is simulated and calculated with integrals, and here it gets a bit more complicated. But speaking of integrals, let me show you my favorite formula: the rendering equation.

$L_o(x, \omega_o) = L_e(x, \omega_o) + \int_{\Omega} f_r(x, \omega_i, \omega_o) L_i(x, \omega_i) (\omega_i \cdot n) d\omega_i$

How beautiful, look how beautiful it is. Okay, I'll read it to you, I'll read it simply. The light that arrives in my direction is equal to the light emitted by a certain surface, maybe a LED, and all the light that arrives on this surface and is reflected in my direction. They should teach mathematics like this in school.

Raytracing Algorithm

This is roughly how a ray tracing algorithm works. Don't worry because I'll read it to you, line by line.

for y in range(0..screen.height):
   for x in range(0..screen.width):
       ray = Ray(origin = [x, y, 0], direction = [0, 0, 1])
       for geometry in scene:
           intersection.color = intersect(ray, geometry)
           if intersection is not None:
               screen.pixels[y][x] = intersection.color

For y that goes from zero to the height of the screen, so I can do one row at a time, okay? 0, 1, 2, 3, 4, 5, 6, 7, up to the height of the screen. Simple.

The second line, another loop, for x that goes from 0 to the width of the screen, and I do this for each row. So for the first row, all the pixels of the row. 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15.

Okay, I'll explain the rest in words. In simple terms, for each pixel, I do this: I trace a ray, see what is in front of me, if I hit something it's an intersection and I have to calculate the color. The color varies based on the material I hit and all the lights in the scene.

This is an example of the result. Up close, you can't understand anything, but from a distance you can see that it's a Cornell box. There's a red wall on the left, a green wall on the right, and there are two objects in the scene.

This algorithm is computationally expensive because you have to check for each ray if it intersects an object in the scene, and I have to check all the objects to see which one is closest, so if the complexity of the scene increases, the time I spend doing all these checks also increases. It requires a lot of memory because the entire scene has to be available in memory, because for each bounce I have to check again if I hit all the objects in my scene, and let's say a scene can weigh several MBs if not GBs, and here we are in 1986 and memory isn't like it is today.

Do I have a reasonable alternative? Maybe an algorithm that allows me to focus on one geometry at a time? Yes, I do! It's called rasterization.

So, what it actually does is focus on one geometry at a time. It loads the geometry into the graphics card, performs the necessary calculations, checks if each pixel is within the geometry, and calculates the color.

Rasterization Algorithm

Then, it unloads the geometry and loads another one, so I can focus on just one small triangle at a time, which is only a few bytes. Computationally, okay. I've already mentioned this part: it checks if a point is within a geometry and has low memory usage because it focuses on one geometry at a time.

However, the rasterization technique loses some of the phenomena that light gives us, and the trade-offs are these: I lose reflections, I lose refraction, I lose indirect light because I don't do the bounces, I lose shadows, and I also lose this beautiful phenomenon called caustics.

Caustics are those light phenomena concentrated in certain points due to the curvature of geometries, in this case, the glass.

I can achieve all these techniques with rasterization, but I have to use tricks, I have to approximate them, and they are not as faithful as ray tracing because ray tracing actually simulates the behavior of light and is very precise, giving us all these things for free.

We are approaching the conclusion because a few decades later, after the 80s, the 90s, the 2000s, the 2010s, we reach 2020 and, along with the pandemic, the first hardware products that accelerate ray tracing come to market. What these beautiful, powerful graphics cards do is calculate the intersections between rays and geometries for us.

Hardware Accelerated Raytracing

They are incredibly fast, orders of magnitude faster than the normal processor we have in our computers. So, with the latest generation smartphones, we can do amazing things.

Let me make this cameo: 'What a Time To Be Alive'!

NcJump devlogs

Antonio Caggiano — Thu, 31 Dec 2020 00:00:00 +0000

NcJump is a platform game project developed with a relatively new engine: nCine, an open-source C++ framework for 2D games developed by @encelo.

Some time ago, a bunch of members of the GameLoop community followed CS50's introduction to game development, and I thought the sequence of games presented in this course could give me a good insight into what kind of game to create.

A couple of developers have already made or started to make the first few games listed by that course. There is a Pong clone made by @encelo, a Flappy Bird clone made by @Vasile-Peste, and a Breakout clone under development by @mat3. I opted for a Super Mario Bros clone.

The idea was to follow the steps of CS50's lecture 4 by using nCine instead of Love2D.

Some steps are required in order to start developing a game, but luckily everything you need to know is documented on the nCine download web-page. I installed nCine, cloned ncTemplate, and started working on top of it.

Writing down some code

The main thing to consider from a software design perspective is that I renamed the main class of the template, MyEventHandler, to JumpHandler and introduced a Game class. While JumpHandler acts as a bridge between the game and the engine, Game is the nucleus of the project and is responsible for the lifetimes of its objects and the logic of the application.

Then I proceeded to implement an Entity class, following the idea of an Entity component system. The entity can have components like a graphics sprite, a finite state machine, or a body for physics and collisions.

A GUI is mandatory to quickly iterate on new elements as they are added to the game, both to have visual feedback when debugging is needed and to tweak all sorts of values and configurations at run time. For this, I introduced an Editor class, which makes heavy use of @ocornut's Dear ImGui, also provided directly by nCine.

Box2D is my choice for 2D physics and collisions. It is made by @erincatto and it is very easy to use.

Everything is entity

I implemented some key Entity states: idle, move, jump, and fall. In my opinion they are the foundations of the whole gameplay and I believe the result is good enough to move on to the next steps. Then I spent some time refactoring the Entity source code that was becoming too monolithic, and improving the tileset and tilemap by using entities instead of raw sprites for both tile prototypes and concrete tiles.

An important consideration is that everything is an entity. Characters are entities, tiles are entities, triggers are entities, and so on. So how do you distinguish between them? Every entity can have multiple components, whether it is an image or a state machine or a physics body, therefore different set of components will determine all the different kinds of entities which will populate a game scene.

component	optional
Transform	no
Graphics	yes
Physics	yes
State	yes

Transform

The transform component is simply a wrapper around a ncine::SceneNode. Everything else is supposed to be related to this node, so if we want to move the overall entity, we can just update the node of the transform component. It is worth mentioning that we use a unique pointer to store the node on the heap to make sure its memory would not move. This is needed as the nCine scene graph works with pointers.

Physics

The physics component as well acts as an abstraction layer between the game and Box2D; it holds values like the maximum velocity, jumping strength, and so on. Most importantly, it keeps track of a handle to a b2Body, which is the means to query the current physical state of the entity.

Graphics and State

At the base level, we have a graphics component with a single image or animation, and a state component with a single state which never changes. These are possibly the most common among the entities of a game.

Now we need to consider the concept of a moving character with states like idle, move, jump, and fall. This set of states is also very common, so we implement it directly in C++. The result is the following class hierarchy.

Subclass	states
SingleState	IDLE
CharacterState	IDLE, MOVE, JUMP, FALL

It follows that a CharacterState class is closely coupled to its related graphics component, which we define as CharacterGraphics, so the graphics components class hierarchy is quite similar to the previous one.

Subclass	graphics
SingleGraphics	IDLE
CharacterGraphics	IDLE, MOVE, JUMP, FALL

As a final consideration, while a state component should be unique for each entity, a graphics component could be shared between multiple entities to avoid duplicating these kinds of heavy objects.

The smooth

I introduced a camera component and serialization to load and save to file the state of the game. While the former was pretty easy and straightforward to implement, the latter required introducing a new dependency and various scattered refactorings to pay some technical debt accumulated from previous development iterations.

That was easy. The camera component has two main attributes: the scene root node and the target node. The scene root node is needed because we need to simulate the camera, which means that what we actually transform is the scene root node. In other words, to move the camera in one direction, we translate the scene root node to the opposite of such a direction. The target node is the one the camera should follow. As the target node moves around the scene, the camera is updated to match its coordinates.

The quickest way to implement a following camera is to just write down something like camera.position = target.position, and while it works, it is not the best we could do. A better and nicer approach, which might also prevent motion sickness, is to implement a camera with smooth movement. This can be done by linearly interpolating the camera and the target position by a small factor at every update of the game.

void Camera::update() {
  float smooth_factor = 0.125f;
  Vec2f smoothed_position = lerp(this->position, target->position, smooth_factor);
  this->position = smoothed_position;
}

The file

Conversely, this feature required a bit more work. I started by adding @nlohmann's json as a new dependency of the project for reading and writing to json files. I find it very easy to use in addition to the fact that I already used it for previous projects, like Jamspot: Sokoban. The second step was implementing functions to save certain objects to and load them from file.

void to_json(json& j, const T& t);
void from_json(const json& j, T& t);

The trickiest part was to make sure that all the serializable classes of objects could be default constructed. That means avoiding references as class members and preferring pointers, hence allowing semi-initialized objects while making sure they stay in this state for the shortest period possible to avoid logic errors or even crashes.

Once all this has been taken care of, I was able to edit the game configuration, the tileset, and the tilemap at runtime, close the game, and re-open it to find everything as I set it before. That is key to work on the levels of the game.

Jump higher

From a gameplay perspective, the player gains confidence with the elements of interactivity of the game. First it moves, then jumps, then jumps higher. The implementation is straightforward thanks to Box2D. If the jump button is still down, keep applying a small force upwards. Keep in mind that the force should be weaker than gravity, otherwise the character would take off into space.

void can_jump_higher(Input& input, Entity& entity) {
  if (input.jump.down) {
    auto force = b2Vec2(0.0f, small_amount);
    entity.physics->body->ApplyForceToCenter(force, true);
  }
}

Resizing the tilemap

This was less straightforward. I am starting to believe the more something is boring, the more difficult it is to implement. Resizing is not trivial; many things should be considered. For simplicity, here I will focus on the concrete tiles grid only. At the beginning, I used a simple vector to store all concrete tiles of the map and with a simple formula (y + x * height) I was able to index a cell of the grid. Then I realized that resizing this vector was not convenient as the order of the tiles in the cells would not be preserved.

As a solution, I changed the structure from a simple vector to a vector of vectors, so we could say a list of columns. That simplified indexing as you could just use the subscript operator to access the right tile (tiles[x][y]).

It also simplified resizing. If you want to change the width of the tilemap, you just modify the number of columns by calling tiles.resize(new_width). As you can imagine, if the width shrinks, you lose those columns, while if the width grows, you get new columns with a default concrete tile. I can not overstate the importance of default values. Changing the height is slightly different, as you need to resize all the columns.

for (uint32_t i = 0; i < width; ++i) {
  tiles[i].resize(new_height);
}

The easy stuff

While a static entity is not affected by physical forces and thus does not move, a dynamic entity is affected by forces, so it can fall and can be pushed and pulled around. Thanks again to Box2D, implementing this was just a matter of setting the type of physics bodies to either b2_dynamicBody or b2_staticBody.

Another easy but important thing to add was a proper background to give to players' eyes something more interesting to see than a boring solid color. I just added a static sprite, but I guess it would be nice to implement a fancy parallax scrolling effect in the future.

At this point, I realized that something was missing. Tiles and entities could be added and positioned freely in the scene and, as all normal people who like symmetry, I started wanting to destroy them, not by interacting through the editor, but as Mario does by punching (or hitting with his head?)!

Appetite for Destruction

Well, not every tile should be destructible, but some of them certainly could, and I supposed it could be a good idea to give this ability to the player.

I started by introducing a flag to determine whether a tile is destructible or not. Then I implemented a destruction listener, which is a Box2D contact listener, responsible for checking impulses generated from collisions between entities. When this impulse is big enough, both flags of the entities involved in a collision are checked and, if destructible, added to a list. This list is processed later when the actual destruction happens. It is important to note that this should not be done in the previous step if you want to avoid errors while Box2D is still processing its update.

After tweaking the threshold for the impulse triggering destructions, last thing to do was to increase manually impulses when the collision involved a character punching. In technical words, when one of the entities is a character and the normal of the collision is close to (0, -1) destruction is triggered for the other entity.

The result is really cool because not only do entities get destroyed after a collision with the main character, but they also get destroyed when heavy collisions happen between each other.

Push and pull

Dynamic entities have been added to the game, and they can be pushed and pulled around the scene. This meant that new states should be added to characters, push and pull indeed.

The push state is enabled when a character is trying to move and finds an obstacle either on its left or its right, quite easy to implement. Obstacles in the four directions (up, right, down, left) are collected after the physics system update by checking for physics body collisions and the normal of contact points. In addition, some bitflags are set which tell whether there are obstacles in any of the four directions.

The pull state is enabled when the player presses the x button and there is a dynamic obstacle, which is checked by querying the type of the obstacle's physics body. When the conditions are met, a distance joint is created between the character and the dynamic entity to make sure that, when the character moves, the distance between the two bodies remains the same, effectively giving the character the ability to carry around the entity. Of course, the joint is destroyed when exiting from the pull state.

Data submodule

A git submodule has been added to the repository under the data/ directory, pointing to Fahien/ncJump-data. There you could find the latest assets of the game: configurations, game maps, tile sets, and animations.

A better editor

Many improvements have been added to the in-game editor: a main menu bar at the top for choosing a placing mode between tile and entity, changing the opacity of certain elements of the scene according to the current mode for immediate visual feedback; a config window to tweak all sorts of values not directly related to the gameplay, like the size of the window, the scale of the scene or the UI, the offset of the camera to move around the scene without necessarily moving the character.

Factories

The time to add enemies to the game has finally come, and that translates to factories!

An enemy is just another kind of entity, which is the reason that pushed me towards implementing a class which sole responsibility is to create entities: the EntityFactory. This factory contains a list of entity prototypes which can be selected from the editor and placed into the scene. Under the hood, the prototype is cloned, the clone is moved at mouse position, and it is added to the list of entities of the scene.

At this point I realized that every clone was duplicating textures, which is something that could and should be avoided, so I introduced another factory: the GraphicsFactory. The responsibility of this class is to maintain a list of textures which can be referenced by multiple graphics components, as well as to create any kind of sprite that makes use of one of those textures.

Commands

Once I had enemies in the scene, I began wondering how to make them move. Reusing the state component of the main character sounded OK to me, but there was a problem. The movement logic within the state component was directly checking the gamepad and the keyboard, which meant that player's input would move both the main character and all the enemies. Decoupling to the rescue.

Input → MoveCommand → StateComponent

I removed the dependency to the input from the state component, and I introduced the concept of commands. For simplicity, I will just focus on the MoveCommand. The state component now is just listening for move commands and, when they are issued, the component inspects the values in a move command and updates its state accordingly. Move commands, and possibly other kinds of commands, can be issued by any source: player input, in-game console, scripts, and so on.

Scripts

Other engines may use terms like behaviors, but I prefer to stick with the technical term: script. With this you can indeed model behaviors of entities, like a wandering behavior that I had in mind for my first class of enemies. Ideally it might also be written with a scripting language, like LUA which is supported by nCine, but that is something I may explore in the future.

I wrote down a couple of line for the wandering behavior which should just move the entity to the right or to the left until an obstacle is encountered, and then it should turn back and continue in a loop. The result is quite interesting, but I believe it can be further improved.

Dying state

Definitely one of the fundamental states. Any living entity should die at some point, and this state represents that period of time where an animation should play, telling the player an enemy is defeated or that the game is over. The update method of this state is super easy and it looks like this.

void DyingState::update(Entity& entity)
{
    if (entity.animation.has_finished()) {
        entity.set_enabled(false);
        // just reuse this entity for something else
    }
}

Enabled flag

Of course this explains the Entity::set_enabled() method just introduced in the previous section. By calling it, we can effectively disable an entity and all its components without destroying it or freeing its memory, so that it can be recycled to be reused later when we, for example, need to spawn another entity.

Array of states

This was an important optimization. Before this, every state transition triggered the destruction of the old state and creation of an instance of the new state, which is not really needed and does not scale nicely as a scene grows. Now, a state component keeps track of an array of all the possible state objects, together with a pointer telling us which one is the current state.

Initial position

Another requirement for the scene is to define where the player should start. This initial position is a pair of coordinates which tells us just this. When a scene starts, we put the player there.

Definitions and factories

I love this pattern and I think I will use it from now on for all of my game projects. Basically, we have to deal with big and heavy objects which are not easily serializable. Think of wrappers around third party components like Box2D bodies or nCine sprites. I tried to find a way to serialize those objects and I believe I found a very nice solution which is anyway something widely used, so I possibly just reinvented the wheel here, but that is ok.

I do not serialize those objects. I do serialize their definitions. A definition is a collection of all the parameters needed to construct an object. Let us take a ncJump graphics component as an example.

// Very simplified
auto def = GraphicsDef(GraphicsType::TILE);
def.path = String("image.png");
def.layer = 2;

auto gfx = GraphicsComponent(def);

As you can see, the graphics component constructor takes a graphics definition as a parameter. A graphics definition, like all other definitions, is a Plain Old Data (POD) structure, which enables us to use nlohmann macros to quickly define all the functions needed to serialize it. Done. Awesome.

// That's it
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(GraphicsDef, type, path, layer);

CI and automatic deploy

The project builds automatically through GitHub actions, for Linux, Window, MacOS, Android, and believe it or not for the web. Indeed, click here and be prepared to say wow. All the credits for this go to the brilliant nCine author: @encelo!

All the updates can be found on the NcJump GitHub repository.

Rust+Wasm+WebGL: Create interesting interactive 3D content for the web

Antonio Caggiano — Thu, 17 Dec 2020 00:00:00 +0000

Direct Link

An exercise with boost::asio

Antonio Caggiano — Fri, 03 Apr 2020 00:00:00 +0000

If you are new to boost::asio, you can find a good introduction on boost.org.

This post describes an exercise built upon the asynchronous daytime server presented in the boost tutorial.

List of clients

The first thing we are going to implement is a way to ask the server for the list of clients currently connected. We need to keep track of incoming connections, therefore we add the following field to the server:

std::vector<std::unique_ptr<Connection>> Server::connections;

Since we use references to connection objects in other parts of the program, connections should not move from their position in memory. New connections may come in while other connections are still being handled. If the vector resizes, its objects might move. This is why we allocate connections on the heap and use smart pointers as elements of the vector.

Once we have a field to store incoming connections, Server::accept() can be improved. We do not need to create new connections all the time, as we can recycle old connections that were closed.

std::unique_ptr<Connection>* new_con = nullptr;

for (auto& old_con : connections) {
  if (!old_con->get_socket().is_open()) {
    // Recycle old connection
    new_con = &old_con;
    break;
  }
}

if (!new_con) {
  // No old connections found, so we create a new one
  new_con = &connections.emplace_back(std::make_unique<Connection>(ctx));
}

What happens if a large number of clients try to connect to the server at the same time?

Communication protocol

When either the server or the client wants to wait for incoming packets, it uses the following asynchronous function:

asio::async_read(
    socket,
    asio::buffer(&message, sizeof(message)),
    std::bind(&Connection::handle_read, this, std::placeholders::_1)
);

This function will call handle_read only when exactly sizeof(message) bytes have been received. Data received will be stored in message, an instance of Message, which is defined like this:

enum class Command : uint16_t {
  NOP, HI, LIST, STR, // and more...
};

struct Message {
  Command command;
  uint16_t version;
  std::array<char, 28> data;
};

Here are a few examples of messages that can be created using this design:

This is a command message. It is used by a client to ask the server for the list of all connected clients.

LIST (2 bytes) VERSION (2 bytes) - (28 bytes)
This command sends a human-readable message.

STR (2 bytes) VERSION (2 bytes) STR (28 bytes)

Server

When a new connection comes in, the server introduces itself with a HI message. This message contains the name and version of the server:

HI (2 bytes)

VERSION (2 bytes)

NAME (28 bytes)

Then it waits for incoming packets via async_read, as previously mentioned. By reading data directly into message, the handle_read callback becomes straightforward:

void handle_read(const boost::system::error_code& error) {
  // Error handling [...]

  switch (message.command) {
    case Command::NOP: break; // nothing to do
    case Command::LIST: {
      // @todo Send a message with the list of all clients
      break;
    }
  } // switch

  // [...]
}

Client

The client should run two different threads:

A network thread to handle incoming messages from the server.
A main thread to read user input, update its logic, etc.

For this purpose, before the main loop, we spawn a thread to run the IO context:

auto con = Connection(io, endpoints);
auto thread = std::thread([&io] () { io.run(); });

while (true) {
  // main loop
}

Computer network notes

Antonio Caggiano — Mon, 21 Dec 2015 00:00:00 +0000

Line coding

With line coding, it is possible to represent sequences of bits using digital signals. Among the line codings we have: unipolar, polar, bipolar, multilevel, and multiline.

Nyquist theorem
In a channel without noise, this theorem gives us the maximum velocity at which we can send bits: N_max = 2 × B × log₂ L
where B is the bandwidth and L is the number of signal levels used to represent the data.

Unipolar code NRZ

The NRZ (Non-Return-to-Zero) code represents 1 as a positive voltage and 0 as a null voltage. It is called NRZ because the signal does not return to zero while coding each bit.

Polar code NRZ

In a polar code, two levels of voltage are used: positive and negative. In NRZ-L (Level) a positive voltage represents 0 and a negative voltage represents 1. In NRZ-I (Invert) the bit is determined by a change in the voltage level: absence of change means 0, change means 1.

Bipolar code AMI

The AMI (Alternate Mark Inversion) code represents 0 as a null voltage and 1 as switches between positive and negative voltages.

Switching

Switching is a convenient method to connect nodes in a very large network where special nodes, called switches, are connected together and can create connections between two or more stations connected to the switches. There are three categories of switching networks: circuit switching, packet switching, and message switching.

Circuit switching networks

A circuit switching network has a collection of switches connected together with links divided into multiple channels thanks to multiplexing. The communication between two stations requires three steps:

Connection setup, where a path is found on the links between the switches and a channel is reserved for each link.
Data transfer, where all the channels dedicated to the connection remain unavailable to other connections.
Connection teardown, where a station sends a signal to every switch to free their resources.

Using a circuit switching network is not the best for efficiency: we could have long periods of inactivity with no data transfers, which means wasting those resources dedicated to the connection. On the other hand, the delay is minimal: since a path is dedicated when establishing a connection, data flow without stopping at each switch.

Packet switching networks

In this network, data need to be split into packets independent from each other, namely datagrams, with variable or fixed length depending on the protocol. Switches here are also called routers. A message can be subdivided into more datagrams which can travel on different paths and reach their destination in a different order, or they can get lost, or get eliminated due to a shortage of resources on the network.

Datagram networks have no connection, meaning that switches do not keep track of connection states. There is no connection setup nor teardown. In order to know how to send a datagram, switches maintain dynamic routing tables periodically updated. From an efficiency perspective, packet switching networks are better than circuit switching networks: resources are allocated only when there are packets to transfer. The delay however can be higher: each packet could follow longer paths or need to wait in switches before being forwarded.

Multiple access protocols

With random access protocols, stations do not have control over the medium and its usage is competed for. Stations can check the state of the medium at any time and there is no access order. There could be cases where two or more stations try sending simultaneously, causing a collision which destroys or modifies the frames. Among random access protocols we have: ALOHA; CSMA; CSMA/CA; CSMA/CD.

Aloha

In the original ALOHA protocol, each station sends a frame whenever it wants, therefore there are chances of collisions. We rely on feedback from the recipient and, if it does not come, the recipient will send the frame again. Before resending a frame destroyed by a collision, stations need to wait a random amount of time, namely backoff time or T_b. After a maximum number of transmission attempts, K_max, stations must desist and retry later.

CSMA

The Carrier Sense Multiple Access method tries to improve network performance by minimizing collision probabilities by making stations check the state of the medium before sending data. If two stations check the medium and find it free at the same time, a collision can still happen if both stations choose to transmit. There are three methods which can determine the behavior of the stations:

1-persistent: if the medium is busy, the station continues to check the state until it becomes free to send data.
non-persistent: if the medium is free, the station sends data, otherwise it waits a random time before repeating the same operation.
p-persistent: if the medium is busy, the station continuously checks the state until it becomes free, then:
1. it sends the frame with probability p.
2. it waits, with probability 1-p, for at least the maximum propagation time before checking the medium again. At this point, if the medium is free it restarts from 1, otherwise it performs a backoff operation.

CSMA/CD

The CSMA/CD (collision detection) method adds an algorithm to detect and handle collisions. A station, while sending a frame, continuously checks the medium and if it detects a collision, stops transmitting immediately. In order to be effective, it is important that the minimum transmission time of any frame is at least twice the maximum propagation time. Otherwise, stations could not detect all collisions.

T_fr ≥ 2·T_p

CSMA/CA

The CSMA/CD method is not effective in a wireless network, where signal energy loss during transmission could negatively affect collision detection. The CSMA/CA (collision avoidance) protocol avoids collisions with three strategies:

spacing between frames: when a station finds the medium available, before transmitting, it waits for a period of time, namely interframe spacing (IFS).
collision window: a station that has just finished waiting for IFS waits again for a random number of intervals. After each interval, it checks the state of the medium and if it is busy, pauses this process and restarts it later when the medium is free again.
controls: guarantee that the receiver has received the frame and no collisions have happened.

Controlled access

With controlled access protocols, stations agree on the usage of the medium. There are three methods:

Reservation: stations need to reserve a time interval during which they can transmit.
Polling: one of the stations controls the medium and the other stations follow its instructions.
Token passing: stations are organized as a logic ring and access to the medium is allowed only when a station has the token, a special frame, which circulates among the stations.

Channelization

In channelization the bandwidth is shared between the stations. Among channelization protocols we have:

FDMA, where the bandwidth is subdivided into non-contiguous sections assigned to the stations.
TDMA, where the channel is used by one station at a time.
CDMA, where the medium carries all transmissions simultaneously, isolated thanks to an encoding system.

Spread Spectrum

In Spread Spectrum techniques, signals of various sources are combined to prevent detection and interference. Those techniques are based on redundancy, increasing the width of the original bandwidth.

Frequency Hopping Spread Spectrum

Frequency Hopping Spread Spectrum (FHSS) selects carrier frequencies pseudo-randomly, modulated by the original signal. A third-party does not know on which frequencies data are transmitted and impeding the transmission is difficult since it would require generating interference on multiple frequencies.

Direct Sequence Spread Spectrum

Direct Sequence Spread Spectrum (DSSS) maps every bit of the original signal to a wordcode of n bits through a hopping code. Wireless LANs use Barker code, where n is 11, which means that the required bandwidth is 11 times larger.

Error Control in Data Link Layer

Stop-and-wait ARQ

The Stop-and-wait ARQ protocol is an improvement to the stop-and-wait. After transmitting a frame, the sender waits for an acknowledgement (ACK) from the recipient. At this point, the Automatic Repeat reQuest (ARQ) mechanism checks for errors. The data frame and ACK frame have a 1-bit field for a sequence number, so it can be either 0 or 1. The recipient does not send any feedback for damaged or out-of-order frames. After waiting for the ACK for a certain amount of time, the sender re-transmits the frame. This protocol is quite inefficient as the communication channel will handle at any time at most one frame, therefore we would not use its full transmissive capacity.

Go-back-N ARQ

The Go-back-N ARQ protocol manages to send more than one frame, keeping a copy for each one if re-transmission is needed, discarding them when their relative ACK frame is received. It uses m bits for the sequence number field, so its values are within [0, 2ᵐ - 1]. The sender maintains a sliding window for these values, with size Sₗₑₙ = 2ᵐ - 1, and two indices: Sₚ pointing to the first frame still waiting for the ACK and Sₙ pointing to the next frame to send. The recipient, on the other hand, has a window of size 1 as it is only interested in one ordered frame, while discarding any other.

Go-back-N ARQ sender sliding-window with m = 3

When the time for the ACK of a frame is over, the Sₙ index goes back (go-back) to the first frame without an ACK. In a channel with a high frequency of errors, this protocol would be inefficient: a damaged frame could mean re-sending many frames, resulting in a slowdown of the transmission.

Selective Repeat ARQ

The Selective Repeat ARQ protocol solves the Go-back-N ARQ problems by avoiding re-sending the frames which arrive out of order, focusing only on the damaged ones. Both sender window and recipient window have size 2ᵐ⁻¹. This means that frames can arrive out of order without being discarded by the recipient.

Network switches

Network switches are used to connect together multiple networks. They can operate at various layers of Internet:

below the physics layer: passive hubs;
at the physics layer: repeaters and active hubs;
at the physics and link layer: bridges;
at the physics, link and network layer: router;
at all layers: gateway.

Passice Hubs

Passive hubs are simple connectors between wires. They do not amplify the signal and do not need power supply.

Repeaters and Active Hubs

A signal traveling within a wire is subject to attenuation which can affect the integrity of data. Repeaters receive a signal before it degrades, they regenerate and forward it again. Active hubs are simply repeaters with multiple ports and are useful for star networks.

Bridge

A bridge, as well as having the same capabilities as a repeater, can check source and destination addresses in a frame and figure out which port to forward it to, through a forwarding table. In a transparent bridge, the forwarding table is built automatically based on the traffic on the network.

Router

A router operates on the network layer sending packets based on logic addresses. They are commonly used to connect LANs or WANs to the Internet.

Gateway

A gateway is able to read and interpret messages from applications, therefore it could be used to connect two networks based on different models.

Address resolution

With address resolution protocols it is possible to obtain the logical address corresponding to a physical address and vice versa.

Address Resolution Protocol

Address Resolution Protocol (ARP) allows a node to discover the physical address associated with a particular logical address. Those requests are sent in broadcast while the response is sent in unicast from the unique node which corresponds to that logical address.

Reverse Address Resolution Protocol

Reverse Address Resolution Protocol (RARP) enables a node to find its logical address from its own physical address. This protocol is obsolete and it has been replaced by BOOTP and DHCP.

Bootstrap Protocol

Bootstrap Protocol (BOOTP) works in the application layer and is based on a node of the network called a relay agent which knows the IP address of the BOOTP server. It is not dynamic because the associations between addresses are based on static tables manually managed by the administrator.

Dynamic Host Configuration Protocol

Dynamic Host Configuration Protocol (DHCP) allows both static and dynamic allocation of IP addresses and it is compatible with BOOTP. A server using this protocol has a database to store static addresses and a database to store dynamic addresses.

Routing protocols

Routing protocols allow routers to communicate between each other for updating routing tables. There are protocols for intra-domain (Routing Information Protocol, Open Shortest Path First) and inter-domain (Border Gateway Protocol) routing.

Distance-vector routing protocol

In the Distance-vector routing protocol every node maintains a vector with the minimum distance between other nodes. At the beginning, nodes know only the distance from the nodes they are directly connected to, but by sharing their routing tables with nearby nodes they can discover the topology of the entire network. Routing Information Protocol (RIP) is based on a distance-vector and it is trivial as it assumes that the cost of hopping from one node to another would always be one.

Link-state routing protocol

In the Link-state routing protocol every node builds its own routing table interpreting the entire network as a graph with Dijkstra's algorithm. At the beginning, every node has a partial knowledge of the network, with nearby nodes, and shares that information with other nodes by sending packets called Link State Packets (LSP). The Open Shortest Path First protocol is based on the link layer.

Path-vector routing protocol

Inter-domain routing is based on the Path-vector protocol, where the various autonomous systems have a special node which shares its own routing table with nearby autonomous systems. The routing table will contain all possible destinations and the paths to reach them. The Border Gateway Protocol is based on a path-vector.

Devember: Socket API

Antonio Caggiano — Tue, 15 Dec 2015 00:00:00 +0000

This devlog introduces the fundamental functions of the Berkeley socket API by developing a simple client and server in the C language. The complete source code is available in this GitHub repository.

Client

The first thing to do is to create a connection-oriented (SOCK_STREAM) socket of the IPv6 Internet protocol family (AF_INET6). This will use TCP, a reliable transport protocol.

int sockfd;
if ((sockfd = socket(AF_INET6, SOCK_STREAM, 0)) < 0) {
    perror("socket");
    return -1;
}

The socket can be used to establish a connection with a server, and we can specify the address to connect to using a sockaddr_in6 structure.

struct sockaddr_in6 servaddr;
bzero(&servaddr, sizeof(servaddr));
servaddr.sin6_family = AF_INET6;

Both the port and the address data follow the host byte-ordering, which is not guaranteed to be the same as the ordering used by the network protocol. Accordingly, we need to convert them to a network representation, which can be done by using htons() for the integer port and inet_pton() for the IPv6 address string.

servaddr.sin6_port = htons(atoi(argv[2]));

if (inet_pton(AF_INET6, argv[1], &servaddr.sin6_addr) <= 0) {
    perror("inet_pton");
    return -1;
}

We can then pass the socket and the sockaddr structure to connect(), which will reach out to the server.

if (connect(sockfd, (struct sockaddr*) &servaddr, sizeof(servaddr)) < 0) {
    perror("connect");
    return -1;
}

Once the connection is established, we can receive data from the server by reading from the socket. The bytes read will be stored in the recvline buffer, then a 0 is added at the end to finalize it as a string, and fputs() is used to print it to stdout.

int n;
char recvline[MAXLINE + 1];
while ((n = read(sockfd, recvline, MAXLINE)) > 0) {
    recvline[n] = 0;
    fputs(recvline, stdout);
}
if (n < 0) {
    perror("read");
    return -1;
}

When the communication has finished, we need to close the socket, as with every file descriptor.

close(sockfd);

Server

As with the client, the first thing the server does is create an IPv6 socket.

int listenfd;
if ((listenfd = socket(AF_INET6, SOCK_STREAM, 0)) < 0) {
    perror("socket");
    return -1;
}

Then a sockaddr structure is initialized using in6addr_any, which is a wildcard IPv6 address, letting the system select the address for you.

struct sockaddr_in6 servaddr;
bzero(&servaddr, sizeof(servaddr));
servaddr.sin6_family = AF_INET6;
servaddr.sin6_addr = in6addr_any;
servaddr.sin6_port = htons(atoi(argv[1]));

Before continuing, we call bind() to assign this address to the socket.

if ((bind(listenfd, (struct sockaddr*) &servaddr, sizeof(servaddr))) < 0) {
    perror("bind");
    return -1;
}

Then we convert the socket to a listening one, so that it can be used to accept incoming connections.

if (listen(listenfd, BACKLOG) < 0) {
    perror("listen");
    return -1;
}

Here we can finally make the server wait for client requests. The accept() function is blocking and returns when a new incoming connection has been established. To generate a response from the server, we get the date and time with the time() function, then build the string to send to the client, and finally write it to the socket and close the connection once finished.

int connfd;
int n;
time_t ticks;
char buff[MAXLINE];
while (true) {
    if ((connfd = accept(listenfd, (struct sockaddr*) NULL, NULL)) < 0) {
        perror("accept");
        return 1;
    }

    // Send the time to the client
    ticks = time(NULL);
    snprintf(buff, sizeof(buff), "%.24s\r\n", ctime(&ticks));
    while ((n = write(connfd, buff, strlen(buff))) < 0);

    // Close the connection
    close(connfd);
}

Get client information

The first thing we can do to improve the server is to make better use of the accept() function. By passing a sockaddr structure address as an argument, we can retrieve some information about the client.

struct sockaddr_in6 cliaddr;
socklen_t clilen = sizeof(cliaddr);
bzero(&cliaddr, clilen);
accept(listenfd, (struct sockaddr *) &cliaddr, &clilen);

Please note that the data memory layout is still following the network order, and if we want to have meaningful address and port values on our system, we need to convert them into the appropriate host representation.

inet_ntop(AF_INET6, &cliaddr.sin6_addr, buff, INET6_ADDRSTRLEN);
printf("Serving new client from %s:%d\n", buff, ntohs(cliaddr.sin6_port));

Get local address

We have seen how the server can retrieve the address of a client. Let us see, on the other hand, how the host can query its own local address using getsockname().

struct sockaddr_in6 cliaddr;
socklen_t clilen = sizeof(cliaddr);
bzero(&cliaddr, clilen);
if (getsockname(sockfd, (struct sockaddr *) &cliaddr, &clilen) < 0) {
    perror("getsockname");
    return -1;
}

Now we have the information we need in cliaddr, then we convert the IPv6 address and port into the appropriate host representation and finally print it out.

char clistr[INET6_ADDRSTRLEN];
inet_ntop(AF_INET6, &cliaddr.sin6_addr, clistr, INET6_ADDRSTRLEN);
printf("The current address is %s:%d\n", clistr, ntohs(cliaddr.sin6_port));

Sending an acknowledgement

We would like the client to respond to the server with an acknowledgement message, and this can be done after the reading step by calling write().

char* ack = "Message received\n";
if ((n = write(sockfd, ack, strlen(ack))) < 0) {
    perror("write");
    return -1;
}

On the other side of the connection, the server should invoke read() to receive the data sent by the client.

char recvline[MAXLINE + 1];
if ((n = read(connfd, recvline, MAXLINE)) > 0) {
    recvline[n] = 0;
    fputs(recvline, stdout);
}
if (n < 0) {
    perror("read");
    return -1;
}

As you may notice, both read() and write() return the number of characters written into the socket buffer. In case of an error, the return value is negative (-1) and the errno global variable is set appropriately. This means we can retrieve an informative message corresponding to the current value of errno through the perror() function.

Recursive echo server

Let us now see two new functions useful for our network programs, exso_readln() and exso_writen(), based on some utility functions presented in the Unix Network Programming book and used in a networking course I attended at university.

The exso_readln() function reads a line (a string ending with the newline character '\n') from a socket buffer and automatically appends '\0' to mark the end of that string.
The exso_writen() function writes n bytes into a socket buffer.

More details can be found here: libexso.c.

The daytime server discussed so far features an iterative behaviour, which means it can serve only one client at a time. In order to serve more clients concurrently, we could make it recursive by spawning child processes to manage new incoming connections. That is how it can be done with fork().

pit_t childpid;
if ((childpid = fork()) == 0) {
    close(listenfd);
    server_echo(connfd);
    return 0;
}

The child process must close the listening socket before executing its tasks. At the same time, the parent closes the connected socket and returns to waiting for new requests. Here follows the server_echo() function, which executes all the tasks of a server child process, also using the new read and write functions mentioned above.

void server_echo(int sockfd) {
    ssize_t n;
    char line[MAXLINE];
    while (true) {
        if ((n = exso_readln(sockfd, line, MAXLINE)) == 0) {
            return; // connection closed by the other end
        }
        exso_writen(sockfd, line, n);
    }
}

Kill the zombies

Good, now the server can handle multiple concurrent connections by spawning child processes. However, we should not forget to handle these processes when they finish serving clients, otherwise they will remain in memory as zombies.

When a child process terminates, the operating system sends a SIGCHLD signal to the parent, which by default does not do anything. If we want to remove zombies (dead child processes), the parent can do that by registering a callback function for the SIGCHLD signal.

if (signal(SIGCHLD, handle_zombies) < 0) {
    perror("signal");
    return -1;
}

Here is how the callback function works. By calling the waitpid() function with -1 as the first argument, the parent process waits for the termination of any of its children. The stat output variable will contain information about a child's exit status.

void handle_zombies(int signo) {
    pid_t pid;
    int stat;

    while ((pid = waitpid(-1, &stat, WNOHANG)) > 0) {
        printf("Child %d terminated with exit status %d\n", pid, stat);
    }
}

UDP echo client

So far, we have been using TCP as the transport protocol. If we want to use UDP, we need to make some minor changes.

Change the socket type to SOCK_DGRAM.

int sockfd;
if ((sockfd = socket(AF_INET6, SOCK_DGRAM, 0)) < 0) {
    perror("socket");
    return -1;
}

Data transmissions should be done using the sendto() function.

char sendline[MAXLINE];
if (fgets(sendline, MAXLINE, fp) != NULL) {
    if (sendto(sockfd, sendline, strlen(sendline), 0, servaddr, sizeof(servaddr) < 0) {
        perror("sendto");
        return -1;
    }
}

Incoming data is collected with the recvfrom() function. Notice how, when working with a connectionless protocol, the address of the sender is collected; otherwise, we would not know who sent these packets.

struct sockaddr *replyaddr;
replyaddr = malloc(sizeof(servaddr));
len = sizeof(servaddr);
char recvline[MAXLINE + 1];

if ((n = recvfrom(sockfd, recvline, MAXLINE, 0, replyaddr, &len)) < 0) {
    perror("recvfrom");
    return -1;
}

recvline[n] = 0;

Consequently, we should verify the identity of the peer. Here, we just make sure all the bytes of the sockaddr structures are equal.

char buff[INET6_ADDRSTRLEN];
struct sockaddr_in6 *sa;

if ((len != sizeof(servaddr)) || memcmp(&servaddr, replyaddr, len) != 0) {
   sa = (struct sockaddr_in6 *) replyaddr;
   inet_ntop(AF_INET6, &sa->sin6_addr, buff, INET6_ADDRSTRLEN);
   printf("Ignoring reply from %s\n", buff);
   continue;
}

Distributed calculator

Let us try something a bit more complex: a distributed calculator.

The communication takes place via UDP, so we use sendto() and recvfrom() as introduced in the previous section.

char buff[MAXLINE];
int a = 0;
int b = 0;
char op[OP_LEN] = "+";
while (fgets(buff, MAXLINE, stdin) != NULL) {
    if (sscanf(buff, "%d %s %d", &a, op, &b) == 3) {
        // ... do networking
    }
}

On the other end, the server receives the data, interprets it, computes the result, and sends it back to the client.

char buff[MAXLINE];
socklen_t len;

int a;
int b;
char op[OP_LEN];

while (true) {
    // Receive datagram
    len = clilen;
    if (recvfrom(sockfd, buff, MAXLINE, 0, cliaddr, &len) < 0) {
        perror("recvfrom");
        return -1;
    }
    
    // Interpret data and compute the result
    if (sscanf(buff, "%d %s %d", &a, op, &b) == 3) {
        if (strcmp(op, "+") == 0) {
            sprintf(buff, "%d", a + b);
        } else if (strcmp(op, "-") == 0) {
            sprintf(buff, "%d", a - b);
        } else if (strcmp(op, "*") == 0) {
            sprintf(buff, "%d", a * b);
        } else if (strcmp(op, "/") == 0) {
            if (b != 0) {
                sprintf(buff, "%d", a / b);
            } else {
                sprintf(buff, "Undefined");
            }
        } else if (strcmp(op, "mod") == 0) {
            sprintf(buff, "%d", a % b);
        } else {
            sprintf(buff, "Invalid operator");
        }
    } else {
        sprintf(buff, "Invalid message");
    }
    
    // Send result to the client
    if (sendto(sockfd, buff, strlen(buff), 0, cliaddr, len) < 0) {
        perror("sendto");
        return -1;
    }
}

I/O multiplexing using select

The simple echo client described previously suffers from some robustness problems. For example, if the server closes the connection while the client is blocked waiting for user input, the client would not be aware of anything until it tries to send data again after the user input has been read. I/O multiplexing can help us solve this problem.

By means of the select() function, we can work with more than one descriptor, and that requires preparing an fd_set object. In the example below, we reset readset with FD_ZERO() and then add our file descriptors through FD_SET().

FILE *fp;
int sockfd;
// ...
fd_set readset;
FD_ZERO(&readset);
FD_SET(fileno(fp), &readset);
FD_SET(sockfd, &readset);
int maxfd = MAX(fileno(fp), sockfd) + 1;
if (select(maxfd, &readset, NULL, NULL, NULL) < 0) {
    perror("select");
    return -1;
}

When select() returns, we can check whether the descriptors are ready by making use of FD_ISSET().

// Check if socket is ready to receive data from the server
if (FD_ISSET(sockfd, &readset)) {
    if ((n = exso_readln(sockfd, recvline, MAXLINE)) < 0) {
        perror("exso_readln");
        return -1;
    }
    if (n == 0) {
        printf("Server terminated prematurely\n");
        return -1;
    }
    fputs(recvline, stdout);
}

// Check if file is ready to send its content to the server
if (FD_ISSET(fileno(fp), &readset)) {
    if (fgets(sendline, MAXLINE, fp) == NULL) {
        return 0;
    }
    if (exso_writen(sockfd, sendline, strlen(sendline)) < 0) {
        perror("exso_writen");
        return -1;
    }
}

Half closing the socket

Another way to improve the robustness of the client code is by shutting down the write half of the connection once all reading operations from standard input have finished. This can be done by calling the shutdown() function.

char stdin_eof = 0;
// ...
if (FD_ISSET(fileno(fp), &readset)) {
    if (fgets(sendline, MAXLINE, fp) == NULL) {
        stdin_eof = 1;
        shutdown(sockfd, SHUT_WR);
        FD_CLR(fileno(fp), &readset);
        continue;
    }
    if (exso_writen(sockfd, sendline, strlen(sendline)) < 0) {
        perror("exso_writen");
        return -1;
    }
}

Improved echo server

A recursive server is not the best choice if we want to avoid a proliferation of child processes, given that we fork every time a new client is connected. The server, as well as the client, could benefit from I/O multiplexing via select() to handle both the listening socket and the other connection sockets.

if ((ready = select(maxfd + 1, &rset, NULL, NULL, NULL)) < 0) {
    perror("select");
    return -1;
}

// Check for incoming connections
if (FD_ISSET(listenfd, &rset)) {
    if ((connfd = accept(listenfd, (struct sockaddr *) &cliaddr, &clilen)) < 0) {
        perror("accept");
        return -1;
    }
    // Save connected socket descriptor into an array
    for (i = 0; i < FD_SETSIZE; i++) {
        if (clients[i] < 0) {
            clients[i] = connfd;
            break;
        }
    }
    // ...
}

// Serve clients
for (i = 0; i < FD_SETSIZE; i++) {
    if ((sockfd = clients[i]) < 0) {
        continue;
    }
    if (FD_ISSET(sockfd, &rset)) {
        if ((n = exso_readln(sockfd, buff, MAXLINE)) < 0) {
            perror("exso_readln");
        }
        else if (n == 0) {
            printf("A client is gone\n");
            close(sockfd);
            FD_CLR(sockfd, &allset);
            clients[i] = -1;
        } else if (exso_writen(sockfd, buff, n) < 0) {
            perror("exso_writen");
        }
        // ...
    }
}

Broadcast

What we have now is an array of all the connected clients, and that enables us to turn the server into a chat room! Here, the server broadcasts every message sent by a client to all the other connected clients:

for (i = 0; i < FD_SETSIZE; i++) {
    if (sockfd == client[i] || client[i] == -1) {
        continue;
    }
    if (exso_writen(client[i], buff, n) < 0) {
        perror("exso_writen");
    }
}

Nickname command

After transforming the server into a chat room, it would definitely be a good idea to allow clients to set their nickname with a command. So, when a client is connected, the server expects to receive a message starting with /nickname followed by the actual nickname.

#define MAXNICK 32
// ...
char nicknames[FD_SETSIZE][MAXNICK];
// Processing the i-th client
if (nicknames[i][0] == 0) {
    if (strncmp(buff, "/nickname", 9) == 0) {
        sscanf(buff, "/nickname %s\n", nicknames[i]);
        sprintf(buff, "%s has joined the chat\n", nicknames[i]);
    } else {
        sprintf(buff, "Error, expecting /nickname\n");
        exso_writen(client[i], buff, strlen(buff));
        continue;
    }
}

Once the nickname is set, we can use it as a prefix for the message and broadcast it to everyone.

char temp[MAXLINE];
sprintf(temp, "%s: %s", nicknames[i], buff);
sprintf(buff, "%s", temp);
// ...
for (i = 0; i < FD_SETSIZE; i++) {
    if (sockfd == client[i] || client[i] == -1) {
        continue;
    }
    if (exso_writen(client[i], buff, strlen(buff)) < 0) {
        perror("exso_writen");
    }
}

To conclude, when a client logs out, we can reset their nickname.

// If there are no more characters to read
if (n == 0) {
    close(sockfd);
    FD_CLR(sockfd, &allset);
    client[i] = -1;
    bzero(nicknames[i], MAXNICK);
}

Android notes

Antonio Caggiano — Tue, 27 Oct 2015 00:00:00 +0000

This is a collection of notes I took during the Mobile Programming course at my university.

Project

The project needs to follow a specific structure to be compiled and packaged correctly by the Android Software Development Kit.

At a higher level, we subdivide it into modules, such as:

Android application modules: with code, resources, and configurations. These will be transformed into an apk file that will be installed on devices.
test modules: containing JUnit tests.
library modules: which are code shared with other projects. These will be included in the apk as well.

Files

build/: application build artifacts.
libs/: private libraries.
src/: the source code.
- androidTest/: Java tests.
- main/java/com.project.app: Java code such as activities.
- main/assets/: store for game assets.
- main/res/: various resources.
  - anim/: XML files compiled into animation objects.
  - color/: XML files with colors.
  - drawable/: bitmap files (PNG, JPEG, GIF), 9-Patch, and XML describing drawables.
  - mipmap/: Application icons.
  - layout/: XML files compiled into layouts.
  - menu/: XML files defining menus.
  - raw/: for various assets, like mp3 or ogg files.
  - values/: XML files defining generic values.
  - xml/: other XML files.
- AndroidManifest.xml: main file describing the application and all of its components.
.gitignore/: files to be ignored from git versioning.
app.iml/: IntelliJ IDEA config file.
build.gradle: build config file.
proguard-rules.pro: ProGuard config file.

Localization

When the user launches an app, Android automatically selects and loads the right resources according to the device configuration.

In the res/values/strings.xml file, strings are stored that are used by default, though it is possible to specify alternative resources using qualifiers for different languages.

For instance, to localize text content in Italian, we need to create an alternative strings.xml file under the res/values-it/ folder.

Testing

It is possible to test our apps on an emulator or a real Android device.

The number of smartphones on the market is huge and continuously growing. Nevertheless, every device is different and deciding which ones to test can be challenging.

It would be ideal to support as many devices as possible. We could buy a certain number of devices and test our app under real conditions, but it would definitely be more expensive than using the emulator.

The emulator might not allow us to see how apps work on real devices, but it does not hurt from a financial perspective.

When developing on a device, it is still good practice to use the emulator to test our apps on configurations that are different from those of real devices available to us. Even though the emulator cannot test all settings, it can verify that the apps work correctly on different Android versions, or screen sizes and orientations.

A mix of real device testing and emulator testing could guarantee good test coverage at a reasonable price.

Layout

A layout is the visual structure of a user interface and it can be defined in two ways:

XML: Android provides XML tags corresponding to classes of the View.
Runtime: you can create View and ViewGroup objects programmatically.

We can use one or both methods to declare and manage the graphical interface of our application. For example, we could declare some layout in XML, and later add code to modify at runtime the state of the elements on the screen.

The benefit of using XML files is the separation between presentation and the code controlling the behaviour of the application. The description of the user interface is external to the logic code, enabling us to modify it without needing to recompile. Moreover, declaring the layout in XML makes it easier to visualize the structure of the user interface and simplifies debugging.

View

A View is basically a rectangle with width and height, and a position expressed as left and top. The unit is the pixel. We can also distinguish two pairs of width and height: measured width and height relative to its parent, and drawing width and height, which define the size when drawing on screen.

Drawing a layout involves two steps: measure and layout. The measure step is implemented in measure(int, int), which is a top-down traversal of the view-tree where their dimensions are calculated. The second step is implemented in layout(int, int, int, int), also top-down, where every parent is responsible for moving their children using values calculated during the measure step.

ViewGroup

Linear Layout

A linear layout is a ViewGroup which aligns its children horizontally or vertically (android:orientation).

Relative Layout

A relative layout is a ViewGroup which shows children with relative positions to their siblings (left-of, below, …) or parent (bottom, left, center, …).

List View

A list view is a ViewGroup showing a list of elements. The elements are added automatically using an Adapter, which takes the content of a source, like an array or a database, and converts each element into a View to be inserted into the list.

Grid View

A grid view is a ViewGroup which shows a grid of elements which, like the list view, is populated through an Adapter.

Adapter View

When the content is dynamic, we can use an AdapterView subclass to populate it at runtime. An AdapterView subclass uses an Adapter, which behaves like a mediator between the data source and the layout. The Adapter receives data and converts each entry into a View that can be added to the layout.

Android provides some Adapter subclasses for certain cases:

ArrayAdapter: useful when the data source is an array. By default, it creates a View for every element of the array by calling toString() and putting it into a TextView.

ArrayAdapter<String> adapter = new ArrayAdapter<>(
    this, android.R.layout.simple_list_item1, myStringArray);
ListView listView = (ListView) findViewById(R.id.listview);
listView.setAdapter(adapter);

SimpleCursorAdapter: useful when data come from a Cursor.

Toast

A Toast provides simple feedback for an operation in a small popup. It occupies only the space required by the message and the current Activity remains visible and interactive. Toasts vanish automatically after a timeout. We can create them with the static method Toast.makeText(), which takes three arguments (context, message, and duration), and can be shown with the show() method.

Toast.makeText(context, "text", Toast.LENGTH_SHORT)

We can position it with the setGravity() method, which accepts three arguments (gravity constant, x offset, and y offset).

toast.setGravity(Gravity.TOP | Gravity.LEFT, 0, 0);

It is also possible to create a custom layout for toasts in XML and use it by passing it to the toast through the setView(View) method.

Western Lion: Post mortem

Antonio Caggiano — Thu, 22 Oct 2015 00:00:00 +0000

Western Lion is a collection of two minigames based on the spaghetti western theme, developed during the one-month Spaghetti Western Jam organized by IndieVault.it.

In one of the games, you impersonate Nobody, trying to shoot mugs before they shatter on the pavement, while in the other game you are Jack, annoyed by a fly while waiting at the train station.

Preparation

The idea of minigames originated from the fragmentary way scenes from spaghetti western movies I have seen over the years came back to my mind. Figuring out how to realize that idea was the next step.

The libGDX framework was definitely a good choice from both a prototyping speed and portability perspective.

Talking about graphics, I reduced it to the lowest terms, as it was easier working with an 8-bit palette borrowed from the wonderful PICO-8 fantasy console, and a resolution of 160x90 pixels.

Audio resources were simply collected by searching on Freesound.org.

Jack and the Fly

The first mini-game is Jack and the fly. It is inspired by the concept of waiting, which has a prominent role in the beginning of Sergio Leone's Once Upon a Time in the West.

Waiting makes us think; it gives us time to breathe, to meditate, to observe. This emphasis projects us onto those boundless spaces and, at the same time, allows us to get lost in the tiny details.

Nobody is drinking

The second mini-game is Nobody is drinking. It is based on a scene from Tonino Valerii's My Name Is Nobody.

Nobody, the main character of the movie, bets on a particular game where you drink whiskey from a mug, then throw the mug into the air, and try to shoot it before it shatters into pieces on the ground.

With both games, the key to winning is being alert and quick. Indeed, when you finish a game, your time is recorded onto a leaderboard.

Development

Here is the list of tools I used to develop Western Lion:

Android Studio, for coding;
The GNU Image Manipulation Program to create graphic content;
Audacity to edit audio resources.

Although the right tools greatly simplify the development of projects like this, a good understanding of mathematics and physics is fundamental to realizing the ideas that come to your mind.

A two-dimensional Cartesian coordinate system helps position pictures in the right place on the screen;
The laws of motion allow you to simulate the movement of objects, like the fly and the mugs.
Trigonometric functions can be used to make cool, smooth animations like the sliding in the achievements screen.

These are only some examples of the countless applications that mathematics has in the world of game development.