# Technical Documentation: hexops/mach

> ℹ️ **Provenance:** In-Tree Documentation (10 Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/hexops/mach) · Recency: Active (< 180 days)

## File: README.md

<a href="https://machengine.org">
    
        
        
    
</a>

Zig game engine & graphics toolkit for building high-performance, truly cross-platform, robust & modular games, visualizations, and desktop/mobile GUI apps.

[](https://user-images.githubusercontent.com/3173176/173177664-2ac9e90b-9429-4b09-aaf9-b80b53fee49f.gif)
[](https://user-images.githubusercontent.com/3173176/163936001-fd9eb918-7c29-4dcc-bfcb-5586f2ea1f9a.gif)
[](https://user-images.githubusercontent.com/3173176/173177646-a3f0982c-f07b-496f-947b-265bdc71ece9.gif)

## Learn more

See [machengine.org](https://machengine.org) for docs, tutorials, etc.

## Development

Development occurs on [code.hexops.org](https://code.hexops.org/hexops/mach) - our GitHub [mirror](https://github.com/hexops/mach) is purely for visibility.

## Join the community

Join the [Mach community on Discord](https://discord.gg/XNG3NZgCqp) to discuss this project, ask questions, get help, etc.

**We're here to make games in Zig and have fun, so please help us keep the community focused on that.** Everyone is welcome here, LGBTQ+ and otherwise. 💛

---

## File: src/sysgpu/conventions.md

### Object ordering

Backends should be a single file with object in the following order:

- Instance
- Adapter
- Surface
- SurfaceCapabilities
- Device
- SwapChain
- Buffer
- Texture
- TextureView
- Sampler
- BindGroupLayout
- BindGroup
- PipelineLayout
- ShaderModule
- ComputePipeline
- RenderPipeline
- CommandBuffer
- CommandEncoder
- ComputePassEncoder
- RenderPassEncoder
- RenderBundle
- RenderBundleEncoder
- Queue
- QuerySet

Utility objects (e.g. StateTracker should come after the closest object that "owns" them.

---

## File: src/sysgpu/d3d12/notes.md

### Interface Support

Windows release version needed to use various functionality in DXGI and D3D12.

DXGI
- 1.4 - baseline
- 1.5 - 1607
- 1.6 - 1703/1803/1809

CreateDXGIFactory

- CreateDXGIFactory2 - baseline

DXGIGetDebugInterface

- DXGIGetDebugInterface1 - baseline

IDXGIAdapter

- IDXGIAdapter3 - baseline
- IDXGIAdapter4 - 1703

IDXGIDevice

- IDXGIDevice3 - baseline
- IDXGIDevice4 - 1607

IDXGIFactory

- IDXGIFactory4 - baseline
- IDXGIFactory5 - 1607
- IDXGIFactory6 - 1803
- IDXGIFactory7 - 1809

IDXGIOutput

- IDXGIOutput4 - baseline
- IDXGIOutput5 - 1607
- IDXGIOutput6 - 1703

IDXGISwapChain

- IDXGISwapChain3 - baseline
- IDXGISwapChain4 - 1607

---

## File: .forgejo/FUNDING.yml

github: emidoots

---

## File: .forgejo/pull_request_template.md

- [ ] By selecting this checkbox, I agree to license my contributions to this project under the license(s) described in the LICENSE file, and I have the right to do so or have received permission to do so by an employer or client I am producing work for whom has this right.

---

## File: .forgejo/ISSUE_TEMPLATE/bug.md

---
name: Bug
about: Report a bug
title: ': '
labels: bug, needs-triage
assignees: ''

---

Before filing an issue, please make sure you're using a supported Zig version: https://machengine.org/about/zig-version

---

## File: .forgejo/ISSUE_TEMPLATE/dev_release.md

---
name: (dev) Release checklist
about: The checklist we follow to perform a Mach release
title: 'all: Mach 0.3 release checklist'
labels: all, zig-update
assignees: 'emidoots'

---

This is a tracking issue for preparing the next Mach release.

## Checklist

* [ ] In `mach` repository, the release has been tagged (`git tag v0.3.0 && git push origin v0.3.0`)
* [ ] In `machengine.org` repository `static/zig` folder, `wrench script nominate-zig-index-update tag 2024.1.0-mach 0.3.0-mach` has been ran to tag the Zig version that the Mach release will use, and the [`index.json`](https://machengine.org/zig/index.json) shows the new version.
* [ ] In `machengine.org` main branch, `deploy.yml` has a new `hugo --minify` entry for the version to be released
* [ ] In `machengine.org` main branch, `zig-version.md` has been updated with a new `Supported Zig versions` entry
* [ ] 
* [ ] In `machengine.org` repository, a branch for the major release has been created `git checkout -B v0.3 && git push --set-upstream origin v0.3`
* [ ] In `machengine.org` repository's new major release branch `v0.3`, `config.toml`'s `branch = 'main'` has been changed to `branch = 'v0.3'` and https://machengine.org/v0.3 now loads fine

---

## File: .forgejo/ISSUE_TEMPLATE/dev_zig_nomination.md

---
name: (dev) Zig version update
about: The process we follow to perform a Zig version update
title: 'all: nominate Zig YYYY.MM.0-mach'
labels: all, zig-update
assignees: 'emidoots'

---

Periodically we [nominate a new Zig nightly version](https://machengine.org/about/nominated-zig) to be the version that Mach targets, and begin the meticulous process of updating every Mach project to use that new version.

This is the tracking issue to do that for the next scheduled nomination (see the date in the issue title.)

You may have been linked to this issue because you sent a pull request to update a Mach project to use a new Zig API - if that is the case we do appreciate the PR and will look at merging it once this process begins. In the meantime, your PR may stay open for a while. You can either use a fork of the project, or [use the version of Zig that Mach currently supports.](https://machengine.org/about/zig-version)

## Update process

* [ ] It is time to begin (see date in issue title, we aim to begin this checklist between the 1st-4th of that month.)
* [ ] In `machengine.org` repository `static/zig` folder, `wrench script nominate-zig-index-update nominate 2024.1.0-mach-wip` has been ran and the [`index.json`](https://machengine.org/zig/index.json) has been updated.
* [ ] #wrench automation (`!wrench script-all install-zig
` then `!wrench schedule-now update-zig-version`) has created new pull requests to update the Zig version used in CI of all our projects, and it matches index.json.
* [ ] The [_Nomination history_](https://machengine.org/about/nominated-zig/#nomination-history) has a new section for the latest nightly Zig version which Wrench used in its PRs, with a warning at the top `**IN-PROGRESS:** This version is currently being nominated, see [the tracking issue](https://github.com/hexops/mach/issues/1135) for details. Once everything looks good, the new Zig version is confirmed to be working with Mach, we will declare success, close the issue, and remove this in-progress warning.`.
* [ ] #contributing Discord message: `Beginning the process of nominating a new Zig version; $GITHUB_ISSUE`
* [ ] #wrench automation (`!wrench script-all install-zig`) has updated the Zig version used by self-hosted GitHub actions runners.
* [ ] "First-order projects" below (which have zero build.zig.zon dependencies) have been updated, their CI is passing/green using the new version.
* [ ] "Second-order projects" below (which have build.zig.zon dependencies) have been updated, their CI is passing/green using the new version.
* [ ] The `.zigversion` file https://github.com/hexops/mach/blob/main/.zigversion has been updated.
* [ ] The mach build.zig version check has been updated: https://github.com/hexops/mach/blob/main/build.zig#L427-L432
* [ ] https://machengine.org/docs/zig-version has been updated
* [ ] In `machengine.org` repository `static/zig` folder, `wrench script nominate-zig-index-update finalize 2024.1.0-mach-wip` has been ran and the [`index.json`](https://machengine.org/zig/index.json) has had `-wip` removed and the `mach-latest` entry has been updated.
* [ ] The `**IN-PROGRESS**` warning in the _Nomination history_ has been removed.
* [ ] A [new issue](https://github.com/hexops/mach/issues/new?assignees=emidoots&labels=all%2C+zig-update&projects=&template=dev_zig_nomination.md&title=all%3A+nominate+Zig+YYYY.MM) has been filed for the next nomination.
* [ ] A #progress announcement has been made:

> We've just finalized nominating and updating to Zig 2024.1.0-mach. We encourage you to update your projects to that Zig version now. :)
>
> * Get the new Zig version: https://machengine.org/docs/nominated-zig/#2024110-mach
> * Tips on upgrading your own Zig code: https://github.com/hexops/mach/issues/1135#issuecomment-1891175749
> * Nomination tracking issue: $GITHUB_ISSUE

## First-order projects

These projects have zero `build.zig.zon` dependencies, we update them first - and in any order.

* [ ] [fastfilter](https://github.com/hexops/fastfilter)
* [ ] [spirv-cross](https://github.com/hexops/spirv-cross)
* [ ] [brotli](https://github.com/hexops/brotli)
* [ ] [wayland-headers](https://github.com/hexops/wayland-headers)
* [ ] [x11-headers](https://github.com/hexops/x11-headers)
* [ ] [vulkan-headers](https://github.com/hexops/vulkan-headers)
* [ ] [opengl-headers](https://github.com/hexops/opengl-headers)
* [ ] [linux-audio-headers](https://github.com/hexops/linux-audio-headers)
* [ ] [xcode-frameworks](https://github.com/hexops/xcode-frameworks)
* [ ] [vulkan-zig-generated](https://github.com/hexops/vulkan-zig-generated)
* [ ] [directx-headers](https://github.com/hexops/directx-headers)
* [ ] [opus](https://github.com/hexops/opus)
* [ ] [flac](https://github.com/hexops/flac)
* [ ] [ogg](https://github.com/hexops/ogg)
* [ ] [mach-example-assets](https://github.com/hexops/mach-example-assets)

## Second-order projects

These projects have dependencies on other projects. We update them in the exact order below, top-to-bottom.

* [ ] [spirv-tools](https://github.com/hexops/spirv-tools), which depends on:
  * External package https://github.com/KhronosGroup/SPIRV-Headers
* [ ] [opusenc](https://github.com/hexops/opusenc), which depends on:
  * opus
* [ ] [freetype](https://github.com/hexops/freetype), which depends on:
  * brotli
* [ ] [opusfile](https://github.com/hexops/opusfile), which depends on:
  * opus
  * ogg
* [ ] [harfbuzz](https://github.com/hexops/harfbuzz), which depends on:
  * freetype
  * brotli
* [ ] [mach-dxcompiler](https://github.com/hexops/mach-dxcompiler), which depends on:
* [ ] [mach-objc](https://github.com/hexops/mach-objc), which depends on:
  * xcode-frameworks
* [ ] [mach-freetype](https://github.com/hexops/mach-freetype), which depends on:
  * freetype
  * harfbuzz
* [ ] [mach-flac](https://github.com/hexops/mach-flac), which depends on:
  * flac
  * mach-sysaudio
  * linux-audio-headers
* [ ] [mach-opus](https://github.com/hexops/mach-opus), which depends on:
  * opusfile
  * opusenc 
  * mach-sysaudio
  * linux-audio-headers
* [ ] [mach](https://github.com/hexops/mach), which depends on:
  * .zigversion
  * build.zig version check
  * mach-freetype
  * mach-objc
  * mach-example-assets
  * spirv-cross
  * spirv-tools
  * xcode-frameworks
  * vulkan-zig-generated
  * direct3d-headers
  * opengl-headers
  * x11-headers
  * linux-audio-headers
  * wayland-headers

---

## File: .forgejo/ISSUE_TEMPLATE/feedback.md

---
name: Suggestion / feedback
about: Suggest a feature, provide general feedback, etc.
title: ''
labels: feedback, needs-triage
assignees: ''

---

---

## File: .forgejo/workflows/ci.yml

name: CI
on:
  push:
    paths-ignore:
      - "doc/**"
      - "README.md"
      - "**.md"
      - "LICENSE**"
  pull_request:
    paths-ignore:
      - "doc/**"
      - "README.md"
      - "**.md"
      - "LICENSE**"
jobs:
  x86_64-linux:
    runs-on: ubuntu-latest
    # We want to run on external PRs, but not on our own internal PRs as they'll be run by the push
    # to the branch.
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
    env:
      DISPLAY: ':99.0'
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Zig
        run: |
          sudo apt install xz-utils
          sudo sh -c 'wget -c https://pkg.machengine.org/zig/zig-linux-x86_64-0.14.0-dev.2577+271452d22.tar.xz -O - | tar -xJ --strip-components=1 -C /usr/local/bin'
      - name: launch xvfb
        run: Xvfb :99 -screen 0 1680x720x24 > /dev/null 2>&1 &
      # - name: x86_64-linux -> x86_64-linux-musl
      #   run: zig build -Dtarget=x86_64-linux-musl
      # TODO(build): currently cannot link on macOS due to a bug in the Zig linker. https://github.com/hexops/mach/issues/1276
      # - name: x86_64-linux -> x86_64-macos
      #   run: zig build -Dtarget=x86_64-macos
      # - name: x86_64-linux -> aarch64-macos
      #   run: zig build -Dtarget=aarch64-macos
      - name: x86_64-linux -> x86_64-windows
        run: zig build -Dtarget=x86_64-windows-gnu
      - name: build
        run: zig build
      - name: test
        run: zig build test
      - name: test (with core deps only)
        run: zig build -Dcore test
      - name: test (with sysaudio deps only)
        run: zig build -Dsysaudio test
      - name: test (with sysgpu deps only)
        run: zig build -Dsysgpu test
      - name: test (specific deps only)
        run: zig build -Dcore -Dsysaudio -Dsysgpu test
      ## TODO: use hexops/spirv-tools for spirv validation instead OR if we are using ZLS finally, just remove this commented block
      ## The following block throws this error, so it is disabled for now:
      ## https://github.com/hexops/mach/actions/runs/11223060751/job/31196848244?pr=1279#step:14:79
      # - name: 'sysgpu: validate spirv code generation'
      #   run: |
      #     wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo tee /etc/apt/trusted.gpg.d/lunarg.asc
      #     sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-jammy.list http://packages.lunarg.com/vulkan/lunarg-vulkan-jammy.list
      #     sudo apt update
      #     sudo apt install libyaml-cpp-dev vulkan-sdk spirv-tools
      # - name: 'sysgpu: validate spirv output'
      #   run: bash ./src/sysgpu/tools/validate_spirv.sh
  x86_64-windows:
    runs-on: windows-latest
    # We want to run on external PRs, but not on our own internal PRs as they'll be run by the push
    # to the branch.
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Zig
        run: |
          $ProgressPreference = 'SilentlyContinue'
          Invoke-WebRequest -Uri 'https://pkg.machengine.org/zig/zig-windows-x86_64-0.14.0-dev.2577+271452d22.zip' -OutFile 'C:\zig.zip'
          cd C:\
          7z x zig.zip
          Add-Content $env:GITHUB_PATH 'C:\zig-windows-x86_64-0.14.0-dev.2577+271452d22\'
      - name: build
        run: zig build
      - name: test
        run: zig build test
  x86_64-macos:
    runs-on: macos-13
    # We want to run on external PRs, but not on our own internal PRs as they'll be run by the push
    # to the branch.
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Zig
        run: |
          brew uninstall --ignore-dependencies libx11 # https://github.com/ziglang/zig/issues/11066
          brew install xz
          sudo sh -c 'wget -c https://pkg.machengine.org/zig/zig-macos-x86_64-0.14.0-dev.2577+271452d22.tar.xz -O - | tar -xJ --strip-components=1 -C /usr/local/bin'
      - name: build
        run: zig build
      - name: test
        run: zig build test

--- METRICS ---
- Files Extracted: 10
- Estimated Token Budget: ~4418 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/hexops/mach