Mach Engine

https://machengine.org/docs
Admin
Mach is an experimental game engine and graphics toolkit written in Zig, providing modular...
Tokens:10,369
Snippets:154
Trust Score:7.2
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Mach Core Textured Cube Example

Source: https://machengine.org/docs/modularity/about/zig-version

Clone the Mach repository, checkout the desired version, and run the core textured cube example.

```bash
$ git clone https://code.hexops.org/hexops/mach
$ cd mach/ && git checkout 0.4
$ zig build run-core-textured-cube

```

--------------------------------

### Initialize a New Mach Project

Source: https://machengine.org/docs/getting-started

Create a new Mach project with a basic 'Hello, Mach!' example using the Mach CLI.

```bash
mach init
```

--------------------------------

### Install Zig 2026.4.10-mach using build.zig.zon

Source: https://machengine.org/docs/nominated-zig

Set the Zig version to 2026.4.10-mach in your build.zig.zon file for automatic use by anyzig.

```zig
.mach_zig_version = "2026.4.10-mach"
```

--------------------------------

### Setting a Module's Callback System ID

Source: https://machengine.org/docs/object/systems

This example demonstrates how an application module can set the `on_render` callback in a windowing module by providing its own render system's ID.

```zig
pub const mach_module = .app;

pub const mach_systems = .{ .init, .render };

pub fn init(app_mod: mach.Mod(@This()), windows: *Windows) void {
    // When the windowing library wants to render a new frame, have it run our app's .render system
    windows.on_render = app_mod.id.render;
}

pub fn render() void {
    // ...
}

```

--------------------------------

### Unconditional System Execution Example

Source: https://machengine.org/docs/object/systems

This snippet illustrates the correct way to structure system calls, ensuring that dependent systems are always run, even if no work is immediately apparent. The commented-out line shows the incorrect conditional approach.

```zig
pub fn spawnMonsters(monsters: *Monsters) void {
    // Maybe spawn some monsters
    // run processMonsterUpdates
}

pub fn processNewMonsters(monsters: *Monsters) void {
    // If there are new monsters, process them.
}

```

--------------------------------

### Create New Object with ID

Source: https://machengine.org/docs/object/objects

Example of creating a new object and obtaining its unique identifier. The ObjectID contains array index, generation, module, and list information.

```zig
const new_monster_id: mach.ObjectID = app.monsters.new(.{
        .health = 100,
        .damage = 10,
    });

```

--------------------------------

### Initialize, Create, and Access Objects

Source: https://machengine.org/docs/object/objects

Demonstrates initializing an object list, creating a new object with initial values, accessing its fields, and modifying them. Ensure the object list is locked before modification and unlocked afterward.

```zig
pub fn init(app: *App) void {
    app.monsters.lock();
    defer app.monsters.unlock();

    // Create a new monster object
    const new_monster_id: mach.ObjectID = app.monsters.new(.{
        .health = 100,
        .damage = 10,
    });

    // Print the monsters' health
    const new_monster = app.monsters.get(new_monster_id);
    std.debug.print("monster health: {}\n", .{new_monster.health});

    // Give the monster 2x damage!
    new_monster.damage *= 2;
    app.monsters.set(new_monster_id, new_monster); // save the change
}

```

--------------------------------

### Mach Application Entrypoint with Modules

Source: https://machengine.org/docs/object/modules

This snippet shows how to define the set of Mach modules an application will use and initialize them. It demonstrates passing control to an application-specific module.

```zig
const std = @import("std");
const mach = @import("mach");

// The set of Mach modules our application may use.
const Modules = mach.Modules(.{
    mach.Core,
    @import("App.zig"),
    @import("Renderer.zig"),
});

pub fn main() !void {
    const allocator = std.heap.c_allocator;

    // Initialize the module system.
    var mods: Modules = undefined;
    try mods.init(allocator);

    // Pass control to our App.zig module.
    const app = mods.get(.app);
    app.run(.main);
}

```

--------------------------------

### Run the Mach Project

Source: https://machengine.org/docs/getting-started

Build and run your Mach project using the Zig build system.

```bash
zig build run
```

--------------------------------

### Clone and Build Mach CLI

Source: https://machengine.org/docs/getting-started

Clone the Mach repository and build the CLI executable using Zig. Ensure the resulting executable is added to your system's PATH.

```bash
git clone https://code.hexops.org/hexops/mach
cd mach/
zig build -Doptimize=ReleaseFast editor
```

--------------------------------

### Lazy Dependency Loading in build.zig

Source: https://machengine.org/docs/stdlib

Optimizes build times by specifying only the necessary Mach stdlib components, fetching only their external dependencies.

```zig
    const mach_dep = b.dependency("mach", .{
        .target = target,
        .optimize = optimize,

        // We only use mach.core and mach.sysaudio, so only fetch the dependencies needed by those.
        .core = true,
        .sysaudio = true,
    });

```

--------------------------------

### Registering a System Callback in a Module

Source: https://machengine.org/docs/object/systems

This snippet shows how a module can store a system ID for a callback. The `update` function then uses `windows_mod.call()` to execute the registered system.

```zig
pub const mach_module = .gui_windows;

// ...

on_render: ?mach.SystemID = null,

pub fn update(windows: *@This(), windows_mod: mach.Mod(@This())) void {
    // Call whatever function is set in on_render.
    windows_mod.call(windows.on_render.?);
}

```

--------------------------------

### Specify Zig Version in build.zig.zon

Source: https://machengine.org/docs/nominated-zig

Use this to automatically select a specific Zig version for your project when using anyzig. Ensure the version string matches a downloaded or available Zig release.

```zig
.mach_zig_version = "2024.5.0-mach"
```

--------------------------------

### Specify Zig Version in build.zig.zon

Source: https://machengine.org/docs/nominated-zig

Use this to automatically select a specific Zig version for your project when using anyzig. Ensure the version string matches a downloaded or available Zig release.

```zig
.mach_zig_version = "2024.10.0-mach"
```

--------------------------------

### Run Zig Tests

Source: https://machengine.org/docs/getting-started

Execute any Zig test blocks defined in your project's source files.

```bash
zig build test
```

--------------------------------

### Declare Module Systems

Source: https://machengine.org/docs/object/modules

Declare the systems that a module will have. These are just names and must correspond to actual functions or schedules.

```zig
pub const mach_systems = .{ .main, .init, .tick, .deinit };

```

--------------------------------

### Cross-compile Mach Project for Linux

Source: https://machengine.org/docs/getting-started

Build the Mach project for the x86_64 Linux target.

```bash
zig build -Dtarget=x86_64-linux-gnu
```

--------------------------------

### Cross-compile Mach Project for Windows

Source: https://machengine.org/docs/getting-started

Build the Mach project for the x86_64 Windows target using the GNU toolchain.

```bash
zig build -Dtarget=x86_64-windows-gnu
```

--------------------------------

### Set Minimum Zig Version in build.zig.zon

Source: https://machengine.org/docs/nominated-zig

Specify the minimum required Zig version for a project in the build.zig.zon file.

```zig
.minimum_zig_version = "0.16.0-dev.3142+5ccfeb926",
```

--------------------------------

### Define a Public System Function

Source: https://machengine.org/docs/object/systems

Define a public function with the same name as a declared system. This function will contain the system's logic.

```zig
pub fn tick() void {
    // could do something interesting here!
}

```

--------------------------------

### Define a Public System Schedule

Source: https://machengine.org/docs/object/systems

Define a public schedule using `mach.schedule` to run a sequence of other systems. This is an alternative to a direct function definition for a system.

```zig
pub const init = mach.schedule(.{
    .{ OtherModule, .init }, // run OtherModule's .init system first,
    .{ App, .start },        // then afterwards run App's .start system
});

```

--------------------------------

### Declare Mach Systems

Source: https://machengine.org/docs/object/systems

Add system names to the `mach_systems` list to declare them. A public function or schedule with the same name must exist.

```zig
pub const mach_module = .foo;

// ...

pub const mach_systems = .{ .init, .tick, .deinit };

```

--------------------------------

### OpenGL-style Matrix-Vector Multiplication (Column-Major)

Source: https://machengine.org/docs/math/matrix-storage

Illustrates the standard mathematical convention for matrix-vector multiplication using column-major storage and column-vectors, common in OpenGL and its descendants.

```mathematica
|1 0 0 tx| |x|   |x+w*tx|
|0 1 0 ty| |y| = |y+w*ty|
|0 0 1 tz| |z|   |z+w*tz|
|0 0 0 tw| |1|   |tw    |
```

--------------------------------

### Declare Dynamically-Sized List of Objects

Source: https://machengine.org/docs/object/objects

Declare a list of objects with specified fields. This is how you define the structure for a collection of objects.

```zig
pub const mach_module = .app;

// ...

monsters: mach.Objects(struct {
    health: f32,
    damage: f32,
}),

```

--------------------------------

### Cross-Compile Mach for Different Targets

Source: https://machengine.org/docs/modularity/about/zig-version

Build Mach for various operating systems and architectures using Zig's cross-compilation capabilities.

```bash
$ zig build -Dtarget=x86_64-windows

```

```bash
$ zig build -Dtarget=x86_64-linux-gnu

```

```bash
$ zig build -Dtarget=x86_64-macos

```

```bash
$ zig build -Dtarget=aarch64-macos

```

--------------------------------

### Run a Mach System

Source: https://machengine.org/docs/object/systems

Use `mach.Mod(T).run()` to invoke a system within a specific Mach module. Mach handles argument injection and performance observation.

```zig
pub fn main() !void {
    // ...

    // Pass control to our App.zig module.
    const app: mach.Mod(App) = mods.get(.app);
    app.run(.main);
}

```

--------------------------------

### Add Mach Dependency to Zig Project

Source: https://machengine.org/docs/getting-started

Manually add the Mach dependency to your project's build.zig.zon file using zig fetch.

```bash
zig fetch --save https://pkg.hexops.org/pkg/hexops/mach/$LATEST_COMMIT.tar.gz
```

--------------------------------

### Cross-compile Mach Project for macOS

Source: https://machengine.org/docs/getting-started

Build the Mach project for the Apple Silicon macOS target.

```bash
zig build -Dtarget=aarch64-macos
```

--------------------------------

### Configure Project to Use Specific Zig Version

Source: https://machengine.org/docs/nominated-zig

Specify the desired Zig version in your `build.zig.zon` file. This ensures that `zig build` commands automatically use the designated Zig compiler.

```zig
.mach_zig_version = "2024.3.0-mach"

```

```zig
.mach_zig_version = "2024.1.0-mach"

```

--------------------------------

### Set Mach Nominated Zig Version in build.zig.zon

Source: https://machengine.org/docs/nominated-zig

Configure a specific Mach nominated Zig version for your project within the build.zig.zon file.

```zig
.mach_zig_version = "2024.11.0-mach"
```

--------------------------------

### Define a Module System Function

Source: https://machengine.org/docs/object/modules

Define a public function that corresponds to a system declared in `mach_systems`. This function will be executed if the system is invoked.

```zig
pub fn init() void {
    // ...
}

```

--------------------------------

### Fetch Mach Dependency

Source: https://machengine.org/docs/stdlib

Fetches the latest Mach dependency for your project. Ensure you replace $LATEST_COMMIT with the actual commit hash.

```zig
zig fetch --save https://pkg.hexops.org/pkg/hexops/mach/$LATEST_COMMIT.tar.gz

```

--------------------------------

### Add Mach Dependency to build.zig

Source: https://machengine.org/docs/stdlib

Integrates the Mach dependency into your Zig build file, making it importable by your library and executable.

```zig
pub fn build(b: *std.Build) void {
    // ...

    // Add Mach to our library and executable
    const mach_dep = b.dependency("mach", .{
        .target = target,
        .optimize = optimize,
    });
    lib.root_module.addImport("mach", mach_dep.module("mach"));
    exe.root_module.addImport("mach", mach_dep.module("mach"));
}

```

--------------------------------

### Column-Major Matrix in Code (C-like Syntax)

Source: https://machengine.org/docs/math/matrix-storage

Demonstrates a column-major matrix representation in code, where vector elements are stored contiguously in memory.

```c
const m = [4][4]f32{
    .{ 1,  0,  0,  0},
    .{ 0,  1,  0,  0},
    .{ 0,  0,  1,  0},
    .{tx, ty, tz, tw},
};

```

--------------------------------

### Declare Module Objects

Source: https://machengine.org/docs/object/modules

Declare lists of objects within a module. Each object can have defined fields like health and damage.

```zig
monsters: mach.Objects(struct {
    health: f32,
    damage: f32,
}),

```

--------------------------------

### Simplest Mach Module Definition

Source: https://machengine.org/docs/object/modules

Defines a minimal Mach module with only a name. This is the most basic structure for a Mach module.

```zig
pub const mach_module = .app;

```

--------------------------------

### Matrix-Vector Multiplication (Mathematical Convention)

Source: https://machengine.org/docs/math/matrix-storage

Demonstrates matrix-vector multiplication using the mathematical convention where the vector is treated as a column.

```plaintext
|1 0 0 tx| |x|   |x+w*tx|
|0 1 0 ty| |y| = |y+w*ty|
|0 0 1 tz| |z|   |z+w*tz|
|0 0 0 tw| |1|   |tw    |

```

--------------------------------

### System Function with Injected Arguments

Source: https://machengine.org/docs/object/systems

System functions can accept injected arguments, allowing access to any Mach module in the program. Mach automatically provides these arguments when calling the function.

```zig
pub fn tick(app: *App, other_mod: mach.Mod(Other), other: *Other) void {
    // Access App modules' global state
    app.counter += 1;

    // Access Other modules' global state
    other.counter += 1;

    // Run Other module's system (covered more in the next section)
    other_mod.run(.tick);
}

```

--------------------------------

### Matrix-Vector Multiplication (Alternative Notation)

Source: https://machengine.org/docs/math/matrix-storage

Presents an alternative notation for matrix-vector multiplication, highlighting the difference in vector representation.

```plaintext
          |1  0  0  0 |
|x y z 1| |0  1  0  0 | = |x+w*tx, y+w*ty, z+w*tz, tw|
          |0  0  1  0 |
          |tx ty tz tw|

```

--------------------------------

### Synchronize Access to Mach Objects

Source: https://machengine.org/docs/object/objects

Acquire a read-write lock before accessing Mach objects to prevent data race conditions in multi-threaded environments. Ensure the lock is released using defer.

```Go
app.monsters.lock()
defer app.monsters.unlock()

```

--------------------------------

### Incorrect Conditional System Call

Source: https://machengine.org/docs/object/systems

This code demonstrates an anti-pattern where a system is conditionally executed. This can lead to missed updates if other modules or external factors modify the system's state without triggering the conditional check.

```zig
pub fn spawnMonsters(monsters: *Monsters, monsters_mod: mach.Mod(Monsters)) void {
    for (monsters.amount_to_spawn) {
        // ...
    }

    // BAD!:
    if (monsters.amount_to_spawn > 0) monsters_mod.run(.processNewMonsters);

    // GOOD!:
    // monsters_mod.run(.processNewMonsters);
}

```

--------------------------------

### Mach Module with Global State

Source: https://machengine.org/docs/object/modules

Adds state fields like a timer and counter to a Mach module. These fields act as effectively global variables for the module instance.

```zig
pub const mach_module = .app;

timer: mach.time.Timer,
counter: u32,


```

--------------------------------

### Row-Major Matrix in Code (C-like Syntax)

Source: https://machengine.org/docs/math/matrix-storage

Shows how a matrix, following mathematical row-major convention, might be represented in a programming language like C or Zig, leading to non-contiguous vector elements.

```c
const m = [4][4]f32{
    .{1, 0, 0, tx},
    .{0, 1, 0, ty},
    .{0, 0, 1, tz},
    .{0, 0, 0, tw},
};

```

--------------------------------

### DirectX-style Matrix-Vector Multiplication (Row-Major)

Source: https://machengine.org/docs/math/matrix-storage

Shows the convention used in DirectX-style graphics programming, which employs row-major storage and row-vectors, resulting in a different matrix-vector multiplication order compared to the standard mathematical convention.

```mathematica
          |1  0  0  0 |
|x y z 1| |0  1  0  0 | = |x+w*tx, y+w*ty, z+w*tz, tw|
          |0  0  1  0 |
          |tx ty tz tw|
```

--------------------------------

### Mathematical Matrix Representation (4x4)

Source: https://machengine.org/docs/math/matrix-storage

Illustrates a standard 4x4 matrix as commonly represented in mathematical contexts, emphasizing row-major order.

```plaintext
|a00 a01 a02 a03|
|a10 a11 a12 a13|
|a20 a21 a22 a23|
|a30 a31 a32 a33|

```

--------------------------------

### Iterate and Modify Mach Objects

Source: https://machengine.org/docs/object/objects

Iterate over Mach objects, modify their properties, and safely delete them within the loop. The object system handles recycling, making deletion safe during iteration.

```Go
pub fn tick(app: *App) void {
    app.monsters.lock()
    defer app.monsters.unlock()

    // Iterate over each monster and do something with them
    var slice = app.monsters.slice()
    while (slice.next()) |monster_id| {
        const monster = slice.get(monster_id)
        monster.health = 100; // they can never die!
        slice.set(monster_id, monster)

        // But we will delete them anyway :)
        if (monster.health == 0) slice.delete(monster_id)
    }
}

```
Tokens:
Raw