goarrg

README

goARRG - go Assembly RequiRed Game-engine

goARRG is a assembly required game engine where the pieces may or may not be provided and it is up to you to put them together. This allows the user to customize the engine almost exactly to their needs. It is not a goal however to make it easy to rip out a piece and replace it later.

Development Roadmap

*Not in actual development order

• MVP for engine development
  • Platform initialization and setup
  • Maths
  • Glue APIs
  • Basic Tooling
• Renderer? (we may never release an actual renderer)
  • RHI
• ECS?
• Editor

Supported Platforms

Currently goarrg only supports Ubuntu (tested on 24.04 LTS) and Windows 10, 386 and amd64. Vulkan is only tested on amd64.

Dependencies

goarrg requires go 1.23+
The following list of dependencies assume you are using the make package to install the rest.

OS	Dependencies
Ubuntu	sudo apt-get install build-essential cmake
Windows	llvm-mingw, cmake

SDL3 (Linux)

https://wiki.libsdl.org/SDL3/README-linux#build-dependencies

Graphics API Specific

OS	API	Dependencies
Ubuntu	gl	sudo apt-get install libglu1-mesa-dev mesa-common-dev

Cross Compile

There is cross compile support for the supported platforms, assuming you installed a C/C++ cross compiler with the correct file names. To cross compile to other platforms, or to use a non default toolchain, you need to set the CC/CXX/AR environmental variables. For Windows, you also need to set RC.

The toolchain/cc package is there to help setup these environmental variables.

Default Compiler Selection

Taraget Platform	Prefix
linux_386	i686-linux-gnu
linux_amd64	x86_64-linux-gnu
windows_386	i686-w64-mingw32
windows_amd64	x86_64-w64-mingw32

GCC

CC={{.Prefix}}-gcc
CXX={{.Prefix}}-g++
AR={{.Prefix}}-gcc-ar

Clang

CC={{.Prefix}}-clang
CXX={{.Prefix}}-clang++
AR={{.Prefix}}-llvm-ar

Windows Only:
RC={{.Prefix}}-windres

Install instructions

Install Go manually to ensure you have the latest version.
https://golang.org/doc/install

mkdir projectfolder
cd projectfolder
go mod init github.com/username/projectname
go get -d goarrg.com/...

After which you write a ./cmd/make program that imports the goarrg.com/make package to build dependencies and to build your project.

Examples

Examples can be found at https://github.com/goarrg/examples

Documentation

Index

• Constants
• func Run(cfg Config) error
• func Running() bool
• func Shutdown()
• type Audio
• type AudioConfig
• type Config
• type GLConfig
• type GLInstance
• type GLProfile
• type GLRenderer
• type Platform
• type PlatformInterface
• type Program
• type Renderer
• type VkConfig
• type VkInstance
• type VkRenderer

Constants

const Build = build.BuildRelease

Functions

func Run

func Run(cfg Config) error

func Running

func Running() bool

Running reports whether the engine is considered to still be running. It will only return true when the main loop is running and before shutdown confirmation from Program.Shutdown(). This is so that you can depend on Running() to terminate your loops/threads.

SIGINT will bypass Program.Shutdown() and force a terminate. This is so we have a easy way to terminate the engine in the event of deadlocks.

func Shutdown

func Shutdown()

Shutdown is a thread safe signal to the engine that it should shutdown. The signal usually would come from the Platform or Program packages.

Types

type Audio

type Audio interface {
	AudioConfig() AudioConfig
	Init(PlatformInterface, AudioConfig) error
	Mix() (int, audio.Track)
	Update()
	Destroy()
}

type AudioConfig

type AudioConfig struct {
	Spec audio.Spec
}

Refer to driver's documentation on the valid value ranges

type Config

type Config struct {
	Platform Platform
	Audio    Audio
	Renderer Renderer
	Program  Program
}

type GLConfig

type GLConfig struct {
	Major   uint8
	Minor   uint8
	Profile GLProfile
}

type GLInstance

type GLInstance interface {
	ProcAddr() uintptr
	SwapBuffers()
}

type GLProfile

type GLProfile uint8

const (
	GLProfileCore GLProfile = iota
	GLProfileCompat
	GLProfileES
)

type GLRenderer

type GLRenderer interface {
	Renderer
	GLConfig() GLConfig
	GLInit(PlatformInterface, GLInstance) error
}

type Platform

type Platform interface {
	Init() (PlatformInterface, error)
	AudioInit(Audio) error
	DisplayInit(Renderer) error
	Update()
	Destroy()
}

type PlatformInterface

type PlatformInterface interface {
	// Abort terminates the application and potentially creates a dump.
	// May be implemented with a panic().
	Abort()

	// AbortPopup displays a popup in a platform specific manner, visually indicating an error to the user.
	// Then terminates the application and potentially creates a dump.
	// May be implemented with a panic().
	AbortPopup(string, ...interface{})
}

PlatformInterface defines a set of functions all Platforms must support, this is to facilitate the creation of packages that only requires basic functionality without having a dependency on a specific Platform package.

type Program

type Program interface {
	Init(PlatformInterface) error
	Update(float64)
	Shutdown() bool
	Destroy()
}

type Renderer

type Renderer interface {
	Draw() float64
	Resize(int, int)
	Destroy()
}

type VkConfig

type VkConfig struct {
	API        uint32
	Layers     []string
	Extensions []string
}

type VkInstance

type VkInstance interface {
	Uintptr() uintptr
	ProcAddr() uintptr
	// Creates a new VkSurfaceKHR, destroying the old one if called a second time onwards,
	// caller is responsible for fulfilling any sync requirements
	CreateSurface() (uint64, error)
}

type VkRenderer

type VkRenderer interface {
	Renderer
	VkConfig() VkConfig
	VkInit(PlatformInterface, VkInstance) error
}