Go bindings for [raylib](https://www.raylib.com/), a simple and easy-to-use library to learn videogames programming

![logo](https://goo.gl/XlIcXz)
## raylib-go
[![Build Status](https://github.com/gen2brain/raylib-go/actions/workflows/build.yml/badge.svg)](https://github.com/gen2brain/raylib-go/actions)
[![GoDoc](https://godoc.org/github.com/gen2brain/raylib-go/raylib?status.svg)](https://godoc.org/github.com/gen2brain/raylib-go/raylib)
[![Go Report Card](https://goreportcard.com/badge/github.com/gen2brain/raylib-go/raylib)](https://goreportcard.com/report/github.com/gen2brain/raylib-go/raylib)
[![Examples](https://img.shields.io/badge/learn%20by-examples-0077b3.svg?style=flat-square)](https://github.com/gen2brain/raylib-go/tree/master/examples)

Golang bindings for [raylib](http://www.raylib.com/), a simple and easy-to-use library to enjoy videogames programming.

raylib C source code is included and compiled together with bindings. Note that the first build can take a few minutes.

It is also possible to use raylib-go without cgo (Windows only; see requirements below).

### Requirements

##### Ubuntu

 apt-get install libgl1-mesa-dev libxi-dev libxcursor-dev libxrandr-dev libxinerama-dev libwayland-dev libxkbcommon-dev

##### Fedora

 dnf install mesa-libGL-devel libXi-devel libXcursor-devel libXrandr-devel libXinerama-devel wayland-devel libxkbcommon-devel

##### macOS

On macOS, you need Xcode or Command Line Tools for Xcode (if you have `brew` installed, you already have this).

##### Windows

###### cgo

On Windows you need C compiler, like [Mingw-w64](https://mingw-w64.org) or [TDM-GCC](http://tdm-gcc.tdragon.net/).
You can also build binary in [MSYS2](https://msys2.github.io/) shell.

To remove console window, build with `-ldflags "-H=windowsgui"`.

###### purego (without cgo, i.e. CGO_ENABLED=0)

Download the raylib.dll from the assets on the [releases page](https://github.com/raysan5/raylib/releases). It is contained in the `raylib-*_win64_msvc*.zip`.
Put the raylib.dll into the root folder of your project or copy it into `C:\Windows\System32` for a system-wide installation.

It is also possible to build the DLL yourself. You can find more info at [raylib's wiki](https://github.com/raysan5/raylib/wiki/Working-on-Windows).

##### Android

[Android example](https://github.com/gen2brain/raylib-go/tree/master/examples/others/android/example).

##### Wasm

For web bindings, refer to [Raylib-Go-Wasm](https://github.com/BrownNPC/Raylib-Go-Wasm); it should be largely compatible with this repository.


### Installation

 go get -v -u github.com/gen2brain/raylib-go/raylib

### Build tags

* `drm` - build for Linux native [DRM](https://en.wikipedia.org/wiki/Direct_Rendering_Manager) mode, including Raspberry Pi 4 and other devices (PLATFORM_DRM)
* `sdl` - build for [SDL](https://github.com/libsdl-org/SDL) backend (PLATFORM_DESKTOP_SDL)
* `sdl3` - build for [SDL3](https://github.com/libsdl-org/SDL) backend (PLATFORM_DESKTOP_SDL3)
* `rgfw` - build for [RGFW](https://github.com/ColleagueRiley/RGFW) backend (PLATFORM_DESKTOP_RGFW)
* `noaudio` - disables audio functions
* `opengl43` - uses OpenGL 4.3 backend
* `opengl21` - uses OpenGL 2.1 backend (default is 3.3 on desktop)
* `opengl11` - uses OpenGL 1.1 backend (pseudo OpenGL 1.1 style)
* `es2` - uses OpenGL ES 2.0 backend (can be used to link against [Google's ANGLE](https://github.com/google/angle))
* `es3` - experimental support for OpenGL ES 3.0
* `x11` - force X11 compatibility mode on Wayland (PLATFORM_DESKTOP/GLFW)
* `wayland` - force Wayland only mode (PLATFORM_DESKTOP/GLFW)

### Documentation

Documentation on [GoDoc](https://godoc.org/github.com/gen2brain/raylib-go/raylib). Also check raylib [cheatsheet](http://www.raylib.com/cheatsheet/cheatsheet.html). If you have problems or need assistance there is an active community in the #raylib-go channel of the [Raylib Discord Server](https://discord.gg/raylib) that can help.

### Example

```go
package main

import rl "github.com/gen2brain/raylib-go/raylib"

func main() {
 rl.InitWindow(800, 450, "raylib [core] example - basic window")
 defer rl.CloseWindow()

 rl.SetTargetFPS(60)

 for !rl.WindowShouldClose() {
 rl.BeginDrawing()

 rl.ClearBackground(rl.RayWhite)
 rl.DrawText("Congrats! You created your first window!", 190, 200, 20, rl.LightGray)

 rl.EndDrawing()
 }
}
```

Check more [examples](https://github.com/gen2brain/raylib-go/tree/master/examples) organized by raylib modules.

### Cross-compile (Linux)

To cross-compile for Windows install [MinGW](https://www.mingw-w64.org/) toolchain.

```
$ CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows GOARCH=amd64 go build -ldflags "-s -w"
$ file basic_window.exe
basic_window.exe: PE32+ executable (console) x86-64 (stripped to external PDB), for MS Windows, 11 sections

$ CGO_ENABLED=1 CC=i686-w64-mingw32-gcc GOOS=windows GOARCH=386 go build -ldflags "-s -w"
$ file basic_window.exe
basic_window.exe: PE32 executable (console) Intel 80386 (stripped to external PDB), for MS Windows, 9 sections
```

To cross-compile for macOS install [OSXCross](https://github.com/tpoechtrager/osxcross) toolchain.

```
$ CGO_ENABLED=1 CC=x86_64-apple-darwin21.1-clang GOOS=darwin GOARCH=amd64 go build -ldflags "-linkmode external -s -w '-extldflags=-mmacosx-version-min=10.15'"
$ file basic_window
basic_window: Mach-O 64-bit x86_64 executable, flags:<NOUNDEFS|DYLDLINK|TWOLEVEL>

$ CGO_ENABLED=1 CC=aarch64-apple-darwin21.1-clang GOOS=darwin GOARCH=arm64 go build -ldflags "-linkmode external -s -w '-extldflags=-mmacosx-version-min=12.0.0'"
$ file basic_window
basic_window: Mach-O 64-bit arm64 executable, flags:<NOUNDEFS|DYLDLINK|TWOLEVEL|PIE>
```

### License

raylib-go is licensed under an unmodified zlib/libpng license. View [LICENSE](https://github.com/gen2brain/raylib-go/blob/master/LICENSE).

raylib-go

Terminal-based game engine for Go, built on top of Termbox

## Termloop

[![Join the chat at https://gitter.im/JoelOtter/termloop](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/JoelOtter/termloop?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![GoDoc](https://godoc.org/github.com/JoelOtter/termloop?status.svg)](http://godoc.org/github.com/JoelOtter/termloop)

![](_examples/images/maze.png)

Termloop is a pure Go game engine for the terminal, built on top of the excellent [Termbox](https://github.com/nsf/termbox-go). It provides a simple render loop for building games in the terminal, and is focused on making terminal game development as easy and as fun as possible.

Termloop is still under active development so changes may be breaking. I add any breaking changes to the [Changelog](https://github.com/JoelOtter/termloop/wiki/Changelog) - hopefully at this stage there shouldn't be too many. Pull requests and issues are *very* welcome, and do feel free to ask any questions you might have on the Gitter. I hope you enjoy using Termloop; I've had a blast making it.

## Installing
Install and update with `go get -u github.com/JoelOtter/termloop`

## Features

- Keyboard and mouse input
- Collision detection
- Render timers
- Level offsets to simulate 'camera' movement
- Debug logging
- Built-in entity types such as:
 - Framerate counters
 - Rectangles
 - Text
- Loading entities from ASCII art
- Loading colour maps from images
- Loading level maps from JSON
- Optional 'pixel mode' - draw two 'pixels' to a terminal character, doubling screen height at the expense of being able to render text.
- Pure Go - easy portability of compiled games, and cross-compilation built right in.

*To see what's on the roadmap, have a look at the [issue tracker](https://github.com/JoelOtter/termloop/issues).*

## termloop/extra

The Termloop extras are a collection of types and functions, the use of which will not result in a fully portable binary - that is, they have some external dependencies. However, if you're willing to require these dependencies in your project, they should integrate quite nicely with the rest of Termloop. Some of the included examples use these extras.

- Audio playback 
 - audio.go
 - Requirements: PortAudio and libsndfile

## Cool stuff built with Termloop
 
- [Included examples](https://github.com/JoelOtter/termloop/tree/master/_examples) (@JoelOtter)
- [Number Crusher](https://github.com/aquilax/number_crusher) (@aquilax)
- [Go Tapper](https://github.com/swapagarwal/gotapper) (@swapagarwal)
- [Frame Assault](https://github.com/Ariemeth/frame_assault) (@Ariemeth)
- [Minesweeper](https://github.com/ryanbaer/minesweeper-go) (@ryanbaer)
- [Termtank](https://github.com/TerrySolar/termtank) (@TerrySolar)
- [Snake](https://github.com/mattkelly/snake-go) (@mattkelly)
- [Go Man's Sky](https://rawktron.itch.io/go-mans-sky) (@rawktron)
- [conwaygo](https://github.com/buckley-w-david/conwaygo) (@buckley-w-david)
- [Doric (a Columns clone)](https://github.com/svera/doric) (@svera)
- [Terminal-based Snake](https://github.com/tristangoossens/snake-go) (@tristangoossens)
- [Sokoban](https://github.com/tristangoossens/sokoban-go) (@tristangoossens)
- [Gopher Typer](https://github.com/ScottBrooks/gopher_typer) (@scottbrooksca)
- [Tetris](https://bitbucket.org/cam73/tetris) (@cam73)
- [Gorched](https://github.com/zladovan/gorched) (@zladovan)
- [Go Invaders](https://github.com/afagundes/go-invaders) (@afagundes)

_Feel free to add yours with a pull request!_

## Tutorial
 
> More full documentation will be added to the Wiki soon. In the meantime, check out this tutorial, the [GoDoc](http://godoc.org/github.com/JoelOtter/termloop), or the [included examples](https://github.com/JoelOtter/termloop/tree/master/_examples). If you get stuck during this tutorial, worry not, the full source is [here](https://github.com/JoelOtter/termloop/blob/master/_examples/tutorial.go).

Creating a blank Termloop game is as simple as:

```go
package main

import tl "github.com/JoelOtter/termloop"

func main() {
	game := tl.NewGame()
	game.Start()
}
```

We can press Ctrl+C to exit. It's just a blank screen - let's make it a little more interesting.

Let's make a green background, because grass is really nice to run around on. We create a new level like so:

```go
level := tl.NewBaseLevel(tl.Cell{
	Bg: tl.ColorGreen,
	Fg: tl.ColorBlack,
	Ch: 'v',
})
```

Cell is a struct that represents one cell on the terminal. We can set its background and foreground colours, and the character that is displayed. Creating a [BaseLevel](http://godoc.org/github.com/JoelOtter/termloop#BaseLevel) in this way will fill the level with this Cell.

Let's make a nice pretty lake, too. We'll use a [Rectangle](http://godoc.org/github.com/JoelOtter/termloop#Rectangle) for this. We'll put the lake at position (10, 10), with width 50 and height 20. All measurements are in terminal characters! The last argument is the colour of the Rectangle.

```go
level.AddEntity(tl.NewRectangle(10, 10, 50, 20, tl.ColorBlue))
```

We don't need to use a Level - we can add entities directly to the [Screen](http://godoc.org/github.com/JoelOtter/termloop#Screen)! This is great for building a HUD, or a very simple app. However, if we want camera scrolling or collision detection, we're going to need to use a Level.

Putting together what we have so far:

```go
package main

import tl "github.com/JoelOtter/termloop"

func main() {
	game := tl.NewGame()
	level := tl.NewBaseLevel(tl.Cell{
		Bg: tl.ColorGreen,
		Fg: tl.ColorBlack,
		Ch: 'v',
	})
	level.AddEntity(tl.NewRectangle(10, 10, 50, 20, tl.ColorBlue))
	game.Screen().SetLevel(level)
	game.Start()
}
```

When we run it with `go run tutorial.go`, it looks like this:

![](_examples/images/tutorial01.png)

Pretty! Ish. OK, let's create a character that can walk around the environment. We're going to use object composition here - we'll create a new struct type, which extends an [Entity](http://godoc.org/github.com/JoelOtter/termloop#Entity).

To have Termloop draw our new type, we need to implement the [Drawable](http://godoc.org/github.com/JoelOtter/termloop#Drawable) interface, which means we need two methods: **Draw()** and **Tick()**. The Draw method defines how our type is drawn to the [Screen](http://godoc.org/github.com/JoelOtter/termloop#Screen) (Termloop's internal drawing surface), and the Tick method defines how we handle input.

We don't need to do anything special for `Draw`, and it's already handled by `Entity`, so we just need a `Tick`:

```go
type Player struct {
	*tl.Entity
}

func (player *Player) Tick(event tl.Event) {
	if event.Type == tl.EventKey { // Is it a keyboard event?
		x, y := player.Position()
		switch event.Key { // If so, switch on the pressed key.
		case tl.KeyArrowRight:
			player.SetPosition(x+1, y)
		case tl.KeyArrowLeft:
			player.SetPosition(x-1, y)
		case tl.KeyArrowUp:
			player.SetPosition(x, y-1)
		case tl.KeyArrowDown:
			player.SetPosition(x, y+1)
		}
	}
}
```

Now that we've built our Player type, let's add one to the level. I'm going to use the character '옷', because I think it looks a bit like a stick man.

```go
player := Player{tl.NewEntity(1, 1, 1, 1)}
// Set the character at position (0, 0) on the entity.
player.SetCell(0, 0, &tl.Cell{Fg: tl.ColorRed, Ch: '옷'})
level.AddEntity(&player)

```

![](_examples/images/tutorial02.png)

Running the game again, we see that we can now move around the map using the arrow keys. Neato! However, we can stroll across the lake just as easily as the grass. Our character isn't the Messiah, ~~he's a very naughty boy,~~ so let's add some collisions.

In Termloop, we have two interfaces that are used for collisions. Here they are.

```go
// Physical represents something that can collide with another
// Physical, but cannot process its own collisions.
// Optional addition to Drawable.
type Physical interface {
	Position() (int, int) // Return position, x and y
	Size() (int, int)     // Return width and height
}

// DynamicPhysical represents something that can process its own collisions.
// Implementing this is an optional addition to Drawable.
type DynamicPhysical interface {
	Position() (int, int) // Return position, x and y
	Size() (int, int)     // Return width and height
	Collide(Physical)     // Handle collisions with another Physical
}
```

It's pretty simple - if we want our object to be 'solid', then we implement Physical. If we want a solid object that actually does some processing on its own collisions, we implement DynamicPhysical! Essentially this just involves adding one more method to your type.

Note that, for performance reasons, you should try and have as few DynamicPhysicals as possible - for example, our Player will be one, but the lake need only be a Physical.

The Rectangle type already implements Physical, so we don't actually need to do anything. As well, Player already implements DynamicPhysical because of the embedded Entity. However, we want custom behaviour for Collide, so let's implement that method. For that, we'll have to modify our struct and Tick method, to keep track of the Player's previous position so we can move it back there if it collides with something.



```go
type Player struct {
	*tl.Entity
	prevX  int
	prevY  int
}

func (player *Player) Tick(event tl.Event) {
	if event.Type == tl.EventKey { // Is it a keyboard event?
		player.prevX, player.prevY = player.Position()
		switch event.Key { // If so, switch on the pressed key.
		case tl.KeyArrowRight:
			player.SetPosition(player.prevX+1, player.prevY)
		case tl.KeyArrowLeft:
			player.SetPosition(player.prevX-1, player.prevY)
		case tl.KeyArrowUp:
			player.SetPosition(player.prevX, player.prevY-1)
		case tl.KeyArrowDown:
			player.SetPosition(player.prevX, player.prevY+1)
		}
	}
}

func (player *Player) Collide(collision tl.Physical) {
	// Check if it's a Rectangle we're colliding with
	if _, ok := collision.(*tl.Rectangle); ok {
		player.SetPosition(player.prevX, player.prevY)
	}
}

```

Not too much extra code! We can now see that the Player can't walk out into the lake. If you see the Player overlap the lake slightly on one side, that's likely because the 'stick man' character we used isn't quite standard width.

We've now got something that looks a bit like a very simple exploration game. There's one more thing to add - let's have the camera scroll to keep the Player in the centre of the screen!

There isn't really a 'camera' in Termloop, like you might find in another graphics library. Instead, we set an offset, and the Screen draws our level appropriately. In our case it's really simple - all we need is for the Player to have a pointer to the Level, so we can make calls on it. Then we simply modify our Draw method, like so:

```go
type Player struct {
	*tl.Entity
	prevX  int
	prevY  int
	level  *tl.BaseLevel
}

func (player *Player) Draw(screen *tl.Screen) {
	screenWidth, screenHeight := screen.Size()
	x, y := player.Position()
	player.level.SetOffset(screenWidth/2-x, screenHeight/2-y)
  // We need to make sure and call Draw on the underlying Entity.
	player.Entity.Draw(screen)
}


// in func main
player := Player{
	Entity:   tl.NewEntity(1, 1, 1, 1),
	level: level,
}
```

That's all it takes. We should now see the camera moving. Of course, due to the static, repeating background, this doesn't look terribly convincing - it kind of looks like the player is standing still and everything else is moving! We could remedy this by, for example, only updating the offset when the player is closer to the edge of the screen. I'll leave it up to you as a challenge.

![](_examples/images/tutorial03.png)

We've now reached the end of our tutorial - I hope it's been useful! If you'd like to learn a little more about Termloop, more comprehensive documentation is coming on the Wiki. In the meantime, you can check out the [GoDoc](http://godoc.org/github.com/JoelOtter/termloop), or the [included examples](https://github.com/JoelOtter/termloop/tree/master/_examples). I'll be hanging out on the [Gitter](https://gitter.im/JoelOtter/termloop) too, if you have any questions. Have fun, and please do show me if you make something cool!


termloop

Data-oriented and cache-friendly 2D Grid library (TileMap), includes pathfinding, observers and import/export

# Tile: Data-Oriented 2D Grid Engine


 <img width="200" height="100" src="./.github/logo.png">
 
 <img src="https://img.shields.io/github/go-mod/go-version/kelindar/tile" alt="Go Version">
 <a href="https://pkg.go.dev/github.com/kelindar/tile"><img src="https://pkg.go.dev/badge/github.com/kelindar/tile" alt="PkgGoDev"></a>
 <a href="https://goreportcard.com/report/github.com/kelindar/tile"><img src="https://goreportcard.com/badge/github.com/kelindar/tile" alt="Go Report Card"></a>
 <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
 <a href="https://coveralls.io/github/kelindar/tile"><img src="https://coveralls.io/repos/github/kelindar/tile/badge.svg" alt="Coverage"></a>


This repository contains a 2D tile map engine which is built with data and cache friendly ways. My main goal here is to provide a simple, high performance library to handle large scale tile maps in games.

- **Compact**. Each tile value is 4 bytes long and each grid page is 64-bytes long, which means a grid of 3000x3000 should take around 64MB of memory.
- **Thread-safe**. The grid is thread-safe and can be updated through provided update function. This allows multiple goroutines to read/write to the grid concurrently without any contentions. There is a spinlock per tile page protecting tile access.
- **Views & observers**. When a tile on the grid is updated, viewers of the tile will be notified of the update and can react to the changes. The idea is to allow you to build more complex, reactive systems on top of the grid.
- **Zero-allocation** (or close to it) traversal of the grid. The grid is pre-allocated entirely and this library provides a few ways of traversing it.
- **Path-finding**. The library provides a A\* pathfinding algorithm in order to compute a path between two points, as well as a BFS-based position scanning which searches the map around a point.

_Disclaimer_: the API or the library is not final and likely to change. Also, since this is just a side project of mine, don't expect this to be updated very often but please contribute!

# Grid & Tiles

The main entry in this library is `Grid` which represents, as the name implies a 2 dimentional grid which is the container of `Tile` structs. The `Tile` is essentially a cursor to a particular x,y coordinate and contains the following

- Value `uint32` of the tile, that can be used for calculating navigation or quickly retrieve sprite index.
- State set of `T comparable` that can be used to add additional information such as objects present on the tile. These things cannot be used for pathfinding, but can be used as an index.

Granted, uint32 value a bit small. The reason for this is the data layout, which is organised in thread-safe pages of 3x3 tiles, with the total size of 64 bytes which should neatly fit onto a cache line of a CPU.

In order to create a new `Grid[T]`, you first need to call `NewGridOf[T]()` method which pre-allocates the required space and initializes the tile grid itself. For example, you can create a 1000x1000 grid as shown below. The type argument `T` sets the type of the state objects. In the example below we want to create a new grid with a set of strings.

```go
grid := tile.NewGridOf[string](1000, 1000)
```

The `Each()` method of the grid allows you to iterate through all of the tiles in the grid. It takes an iterator function which is then invoked on every tile.

```go
grid.Each(func(p Point, t tile.Tile[string]) {
 // ...
})
```

The `Within()` method of the grid allows you to iterate through a set of tiles within a bounding box, specified by the top-left and bottom-right points. It also takes an iterator function which is then invoked on every tile matching the filter.

```go
grid.Within(At(1, 1), At(5, 5), func(p Point, t tile.Tile[string]) {
 // ...
})
```

The `At()` method of the grid allows you to retrieve a tile at a specific `x,y` coordinate. It simply returns the tile and whether it was found in the grid or not.

```go
if tile, ok := grid.At(50, 100); ok {
 // ...
}
```

The `WriteAt()` method of the grid allows you to update a tile at a specific `x,y` coordinate. Since the `Grid` itself is thread-safe, this is the way to (a) make sure the tile update/read is not racing and (b) notify observers of a tile update (more about this below).

```go
grid.WriteAt(50, 100, tile.Value(0xFF))
```

The `Neighbors()` method of the grid allows you to get the direct neighbors at a particular `x,y` coordinate and it takes an iterator funcion which is called for each neighbor. In this implementation, we are only taking direct neighbors (top, left, bottom, right). You rarely will need to use this method, unless you are rolling out your own pathfinding algorithm.

```go
grid.Neighbors(50, 100, func(point tile.Point, t tile.Tile[string]) {
 // ...
})
```

The `MergeAt()` method of the grid allows you to atomically update a value given a current value of the tile. For example, if we want to increment the value of a tile we can call this method with a function that increments the value. Under the hood, the increment will be done using an atomic compare-and-swap operation.

```go
grid.MergeAt(50, 100, func(v Value) Value {
 v += 1
 return v
})
```

The `MaskAt()` method of the grid allows you to atomically update only some of the bits at a particular `x,y` coordinate. This operation is as well thread-safe, and is actually useful when you might have multiple goroutines updating a set of tiles, but various goroutines are responsible for the various parts of the tile data. You might have a system that updates only a first couple of tile flags and another system updates some other bits. By using this method, two goroutines can update the different bits of the same tile concurrently, without erasing each other's results, which would happen if you just call `WriteAt()`.

```go
// assume byte[0] of the tile is 0b01010001
grid.MaskAt(50, 100,
 0b00101110, // Only last 2 bits matter
 0b00000011 // Mask specifies that we want to update last 2 bits
)

// If the original is currently: 0b01010001
// ...the result result will be: 0b01010010
```

# Pathfinding

As mentioned in the introduction, this library provides a few grid search / pathfinding functions as well. They are implemented as methods on the same `Grid` structure as the rest of the functionnality. The main difference is that they may require some allocations (I'll try to minimize it further in the future), and require a cost function `func(Tile) uint16` which returns a "cost" of traversing a specific tile. For example if the tile is a "swamp" in your game, it may cost higher than moving on a "plain" tile. If the cost function returns `0`, the tile is then considered to be an impassable obstacle, which is a good choice for walls and such.

The `Path()` method is used for finding a way between 2 points, you provide it the from/to point as well as costing function and it returns the path, calculated cost and whether a path was found or not. Note of caution however, avoid running it between 2 points if no path exists, since it might need to scan the entire map to figure that out with the current implementation.

```go
from := At(1, 1)
goal := At(7, 7)
path, distance, found := m.Path(from, goal, func(v tile.Value) uint16{
 if isImpassable(v) {
 return 0
 }
 return 1
})
```

The `Around()` method provides you with the ability to do a breadth-first search around a point, by providing a limit distance for the search as well as a cost function and an iterator. This is a handy way of finding things that are around the player in your game.

```go
point := At(50, 50)
radius := 5
m.Around(point, radius, func(v tile.Value) uint16{
 if isImpassable(v) {
 return 0
 }
 return 1
}, func(p tile.Point, t tile.Tile[string]) {
 // ... tile found
})
```

# Observers

Given that the `Grid` is mutable and you can make changes to it from various goroutines, I have implemented a way to "observe" tile changes through a `NewView()` method which creates an `Observer` and can be used to observe changes within a bounding box. For example, you might want your player to have a view port and be notified if something changes on the map so you can do something about it.

In order to use these observers, you need to first call the `NewView()` function and start polling from the `Inbox` channel which will contain the tile update notifications as they happen. This channel has a small buffer, but if not read it will block the update, so make sure you always poll everything from it. Note that `NewView[S, T]` takes two type parameters, the first one is the type of the state object and the second one is the type of the tile value. The state object is used to store additional information about the view itself, such as the name of the view or a pointer to a socket that is used to send updates to the client.

In the example below we create a new 20x20 view on the grid and iterate through all of the tiles in the view.

```go
view := tile.NewView[string, string](grid, "My View #1")
view.Resize(tile.NewRect(0, 0, 20, 20), func(p tile.Point, t tile.Tile){
 // Optional, all of the tiles that are in the view now
})

// Poll the inbox (in reality this would need to be with a select, and a goroutine)
for {
 update := <-view.Inbox
 // Do something with update.Point, update.Tile
}
```

The `MoveBy()` method allows you to move the view in a specific direction. It takes in a `x,y` vector but it can contain negative values. In the example below, we move the view upwards by 5 tiles. In addition, we can also provide an iterator and do something with all of the tiles that have entered the view (e.g. show them to the player).

```go
view.MoveBy(0, 5, func(p tile.Point, tile tile.Tile){
 // Every tile which entered our view
})
```

Similarly, `MoveAt()` method allows you to move the view at a specific location provided by the coordinates. The size of the view stays the same and the iterator will be called for all of the new tiles that have entered the view port.

```go
view.MoveAt(At(10, 10), func(p tile.Point, t tile.Tile){
 // Every tile which entered our view
})
```

The `Resize()` method allows you to resize and update the view port. As usual, the iterator will be called for all of the new tiles that have entered the view port.

```go
viewRect := tile.NewRect(10, 10, 30, 30)
view.Resize(viewRect, func(p tile.Point, t tile.Tile){
 // Every tile which entered our view
})
```

The `Close()` method should be called when you are done with the view, since it unsubscribes all of the notifications. Be careful, if you do not close the view when you are done with it, it will lead to memory leaks since it will continue to observe the grid and receive notifications.

```go
// Unsubscribe from notifications and close the view
view.Close()
```

# Save & Load

The library also provides a way to save the `Grid` to an `io.Writer` and load it from an `io.Reader` by using `WriteTo()` method and `ReadFrom()` function. Keep in mind that the save/load mechanism does not do any compression, but in practice you should [use to a compressor](https://github.com/klauspost/compress) if you want your maps to not take too much of the disk space - snappy is a good option for this since it's fast and compresses relatively well.

The `WriteTo()` method of the grid only requires a specific `io.Writer` to be passed and returns a number of bytes that have been written down to it as well if any specific error has occured. Below is an example of how to save the grid into a compressed buffer.

```go
// Prepare the output buffer and compressor
output := new(bytes.Buffer)
writer, err := flate.NewWriter(output, flate.BestSpeed)
if err != nil {
 // ...
}

defer writer.Close() // Make sure we flush the compressor
_, err := grid.WriteTo(writer) // Write the grid
if err != nil {
 // ...
}
```

The `ReadFrom()` function allows you to read the `Grid` from a particular reader. To complement the example above, the one below shows how to read a compressed grid using this function.

```go
// Prepare a compressed reader over the buffer
reader := flate.NewReader(output)

// Read the Grid
grid, err := ReadFrom(reader)
if err != nil{
 // ...
}
```

# Benchmarks

This library contains quite a bit of various micro-benchmarks to make sure that everything stays pretty fast. Feel free to clone and play around with them yourself. Below are the benchmarks which we have, most of them are running on relatively large grids.

```
cpu: Intel(R) Core(TM) i7-9700K CPU @ 3.60GHz
BenchmarkGrid/each-8 868 1358434 ns/op 0 B/op 0 allocs/op
BenchmarkGrid/neighbors-8 66551679 17.87 ns/op 0 B/op 0 allocs/op
BenchmarkGrid/within-8 27207 44753 ns/op 0 B/op 0 allocs/op
BenchmarkGrid/at-8 399067512 2.994 ns/op 0 B/op 0 allocs/op
BenchmarkGrid/write-8 130207965 9.294 ns/op 0 B/op 0 allocs/op
BenchmarkGrid/merge-8 124156794 9.663 ns/op 0 B/op 0 allocs/op
BenchmarkGrid/mask-8 100000000 10.67 ns/op 0 B/op 0 allocs/op
BenchmarkState/range-8 12106854 98.91 ns/op 0 B/op 0 allocs/op
BenchmarkState/add-8 48827727 25.43 ns/op 0 B/op 0 allocs/op
BenchmarkState/del-8 52110474 21.59 ns/op 0 B/op 0 allocs/op
BenchmarkPath/9x9-8 264586 4656 ns/op 16460 B/op 3 allocs/op
BenchmarkPath/300x300-8 601 1937662 ns/op 7801502 B/op 4 allocs/op
BenchmarkPath/381x381-8 363 3304134 ns/op 62394356 B/op 5 allocs/op
BenchmarkPath/384x384-8 171 7165777 ns/op 62394400 B/op 5 allocs/op
BenchmarkPath/3069x3069-8 31 36479106 ns/op 124836075 B/op 4 allocs/op
BenchmarkPath/3072x3072-8 30 34889740 ns/op 124837686 B/op 4 allocs/op
BenchmarkPath/6144x6144-8 142 7594013 ns/op 62395376 B/op 3 allocs/op
BenchmarkAround/3r-8 506857 2384 ns/op 385 B/op 1 allocs/op
BenchmarkAround/5r-8 214280 5539 ns/op 922 B/op 2 allocs/op
BenchmarkAround/10r-8 85723 14017 ns/op 3481 B/op 2 allocs/op
BenchmarkPoint/within-8 1000000000 0.2190 ns/op 0 B/op 0 allocs/op
BenchmarkPoint/within-rect-8 1000000000 0.2195 ns/op 0 B/op 0 allocs/op
BenchmarkStore/save-8 14577 82510 ns/op 8 B/op 1 allocs/op
BenchmarkStore/read-8 3199 364771 ns/op 647419 B/op 7 allocs/op
BenchmarkView/write-8 6285351 188.2 ns/op 48 B/op 1 allocs/op
BenchmarkView/move-8 10000 116953 ns/op 0 B/op 0 allocs/op
```

# Contributing

We are open to contributions, feel free to submit a pull request and we'll review it as quickly as we can. This library is maintained by [Roman Atachiants](https://www.linkedin.com/in/atachiants/)

## License

Tile is licensed under the [MIT License](LICENSE.md).

tile

Scalable game server framework with clustering support and client libraries for iOS, Android, Unity and others through the C SDK

# pitaya [![Build Status][7]][8] [![Coverage Status][9]][10] [![GoDoc][1]][2] [![Docs][11]][12] [![Go Report Card][3]][4] [![MIT licensed][5]][6]

---

[1]: https://godoc.org/github.com/topfreegames/pitaya?status.svg
[2]: https://godoc.org/github.com/topfreegames/pitaya
[3]: https://goreportcard.com/badge/github.com/topfreegames/pitaya
[4]: https://goreportcard.com/report/github.com/topfreegames/pitaya
[5]: https://img.shields.io/badge/license-MIT-blue.svg
[6]: LICENSE
[7]: https://github.com/topfreegames/pitaya/actions/workflows/tests.yaml/badge.svg
[8]: https://github.com/topfreegames/pitaya/actions/workflows/tests.yaml
[9]: https://coveralls.io/repos/github/topfreegames/pitaya/badge.svg?branch=master
[10]: https://coveralls.io/github/topfreegames/pitaya?branch=master
[11]: https://readthedocs.org/projects/pitaya/badge/?version=latest
[12]: https://pitaya.readthedocs.io/en/latest/?badge=latest

Pitaya is an simple, fast and lightweight game server framework with clustering support and client libraries for iOS, Android, Unity and others through the [C SDK](https://github.com/topfreegames/libpitaya).
It provides a basic development framework for distributed multiplayer games and server-side applications.

## Getting Started

### Prerequisites

* [Go](https://golang.org/) >= 1.16
* [etcd](https://github.com/coreos/etcd) (optional, used for service discovery)
* [nats](https://github.com/nats-io/nats.go) (optional, used for sending and receiving rpc)
* [docker](https://www.docker.com) (optional, used for running etcd and nats dependencies on containers)

### Installing
clone the repo
```
git clone https://github.com/topfreegames/pitaya.git
```
setup pitaya dependencies
```
make setup
```

### Hacking pitaya

Here's one example of running Pitaya:

Start etcd (This command requires docker-compose and will run an etcd container locally. An etcd may be run without docker if preferred.)
```
cd ./examples/testing && docker compose up -d etcd
```
run the connector frontend server from cluster_grpc example
```
make run-cluster-grpc-example-connector
```
run the room backend server from the cluster_grpc example
```
make run-cluster-grpc-example-room
```

Now there should be 2 pitaya servers running, a frontend connector and a backend room. To send requests, use a REPL client for pitaya [pitaya-cli](https://github.com/topfreegames/pitaya/tree/main/pitaya-cli).

```
$ pitaya-cli
Pitaya REPL Client
>>> connect localhost:3250
connected!
>>> request room.room.entry
>>> sv-> {"code":0,"result":"ok"}
```

## Running the tests
```
make test
```
This command will run both unit and e2e tests.

## Contributing
#TODO

## Authors
* **TFG Co** - Initial work

## License
[MIT License](./LICENSE)

## Acknowledgements
* [nano](https://github.com/lonnng/nano) authors for building the framework pitaya is based on.
* [pomelo](https://github.com/NetEase/pomelo) authors for the inspiration on the distributed design and protocol

## Security
If you have found a security vulnerability, please email security@tfgco.com

## Resources
- Other pitaya-related projects
  + [libpitaya-cluster](https://github.com/topfreegames/libpitaya-cluster)
  + [libpitaya](https://github.com/topfreegames/libpitaya)
  + [pitaya-admin](https://github.com/topfreegames/pitaya-admin)
  + [pitaya-bot](https://github.com/topfreegames/pitaya-bot)
  + [pitaya-cli](https://github.com/topfreegames/pitaya/tree/main/pitaya-cli)
  + [pitaya-protos](https://github.com/topfreegames/pitaya-protos)

- Documents
  + [API Reference](https://godoc.org/github.com/topfreegames/pitaya)
  + [In-depth documentation](https://pitaya.readthedocs.io/en/latest/)

- Demo
  + [Implement a chat room in ~100 lines with pitaya and WebSocket](./examples/demo/chat) (adapted from [nano](https://github.com/lonnng/nano)'s example)
  + [Pitaya cluster mode example](./examples/demo/cluster)
  + [Pitaya cluster mode with protobuf protocol example](./examples/demo/cluster_protobuf)


Pitaya

Cross-platform (Windows/Linux/Mac) library for creating desktop games using a minimal API

# prototype

Simply prototype 2D games using an easy, minimal interface that lets you draw
simple primitives and images on the screen, easily handle mouse and keyboard
events, and play sounds.

![Games](https://github.com/gonutz/prototype/blob/master/samples/screenshots/games.png)

## Installation

Install the [Go programming language](https://golang.org/dl/). After clicking
the download link you will be referred to the installation instructions for your
specific operating system.

Install [Git](https://git-scm.com/downloads) and make it available in the PATH
so the Go tool can use it.

For Linux and macOS, you need a C compiler installed. On Windows this is not
necessary.

### Supported Targets

The prototype framework supports multiple targets:

#### Windows (default)

- Uses Direct3D 9
- No additional dependencies needed

#### Linux/macOS (GLFW backend)

- Uses OpenGL via GLFW
- Install required packages (example for Ubuntu/Debian):
 ```sh
 sudo apt install libx11-dev libxrandr-dev libgl1-mesa-dev libxcursor-dev libxinerama-dev libxi-dev
 ```

#### WebAssembly (experimental)

To build and run a WASM version of your game, you can use the `drawsm` tool.
Install it with

	go install github.com/gonutz/prototype/cmd/drawsm@latest

It allows you to run your game locally from within your project directory with

	drawsm run

or build it into the project directory with

	drawsm build

## Installation (Library & Samples)

## Documentation

For a description of all library functions, see [the package doc
page](https://pkg.go.dev/github.com/gonutz/prototype/draw). Most functionality
is in the `Window` interface, and documented via code comments.

## Example

```go
package main

import (
	"math"

	"github.com/gonutz/prototype/draw"
)

func main() {
	draw.RunWindow("Title", 640, 480, update)
}

func update(window draw.Window) {
	w, h := window.Size()
	centerX, centerY := w/2, h/2

	mouseX, mouseY := window.MousePosition()
	mouseInCircle := math.Hypot(float64(mouseX-centerX), float64(mouseY-centerY)) < 20
	color := draw.DarkRed
	if mouseInCircle {
		color = draw.Red
	}
	window.FillEllipse(centerX-20, centerY-20, 40, 40, color)
	window.DrawEllipse(centerX-20, centerY-20, 40, 40, draw.White)
	if mouseInCircle {
		window.DrawScaledText("Close!", centerX-40, centerY+25, 1.6, draw.Green)
	}

	for _, click := range window.Clicks() {
		dx, dy := click.X-centerX, click.Y-centerY
		if dx*dx+dy*dy <= 20*20 {
			window.Close()
		}
	}
}
```

This example displays a window with a round button in the middle to close it. It demonstrates basic drawing and event handling.

prototype

# \*\*\*\*\*NOTICE\*\*\*\*\* 

This repo is not under active development anymore and has been archived. Continued development has been migrated to [Pixel2](https://github.com/gopxl/pixel). A big thank you to [faiface](https://github.com/faiface) for creating this awesome library and for all the hard work put into it. We encourage old and new users to check out the new repo and contribute to it.



<img src="logo/LOGOTYPE-HORIZONTAL-BLUE.png">

# Pixel [![Build Status](https://travis-ci.org/faiface/pixel.svg?branch=master)](https://travis-ci.org/faiface/pixel) [![GoDoc](https://godoc.org/github.com/faiface/pixel?status.svg)](https://godoc.org/github.com/faiface/pixel) [![Go Report Card](https://goreportcard.com/badge/github.com/faiface/pixel)](https://goreportcard.com/report/github.com/faiface/pixel) [![Join the chat at https://gitter.im/pixellib/Lobby](https://badges.gitter.im/pixellib/Lobby.svg)](https://gitter.im/pixellib/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Discord Chat](https://img.shields.io/discord/699679031603494954)](https://discord.gg/q2DK4MP) 

A hand-crafted 2D game library in Go. Take a look into the [features](#features) to see what it can
do.

```
go get github.com/faiface/pixel
```

If you are using Modules (Go 1.11 or higher) and want a mutable copy of the source code:

```
git clone https://github.com/faiface/pixel # clone outside of $GOPATH
cd pixel
go install ./...
```

See [requirements](#requirements) for the list of libraries necessary for compilation.

All significant changes are documented in [CHANGELOG.md](CHANGELOG.md).

## Tutorial

The [Wiki of this repo](https://github.com/faiface/pixel/wiki) contains an extensive tutorial
covering several topics of Pixel. Here's the content of the tutorial parts so far:

- [Creating a Window](https://github.com/faiface/pixel/wiki/Creating-a-Window)
- [Drawing a Sprite](https://github.com/faiface/pixel/wiki/Drawing-a-Sprite)
- [Moving, scaling and rotating with Matrix](https://github.com/faiface/pixel/wiki/Moving,-scaling-and-rotating-with-Matrix)
- [Pressing keys and clicking mouse](https://github.com/faiface/pixel/wiki/Pressing-keys-and-clicking-mouse)
- [Drawing efficiently with Batch](https://github.com/faiface/pixel/wiki/Drawing-efficiently-with-Batch)
- [Drawing shapes with IMDraw](https://github.com/faiface/pixel/wiki/Drawing-shapes-with-IMDraw)
- [Typing text on the screen](https://github.com/faiface/pixel/wiki/Typing-text-on-the-screen)
- [Using a custom fragment shader](https://github.com/faiface/pixel/wiki/Using-a-custom-fragment-shader)

## [Examples](https://github.com/faiface/pixel-examples)

The [examples](https://github.com/faiface/pixel-examples) repository contains a few
examples demonstrating Pixel's functionality.

**To run an example**, navigate to it's directory, then `go run` the `main.go` file. For example:

```
$ cd pixel-examples/platformer
$ go run main.go
```

Here are some screenshots from the examples!

| [Lights](https://github.com/faiface/pixel-examples/blob/master/lights) | [Platformer](https://github.com/faiface/pixel-examples/blob/master/platformer) |
| --- | --- |
| ![Lights](https://github.com/faiface/pixel-examples/blob/master/lights/screenshot.png) | ![Platformer](https://github.com/faiface/pixel-examples/blob/master/platformer/screenshot.png) |

| [Smoke](https://github.com/faiface/pixel-examples/blob/master/smoke) | [Typewriter](https://github.com/faiface/pixel-examples/blob/master/typewriter) |
| --- | --- |
| ![Smoke](https://github.com/faiface/pixel-examples/blob/master/smoke/screenshot.png) | ![Typewriter](https://github.com/faiface/pixel-examples/blob/master/typewriter/screenshot.png) |

| [Raycaster](https://github.com/faiface/pixel-examples/blob/master/community/raycaster) | [Gizmo](https://github.com/Lallassu/gizmo) |
| --- | --- |
| ![Raycaster](https://github.com/faiface/pixel-examples/blob/master/community/raycaster/screenshot.png) | ![Gizmo](https://github.com/Lallassu/gizmo/blob/master/preview.png) |

## Features

Here's the list of the main features in Pixel. Although Pixel is still under heavy development,
**there should be no major breakage in the API.** This is not a 100% guarantee, though.

- Fast 2D graphics
 - Sprites
 - Primitive shapes with immediate mode style
 [IMDraw](https://github.com/faiface/pixel/wiki/Drawing-shapes-with-IMDraw) (circles, rectangles,
 lines, ...)
 - Optimized drawing with [Batch](https://github.com/faiface/pixel/wiki/Drawing-efficiently-with-Batch)
 - Text drawing with [text](https://godoc.org/github.com/faiface/pixel/text) package
- Audio through a separate [Beep](https://github.com/faiface/beep) library.
- Simple and convenient API
 - Drawing a sprite to a window is as simple as `sprite.Draw(window, matrix)`
 - Wanna know where the center of a window is? `window.Bounds().Center()`
 - [...](https://godoc.org/github.com/faiface/pixel)
- Full documentation and tutorial
- Works on Linux, macOS and Windows
- Window creation and manipulation (resizing, fullscreen, multiple windows, ...)
- Keyboard (key presses, text input) and mouse input without events
- Well integrated with the Go standard library
 - Use `"image"` package for loading pictures
 - Use `"time"` package for measuring delta time and FPS
 - Use `"image/color"` for colors, or use Pixel's own `color.Color` format, which supports easy
 multiplication and a few more features
 - Pixel uses `float64` throughout the library, compatible with `"math"` package
- Geometry transformations with
 [Matrix](https://github.com/faiface/pixel/wiki/Moving,-scaling-and-rotating-with-Matrix)
 - Moving, scaling, rotating
 - Easy camera implementation
- Off-screen drawing to Canvas or any other target (Batch, IMDraw, ...)
- Fully garbage collected, no `Close` or `Dispose` methods
- Full [Porter-Duff](http://ssp.impulsetrain.com/porterduff.html) composition, which enables
 - 2D lighting
 - Cutting holes into objects
 - Much more...
- Pixel let's you draw stuff and do your job, it doesn't impose any particular style or paradigm
- Platform and backend independent [core](https://godoc.org/github.com/faiface/pixel)
- Core Target/Triangles/Picture pattern makes it easy to create new drawing targets that do
 arbitrarily crazy stuff (e.g. graphical effects)
- Small codebase, ~5K lines of code, including the backend [glhf](https://github.com/faiface/glhf)
 package

 ## Related repositories

 Here are some packages which use Pixel:
 - [TilePix](https://github.com/bcvery1/tilepix) Makes handling TMX files built with [Tiled](https://www.mapeditor.org/) trivially easy to work with using Pixel.
 - [spriteplus](https://github.com/cebarks/spriteplus) Basic `SpriteSheet` and `Animation` implementations
 - [PixelUI](https://github.com/dusk125/pixelui) Imgui-based GUIs for Pixel
 - [pixelutils](https://github.com/dusk125/pixelutils) Variety of game related utilities (sprite packer, id generator, ticker, sprite loader, voronoia diagrams)

## Missing features

Pixel is in development and still missing few critical features. Here're the most critical ones.

- ~~Audio~~
- ~~Drawing text~~
- Antialiasing (filtering is supported, though)
- ~~Advanced window manipulation (cursor hiding, window icon, ...)~~
- Better support for Hi-DPI displays
- Mobile (and perhaps HTML5?) backend
- ~~More advanced graphical effects (e.g. blur)~~ (solved with the addition of GLSL effects)
- Tests and benchmarks
- Vulkan support

**Implementing these features will get us to the 1.0 release.** Contribute, so that it's as soon as
possible!

## Requirements

If you're using Windows and having trouble building Pixel, please check [this
guide](https://github.com/faiface/pixel/wiki/Building-Pixel-on-Windows) on the
[wiki](https://github.com/faiface/pixel/wiki).

[PixelGL](https://godoc.org/github.com/faiface/pixel/pixelgl) backend uses OpenGL to render
graphics. Because of that, OpenGL development libraries are needed for compilation. The dependencies
are same as for [GLFW](https://github.com/go-gl/glfw).

The OpenGL version used is **OpenGL 3.3**.

- On macOS, you need Xcode or Command Line Tools for Xcode (`xcode-select --install`) for required
 headers and libraries.
- On Ubuntu/Debian-like Linux distributions, you need `libgl1-mesa-dev` and `xorg-dev` packages.
- On CentOS/Fedora-like Linux distributions, you need `libX11-devel libXcursor-devel libXrandr-devel
 libXinerama-devel mesa-libGL-devel libXi-devel libXxf86vm-devel` packages.
- See [here](http://www.glfw.org/docs/latest/compile.html#compile_deps) for full details.

**The combination of Go 1.8, macOS and latest XCode seems to be problematic** as mentioned in issue
[#7](https://github.com/faiface/pixel/issues/7). This issue is probably not related to Pixel.
**Upgrading to Go 1.8.1 fixes the issue.**

## Contributing

Join us in the [Discord Chat!](https://discord.gg/q2DK4MP)

Pixel is in, let's say, mid-stage of development. Many of the important features are here, some are
missing. That's why **contributions are very important and welcome!** All alone, I will be able to
finish the library, but it'll take a lot of time. With your help, it'll take much less. I encourage
everyone to contribute, even with just an idea. Especially welcome are **issues** and **pull
requests**.

**However, I won't accept everything. Pixel is being developed with thought and care.** Each
component was designed and re-designed multiple times. Code and API quality is very important here.
API is focused on simplicity and expressiveness.

When contributing, keep these goals in mind. It doesn't mean that I'll only accept perfect pull
requests. It just means that I might not like your idea. Or that your pull requests could need some
rewriting. That's perfectly fine, don't let it put you off. In the end, we'll just end up with a
better result.

Take a look at [CONTRIBUTING.md](CONTRIBUTING.md) for further information.

## License

[MIT](LICENSE)

Pixel

Engo is an open-source 2D game engine written in Go. It follows the Entity-Component-System paradigm

# Engo
[![GoDoc](https://godoc.org/github.com/EngoEngine/engo?status.svg)](https://godoc.org/github.com/EngoEngine/engo)
[![Join the chat at https://gitter.im/EngoEngine/engo](https://badges.gitter.im/EngoEngine/engo.svg)](https://gitter.im/EngoEngine/engo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ![License](https://img.shields.io/badge/License-MIT-blue.svg)
[![Build Status](https://travis-ci.org/EngoEngine/engo.svg?branch=master)](https://travis-ci.org/EngoEngine/engo)
[![Build status](https://ci.appveyor.com/api/projects/status/019qc8hncmhnje83?svg=true)](https://ci.appveyor.com/project/otraore/engo)
[![Go Report Card](https://goreportcard.com/badge/github.com/EngoEngine/engo)](https://goreportcard.com/report/github.com/EngoEngine/engo)
[![Coverage Status](https://coveralls.io/repos/github/EngoEngine/engo/badge.svg?branch=master)](https://coveralls.io/github/EngoEngine/engo?branch=master)

A cross-platform game engine written in Go following an interpretation of the Entity Component System paradigm. Engo is
currently compilable for Mac OSX, Linux and Windows. With the release of Go 1.4, supporting Android and the inception of
iOS compatibility, mobile has been be added as a release target. Web support
([wasm](https://github.com/golang/go/wiki/WebAssembly)) is also available.

v1.0 is now available! To celebrate, there will be a game jam coming soon to celebrate the release, start actually
building things and hopefully find any issues. Updates for this will come soon.

## Getting in touch / Contributing

We have a [gitter](https://gitter.im/EngoEngine/engo) chat for people to join who want to further discuss `engo`. We are happy to discuss bugs, feature requests and would love to hear about the projects you are building!

## Getting Started

### Theory: `common` vs `engo`

There are currently two major important packages within this repository: `github.com/EngoEngine/engo` and `github.com/EngoEngine/engo/common`.

The top level `engo` package contains the functionality of creating windows, starting the game, creating an OpenGL
context and handling input. It is designed to be used with Systems designed as per `github.com/EngoEngine/ecs` specifications.
The `common` package contains our ECS implementations of common game development Systems like a  `RenderSystem` or
`CameraSystem`.

### Practice: Getting it to Run

1. First, you have to install some dependencies:
  1. If you're running on Debian/Ubuntu:
    `sudo apt-get install libasound2-dev libglu1-mesa-dev freeglut3-dev mesa-common-dev xorg-dev libgl1-mesa-dev git-all`
  2. If you're running on Windows you'll need a gcc compiler that the go tool can use and have `gcc.exe` in your PATH environmental variable. We recommend [Mingw](http://mingw-w64.org/doku.php/start) since it has been tested. You'll also need git installed, we recommend getting it from [The official Git site](http://git-scm.com/download/win)
  3. If you're on OSX, you will also need Git. You can find instructions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Mac). You can also use homebrew to install git as well. [Open an issue if you have any issues](https://github.com/EngoEngine/engo/issues/new)
2. Then, you can go get it:
`go get -u github.com/EngoEngine/engo`
  1. You may also want to get the dependencies of platform specific builds, so that build tools like godef can use them:
  `go get -u -tags js ./...`
  `go get -u -tags android ./...`
3. Now, you have two choices:
  1. Visit [our website](https://engoengine.github.io/), which hosts a full-blown tutorial series on how to create your own game, and on top of that, has some conceptual explanations;
  2. Check out some demos in our [demos folder](https://github.com/EngoEngine/engo/tree/master/demos).
4. Finally, if you run into problems, if you've encountered a bug, or want to request a feature, feel free to shoot
us a DM or [create an issue](https://github.com/EngoEngine/engo/issues/new).

## Breaking Changes Since v1.0
Engo is always undergoing a lot of optimizations and constantly gets new features. However, this sometimes means things break. In order to make transitioning easier for you,
we have a list of those changes, with the most recent being at the top. If you run into any problems, please contact us at [gitter](https://gitter.im/EngoEngine/engo).

* TMXObject Width and Height is in pixels, and can be fractional. This has changed from an int to a float64.
* TMXTileset now uses a Spritesheet instead of a Texture. This helps keep track of the guid better and allows the gid to not start at zero and have skips in it, as well as for borders and spacing in the tile sheet.
* TMX Level's objects have all been rolled into Object rather than have separate things like "PolyLineObject". This is to be
consistent with the TMX format.
* The Shader interface now has a `SetCamera(*CameraSystem)` method. This method allows shaders to automatically update the camera system as it changes, such as between scenes or when the camera system is added.
* The domain engo.io has expired. Now use `github.com/EngoEngine/engo` as the import path, and the site can be located at
engoengine.github.io

## Roadmap to v1.1
A list of issues for v1.1 can be found [here](https://github.com/EngoEngine/engo/issues/552). There's always room
for improvement! Feel free to submit proposals, open issues, and let us know how we can improve!

## History

Engo, originally known as `Engi` was written by [ajhager](https://github.com/ajhager) as a general purpose Go game engine. With a desire to build it into an "ECS" game engine, it was forked to `github.com/paked/engi`. After passing through several iterations, it was decided that the project would be rebranded and rereleased as Engo on its own GitHub organization.

## Credits

Thank you to everyone who has worked on, or with `Engo`. None of this would be possible without you, and your help has been truly amazing.

- [ajhager](https://github.com/ajhager): Building the original `engi`, which engo was based off of
- [paked](https://github.com/paked): Adding ECS element, project maintenance and management
- [Newbrict](https://github.com/Newbrict): Font rendering, TMX support
- [EtienneBruines](https://github.com/EtienneBruines): Rewriting the OpenGL code, maintenance and helping redesign the API
- [otraore](https://github.com/otraore): Adding in GopherJS support, maintenance
- [Everyone else who has submitted PRs or issues over the years, to any iteration of the project](https://github.com/EngoEngine/engo/graphs/contributors)

These are 3rd party projects that have made `engo` possible.
- The original [engi](https://github.com/ajhager/engi) game engine which engo was based off of ([BSD license](https://github.com/ajhager/engi/blob/master/LICENSE))
- [Oto](https://github.com/hajimehoshi/oto), a low-level cross-platform library to play sound. The AudioSystem uses this and is based on
the audio package used in [Ebiten](https://github.com/hajimehoshi/ebiten).


engo

[![PkgGoDev](https://pkg.go.dev/badge/github.com/s0rg/fantasyname)](https://pkg.go.dev/github.com/s0rg/fantasyname)
[![License](https://img.shields.io/github/license/s0rg/fantasyname)](https://github.com/s0rg/fantasyname/blob/main/LICENSE)
[![Go Version](https://img.shields.io/github/go-mod/go-version/s0rg/fantasyname)](go.mod)
[![Tag](https://img.shields.io/github/v/tag/s0rg/fantasyname?sort=semver)](https://github.com/s0rg/fantasyname/tags)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

[![CI](https://github.com/s0rg/fantasyname/workflows/ci/badge.svg)](https://github.com/s0rg/fantasyname/actions?query=workflow%3Aci)
[![Go Report Card](https://goreportcard.com/badge/github.com/s0rg/fantasyname)](https://goreportcard.com/report/github.com/s0rg/fantasyname)
[![Maintainability](https://qlty.sh/badges/09a35bec-e65e-4587-a845-4ba6982fd69f/maintainability.svg)](https://qlty.sh/gh/s0rg/projects/fantasyname)
[![Code Coverage](https://qlty.sh/badges/09a35bec-e65e-4587-a845-4ba6982fd69f/test_coverage.svg)](https://qlty.sh/gh/s0rg/projects/fantasyname)
![Issues](https://img.shields.io/github/issues/s0rg/fantasyname)

# fantasyname

This is a golang implementation of [name generator described at RinkWorks](http://rinkworks.com/namegen/),
its based on [https://github.com/skeeto/fantasyname](https://github.com/skeeto/fantasyname) code.

# example

How it looks like:
```go
import (
 "fmt"
 "log"
 "time"
 "math/rand"

 fn "github.com/s0rg/fantasyname"
)

func main() {
 rand.Seed(time.Now().UnixNano())

 gen, err := fn.Compile("sV'i", fn.Collapse(true), fn.RandFn(rand.Intn))
 if err != nil {
 log.Fatal(err)
 }

 fmt.Println(gen.String()) // will print something like: entheu'loaf
}
```

[Here](https://github.com/s0rg/fantasyname/blob/master/_example/main.go) is a full example.

You can run it with `go run _example/main.go` to see results.

# ready-to-use cli app

Created by [TLINDEN](https://github.com/TLINDEN/): [gfn](https://github.com/TLINDEN/gfn)

# pattern syntax

The letters `s`, `v`, `V`, `c`, `B`, `C`, `i`, `m`, `M`, `D`, and `d` represent different types of random replacements:

 - `s` - generic syllable
 - `v` - vowel
 - `V` - vowel or vowel combination
 - `c` - consonant
 - `B` - consonant or consonant combination suitable for beginning a word
 - `C` - consonant or consonant combination suitable anywhere in a word
 - `i` - insult
 - `m` - mushy name
 - `M` - mushy name ending
 - `D` - consonant suited for a stupid person's name
 - `d` - syllable suited for a stupid person's name (begins with a vowel)

Everything else is emitted literally.

All characters between parenthesis `()` are emitted literally. For example, the pattern `s(dim)`,
emits a random generic syllable followed by `dim`.

Characters between angle brackets `<>` emit patterns from the table above.
Imagine the entire pattern is wrapped in one of these.

In both types of groupings, a vertical bar `|` denotes a random choice. Empty groups are allowed.
For example, `(foo|bar)` emits either `foo` or `bar`. The pattern `<c|v|>` emits a constant, vowel,
or nothing at all.

An exclamation point `!` means to capitalize the component that follows it. For example,
`!(foo)` will emit `Foo` and `v!s` will emit a lowercase vowel followed by a capitalized syllable, like `eRod`.

fantasyname

<img width="150" src="https://github.com/g3n/g3nd/blob/master/data/images/g3n_logo.png" alt="G3N Banner"/>

 <a href="https://godoc.org/github.com/g3n/engine"><img src="https://godoc.org/github.com/g3n/engine?status.svg" alt="Godoc"></img></a>
 <a href="https://goreportcard.com/report/github.com/g3n/engine"><img src="https://goreportcard.com/badge/github.com/g3n/engine" alt="Go Report Card"/></a>
 <a href="https://discord.gg/NfaeVr8zDg"><img src="https://img.shields.io/badge/Discord-G3N-blue" alt="Discord"/></a>
 

<h1 align="center">G3N - Go 3D Game Engine</h1>

**G3N** (pronounced "gen") is an OpenGL 3D Game Engine written in Go.
It can be used to write cross-platform Go applications that show rich and dynamic 3D representations - not just games. A basic integrated GUI framework is provided, and 3D spatial audio is supported through [OpenAL](https://www.openal.org/).

### **To see G3N in action try the [G3N demo](https://github.com/g3n/g3nd) or the [Gokoban](https://github.com/danaugrs/gokoban) award winning game.**


 <img style="float: right;" src="https://raw.githubusercontent.com/g3n/g3nd/master/data/images/g3nd_screenshots.png" alt="G3ND In Action"/>


## Highlighted Projects Using G3N

* [Gokoban - 3D Puzzle Game (_1st place in the 2017 Gopher Game Jam_)](https://github.com/danaugrs/gokoban)
* [go-tsne (_dimensionality reduction particularly well suited for visualizing high-dimensional datasets_)](https://github.com/danaugrs/go-tsne)
* [G3N Server-Side Rendering](https://github.com/moethu/webg3n)

## Dependencies

**Go 1.8+** is required. The engine also requires the system to have an **OpenGL driver** and a **GCC-compatible C compiler**.

On Unix-based systems the engine depends on some C libraries that can be installed using the appropriate distribution package manager. See below for OS specific requirements.

### Ubuntu/Debian-like

 $ sudo apt-get install xorg-dev libgl1-mesa-dev libopenal1 libopenal-dev libvorbis0a libvorbis-dev libvorbisfile3

### Fedora

 $ sudo dnf -y install xorg-x11-proto-devel mesa-libGL mesa-libGL-devel openal-soft openal-soft-devel libvorbis libvorbis-devel glfw-devel libXi-devel libXxf86vm-devel

### CentOS 7

Enable the EPEL repository:

 $ sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
 
Then install the same packages as for Fedora - remember to use `yum` instead of `dnf` for the package installation command.
 
### Arch

 $ sudo pacman -S base-devel xorg-server mesa openal libvorbis
 
### Void

 $ sudo xbps-install git xorg-server-devel base-devel libvorbis-devel libvorbis libXxf86vm-devel libXcursor-devel libXrandr-devel libXinerama-devel libopenal libopenal-devel libglvnd-devel
 
### Windows

We tested the Windows build using the [mingw-w64](https://mingw-w64.org) toolchain (you can download [this file](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/8.1.0/threads-posix/seh/x86_64-8.1.0-release-posix-seh-rt_v6-rev0.7z) in particular).

The necessary [audio DLLs](audio/windows/bin) are supplied and need to be added to your PATH.
If you would like to build the DLLs yourself you can find the libraries' source code and build instructions [here](audio/windows).

### macOS

Install the development files of OpenAL and Vorbis using [Homebrew](https://brew.sh/):

 brew install libvorbis openal-soft

## Installation

The following set of commands will download and install the engine along with all its Go dependencies:
 
```
git clone https://github.com/g3n/engine g3n-engine
cd g3n-engine
go install ./...
```

## Features

* Cross-platform: Windows, Linux, and macOS. (WebAssembly is 90% complete!)
* Integrated GUI (graphical user interface) with many widgets
* Hierarchical scene graph - nodes can contain other nodes
* 3D spatial audio via OpenAL (.wav, .ogg)
* Real-time lighting: ambient, directional, point, and spot lights
* Physically-based rendering: fresnel reflectance, geometric occlusion, microfacet distribution
* Model loaders: glTF (.gltf, .glb), Wavefront OBJ (.obj), and COLLADA (.dae)
* Geometry generators: box, sphere, cylinder, torus, etc...
* Geometries support morph targets and multimaterials
* Support for animated sprites based on sprite sheets
* Perspective and orthographic cameras
* Text image generation and support for TrueType fonts
* Image textures can be loaded from GIF, PNG or JPEG files
* Animation framework for position, rotation, and scale of objects
* Support for user-created GLSL shaders: vertex, fragment, and geometry shaders
* Integrated basic physics engine (experimental/incomplete)
* Support for HiDPI displays


 <img style="float: right;" src="https://github.com/g3n/g3n.github.io/raw/master/img/g3n_banner_small.png" alt="G3N Banner"/>


## Hello G3N

The code below is a basic "hello world" application ([hellog3n](https://github.com/g3n/demos/tree/master/hellog3n)) that shows a blue torus and a button that when clicked makes the torus red:

```Go
package main

import (
	"github.com/g3n/engine/app"
	"github.com/g3n/engine/camera"
	"github.com/g3n/engine/core"
	"github.com/g3n/engine/geometry"
	"github.com/g3n/engine/gls"
	"github.com/g3n/engine/graphic"
	"github.com/g3n/engine/gui"
	"github.com/g3n/engine/light"
	"github.com/g3n/engine/material"
	"github.com/g3n/engine/math32"
	"github.com/g3n/engine/renderer"
	"github.com/g3n/engine/util/helper"
	"github.com/g3n/engine/window"
	"time"
)

func main() {

	// Create application and scene
	a := app.App(800, 600, "Hello World")
	scene := core.NewNode()

	// Set the scene to be managed by the gui manager
	gui.Manager().Set(scene)

	// Create perspective camera
	cam := camera.New(1)
	cam.SetPosition(0, 0, 3)
	scene.Add(cam)

	// Set up orbit control for the camera
	camera.NewOrbitControl(cam)

	// Set up callback to update viewport and camera aspect ratio when the window is resized
	onResize := func(evname string, ev interface{}) {
		// Get framebuffer size and update viewport accordingly
		width, height := a.GetSize()
		a.Gls().Viewport(0, 0, int32(width), int32(height))
		// Update the camera's aspect ratio
		cam.SetAspect(float32(width) / float32(height))
	}
	a.Subscribe(window.OnWindowSize, onResize)
	onResize("", nil)

	// Create a blue torus and add it to the scene
	geom := geometry.NewTorus(1, .4, 12, 32, math32.Pi*2)
	mat := material.NewStandard(math32.NewColor("DarkBlue"))
	mesh := graphic.NewMesh(geom, mat)
	scene.Add(mesh)

	// Create and add a button to the scene
	btn := gui.NewButton("Make Red")
	btn.SetPosition(100, 40)
	btn.SetSize(40, 40)
	btn.Subscribe(gui.OnClick, func(name string, ev interface{}) {
		mat.SetColor(math32.NewColor("DarkRed"))
	})
	scene.Add(btn)

	// Create and add lights to the scene
	scene.Add(light.NewAmbient(&math32.Color{1.0, 1.0, 1.0}, 0.8))
	pointLight := light.NewPoint(&math32.Color{1, 1, 1}, 5.0)
	pointLight.SetPosition(1, 0, 2)
	scene.Add(pointLight)

	// Create and add an axis helper to the scene
	scene.Add(helper.NewAxes(0.5))

	// Set background color to gray
	a.Gls().ClearColor(0.5, 0.5, 0.5, 1.0)

	// Run the application
	a.Run(func(renderer *renderer.Renderer, deltaTime time.Duration) {
		a.Gls().Clear(gls.DEPTH_BUFFER_BIT | gls.STENCIL_BUFFER_BIT | gls.COLOR_BUFFER_BIT)
		renderer.Render(scene, cam)
	})
}
```


 <img style="float: right;" src="https://github.com/g3n/demos/blob/master/hellog3n/screenshot.png" alt="hellog3n Screenshot"/>
 
 
You can download and install `hellog3n` via:
 
 go install github.com/g3n/demos/hellog3n@latest

For more complex demos please see the [G3N demo program](https://github.com/g3n/g3nd).

## Documentation

The complete engine API reference can be found here: [![GoDoc](https://godoc.org/github.com/g3n/engine?status.svg)](https://godoc.org/github.com/g3n/engine).

There is also the beginning of a Getting Started Guide, and a newly created list of Guides and Tutorials:

* [Getting Started](https://github.com/g3n/engine/wiki/Getting-Started-(WIP))
* [Guides and Tutorials](https://github.com/g3n/engine/wiki/Guides-and-Tutorials)

Along with those, a good way to learn how to use the engine is to see the source code of [G3ND - the G3N demo](https://github.com/g3n/g3nd).
 
## Contributing

If you find a bug or create a new feature you are encouraged to send pull requests!

## Community

Join our [Discord channel](https://discord.gg/NfaeVr8zDg). It's the best way to have your questions answered quickly by the G3N community.

## Stargazers over time

[![Stargazers over time](https://starchart.cc/g3n/engine.svg)](https://starchart.cc/g3n/engine)

Leaf
====
A pragmatic game server framework in Go (golang).

Features
---------

* Extremely easy to use
* Reliable
* Multicore support
* Modularity

Community
---------



Documentation
---------

* [中文文档](https://github.com/name5566/leaf/blob/master/TUTORIAL_ZH.md)
* [English](https://github.com/name5566/leaf/blob/master/TUTORIAL_EN.md)

Licensing
---------

Leaf is licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/name5566/leaf/blob/master/LICENSE) for the full license text.


Leaf

Lightweight, facility, high performance golang based game server framework

# Nano [![Build Status][1]][2] [![GoDoc][3]][4] [![Go Report Card][5]][6] [![MIT licensed][7]][8] 

[1]: https://github.com/lonng/nano/actions/workflows/go.yml/badge.svg?branch=master
[2]: https://github.com/lonng/nano/actions/workflows/go.yml
[3]: https://godoc.org/github.com/lonng/nano?status.svg
[4]: https://godoc.org/github.com/lonng/nano
[5]: https://goreportcard.com/badge/github.com/lonng/nano
[6]: https://goreportcard.com/report/github.com/lonng/nano
[7]: https://img.shields.io/badge/license-MIT-blue.svg
[8]: LICENSE

Nano is an easy to use, fast, lightweight game server networking library for Go.
It provides a core network architecture and a series of tools and libraries that
can help developers eliminate boring duplicate work for common underlying logic.
The goal of nano is to improve development efficiency by eliminating the need to
spend time on repetitious network related programming.

Nano was designed for server-side applications like real-time games, social games,
mobile games, etc of all sizes.

Join to Discord: [Nano Community](https://discord.gg/eHEDrBH5PV) 

## How to build a system with `Nano`

#### What does a `Nano` application look like?

The simplest "nano" application as shown in the following figure, you can make powerful applications by combining different components.

![Application](media/application.png)

In fact, the `nano` application is a collection of  [Component ](./docs/get_started.md#component) , and a component is a bundle of  [Handler](./docs/get_started.md#handler), once you register a component to nano, nano will register all methods that can be converted to `Handler` to nano service container. Service was accessed by `Component.Handler`, and the handler will be called while client request. The handler will receive two parameters while handling a message:
  - `*session.Session`: corresponding a client that apply this request or notify.
  - `*protocol.FooBar`: the payload of the request.

While you had processed your logic, you can response or push message to the client by `session.Response(payload)` and `session.Push('eventName', payload)`, or returns error when some unexpected data received.

#### How to build distributed system with `Nano`

Nano contains built-in distributed system solution, and make you creating a distributed game server easily.

See: [The distributed chat demo](https://github.com/lonng/nano/tree/master/examples/cluster)

The Nano will remain simple, but you can perform any operations in the component and get the desired goals. You can startup a group of `Nano` application as agent to dispatch message to backend servers.

#### How to execute the asynchronous task

```golang
func (manager *PlayerManager) Login(s *session.Session, msg *ReqPlayerLogin) error {
    var onDBResult = func(player *Player) {
        manager.players = append(manager.players, player)
        s.Push("PlayerSystem.LoginSuccess", &ResPlayerLogin)
    }
    
    // run slow task in new gorontine
    go func() {
        player, err := db.QueryPlayer(msg.PlayerId) // ignore error in demo
        // handle result in main logical gorontine
        nano.Invoke(func(){ onDBResult(player) })
    }
    return nil
}
```

## Documents

- English
    + [How to build your first nano application](./docs/get_started.md)
    + [Route compression](./docs/route_compression.md)
    + [Communication protocol](./docs/communication_protocol.md)
    + [Design patterns](./docs/design_patterns.md)
    + [API Reference(Server)](https://godoc.org/github.com/lonnng/nano)
    + [How to integrate `Lua` into `Nano` component(incomplete)](.)

- 简体中文
    + [如何构建你的第一个nano应用](./docs/get_started_zh_CN.md)
    + [路由压缩](./docs/route_compression_zh_CN.md)
    + [通信协议](./docs/communication_protocol_zh_CN.md)
    + [API参考(服务器)](https://godoc.org/github.com/lonnng/nano)
    + [如何将`lua`脚本集成到`nano`组件中(未完成)](.)

## Resources

- Javascript
  + [nano-websocket-client](https://github.com/lonnng/nano-websocket-client)
  + [nano-egret-client](https://github.com/lonnng/nano-egret-client)

- Typescript/cocos-creator
  + [nano-client-ts](https://github.com/adoontheway/nano-client-ts)

- Demo
  + [Implement a chat room in 100 lines with nano and WebSocket](./examples/demo/chat)
  + [Tadpole demo](./examples/demo/tadpole)
  + [四川麻将, 血战到底(三人模式/四人模式)完整项目实例](https://github.com/lonnng/nanoserver)

## Community

- ~~QQGroup: [289680347](https://jq.qq.com/?_wv=1027&k=4EMMaha)~~ Q群已满员(加微信 `gsw_945` 邀请进微信群, 需备注 `nano加群`)
- Reddit: [nanolabs](https://www.reddit.com/r/nanolabs/)

## Successful cases

- [空来血战](https://fir.im/tios)

## Go version

`> go1.8`

## Installation

```bash
go get github.com/lonng/nano

# dependencies
go get -u github.com/pingcap/check
go get -u github.com/pingcap/errors
go get -u github.com/urfave/cli

go get -u google.golang.org/protobuf/proto
go get -u github.com/gorilla/websocket
go get -u google.golang.org/grpc
```

## Protocol Buffers
```bash
# protoc
# download form: https://github.com/protocolbuffers/protobuf/releases
# protoc-gen-go
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
# delve
go install github.com/go-delve/delve/cmd/dlv@latest
```

## Test
```bash
go test -v ./...
```

## Benchmark

```bash
# Case:   PingPong
# OS:     Windows 10
# Device: i5-6500 3.2GHz 4 Core/1000-Concurrent   => IOPS 11W(Average)
# Other:  ...

cd ./benchmark/io
go test -v -tags "benchmark"
```

## License

[MIT License](./LICENSE)


nano

# Oak

## A Pure Go game engine

[![Go Reference](https://pkg.go.dev/badge/github.com/oakmound/oak/v4.svg)](https://pkg.go.dev/github.com/oakmound/oak/v4)
[![Code Coverage](https://codecov.io/gh/oakmound/oak/branch/master/graph/badge.svg)](https://codecov.io/gh/oakmound/oak)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)

## Table of Contents

1. [Installation](#installation)

1. [Features](#features)

1. [Support](#support)

1. [Quick Start](#quick-start)

1. [Examples](#examples)

1. [Finished Games](#finished-games)

***

## Installation <a name="installation"/>

`go get -u github.com/oakmound/oak/v4`

## Features and Systems <a name="features"></a>

1. Window Management
 - Windows and key events forked from [shiny](https://pkg.go.dev/golang.org/x/exp/shiny)
 - Support for multiple windows running at the same time
1. [Image Rendering](https://pkg.go.dev/github.com/oakmound/oak/v4/render)
 - Manipulation
 - `render.Modifiable` interface
 - Integrated with optimized image manipulation via [gift](https://github.com/disintegration/gift)
 - Built in `Renderable` types covering common use cases
 - `Sprite`, `Sequence`, `Switch`, `Composite`
 - Primitive builders, `ColorBox`, `Line`, `Bezier`
 - History-tracking `Reverting`
 - Primarily 2D
1. [Particle System](https://pkg.go.dev/github.com/oakmound/oak/v4/render/particle)
1. [Mouse Handling](https://pkg.go.dev/github.com/oakmound/oak/v4/mouse)
1. [Joystick Support](https://pkg.go.dev/github.com/oakmound/oak/v4/joystick)
1. [Audio Support](https://pkg.go.dev/github.com/oakmound/oak/v4/audio)
1. [Collision](https://pkg.go.dev/github.com/oakmound/oak/v4/collision)
 - Collision R-Tree forked from [rtreego](https://github.com/dhconnelly/rtreego)
 - [2D Raycasting](https://pkg.go.dev/github.com/oakmound/oak/v4/collision/ray)
 - Collision Spaces
 - Attachable to Objects
 - Auto React to collisions through events
1. [2D Physics System](https://pkg.go.dev/github.com/oakmound/oak/v4/physics)
1. [Event Handler](https://pkg.go.dev/github.com/oakmound/oak/v4/event)

## Support <a name="support"></a>

For discussions not significant enough to be an Issue or PR, feel free to ping us in the #oak channel on the [gophers slack](https://invite.slack.golangbridge.org/). For insight into what is happening in oak see the [blog](https://200sc.dev/).

## Quick Start <a name="quick-start"></a>

This is an example of the most basic oak program:

```go
package main

import (
 "github.com/oakmound/oak/v4"
 "github.com/oakmound/oak/v4/scene"
)

func main() {
 oak.AddScene("firstScene", scene.Scene{
 Start: func(*scene.Context) {
 // ... draw entities, bind callbacks ... 
 }, 
 })
 oak.Init("firstScene")
}
```

See below or navigate to the [examples](examples) folder for demos. For more examples and documentation checkout [godoc](https://pkg.go.dev/github.com/oakmound/oak/v4) for reference documentation, the [wiki](https://github.com/oakmound/oak/wiki), or our extended features in [grove](https://github.com/oakmound/grove). 

## Examples <a name="examples"></a>

| | | |
|:-------------------------:|:-------------------------:|:-------------------------:|
|<img width="200" src="examples/platformer/example.gif" a=examples/platformer> [Platformer](examples/platformer) | <img width="200" src="examples/top-down-shooter//example.gif"> [Top down shooter](examples/top-down-shooter)|<img width="200" src="examples/flappy-bird//example.gif"> [Flappy Bird](examples/flappy-bird/)
| <img width="200" src="examples/bezier/example.PNG"> [Bezier Curves](examples/bezier) |<img width="200" src="examples/joystick-viz/example.gif"> [Joysticks](examples/joystick-viz)|<img width="200" src="examples/piano/example.gif"> [Piano](examples/piano)|
|<img width="200" src="examples/screenopts/example.PNG"> [Screen Options](examples/screenopts) | <img width="200" src="examples/multi-window/example.PNG"> [Multi Window](examples/multi-window) |<img width="200" src="examples/particle-demo/overviewExample.gif"> [Particles](examples/particle-demo)|

## Games using Oak <a name="finished-games"></a>

To kick off a larger game project you can get started with [game-template](https://github.com/oakmound/game-template).

| | |
|:-------------------------:|:-------------------------:|
|<img width="200" src="https://img.itch.zone/aW1hZ2UvMTk4MjIxLzkyNzUyOC5wbmc=/original/aRusLc.png" a=examples/platformer-tutorial> [Agent Blue](https://oakmound.itch.io/agent-blue) | <img width="200" src="https://img.itch.zone/aW1hZ2UvMTY4NDk1Lzc4MDk1Mi5wbmc=/original/hIjzFm.png"> [Fantastic Doctor](https://github.com/oakmound/lowrez17)
|<img width="200" src="https://img.itch.zone/aW1hZ2UvMzkwNjM5LzI2NzU0ODMucG5n/original/eaoFrd.png"> [Hiring Now: Looters](https://oakmound.itch.io/cheststacker) | <img width="200" src="https://img.itch.zone/aW1hZ2UvMTYzNjgyLzc1NDkxOS5wbmc=/original/%2BwvZ7j.png"> [Jeremy The Clam](https://github.com/200sc/jeremy)
|<img width="200" src="https://img.itch.zone/aW1hZ2UvOTE0MjYzLzUxNjg3NDEucG5n/original/5btfEr.png"> [Diamond Deck Championship](https://oakmound.itch.io/diamond-deck-championship) | <img width="200" src="https://img.itch.zone/aW1nLzgzMDM5MjcucG5n/105x83%23/oA19CL.png"> [SokoPic](https://oakmound.itch.io/sokopic) 

## On Pure Go <a name="pure-go"/>

Oak has recently brought in dependencies that include C code, but we still describe the engine as a Pure Go engine, which at face value seems contradictory. Oak's goal is that, by default, a user can pull down the engine and create a fully functional game or GUI application on a machine with no C compiler installed, so when we say Pure Go we mean that, by default, the library is configured so no C compilation is required, and that no major features are locked behind C compliation. 

We anticipate in the immediate future needing to introduce alternate drivers that include C dependencies for performance improvements in some scasenarios, and currently we have no OSX solution that lacks objective C code.

3D engine for the Go language, works on Windows and Linux ([Harfang on Go.dev](https://github.com/harfang3d/harfang-go)).

<img src="https://github.com/harfang3d/image-storage/raw/main/brand/logo_harfang3d_owl_only.png" align="right" width="200"/>

# HARFANG® 3D engine

[![PyPI](https://img.shields.io/pypi/v/harfang)](https://pypi.org/project/harfang)
[![Downloads](https://static.pepy.tech/badge/harfang)](https://pepy.tech/project/harfang)
[![Downloads](https://static.pepy.tech/badge/harfang/month)](https://pepy.tech/project/harfang)

HARFANG®3D is an all-in-one 3D visualization library usable in C++, Python, Lua and Go.
#### Table of contents

1. [About](#section_1)
 - [Features](#subsection_1a)
 - [Screenshots](#subsection_1b)
2. [Download](#section_2)
3. [Building the SDK](#section_3)
 - [Prerequisites](#subsection_3a)
 - [Building](#subsection_3b)
4. [Using the C++ SDK](#section_4)
5. [Version](#section_5)
6. [License](#section_6)
7. [Contribute](#section_7)
8. [Support Harfang](#section_8)

<a name="section_1"></a>
# About

HARFANG®3D is an easy-to-adapt, cross-platform, multi-language, powerful and optimized solution to integrate with embedded systems, into existing environments and combining features to meet the industrial standards of real-time 3D imaging.

The HARFANG®3D architecture makes it easy to meet the requirements for hardware integration, display performance and security.

HARFANG®3D is written in C++ and is based on the open-source bgfx library supporting Vulkan, Metal, DirectX (from 9 to 12), OpenGL and OpenGL ES. It Builds on Windows, Linux, Intel and ARM.

<a name="subsection_1a"></a>
## Features

Platforms supported
* Win32 and Win64 Intel
* Linux 64 Intel
* Aarch 64 ARM

Scene API
* Node & component based
* Performance oriented

Rendering pipeline
* Low-spec PBR rendering pipeline
* High-spec 'AAA' rendering pipeline (screen space GI & reflection)
* Support of user pipeline shaders

VR API
* XR support via OpenXR
* VR support via OpenVR/SteamVR including Eye tracking (SRanipal)
* Tested with the HTC Vive/Vive Pro, Valve Index, Lenovo Explorer, Oculus Rift S, Oculus Quest 2, Varjo XR-3

Physics API
* Rigid bodies, collisions, mechanical constraints, ray casting

Audio API
* Play/stream WAV/OGG formats
* 3D audio spatialization

Languages supported
* C++
* Python _(3.2+)_
* Lua _(5.4)_
* Go _(1+, experimental)_
<a name="subsection_1b"></a>
## Screenshots

The following screenshots were captured on a 1080GTX in 1080P running at 60FPS.

![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/2.0.111/sun_temple_aaa.png)

![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/2.0.111/sun_temple_aaa_2.png)

*(Sun Temple, courtesy of the Open Research Content Archive (ORCA))*

<a name="section_2"></a>
# Download

You can download the HARFANG binaries from the official website:
https://dev.harfang3d.com/releases

<a name="section_3"></a>
# Build the SDK

<a name="subsection_3a"></a>
## Prerequisites

* Git
* CMake 3.19+
* CPython 3.2+
* Go 1+ _(for Harfang Go module)_
* Doxygen _(for Harfang C++ SDK documentation)_
* Autodesk FBX SDK _(for FBX Converter)_

### Windows
* Visual Studio 2019 _(C++ compiler and IDE)_
* MinGW _(for Harfang Go module)_

### Linux
* GCC 9 or above
* CLang 

<a name="subsection_3b"></a>
## Building

1. Clone the `Harfang 3D` repository including its submodules.
 ```
 git clone --recursive -j8 https://github.com/harfang3d/harfang3d.git
 cd harfang3d
 ```

1. Create build directory. Note that the described directory layout is not mandatory.
 ```
 mkdir build
 cd build
 ``` 

1. Clone Fabgen.
 ```
 git clone https://github.com/ejulien/FABGen.git
 ```

1. Download and install Autodesk FBX SDK.

1. Create a directory that will hold the build system generated by CMake.
 ```
 mkdir cmake
 cd cmake
 ```

1. Generate the build system using CMake. For example, on Windows it will be:
 ```
 cmake ../.. -G "Visual Studio 16 2019" -A x64 \
 -DCMAKE_INSTALL_PREFIX:PATH="D:/harfang/build/install" \
 -DPYTHON_EXECUTABLE:FILEPATH="C:/Python36/python.exe" \
 -DHG_FABGEN_PATH:PATH="D:/harfang/build/fabgen" \
 -DHG_FBX_SDK:PATH="D:/fbx_sdk" 
 ``` 

 * `CMAKE_INSTALL_PREFIX` specifies the directory where the Harfang SDK will installed.
 * `PYTHON_EXECUTABLE` is the path the Python 3 interpreter.
 * `FABGEN_PATH` is the path to Fabgen binding generator.
 * `HG_FBX_SDK` is the path to Autodesk FBX SDK.

 &nbsp; 
 Here is the list of available CMake options.

 * __C++ SDK__
 * `HG_BUILD_CPP_SDK` : Build C++ SDK (default: __OFF__).
 * `HG_BUILD_TESTS` : Build C++ SDK unit tests (default: __OFF__).
 * `HG_BUILD_DOCS` : Build API and C++ SDK documentations (default: __OFF__).
 * `HG_ENABLE_BULLET3_SCENE_PHYSICS` : Enable Bullet physics API (default: __ON__).
 * `HG_ENABLE_RECAST_DETOUR_API` : Enable Recast/Detour navigation mesh and path finding API (default: __ON__).
 * `HG_ENABLE_OPENVR_API` : Enable OpenVR API (default: __OFF__).
 * `HG_ENABLE_SRANIPAL_API` : Enable VIVE Eye and Facial Tracking SDK (SRanipal) API (default: __OFF__).
 * __Tools__
 * `HG_BUILD_ASSETC` : Build AssetC asset compiler (default: __ON__).
 * `HG_BUILD_ASSIMP_CONVERTER` : Build Assimp based 3D model converter (default: __ON__).
 * `HG_BUILD_FBX_CONVERTER` : Build FBX converter (default: __ON__).
 * `HG_BUILD_GLTF_IMPORTER` : Build GLTF importer (default: __ON__).
 * `HG_BUILD_GLTF_EXPORTER` : Build GLTF exporter (default: __ON__).
 * __Bindings__
 * `HG_BUILD_HG_LUA` : Build Harfang LUA module (default: __OFF__).
 * `HG_BUILD_HG_PYTHON` : Build Harfang Python module (wheel) (default: __OFF__).
 * `HG_BUILD_HG_GO` : Build Harfang GO module (default: __OFF__).
 
 &nbsp; 

1. Build the SDK.
 ```
 cmake --build . --config Release --target INSTALL
 ```
 _Note: On Linux you will need to explicitly specify the build type with `-DCMAKE_BUILD_TYPE=Release`_ 

 Depending on the set of option passed to CMake the install directory will contain the following subdirectories:
 * `cppsdk` : Harfang C++ SDK.
 * `hg_python` : Harfang Python module.
 * `hg_lua` : Harfang LUA module.
 * `hg_go` : Harfang Go module.
 * `assetc` : Asset compiler.
 * `assimp_converter` : Assimp 3D model converter.
 * `fbx_converter` : FBX converter.
 * `gltf_importer` : GLTF importer.
 * `gltf_exporter` : GLTF exporter.
 
### Notes on Visual Studio Code

1. Install the CMakeTools extension.

1. Copy the `harfang/.vscode/template_settings.json` file to `harfang/.vscode/settings.json` and edit it to reflect your local installation.

1. Open the `harfang` folder in Visual Studio Code. CMakeTools should succesfully configure the project.

<a name="section_4"></a>
# Use the SDK

The Harfang C++ SDK directory `cppsdk` contains the following:
* `bin` : depending on the configuration used, this directory contains either a `Release` or `Debug` subdirectory with all the shared libraries.
* `lib` : like the `bin` directory, it contains a subdirectories named after the configuration used during build (`Release` or `Debug`) with all the generated static libraries.
* `include` : contains all the C++ include files of Harfang public API.
* `cmake` : contains the CMake configuration files. 

To add the Harfang C++ SDK to your CMake project, just add the following to the `CMakeLists.txt` file:
```cmake
find_package(harfang REQUIRED
 COMPONENTS cppsdk
 PATHS ${HG_CPPSDK_PATH}
 NO_DEFAULT_PATH
)
```
with `HG_CPPSDK_PATH` the path to the `cppsdk` directory. For example, if we follow the directory layout given above, it will be `D:/harfang/build/install/cppsdk`.

Targets should link against the following libraries.
* `hg::engine` 
* `hg::foundation` 
* `hg::platform`
* `hg::libluadll`

The `install_cppsdk_dependencies` function installs the Harfang C++ SDK shared libraries dependencies.
```cmake
install_cppsdk_dependencies(destination component)
```
* `destination` : is the library where the shared libraries will be installed.
* `component` : installation component name.

<a name="section_5"></a>
# Version

Harfang follows the Semantic Versioning Specification (SemVer) (http://semver.org).

Given a version number MAJOR.MINOR.PATCH, increment the:

* MAJOR version when you make incompatible API changes,
* MINOR version when you add functionality in a backwards-compatible manner, and
* PATCH version when you make backwards-compatible bug fixes.

<a name="section_6"></a>
# License

Harfang is licensed under the GPLv3, LGPLv3 and a commercial license: 
https://www.harfang3d.com/license

<a name="section_7"></a>
# Contribute
## Contributor License Agreement

By contributing your code to HARFANG you grant the [HARFANG3D organization](https://www.harfang3d.com/en_US/legal) a non-exclusive, irrevocable, worldwide, royalty-free, sublicenseable, transferable license under all of Your relevant intellectual property rights (including copyright, patent, and any other rights), to use, copy, prepare derivative works of, distribute and publicly perform and display the Contributions on any licensing terms, including without limitation:
(a) open source licenses like the MIT license; and (b) binary, proprietary, or commercial licenses. Except for the licenses granted herein, You reserve all right, title, and interest in and to the Contribution.

You confirm that you are able to grant us these rights. You represent that You are legally entitled to grant the above license. If Your employer has rights to intellectual property that You create, You represent that You have received permission to make the Contributions on behalf of that employer, or that Your employer has waived such rights for the Contributions.

You represent that the Contributions are Your original works of authorship, and to Your knowledge, no other person claims, or has the right to claim, any right in any invention or patent related to the Contributions. You also represent that You are not legally obligated, whether by entering into an agreement or otherwise, in any way that conflicts with the terms of this license.

The [HARFANG3D organization](https://www.harfang3d.com/en_US/legal) acknowledges that, except as explicitly described in this Agreement, any Contribution which you provide is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

<a name="section_8"></a>
# How to support Harfang?

There are numerous ways to help Harfang grow its community:

* Give the repository a [Star :star:](https://github.com/harfang3d/harfang3d)
* Purchase a license of [Harfang Studio](https://www.harfang3d.com/en_US/studio)
* Subscribe to Harfang [Youtube channel](https://www.youtube.com/c/HARFANG3D/videos)
* Follow us on [Twitter](https://twitter.com/harfang3dengine/)
* Leave a Comment/Like on [Alternative To](https://alternativeto.net/software/harfang-3d/about/)

<a name="section_9"></a>
# More screenshots...

![Nvidia USD Attic](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.2.6/attic_harfang.png)

*(The NVIDIA USD Attic using the HARFANG 3D AAA renderer)*

![ORCA Sun Temple](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sun_temple_aaa.png)

![ORCA Sun Temple](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sun_temple_aaa_2.png)

*(Sun Temple, courtesy of the Open Research Content Archive (ORCA))*

![ORCA Bistro](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/cafe_exterior_aaa.png)

![ORCA Bistro](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/cafe_exterior_aaa_2.png)

*(Bistro, courtesy of the Open Research Content Archive (ORCA))*

![Sponza Atrium](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sponza_atrium_aaa.png)

![Sponza Atrium](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.1.1/sponza_atrium_aaa_2.png)

*(Sponza Atrium GLTF, courtesy of Crytek/Themaister)*

![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/3.2.6/marine-melodies-screenshot_1280.png)

*(Marine Melodies, by Resistance Norway)*

Harfang3D

Game server skeleton implemented with golang

### A game server skeleton implemented with golang.
![Architecture](doc/arch.png)

### gonet/2

gonet1已停止维护(I no longer maintain this, please move forward to http://github.com/gonet2 )

建议移步至新架构: http://gonet2.github.io

#### 部署: 
* Game Server(GS): 
玩家直接连接GS， 处理玩家逻辑，并与 HUB/SS 通信，GS存在若干个。 
(Players connect directly to GS(s) and process, GS(s) will communication with HUB)
 
* Hub Server(HUB): 
若干个GS 连接到一个HUB, 只存在一个HUB，维护基础的全局信息，以及 GS<--->GS 的消息转发. 
(packet forwarding)
 
* Stats Server(SS): 
统计服务器，根据玩家的行为，记录策划需要的数据，以便于后期统计。 
统计属于事后分析，数据量较大，性能需求不同, 故单独列为一个服务器。

#### 通信原则: 
1. GS到HUB/SS的通信，都是Call同步调用，即GS必须等待ACK。 
2. HUB到GS的通信，只有forward数据包。 
3. 单播消息在玩家离线时会存入db, 登录后的启动过程 ___GS___ 直接读取db，并forward给玩家goroutine。(持久化) 
4. 多播消息会发送给所有的在线玩家(非持久化) 
5. 广播消息会发送给所有的在线玩家(非持久化) 

#### 服务器状态一致性
1. GS节点可以单独重启 
2. HUB 重启后，GS必须全部重启 
3. SS 可随意重启，不影响业务 

#### 安装先决条件:
0. 确保安装好graphviz, gawk
1. 确保安装好mongodb
2. 确保config.ini中的mongo_xxxx配置正确
3. export GOPATH='当前目录'

#### 安装:
* xtaci@ubuntu:~$ git clone https://github.com/xtaci/gonet 
* xtaci@ubuntu:~$ cd gonet 
* xtaci@ubuntu:~/gonet$ export GOPATH=~/gonet 
* xtaci@ubuntu:~/gonet$ go get gopkg.in/mgo.v2
* xtaci@ubuntu:~/gonet$ make 
* xtaci@ubuntu:~/gonet$ ./start-test.sh

gonet

Archetype-based Entity Component System (ECS) for Go

<div align="center" width="100%">
<a href="https://github.com/mlange-42/ark">
<picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlange-42/ark/refs/heads/main/docs/static/images/ark-logo-text-dark.svg">
 <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/mlange-42/ark/refs/heads/main/docs/static/images/ark-logo-text-light.svg">
 <img alt="Ark Logo" src="https://raw.githubusercontent.com/mlange-42/ark/refs/heads/main/docs/static/images/ark-logo-text-light.svg">
</picture>
</a>

[![Test status](https://img.shields.io/github/actions/workflow/status/mlange-42/ark/tests.yml?branch=main&label=Tests&logo=github)](https://github.com/mlange-42/ark/actions/workflows/tests.yml)
[![codecov](https://codecov.io/github/mlange-42/ark/graph/badge.svg?token=YMYMFN2ESZ)](https://codecov.io/github/mlange-42/ark)
[![Go Report Card](https://goreportcard.com/badge/github.com/mlange-42/ark)](https://goreportcard.com/report/github.com/mlange-42/ark)
[![User Guide](https://img.shields.io/badge/user_guide-%23007D9C?logo=go&logoColor=white&labelColor=gray)](https://mlange-42.github.io/ark/)
[![Go Reference](https://img.shields.io/badge/reference-%23007D9C?logo=go&logoColor=white&labelColor=gray)](https://pkg.go.dev/github.com/mlange-42/ark)
[![GitHub](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/mlange-42/ark)
[![DOI:10.5281/zenodo.14994239](https://img.shields.io/badge/10.5281%2Fzenodo.14994239-blue?label=doi)](https://doi.org/10.5281/zenodo.14994239)
[![MIT license](https://img.shields.io/badge/MIT-brightgreen?label=license)](https://github.com/mlange-42/ark/blob/main/LICENSE-MIT)
[![Apache 2.0 license](https://img.shields.io/badge/Apache%202.0-brightgreen?label=license)](https://github.com/mlange-42/ark/blob/main/LICENSE-APACHE)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

Ark is an archetype-based [Entity Component System](https://en.wikipedia.org/wiki/Entity_component_system) (ECS) for [Go](https://go.dev/).

&mdash;&mdash;

[Features](#features) &nbsp; &bull; &nbsp; [Installation](#installation) &nbsp; &bull; &nbsp; [Usage](#usage) &nbsp; &bull; &nbsp; [Tools](#tools)
</div>

## Features

- Designed for performance and highly optimized. See the [Benchmarks](https://mlange-42.github.io/ark/benchmarks/).
- Well-documented, type-safe [API](https://pkg.go.dev/github.com/mlange-42/ark), and a comprehensive [User guide](https://mlange-42.github.io/ark/).
- [Entity relationships](https://mlange-42.github.io/ark/relations/) as a first-class feature.
- Extensible [event system](https://mlange-42.github.io/ark/events/) with filtering and custom event types.
- Fast [batch operations](https://mlange-42.github.io/ark/batch/) for mass manipulation.
- No systems. Just queries. Use your own structure (or the [Tools](https://github.com/mlange-42/ark#tools)).
- World serialization and deserialization with [ark-serde](https://github.com/mlange-42/ark-serde).
- Zero [dependencies](https://github.com/mlange-42/ark/blob/main/go.mod), 100% [test coverage](https://app.codecov.io/github/mlange-42/ark).

## Installation

To use Ark in a Go project, run:

```shell
go get github.com/mlange-42/ark
```

## Usage

Below is the classical Position/Velocity example that every ECS shows in the docs.

See the [User Guide](https://mlange-42.github.io/ark/), [API docs](https://pkg.go.dev/github.com/mlange-42/ark) and [examples](https://github.com/mlange-42/ark/tree/main/examples) for details.

```go
package main

import (
	"math/rand/v2"
	"github.com/mlange-42/ark/ecs"
)

// Position component
type Position struct {
	X, Y float64
}

// Velocity component
type Velocity struct {
	DX, DY float64
}

func main() {
	// Create a new World
	world := ecs.NewWorld()

	// Create a component mapper
	// Save mappers permanently and re-use them for best performance
	mapper := ecs.NewMap2[Position, Velocity](world)

	// Create entities with components
	for range 1000 {
		_ = mapper.NewEntity(
			&Position{X: rand.Float64() * 100, Y: rand.Float64() * 100},
			&Velocity{DX: rand.NormFloat64(), DY: rand.NormFloat64()},
		)
	}

	// Create a filter
	// Save filters permanently and re-use them for best performance
	filter := ecs.NewFilter2[Position, Velocity](world)

	// Time loop
	for range 5000 {
		// Get a fresh query and iterate it
		query := filter.Query()
		for query.Next() {
			// Component access through the Query
			pos, vel := query.Get()
			// Update component fields
			pos.X += vel.DX
			pos.Y += vel.DY
		}
	}
}
```

## Tools

- [ark-serde](https://github.com/mlange-42/ark-serde) provides JSON serialization and deserialization for Ark's World.
- [ark-tools](https://github.com/mlange-42/ark-tools) provides systems, a scheduler, and other useful stuff for Ark.
- [ark-pixel](https://github.com/mlange-42/ark-pixel) provides OpenGL graphics and live plots via the [Pixel](https://github.com/gopxl/pixel) game engine.

## Cite as

Lange, M. & contributors (2025): Ark &ndash; An archetype-based Entity Component System for Go. DOI: [10.5281/zenodo.14994239](https://doi.org/10.5281/zenodo.14994239), GitHub repository: https://github.com/mlange-42/ark

## License

Ark and all its sources and documentation are distributed under the [MIT license](./LICENSE-MIT) and the [Apache 2.0 license](./LICENSE-APACHE), as your options.

# Ebitengine (v2)

[![Go Reference](https://pkg.go.dev/badge/github.com/hajimehoshi/ebiten/v2.svg)](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2)
[![Build Status](https://github.com/hajimehoshi/ebiten/actions/workflows/test.yml/badge.svg)](https://github.com/hajimehoshi/ebiten/actions?query=workflow%3Atest)

**A dead simple 2D game engine for Go**

Ebitengine (formerly known as Ebiten) is an open source game engine for the Go programming language. Ebitengine's simple API allows you to quickly and easily develop 2D games that can be deployed across multiple platforms.

* [Website (ebitengine.org)](https://ebitengine.org)
* [API Reference](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2)
* [Cheat Sheet](https://ebitengine.org/en/documents/cheatsheet.html)
* [Awesome Ebitengine](https://github.com/sedyh/awesome-ebitengine)

![Overview](https://ebitengine.org/images/overview2.png)

## Platforms

* [Windows](https://ebitengine.org/en/documents/install.html?os=windows) (No Cgo required!)
* [macOS](https://ebitengine.org/en/documents/install.html?os=darwin) (No Cgo required!)
* [Linux](https://ebitengine.org/en/documents/install.html?os=linux)
* [FreeBSD](https://ebitengine.org/en/documents/install.html?os=freebsd)
* [Android](https://ebitengine.org/en/documents/mobile.html)
* [iOS](https://ebitengine.org/en/documents/mobile.html)
* [WebAssembly](https://ebitengine.org/en/documents/webassembly.html)
* Nintendo Switch
* Xbox (Xbox support is limited and not available to everyone. Negotiations are currently underway to make it accessible to all.)

For installation on desktops, see [the installation instruction](https://ebitengine.org/en/documents/install.html).

## Features

* 2D Graphics (Geometry and color transformation by matrices, Various composition modes, Offscreen rendering, Text rendering, Automatic batches, Automatic texture atlas, Custom shaders)
* Input (Mouse, Keyboard, Gamepads, Touches)
* Audio (Ogg/Vorbis, MP3, WAV, PCM)

## Packages

* [ebiten](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2)
  * [audio](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/audio)
    * [mp3](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/audio/mp3)
    * [vorbis](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/audio/vorbis)
    * [wav](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/audio/wav)
  * [colorm](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/colorm)
  * [ebitenutil](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/ebitenutil)
  * [inpututil](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/inpututil)
  * [mobile](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/mobile)
  * [text/v2](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/text/v2)
  * [vector](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/vector)
  * [exp/textinput](https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2/exp/textinput)

## Community

- [Discord](https://discord.gg/3tVdM5H8cC)
- `#ebitengine` channel in [Gophers Slack](https://blog.gopheracademy.com/gophers-slack-community/)
- [GitHub Discussion](https://github.com/hajimehoshi/ebiten/discussions)
- [`r/ebitengine` in Reddit](https://www.reddit.com/r/ebitengine/)

## License

Ebitengine is licensed under Apache license version 2.0. See [LICENSE](LICENSE) file.

[The Ebitengine logo](https://ebitengine.org/images/logo.png) by Hajime Hoshi is licensed under [the Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/).

### GLFW

https://github.com/glfw/glfw


```
Copyright (c) 2002-2006 Marcus Geelnard

Copyright (c) 2006-2019 Camilla Löwy

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would
   be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not
   be misrepresented as being the original software.

3. This notice may not be removed or altered from any source
   distribution.
```

### Go

https://cs.opensource.google/go/go


```
Copyright (c) 2009 The Go Authors. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   * Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
   * Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```

### go-gl/gl

https://github.com/go-gl/gl


```
The MIT License (MIT)

Copyright (c) 2014 Eric Woroshow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

### go-gl/glfw

https://github.com/go-gl/glfw


```
Copyright (c) 2012 The glfw3-go Authors. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   * Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
   * Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```


Ebitengine

Build your own Game-Engine based on the Entity Component System concept in Golang

<img src="https://github.com/andygeiss/ecs/blob/master/logo.png?raw=true" />


# ECS - Entity Component System

[![License](https://img.shields.io/github/license/andygeiss/ecs)](https://github.com/andygeiss/ecs/blob/master/LICENSE)
[![Releases](https://img.shields.io/github/v/release/andygeiss/ecs)](https://github.com/andygeiss/ecs/releases)
[![Go Report Card](https://goreportcard.com/badge/github.com/andygeiss/ecs)](https://goreportcard.com/report/github.com/andygeiss/ecs)
[![Codacy Grade Badge](https://app.codacy.com/project/badge/Grade/b4f4c9b35f4b46d8bf19f73379864b45)](https://app.codacy.com/gh/andygeiss/ecs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![Codacy Coverage Badge](https://app.codacy.com/project/badge/Coverage/b4f4c9b35f4b46d8bf19f73379864b45)](https://app.codacy.com/gh/andygeiss/ecs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)

Build your own Game-Engine based on the Entity Component System concept in Golang.

## Features

- [x] Provide an **easy-to-use** framework to build a game engine from scratch.
- [x] **No dependencies** to other modules or specific game libraries - Feel free to use what fits your needs.
- [x] **Minimum overhead** - use only what is really needed.

### Example engine

See [engine-example](https://github.com/andygeiss/engine-example) for a basic
implementation using [raylib](https://www.raylib.com).

## Walkthrough

### Project layout

At first we create a basic project layout:

```bash
mkdir ecs-example
cd ecs-example
go mod init example
mkdir components systems
```

Next we create a `main.go` with the following content:

```go
package main

import (
 "github.com/andygeiss/ecs"
)

func main() {
 em := ecs.NewEntityManager()
 sm := ecs.NewSystemManager()
 de := ecs.NewDefaultEngine(em, sm)
 de.Setup()
 defer de.Teardown()
 de.Run()
}
```

The execution of the program leads to an endless loop, as our engine is not yet
able to react to user input.

### The movement system

A system needs to implement the methods defined by the interface
[System](https://github.com/andygeiss/ecs/blob/master/core/system.go).
So we create a new file locally at `systems/movement.go`:

```go
package systems

import (
 "github.com/andygeiss/ecs"
)

type movementSystem struct{}

func (a *movementSystem) Process(em ecs.EntityManager) (state int) {
 // This state simply tells the engine to stop after the first call.
 return ecs.StateEngineStop
}

func (a *movementSystem) Setup() {}

func (a *movementSystem) Teardown() {}

func NewMovementSystem() ecs.System {
 return &movementSystem{}
}
```

Now we can add the following lines to `main.go`:

```go
sm := ecs.NewSystemManager()
sm.Add(systems.NewMovementSystem()) // <--
de := ecs.NewDefaultEngine(em, sm)
```

If we start our program now, it returns immediately without looping forever.

### The player entity

A game engine usually processes different types of components that represent
information about the game world itself. A component only represents the data,
and the systems are there to implement the behavior or game logic and change
these components. Entities are simply a composition of components that provide
a scalable data-oriented architecture.

A component needs to implement the methods defined by the interface
[Component](https://github.com/andygeiss/ecs/blob/master/core/component.go).
Let's define our `Player` components by first creating a mask at
`components/components.go`:

```go
package components

const (
 MaskPosition = uint64(1 << 0)
 MaskVelocity = uint64(1 << 1)
)
```

Then create a component for `Position` and `Velocity` by creating
corresponding files such as `components/position.go`:

```go
package components

type Position struct {
 X float32 `json:"x"`
 Y float32 `json:"y"`
}

func (a *Position) Mask() uint64 {
 return MaskPosition
}

func (a *Position) WithX(x float32) *Position {
 a.X = x
 return a
}

func (a *Position) WithY(y float32) *Position {
 a.Y = y
 return a
}

func NewPosition() *Position {
 return &Position{}
}
```

Now we can add the following lines to `main.go`:

```go
em := ecs.NewEntityManager()
em.Add(ecs.NewEntity("player", []ecs.Component{ // <--
components.NewPosition().
 WithX(10).
 WithY(10),
components.NewVelocity().
 WithX(100).
 WithY(100),
})) // -->
```

### Extend the movement system

Our final step is to add behavior to our movement system:

```go
func (a *movementSystem) Process(em ecs.EntityManager) (state int) {
 for _, e := range em.FilterByMask(components.MaskPosition | components.MaskVelocity) {
 position := e.Get(components.MaskPosition).(*components.Position)
 velocity := e.Get(components.MaskVelocity).(*components.Velocity)
 position.X += velocity.X * rl.GetFrameTime()
 position.Y += velocity.Y * rl.GetFrameTime()
 }
 return ecs.StateEngineStop
}
```

The movement system now moves every entity which has a position and velocity component.

We can replace `ecs.StateEngineStop` with `ecs.StateEngineContinue` later if we add
another system to handle user input.

A rendering system is also essential for a game, so you can use game libraries
such as [raylib](https://www.raylib.com) or
[SDL](https://github.com/libsdl-org/SDL).
This system could look like this with raylib:

```go
// ...
func (a *renderingSystem) Setup() {
 rl.InitWindow(a.width, a.height, a.title)
}

func (a *renderingSystem) Process(em core.EntityManager) (state int) {
 // First check if app should stop.
 if rl.WindowShouldClose() {
 return core.StateEngineStop
 }
 // Clear the screen
 if rl.IsWindowReady() {
 rl.BeginDrawing()
 rl.ClearBackground(rl.Black)
 rl.DrawFPS(10, 10)
 rl.EndDrawing()
 }
 return core.StateEngineContinue
}

func (a *renderingSystem) Teardown() {
 rl.CloseWindow()
}
```

Go implementation of the A\* path finding algorithm

go-astar
========

**A\* pathfinding implementation for Go**

[![Build Status](https://travis-ci.org/beefsack/go-astar.svg?branch=master)](https://travis-ci.org/beefsack/go-astar)

The [A\* pathfinding algorithm](http://en.wikipedia.org/wiki/A*_search_algorithm) is a pathfinding algorithm noted for its performance and accuracy and is commonly used in game development. It can be used to find short paths for any weighted graph.

A fantastic overview of A\* can be found at [Amit Patel's Stanford website](http://theory.stanford.edu/~amitp/GameProgramming/AStarComparison.html).

Examples
--------

The following crude examples were taken directly from the automated tests. Please see `path_test.go` for more examples.

### Key

* `.` - Plain (movement cost 1)
* `~` - River (movement cost 2)
* `M` - Mountain (movement cost 3)
* `X` - Blocker, unable to move through
* `F` - From / start position
* `T` - To / goal position
* `●` - Calculated path

### Straight line

```
.....~...... .....~......
.....MM..... .....MM.....
.F........T. -> .●●●●●●●●●●.
....MMM..... ....MMM.....
............ ............
```

### Around a mountain

```
.....~...... .....~......
.....MM..... .....MM.....
.F..MMMM..T. -> .●●●MMMM●●●.
....MMM..... ...●MMM●●...
............ ...●●●●●....
```

### Blocked path

```
............ 
.........XXX
.F.......XTX -> No path
.........XXX
............
```

### Maze

```
FX.X........ ●X.X●●●●●●..
.X...XXXX.X. ●X●●●XXXX●X.
.X.X.X....X. -> ●X●X.X●●●●X.
...X.X.XXXXX ●●●X.X●XXXXX
.XX..X.....T .XX..X●●●●●●
```

### Mountain climber

```
..F..M...... ..●●●●●●●●●.
.....MM..... .....MM...●.
....MMMM..T. -> ....MMMM..●.
....MMM..... ....MMM.....
............ ............
```

### River swimmer

```
.....~...... .....~......
.....~...... ....●●●.....
.F...X...T.. -> .●●●●X●●●●..
.....M...... .....M......
.....M...... .....M......
```

Usage
-----

### Import the package

```go
import "github.com/beefsack/go-astar"
```

### Implement Pather interface

An example implementation is done for the tests in `path_test.go` for the Tile type.

The `PathNeighbors` method should return a slice of the direct neighbors.

The `PathNeighborCost` method should calculate an exact movement cost for direct neighbors.

The `PathEstimatedCost` is a heuristic method for estimating the distance between arbitrary tiles. The examples in the test files use [Manhattan distance](http://en.wikipedia.org/wiki/Taxicab_geometry) to estimate orthogonal distance between tiles.

```go
type Tile struct{}

func (t *Tile) PathNeighbors() []astar.Pather {
	return []astar.Pather{
		t.Up(),
		t.Right(),
		t.Down(),
		t.Left(),
	}
}

func (t *Tile) PathNeighborCost(to astar.Pather) float64 {
	return to.MovementCost
}

func (t *Tile) PathEstimatedCost(to astar.Pather) float64 {
	return t.ManhattanDistance(to)
}
```

### Call Path function

```go
// t1 and t2 are *Tile objects from inside the world.
path, distance, found := astar.Path(t1, t2)
if !found {
	log.Println("Could not find path")
}
// path is a slice of Pather objects which you can cast back to *Tile.
```

Authors
-------

Michael Alexander <beefsack@gmail.com>
Robin Ranjit Chauhan <robin@pathwayi.com>

go-astar

Go bindings for the [Simple DirectMedia Layer](https://www.libsdl.org/)

For SDL3, please check https://github.com/JupiterRider/purego-sdl3 which doesn't require cgo and uses codegen!

# SDL2 binding for Go [![Build Status](https://github.com/veandco/go-sdl2/actions/workflows/test-build.yml/badge.svg)](https://github.com/veandco/go-sdl2/actions/workflows/test-build.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/veandco/go-sdl2)](https://goreportcard.com/report/github.com/veandco/go-sdl2) [![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com) [![Financial Contributors on Open Collective](https://opencollective.com/veandco/all/badge.svg?label=financial+contributors)](https://opencollective.com/veandco)

`go-sdl2` is SDL2 wrapped for Go users. It enables interoperability between Go and the SDL2 library which is written in C. That means the original SDL2 installation is required for this to work. Note that the first build may take several minutes on machines that are not powerful such as Raspberry Pi.

NOTE: For the latest versions of SDL2, please use the `master` branch!

# Table of Contents
* [Documentation](#documentation)
* [Examples](#examples)
* [Requirements](#requirements)
* [Installation](#installation)
* [Cross-compiling](#cross-compiling)
* [FAQ](#faq)
* [License](#license)


# Documentation
* [GoDoc documentation for go-sdl2](https://godoc.org/github.com/veandco/go-sdl2)
* [Original SDL2 wiki](https://wiki.libsdl.org/SDL2)

# Getting Started

If you haven't created a Go module for your program, you can do it by making a directory called, for example, `app` and running the following command inside it:
```
go mod init app
```

After that you can start writing code that uses `go-sdl2`, for example, like the following:
```go
// main.go
package main

import (
	"github.com/veandco/go-sdl2/sdl"
)

func main() {
	sdl.Init(sdl.INIT_EVERYTHING)
}
```

Then to tell Go to fetch dependencies, you can run:
```
go mod tidy
```

and then the program can be built using:
```
go build
```

After that, you can execute your program:

```
./app
```

# Requirements
* [Go v1.13+](https://go.dev/dl/)
* [SDL2](https://github.com/libsdl-org/SDL/releases)
* [SDL2_image (optional)](https://github.com/libsdl-org/SDL_image/releases)
* [SDL2_mixer (optional)](https://github.com/libsdl-org/SDL_mixer/releases)
* [SDL2_ttf (optional)](https://github.com/libsdl-org/SDL_ttf/releases)
* [SDL2_gfx (optional)](http://www.ferzkopp.net/wordpress/2016/01/02/sdl_gfx-sdl2_gfx/)

On __Ubuntu 22.04 and above__, type:\
`apt install libsdl2{,-image,-mixer,-ttf,-gfx}-dev`

On __Fedora 36 and above__, type:\
`dnf install SDL2{,_image,_mixer,_ttf,_gfx}-devel`

On __Arch Linux__, type:\
`pacman -S sdl2{,_image,_mixer,_ttf,_gfx}`

On __Gentoo__, type:\
`emerge -av libsdl2 sdl2-{image,mixer,ttf,gfx}`

On __macOS__, install SDL2 via [Homebrew](http://brew.sh) like so:\
`brew install sdl2{,_image,_mixer,_ttf,_gfx} pkg-config`

On __Windows__,
1. Install mingw-w64 from [Mingw-builds](https://github.com/niXman/mingw-builds-binaries/releases). A 7z archive extractor software might be needed which can be downloaded [here](https://www.7-zip.org/download.html). In this example, we extract the content, which is `mingw64`, into `C:\`.
2. Download and install `SDL2-devel-[version]-mingw.zip` files from https://github.com/libsdl-org/SDL/releases.
 * Extract the SDL2 folder from the archive using a tool like [7zip](http://7-zip.org)
 * Inside the extracted SDL2 folder, copy the `i686-w64-mingw32` and/or `x86_64-w64-mingw32` into mingw64 folder e.g. `C:\mingw64`
3. Setup `Path` environment variable
 * Put mingw-w64 binaries location into system `Path` environment variable (e.g. `C:\mingw64\bin`)
4. Close and open terminal again so the new `Path` environment variable takes effect. Now we should be able to run `go build` inside the project directory.
5. Download and install SDL2 runtime libraries from https://github.com/libsdl-org/SDL/releases. Extract and copy the `.dll` file into the project directory. After that, the program should become runnable.
6. (Optional) You can repeat __Step 2__ for [SDL_image](https://github.com/libsdl-org/SDL_image/releases), [SDL_mixer](https://github.com/libsdl-org/SDL_mixer/releases), [SDL_ttf](https://github.com/libsdl-org/SDL_ttf/releases)


# Installation
To get the bindings, type:\
`go get -v github.com/veandco/go-sdl2/sdl`\
`go get -v github.com/veandco/go-sdl2/img`\
`go get -v github.com/veandco/go-sdl2/mix`\
`go get -v github.com/veandco/go-sdl2/ttf`\
`go get -v github.com/veandco/go-sdl2/gfx`

or type this if you use Bash terminal:\
`go get -v github.com/veandco/go-sdl2/{sdl,img,mix,ttf}`

Due to `go-sdl2` being under active development, a lot of breaking changes are going to happen during v0.x. With [versioning system](https://github.com/golang/proposal/blob/master/design/24301-versioned-go.md) coming to Go soon, we'll make use of semantic versioning to ensure stability in the future.

# Static compilation

Since v0.3.0, it is possible to build statically against included libraries in `.go-sdl2-libs`. To build statically, run:

`CGO_ENABLED=1 CC=gcc GOOS=linux GOARCH=amd64 go build -tags static -ldflags "-s -w"`

You can also cross-compile to another OS. For example, to Windows:

`CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows GOARCH=amd64 go build -tags static -ldflags "-s -w"`

On Windows, if you would like to hide the Command Prompt window when running the statically-compiled program, you could append `-H windowsgui` to the `-ldflags` value.

For the list of OS and architecture, you can see inside the [.go-sdl2-libs](https://github.com/veandco/go-sdl2/tree/master/.go-sdl2-libs) directory.

NOTE: If you're using the new Go Module system, you will need to refer to the master branch for now by running:

`go get -v github.com/veandco/go-sdl2/sdl@master`

Before building the program.

# Cross-compiling
### Linux to Windows
1. Install MinGW toolchain.
 * On **Arch Linux**, it's simply `pacman -S mingw-w64`.
2. Download the SDL2 development package for MinGW [here](http://libsdl.org/download-2.0.php) (and the others like *SDL_image*, *SDL_mixer*, etc.. [here](https://www.libsdl.org/projects/) if you use them).
3. Extract the SDL2 development package and copy the `x86_64-w64-mingw32` folder inside recursively to the system's MinGW `x86_64-w64-mingw32` folder. You may also do the same for the `i686-w64-mingw32` folder.
 * On **Arch Linux**, it's `cp -r x86_64-w64-mingw32 /usr`.
4. Now you can start cross-compiling your Go program by running `env CGO_ENABLED="1" CC="/usr/bin/x86_64-w64-mingw32-gcc" GOOS="windows" CGO_LDFLAGS="-lmingw32 -lSDL2" CGO_CFLAGS="-D_REENTRANT" go build -x main.go`. You can change some of the parameters if you'd like to. In this example, it should produce a `main.exe` executable file.
5. Before running the program, you need to put `SDL2.dll` from the [SDL2 runtime package](http://libsdl.org/download-2.0.php) (For others like *SDL_image*, *SDL_mixer*, etc.., look for them [here](https://www.libsdl.org/projects/)) for Windows in the same folder as your executable.
6. Now you should be able to run the program using Wine or Windows!

### macOS to Windows
1. Install [Homebrew](https://brew.sh)
2. Install MinGW through Homebrew via `brew install mingw-w64`
3. Download the SDL2 development package for MinGW [here](http://libsdl.org/download-2.0.php) (and the others like *SDL_image*, *SDL_mixer*, etc.. [here](https://www.libsdl.org/projects/) if you use them).
4. Extract the SDL2 development package and copy the `x86_64-w64-mingw` folder inside recursively to the system's MinGW `x86_64-w64-mingw32 folder`. You may also do the same for the `i686-w64-mingw32` folder. The path to MinGW may be slightly different but the command should look something like `cp -r x86_64-w64-mingw32 /usr/local/Cellar/mingw-w64/5.0.3/toolchain-x86_64`.
5. Now you can start cross-compiling your Go program by running `env CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows CGO_LDFLAGS="-L/usr/local/Cellar/mingw-w64/5.0.3/toolchain-x86_64/x86_64-w64-mingw32/lib -lSDL2" CGO_CFLAGS="-I/usr/local/Cellar/mingw-w64/5.0.3/toolchain-x86_64/x86_64-w64-mingw32/include -D_REENTRANT" go build -x main.go`. You can change some of the parameters if you'd like to. In this example, it should produce a `main.exe` executable file.
6. Before running the program, you need to put `SDL2.dll` from the [SDL2 runtime package](http://libsdl.org/download-2.0.php) (For others like *SDL_image*, *SDL_mixer*, etc.., look for them [here](https://www.libsdl.org/projects/)) for Windows in the same folder as your executable.
7. Now you should be able to run the program using Wine or Windows!

### Linux to macOS
1. Install macOS toolchain via [osxcross](https://github.com/tpoechtrager/osxcross)
2. Run the following build command (replace the values in parentheses):
```
CGO_ENABLED=1 CC=[path-to-osxcross]/target/bin/[arch]-apple-darwin[version]-clang GOOS=darwin GOARCH=[arch] go build -tags static -ldflags "-s -w" -a
```

# Examples

NOTE: The following example is for the `master` branch. Please check the [README](https://github.com/veandco/go-sdl2/tree/v0.4.x?tab=readme-ov-file#examples) of `v0.4.x` for the stable version.

```go
package main

import "github.com/veandco/go-sdl2/sdl"

func main() {
	if err := sdl.Init(sdl.INIT_EVERYTHING); err != nil {
		panic(err)
	}
	defer sdl.Quit()

	window, err := sdl.CreateWindow("test", sdl.WINDOWPOS_UNDEFINED, sdl.WINDOWPOS_UNDEFINED, 800, 600, sdl.WINDOW_SHOWN)
	if err != nil {
		panic(err)
	}
	defer window.Destroy()

	surface, err := window.GetSurface()
	if err != nil {
		panic(err)
	}
	surface.FillRect(nil, 0)

	rect := sdl.Rect{0, 0, 200, 200}
	colour := sdl.Color{R: 255, G: 0, B: 255, A: 255} // purple
	pixel := sdl.MapRGBA(surface.Format, colour.R, colour.G, colour.B, colour.A)
	surface.FillRect(&rect, pixel)
	window.UpdateSurface()

	running := true
	for running {
		for event := sdl.PollEvent(); event != nil; event = sdl.PollEvent() {
			switch event.(type) {
			case sdl.QuitEvent: // NOTE: Please use `*sdl.QuitEvent` for `v0.4.x` (current version).
				println("Quit")
				running = false
				break
			}
		}

 sdl.Delay(33)
	}
}
```

There are two ways a game might be running: one that updates on user input using `sdl.WaitEvent()` and one that updates regardless of user input using `sdl.PollEvent()`. You can check the examples of those two loops [here](https://github.com/veandco/go-sdl2-examples/tree/master/examples/gameloop).

For more runnable examples, see https://github.com/veandco/go-sdl2-examples. You can run any of the `.go` files with `go run`.

# FAQ
__Why does the program not run on Windows?__
Try putting the [runtime libraries](http://libsdl.org/download-2.0.php) (e.g. `SDL2.dll` and friends) in the same folder as your program.

__Why does my program crash randomly or hang?__
Putting `runtime.LockOSThread()` at the start of your main() usually solves the problem (see [SDL2 FAQ](https://wiki.libsdl.org/FAQDevelopment) about multi-threading).

UPDATE: Recent update added a call queue system where you can put thread-sensitive code and have it called synchronously on the same OS thread. See the `render_queue` or `render_goroutines` examples from https://github.com/veandco/go-sdl2-examples to see how it works.

__Why can't SDL_mixer seem to play MP3 audio file?__
Your installed SDL_mixer probably doesn't support MP3 file.

On __macOS__, this is easy to correct. First remove the faulty mixer: `brew remove sdl2_mixer`, then reinstall it with the MP3 option: `brew install sdl2_mixer --with-flac --with-fluid-synth --with-libmikmod --with-libmodplug --with-smpeg2`. If necessary, check which options you can enable with `brew info sdl2_mixer`. You could also try installing sdl2\_mixer with mpg123 by running `brew install sdl2_mixer --with-mpg123`.

On __Other Operating Systems__, you will need to compile smpeg and SDL_mixer from source with the MP3 option enabled. You can find smpeg in the `external` directory of SDL_mixer. Refer to issue [#148](https://github.com/veandco/go-sdl2/issues/148) for instructions.

_Note that there seems to be a problem with SDL_mixer 2.0.2 so you can also try to revert back to 2.0.1 and see if it solves your problem_

__Does go-sdl2 support compiling on mobile platforms like Android and iOS?__
For Android, see https://github.com/veandco/go-sdl2-examples/tree/master/examples/android.

There is currently no support for iOS yet.

__Why does my window not immediately render after creation?__
It appears the rendering subsystem needs some time to be able to present the drawn pixels. This can be workaround by adding delay using `sdl.Delay()` or put the rendering code inside a draw loop.

## Contributors

### Code Contributors

This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
<a href="https://github.com/veandco/go-sdl2/graphs/contributors"><img src="https://opencollective.com/veandco/contributors.svg?width=890&button=false" /></a>

### Financial Contributors

Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/veandco/contribute)]

#### Individuals

<a href="https://opencollective.com/veandco"><img src="https://opencollective.com/veandco/individuals.svg?width=890"></a>

#### Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/veandco/contribute)]

<a href="https://opencollective.com/veandco/organization/0/website"><img src="https://opencollective.com/veandco/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/1/website"><img src="https://opencollective.com/veandco/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/2/website"><img src="https://opencollective.com/veandco/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/3/website"><img src="https://opencollective.com/veandco/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/4/website"><img src="https://opencollective.com/veandco/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/5/website"><img src="https://opencollective.com/veandco/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/6/website"><img src="https://opencollective.com/veandco/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/7/website"><img src="https://opencollective.com/veandco/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/8/website"><img src="https://opencollective.com/veandco/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/veandco/organization/9/website"><img src="https://opencollective.com/veandco/organization/9/avatar.svg"></a>

# License
Go-SDL2 is BSD 3-clause licensed.

go-sdl2

Scalable game server engine, featuring space-entity framework and hot-swapping

# GoWorld
_**Scalable Distributed Game Server Engine with Hot Reload in Golang**_


[![GoDoc](https://godoc.org/github.com/xiaonanln/goworld?status.png)](https://godoc.org/github.com/xiaonanln/goworld) 
[![Build Status](https://api.travis-ci.org/xiaonanln/goworld.svg?branch=master)](https://travis-ci.org/xiaonanln/goworld) [![Go Report Card](https://goreportcard.com/badge/github.com/xiaonanln/goworld)](https://goreportcard.com/report/github.com/xiaonanln/goworld) [![codecov](https://codecov.io/gh/xiaonanln/goworld/branch/master/graph/badge.svg)](https://codecov.io/gh/xiaonanln/goworld) 
[![ApacheLicense](https://img.shields.io/badge/license-APACHE%20License-blue.svg)](https://raw.githubusercontent.com/xiaonanln/goworld/master/LICENSE)

  * [Features](#features)
  * [Architecture](#architecture)
  * [Introduction](#introduction)
  * [Get GoWorld](#get-goworld)
  * [Manage GoWorld Servers](#manage-goworld-servers)
  * [Demos](#demos)
    * [Chatroom Demo](#chatroom-demo)
    * [Unity Demo](#unity-demo): [GoWorldUnityDemo.zip](https://drive.google.com/file/d/1A1CJCVWFQWa-iMuAoAdHZ4JoXTtU5Q7z/view?usp=sharing) 
---------------------------------------
#### 中文资料 
> [中文文档](https://godoc.org/github.com/xiaonanln/goworld/cn)  
> [游戏服务器介绍](http://www.cnblogs.com/isaiah/p/7259036.html)  
> [目录结构说明](https://github.com/xiaonanln/goworld/wiki/GoWorld%E6%B8%B8%E6%88%8F%E6%9C%8D%E5%8A%A1%E5%99%A8%E5%BC%95%E6%93%8E%E7%9B%AE%E5%BD%95%E7%BB%93%E6%9E%84)   
> [使用GoWorld轻松实现分布式聊天服务器](https://github.com/xiaonanln/goworld/wiki/%E4%BD%BF%E7%94%A8GoWorld%E6%B8%B8%E6%88%8F%E6%9C%8D%E5%8A%A1%E5%99%A8%E5%BC%95%E6%93%8E%E8%BD%BB%E6%9D%BE%E5%AE%9E%E7%8E%B0%E5%88%86%E5%B8%83%E5%BC%8F%E8%81%8A%E5%A4%A9%E6%9C%8D%E5%8A%A1%E5%99%A8)  


#### 游戏服务端开源引擎GoWorld教程  
1.[安装和运行](https://zhuanlan.zhihu.com/p/66304813 "安装和运行")  
2.[Unity示例双端联调](https://zhuanlan.zhihu.com/p/67065981 "Unity示例双端联调")  
3.[手把手写一个聊天室](https://zhuanlan.zhihu.com/p/67951379 "手把手写一个聊天室")  
4.[多个频道的聊天室](https://zhuanlan.zhihu.com/p/68901701 "多个频道的聊天室")  
5.[登录注册和存储](https://zhuanlan.zhihu.com/p/70039615 "登录注册和存储")  
6.[移动同步和AOI](https://zhuanlan.zhihu.com/p/70778081 "移动同步和AOI")  
7.[源码解析之启动流程和热更新](https://zhuanlan.zhihu.com/p/72093172 "源码解析之启动流程和热更新")  
8.[码解析之gate](https://zhuanlan.zhihu.com/p/73727839 "码解析之gate")  
9.[源码解析之dispatcher](https://zhuanlan.zhihu.com/p/73906406 "源码解析之dispatcher")  
10.[源码解析之entity](https://zhuanlan.zhihu.com/p/74736032 "源码解析之entity")  


---------------------------------------
> **欢迎加入Go服务端开发交流群：[662182346](http://shang.qq.com/wpa/qunwpa?idkey=f2a99bd9bd9e6df3528174180aad753d05b372a8828e1b8e5c1ec5df42b301db)**
---------------------------------------  
## Features
* **Spaces & Entities**: manage multiple spaces and entities with AOI support
* **Distributed**: increase server capacity by using more machines
* **Hot-Swappable**: update game logic by restarting server process
* **Multiple Communication Protocols**: supports TCP, [KCP](https://github.com/skywind3000/kcp) and WebSocket
* **Traffic Compression & Encryption**: traffic between clients and servers can be compressed and encrypted

## Architecture
![GoWorld Architecture](https://docs.google.com/drawings/d/e/2PACX-1vS20sn1rD-x23P6PpBV-C4Uy5BI6vry4TjKV9pBPtmoghlkH_aP24Ip4usyUciPRC6tpvsJX4Gufgvj/pub?w=960&h=720 "GoWorld Architecture")

## Introduction
GoWorld server adopts an entity framework, in which entities represent all players, monsters, NPCs.
Entities in the same space can visit each other directly by calling methods or access attributes. 
Entities in different spaces can call each over using RPC.

A GoWorld server consists of one dispatcher, one or more games and one or more gates. 
The gates are responsible for handling client connections and receive/send packets from/to clients. 
The games manages all entities and runs all game logic. 
The dispatcher is responsible for redirecting packets among games and between games and gates.  

The game processes are **hot-swappable**. 
We can swap a game by sending `SIGHUP` to the process and restart the process with **-restore** parameter to bring game 
back to work but with the latest executable image. This feature enables updating server-side logic or fixing server bugs
 transparently without significant interference of online players. 

## Installing GoWorld
GoWorld requries Go 1.11+ to install.
```bash
go install github.com/xiaonanln/goworld/cmd/...
``` 

## Manage GoWorld Servers
Use command `goworld` to build, start, stop and reload game servers. 

**Build Example Chatroom Server:**
```bash
$ goworld build examples/chatroom_demo
```

**Start Example Chatroom Server: (dispatcher -> game -> gate)**
```bash
$ goworld start examples/chatroom_demo
``` 

**Stop Game Server (gate -> game -> dispatcher):**
```bash
$ goworld stop examples/chatroom_demo
```

**Reload Game Servers:**
```bash
$ goworld reload examples/chatroom_demo
```
Reload will reboot game processes with the current executable while preserving all game server states. 
**However, it does not work on Windows.**

**List Server Processes:**
```bash
$ goworld status examples/chatroom_demo
> 1 dispatcher running, 1/1 gates running, 1/1 games (examples/chatroom_demo) running
> 	2763      dispatcher      /home/ubuntu/go/src/github.com/xiaonanln/goworld/components/dispatcher/dispatcher -dispid 1
> 	2770      chatroom_demo   /home/ubuntu/go/src/github.com/xiaonanln/goworld/examples/chatroom_demo/chatroom_demo -gid 1
> 	2779      gate            /home/ubuntu/go/src/github.com/xiaonanln/goworld/components/gate/gate -gid 1
```  

## Demos

### Chatroom Demo
The chatroom demo is a simple implementation of chatroom server and client. It illustrates how
GoWorld can also be used for games which don't divide players by spaces. 

The chatroom demo provides following features:
* register & login
* send chat message
* switch chatrooms

**Build Server:**
```bash
goworld build examples/chatroom_demo
```
**Run Server:**
```bash
goworld start examples/chatroom_demo
```

**Chatroom Demo Client:**

Chatroom demo client implements the client-server protocol in Javascript.  
The client for chatroom demo is hosted at [github.com/xiaonanln/goworld-chatroom-demo-client](https://github.com/xiaonanln/goworld-chatroom-demo-client).
The project was created and built in [Cocos Creater 1.5](http://www.cocos2d-x.org/). 

### Unity Demo
Unity Demo is a simple multiple player monster shooting game to show how spaces and entities of GoWorld
can be used to create multiple player online games.  

* register & login
* move players in space
* summon monsters
* player shoot monsters
* monsters attack players

Developing features:
* Hit effects
* Players migrate among multiple spaces
* Server side map navigation

**Build Server:**
```bash
goworld build examples/unity_demo
```
**Run Server:**
```bash
goworld start examples/unity_demo
```

**Unity Demo Client:**

Unity demo client implements the client-server protocol in C#. 
The client for unity demo is hosted at [https://github.com/xiaonanln/goworld-unity-demo](https://github.com/xiaonanln/goworld-unity-demo).
The project was created and built in [Unity 2017.1](https://unity3d.com/). 

You can try the demo by downloading [GoWorldUnityDemo.zip](https://drive.google.com/file/d/1A1CJCVWFQWa-iMuAoAdHZ4JoXTtU5Q7z/view?usp=sharing). 
The demo connects to a goworld server on Huawei Cloud instance.


goworld

Generic 2D grid with ray-casting, shadow-casting and path finding

[![PkgGoDev](https://pkg.go.dev/badge/github.com/s0rg/grid)](https://pkg.go.dev/github.com/s0rg/grid)
[![License](https://img.shields.io/github/license/s0rg/grid)](https://github.com/s0rg/grid/blob/master/LICENSE)
[![Go Version](https://img.shields.io/github/go-mod/go-version/s0rg/grid)](go.mod)
[![Tag](https://img.shields.io/github/v/tag/s0rg/grid?sort=semver)](https://github.com/s0rg/grid/tags)

[![CI](https://github.com/s0rg/grid/workflows/ci/badge.svg)](https://github.com/s0rg/grid/actions?query=workflow%3Aci)
[![Go Report Card](https://goreportcard.com/badge/github.com/s0rg/grid)](https://goreportcard.com/report/github.com/s0rg/grid)
[![Maintainability](https://qlty.sh/badges/2683df5e-28a8-4d8d-87da-295f252742d4/maintainability.svg)](https://qlty.sh/gh/s0rg/projects/grid)
[![Code Coverage](https://qlty.sh/badges/2683df5e-28a8-4d8d-87da-295f252742d4/test_coverage.svg)](https://qlty.sh/gh/s0rg/projects/grid)
![Issues](https://img.shields.io/github/issues/s0rg/grid)

# grid

Generic 2D grid

# features

- [DDA RayCasting](https://lodev.org/cgtutor/raycasting.html)
- [A-Star pathfinding](https://en.wikipedia.org/wiki/A*_search_algorithm)
- [Ray-based line of sight](https://en.wikipedia.org/wiki/Line_of_sight_(video_games))
- [Recursive ShadowCasting](http://www.roguebasin.com/index.php/Shadow_casting)
- [Dijkstra maps](http://www.roguebasin.com/index.php/Dijkstra_Maps_Visualized)
- [Bresenham's lines](https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm)
- 100% test cover

# usage

```go
import (
    "image"

    "github.com/s0rg/grid"
)

const mapW, mapH = 100, 100

func valueExample() {
    // working with value-types is straightforward
    g := grid.New[int](image.Rect(0, 0, mapW, mapH))

    // now grid is filled with nil-value for your type
    // you still can re-fill it with some other values:
    g.Fill(func() int {
        return 1
    })
}

func pointerExample() {
    // working with pointer-types is same, but you now you must to pre-fill them
    type mycell struct {}

    g := grid.New[*mycell](image.Rect(0, 0, mapW, mapH))

    // now grid is filled with nil's, so you need pre-fill it with some values,
    // otherwise you will access those nil's with Get / MustGet methods.
    g.Fill(func() *mycell {
        return &mycell{}
    })
}

func usageExample() {
    type mycell struct {
        wall bool
    }

    g := grid.New[*mycell](image.Rect(0, 0, mapW, mapH))

    g.Fill(func() *mycell {
        return &mycell{}
    })

    pt := image.Pt(10, 10)

    // set new value
    g.Set(pt, &mycell{wall: true})

    // update existing value
    if v, ok := g.Get(pt); ok {
        v.wall = false
    }

    // shorthand, for above, will panic on out-of-bounds access
    g.MustGet(pt).wall = true

    // iterate items
    g.Iter(func(p image.Point, c *mycell) (next bool) {
        if c.wall {
            // wall found
        }

        return true
    })
}
```

# example

[Here](https://github.com/s0rg/grid/blob/master/_example/main.go) is a full example.

You can run it with `go run _example/main.go` to see results.

# benchmarks

run:

```bash
make bench
```

results:

```
goos: linux
goarch: amd64
pkg: github.com/s0rg/grid
cpu: AMD Ryzen 5 5500U with Radeon Graphics
BenchmarkGrid/Set-12         	1000000000	        0.8108 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/Get-12         	641611768	        1.764 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/Neighbours-12  	52243890	       23.41 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/LineBresenham-12         	4416172	      269.0 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/CastRay-12               	3829839	      321.1 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/CastShadow-12            	  32648	    36950 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/LineOfSight-12           	   9897	   114576 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/DijkstraMap-12           	   1029	  1190195 ns/op	  20656 B/op	      3 allocs/op
BenchmarkGrid/Path-12                  	    372	  3225325 ns/op	 997588 B/op	  13643 allocs/op
PASS
ok  	github.com/s0rg/grid	12.098s
```


grid

Game engine for creating retro games for modern computers. Inspired by Pico-8 and powered by Ebitengine

# pi <img src="docs/logo.svg" align="right" style="width: 10%"/>

[![Go Reference](https://pkg.go.dev/badge/github.com/elgopher/pi.svg)][pi-godoc]
[![codecov](https://codecov.io/gh/elgopher/pi/branch/master/graph/badge.svg)][pi-codecov]
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)][repostatus-active]
[![Go Report Card](https://goreportcard.com/badge/github.com/elgopher/pi)](https://goreportcard.com/report/github.com/elgopher/pi)

## Table of Contents

- [Introduction](#introduction)
- [What defines the retro games made with Pi?](#what-defines-the-retro-games-made-with-pi)
- [Why Pi?](#why-pi)
- [How to get started?](#how-to-get-started)
- [How does it work?](#how-does-it-work)
- [FAQ](#faq)
- [Attributions](#attributions)

## Introduction

Pi is a game engine for creating retro games for modern computers. Its goal is to limit possibilities — to spark creativity and increase the chance of actually finishing your game. Too much freedom often leads to overly ambitious and never-ending projects. Pi was inspired by [Pico-8][pico-8] and is powered by [Ebitengine][ebitengine].

Although Pi was inspired by fantasy consoles, it is **not** one itself. It doesn't emulate a fictional machine. Instead, it's a real Go library with dev-tools that make it simple (and fun!) to build retro games that run natively on modern hardware.

[![Snake game example](docs/screenshot-snake.png)](_examples/snake)

## What defines the retro games made with Pi?

They resemble games from 8-bit and 16-bit computers, because:
* they run at (very) low resolutions — like 128×128 or 320×180
* they use only 64 colors displayed on screen at once
* they use graphics rendered directly by the CPU — just like in early home computers
* they use sound effects and music made from short, looped audio samples. The audio output is generated by mixing 4 channels.
* they work with limited resources — such as 256 sprites or tile maps with just a few thousand tiles
* their code is short — thousands, not millions, of lines
* they use game controllers with a small number of buttons

## Why Pi?

Because it's probably the easiest and most fun way to write a game in Go. No complex engine setup. No boilerplate. Just write code and see things happen. Perfect for small projects, prototypes, jams — or simply to have fun.

## How to get started?

1. Install dependencies
 * [Go 1.24+][go-downloads]
 * If you are not on Windows, install additional dependencies for:
 * [Linux](docs/install-linux.md)
 * [macOS](docs/install-macos.md)

2. Try examples from the [_examples](_examples) directory
 * Run the Snake example directly:
 ```bash
 go run github.com/elgopher/pi/_examples/snake@HEAD
 ```
 * Or clone the Pi repository and modify the example:
 ```bash
 git clone https://github.com/elgopher/pi
 cd pi/_examples/snake
 # edit main.go to experiment
 go run .
 ```

3. Create a new game
 * Create a new Go module and add Pi as a dependency:
 ```bash
 mkdir mygame
 cd mygame
 go mod init mygame
 go get github.com/elgopher/pi@latest
 ```
 * Create main.go:
 ```go
 package main
 
 import (
 "github.com/elgopher/pi" // import pi core package
 "github.com/elgopher/pi/picofont" // import very small pico-8 font
 "github.com/elgopher/pi/piebiten" // import backend
 )
 
 func main() {
 pi.SetScreenSize(47, 9) // set custom screen size
 pi.Draw = func() { // draw will be executed each frame
 picofont.Print("HELLO WORLD", 2, 2)
 }
 piebiten.Run() // run backend
 }
 ```
 * Tidy go.mod file after importing Pi packages
 ```bash
 go mod tidy
 ```
 * Run the game:
 ```bash
 go run .
 ```


4. Explore further
 * Read the rest of this README.md
 * Check out the [godoc documentation][pi-godoc]

## How does it work?

Pi is designed to make writing a game as simple as possible — even if you've never made one before. 
It gives you just a few core concepts and keeps things minimal, so you can focus on making something fun.

---

### Game loop

Pi runs your game in a loop. In each frame, it calls two functions you define:

* `pi.Update` — where you put your game logic, e.g. handling input. 
* `pi.Draw` — where you put your rendering code. It runs right after `pi.Update`.

By default, Pi runs these functions 30 times per second, but this is configurable.

---

### Backend

Pi has a modular architecture that allows using different backends. 
A backend is a low-level package that runs your game on different devices. 

Currently, the recommended backend is [piebiten](piebiten), which supports Windows, macOS, Linux, and more, using Ebitengine under the hood.

Here's a minimal example that displays "HELLO WORLD" on a 47×9 pixel screen using the piebiten backend:

```go
package main

import (
 "github.com/elgopher/pi" // core package
 "github.com/elgopher/pi/picofont" // tiny Pico-8 font
 "github.com/elgopher/pi/piebiten" // backend
)

func main() {
 pi.SetScreenSize(47, 9) // set custom screen size
 pi.Draw = func() { // draw runs each frame
 picofont.Print("HELLO WORLD", 2, 2)
 }
 piebiten.Run() // run the backend
}
````

When Pi opens a window for your game, it automatically adjusts the window size to match your monitor's resolution. Since modern monitors have much higher resolutions (e.g. 1920×1080 or even 3840×2160), Pi needs to scale up the game screen. Each game pixel is multiplied an integer number of times (integer scaling). This ensures that the game screen always stays true to its original pixel-perfect look without any distortion.

---

### Game screen

Pi gives you a small, low-resolution pixel canvas to draw on. It's like an old-school screen: you can set pixels, draw lines, rectangles, sprites, and text. The limited resolution encourages you to focus on clear shapes and designs.

Each pixel on the game screen has (x, y) coordinates and a `pi.Color`. `pi.Color` is a number from 0 to 63, letting you use up to 64 colors on screen at once. Coordinate (0,0) is the top-left corner of the screen.

Pi does not impose any fixed screen size — you can choose resolutions like 128×128 or 320×180. However, there's a limit on the total number of pixels: 128 KB (131,072 pixels). It's recommended to start with a low resolution for your first game, such as 128×128.

---

### Color palette

Pi uses a game-defined, configurable `pi.Palette` which maps each `pi.Color` to an RGB value. For example, by default color 0 is black (0x000000), and color 7 is white (0xFFF1E8).

You choose your game's palette, but you're limited to 64 colors. That may seem small, but for low-resolution pixel-art it's usually plenty.
The palette can be changed during the game, but changes will appear only when rendering the frame at the end of the update cycle.

---

### Canvas, sprites, and blitting

`pi.Canvas` is a 2D structure storing color values. The game screen itself is a Canvas. Your game can not only draw pixels on a Canvas but also read them back.

This makes it possible to copy pixels from one Canvas to another — for example, you can load a PNG file into a Canvas and then copy (blit) parts of it onto the game screen.

These source images (PNG files with your art) are typically called **sprite sheets**. Pi can decode them into Canvases and help you define sprites that you then blit onto the screen.

---

### Keyboard, mouse, and gamepad input

Pi lets you check the state of buttons on various input devices. To make sure games work across different hardware, Pi defines a subset of buttons that exist on most modern keyboards, mice, and gamepads.

Pi also tries to offer only the kinds of input that were typical in the 16-bit era. For example, mice had just two buttons, and gamepads had only simple digital (on/off) buttons — no analog sticks or triggers.

For handling input devices, you can use these packages: [pikey](pikey), [pimouse](pimouse), and [pipad](pipad).

---

### Audio

Pi audio system is inspired by the Paula audio chip used in Amiga computers.

In Pi, sound is generated in 4 independent channels, which are then mixed to stereo output: channels 0 and 3 are mixed to the left speaker, and channels 1 and 2 to the right.

Each channel plays a single audio sample at a time, which means you can play 4 different samples simultaneously. A channel, in addition to holding the current sample, also stores parameters such as pitch, volume, and loop, which affect how the sound is generated. These parameters can be updated in real-time to play sound effects and music.

Pi only supports samples encoded in 8-bit mono PCM format. 

You can control audio generation with the [piaudio](piaudio) package.

---

### Concurrency

Most of Pi's code is **not** thread-safe. This is an intentional design choice to significantly improve performance. 
You should not call Pi's API from any goroutine other than the one running your `pi.Update` and `pi.Draw` functions.

You can still create your own goroutines in your game, but they must not call any Pi functions or access Pi state (unless the package documentation explicitly says it's safe).

---

### Philosophy: Limitations Make It Fun

Pi intentionally limits:

* screen resolution
* color palette
* number of audio channels

These constraints force you to be creative and keep things simple. It's easier to finish a game when you don't try to do everything at once.
The goal is to have fun, not get lost in complexity!

## FAQ

### Is Pi ready to use?

Yes — the core functionality is implemented and ready to use. Currently, the focus is on developer tools like [piscope](piscope).

Note: Pi does not yet have high-level APIs for music playback. However, there is a low-level [piaudio](piaudio) API that can be used to create custom packages for playing, for example, [MOD][mod] and [XM][xm] modules.

### What similarities does Pi have with Pico-8/Picotron on the API level?

* Many core concepts are similar: game loop, drawing sprites and shapes, printing text, clipping, camera movement, palette swapping, color tables, and handling input.
* The screen resolution is small and the number of colors is limited — just like in Pico-8. 
 However, in Pi you can freely change the resolution and customize the palette.

### Can I use Pi in a game that already uses Ebitengine?

Yes! You can use the [piebiten](piebiten) package to integrate Pi with your existing Ebitengine project. For example, you can copy pixel data from `pi.Canvas` into an `ebiten.Image`.

### What platforms do Pi games run on?

Pi runs on all platforms supported by Ebitengine. However, it is currently tested only on Windows, Linux, and web browsers.

### Can I write my own backend for Pi instead of Ebitengine?

Yes! You can create a specialized backend that runs on unusual devices or is optimized for a specific architecture. For example, there's [piweb][piweb] — an experimental backend for web browsers. Its goal is to cut the size of the generated WASM program roughly in half, which can be important for small browser-based games.

### How can I contribute to Pi's development?

The best way to help Pi grow is by creating your own packages that add new or improved features. Pi is designed so that anyone can extend it without needing to contribute code directly to the main Pi repository. 
Examples of useful packages include:

* developer tools that other programmers can run directly in their games
* packages for generating sound
* packages for drawing
* new backends

### What tools are recommended for making games with Pi?

First of all, you'll need a good Go editor. I recommend GoLand (paid) or Visual Studio Code.

For creating sprites, I highly recommend [Aseprite][aseprite] — probably the best pixel-art editor ever made. It has tons of features, scripting support, and can export images with metadata. In general, try to use the same color indices in your graphics program and in your game code. It really simplifies game development. Aseprite is one of the tools that supports editing images with indexed colors.

For creating tile maps, I recommend [Tiled][tiled].

### How can I persist game state or settings?

Pi itself doesn't include built-in save/load APIs. To store your game's progress or settings, you can use the external Go module [quasilyte/gdata][quasilyte-gdata].

### I have more questions or found a bug. Where can I ask?

Please open an [Issue][issues] or start a [Discussion][discussions] on GitHub. Questions, ideas, bug reports, and contributions are all welcome!

## Attributions

* [picofont](picofont) package uses [original Pico-8 font][pico-8-faq] created by Zep - [CC-0 license][cc-0]
* default palette is the [original Picotron palette][picotron-faq] created by Zep

[aseprite]: https://www.aseprite.org/
[cc-0]: https://creativecommons.org/publicdomain/zero/1.0/
[discussions]: https://github.com/elgopher/pi/discussions
[ebitengine]: https://ebiten.org/
[ebitengine-audio]: https://ebitengine.org/en/examples/#Audio
[go-downloads]: https://go.dev/dl/
[issues]: https://github.com/elgopher/pi/issues
[mod]: https://en.wikipedia.org/wiki/Module_file
[pico-8]: https://www.lexaloffle.com/pico-8.php
[pico-8-faq]: https://www.lexaloffle.com/pico-8.php?page=faq
[picotron-faq]: https://www.lexaloffle.com/picotron.php?page=faq
[piweb]: https://github.com/elgopher/piweb
[pi-codecov]: https://codecov.io/gh/elgopher/pi
[pi-godoc]: https://pkg.go.dev/github.com/elgopher/pi
[pi-template]: https://github.com/elgopher/pi-template
[quasilyte-gdata]: https://github.com/quasilyte/gdata
[quasilyte-xm]: https://github.com/quasilyte/xm
[repostatus-active]: https://www.repostatus.org/#active
[tiled]: https://www.mapeditor.org/
[xm]: https://en.wikipedia.org/wiki/XM_(file_format)

# __**Important Notice **__
Revived fork of the original [Pixel](https://github.com/faiface/pixel) library by [faiface](https://github.com/faiface). This fork is intended to be a community-driven effort to continue the development of the library. We were unable to get a hold of the original author, to take ownership of the original repository to carry on the legacy of the wonderful work. If you are interested in contributing, please join us in the [Discord Chat!](https://discord.gg/n2Y8uVneK6)


<img src="logo/LOGOTYPE-HORIZONTAL-BLUE2.png">


# Pixel 2
[![Go Reference](https://pkg.go.dev/badge/github.com/gopxl/pixel/v2.svg)](https://pkg.go.dev/github.com/gopxl/pixel/v2)
[![Go build status](https://github.com/gopxl/pixel/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/gopxl/pixel/actions/workflows/go.yml?query=branch%3Amain)
[![Coverage Status](https://coveralls.io/repos/github/gopxl/pixel/badge.svg?branch=main)](https://coveralls.io/github/gopxl/pixel?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/gopxl/pixel/v2)](https://goreportcard.com/report/github.com/gopxl/pixel/v2) 
[![Discord Chat](https://img.shields.io/discord/1158461233121468496)](https://discord.gg/hPBTTXGDU3) 

A hand-crafted 2D game library in Go. Take a look into the [features](#features) to see what it can
do.

```
go get github.com/gopxl/pixel/v2
```

If you are using Modules (Go 1.11 or higher) and want a mutable copy of the source code:

```
git clone https://github.com/gopxl/pixel # clone outside of $GOPATH
cd pixel
go install ./...
```

See [requirements](#requirements) for the list of libraries necessary for compilation.

## Tutorial

The [Wiki of this repo](./docs/README.md) contains an extensive tutorial
covering several topics of Pixel. 

For the tutorial walking through the basics of Pixel, check out [The Basics](./docs/Basics/Creating-a-Window.md)!

## [Examples](https://github.com/gopxl/pixel-examples)

The [examples](https://github.com/gopxl/pixel-examples) repository contains a few
examples demonstrating Pixel's functionality.

**To run an example**, navigate to it's directory, then `go run` the `main.go` file. For example:

```
$ cd pixel-examples/platformer
$ go run main.go
```

Here are some screenshots from the examples!

| [Lights](https://github.com/gopxl/pixel-examples/blob/main/lights) | [Platformer](https://github.com/gopxl/pixel-examples/blob/main/platformer) |
| --- | --- |
| ![Lights](https://github.com/gopxl/pixel-examples/blob/main/lights/screenshot.png) | ![Platformer](https://github.com/gopxl/pixel-examples/blob/main/platformer/screenshot.png) |

| [Smoke](https://github.com/gopxl/pixel-examples/blob/main/smoke) | [Typewriter](https://github.com/gopxl/pixel-examples/blob/main/typewriter) |
| --- | --- |
| ![Smoke](https://github.com/gopxl/pixel-examples/blob/main/smoke/screenshot.png) | ![Typewriter](https://github.com/gopxl/pixel-examples/blob/main/typewriter/screenshot.png) |

| [Raycaster](https://github.com/gopxl/pixel-examples/blob/main/community/raycaster) | [Gizmo](https://github.com/Lallassu/gizmo) |
| --- | --- |
| ![Raycaster](https://github.com/gopxl/pixel-examples/blob/main/community/raycaster/screenshot.png) | ![Gizmo](https://github.com/Lallassu/gizmo/blob/master/preview.png) |

## Release Schedule
We aim to release a new version the 1st of every month.

## Features

Here's the list of the main features in Pixel. Although Pixel is still under heavy development,
**there should be no major breakage in the API.** This is not a 100% guarantee, though.

- Fast 2D graphics
 - Sprites
 - Primitive shapes with immediate mode style
 [IMDraw](./docs/Basics/Drawing-shapes-with-IMDraw.md) (circles, rectangles,
 lines, ...)
 - Optimized drawing with [Batch](./docs/Basics/Drawing-efficiently-with-Batch.md)
 - Text drawing with [text](https://godoc.org/github.com/gopxl/pixel/v2/text) package
- Audio through a separate [Beep](https://github.com/gopxl/beep) library.
- Simple and convenient API
 - Drawing a sprite to a window is as simple as `sprite.Draw(window, matrix)`
 - Wanna know where the center of a window is? `window.Bounds().Center()`
 - [...](https://godoc.org/github.com/gopxl/pixel/v2)
- Full documentation and tutorial
- Works on Linux, macOS and Windows
- Window creation and manipulation (resizing, fullscreen, multiple windows, ...)
- Keyboard (key presses, text input) and mouse input without events
- Well integrated with the Go standard library
 - Use `"image"` package for loading pictures
 - Use `"time"` package for measuring delta time and FPS
 - Use `"image/color"` for colors, or use Pixel's own `color.Color` format, which supports easy
 multiplication and a few more features
 - Pixel uses `float64` throughout the library, compatible with `"math"` package
- Geometry transformations with
 [Matrix](./docs/Basics/Moving,-scaling-and-rotating-with-Matrix.md)
 - Moving, scaling, rotating
 - Easy camera implementation
- Off-screen drawing to Canvas or any other target (Batch, IMDraw, ...)
- Fully garbage collected, no `Close` or `Dispose` methods
- Full [Porter-Duff](http://ssp.impulsetrain.com/porterduff.html) composition, which enables
 - 2D lighting
 - Cutting holes into objects
 - Much more...
- Pixel let's you draw stuff and do your job, it doesn't impose any particular style or paradigm
- Platform and backend independent [core](https://godoc.org/github.com/gopxl/pixel/v2)
- Core Target/Triangles/Picture pattern makes it easy to create new drawing targets that do
 arbitrarily crazy stuff (e.g. graphical effects)
- Small codebase, ~5K lines of code, including the backend [glhf](https://github.com/gopxl/glhf/v2)
 package

 ## Related repositories

 Here are some packages which use Pixel:
 - [TilePix](https://github.com/bcvery1/tilepix) Makes handling TMX files built with [Tiled](https://www.mapeditor.org/) trivially easy to work with using Pixel.
 - [spriteplus](https://github.com/cebarks/spriteplus) Basic `SpriteSheet` and `Animation` implementations
 - [PixelUI](https://github.com/dusk125/pixelui) Imgui-based GUIs for Pixel
 - [pixelutils](https://github.com/dusk125/pixelutils) Variety of game related utilities (sprite packer, id generator, ticker, sprite loader, voronoia diagrams)

## Missing features

Pixel is in development and still missing few critical features. Here're the most critical ones.

- ~~Audio~~
- ~~Drawing text~~
- Antialiasing (filtering is supported, though)
- ~~Advanced window manipulation (cursor hiding, window icon, ...)~~
- Better support for Hi-DPI displays
- Mobile (and perhaps HTML5?) backend
- ~~More advanced graphical effects (e.g. blur)~~ (solved with the addition of GLSL effects)
- Tests and benchmarks
- Vulkan support

**Implementing these features will get us to the 1.0 release.** Contribute, so that it's as soon as
possible!

## Requirements

If you're using Windows and having trouble building Pixel, please check [this guide](./docs/Compilation/Building-Pixel-on-Windows.md) on the [wiki](./docs/README.md).

OpenGL development libraries are needed for compilation. The dependencies
are same as for [GLFW](https://github.com/go-gl/glfw).

The OpenGL version used is **OpenGL 3.3**.

- On macOS, you need Xcode or Command Line Tools for Xcode (`xcode-select --install`) for required
 headers and libraries.
- On Ubuntu/Debian-like Linux distributions, you need `libgl1-mesa-dev` and `xorg-dev` packages.
- On CentOS/Fedora-like Linux distributions, you need `libX11-devel libXcursor-devel libXrandr-devel
 libXinerama-devel mesa-libGL-devel libXi-devel libXxf86vm-devel` packages.
- On Linux to use Wayland instead of X11, compile your project with `-tags wayland`.
- See [here](http://www.glfw.org/docs/latest/compile.html#compile_deps) for full details.

**The combination of Go 1.8, macOS and latest XCode seems to be problematic** as mentioned in issue
[#7](https://github.com/gopxl/pixel/v2/issues/7). This issue is probably not related to Pixel.
**Upgrading to Go 1.8.1 fixes the issue.**

### Windows Subsystem for Linux

While pixel does run on Windows, you will likely have significantly better performance running in WSL2, which now has support for GUI applications built-in with WSLg.

Installation instructions [here](https://github.com/microsoft/wslg?tab=readme-ov-file#installing-wslg). If you already have an old version of WSL installed, 
make sure to follow the upgrade instructions to get WSL2 as well as update your distribution of choice to version 2. Additionally, if you have an old `DISPLAY` environment variable set in your ~/.bashrc (or equivalent) for WSL1, you should remove it. This is now configured automatically.

Once WSL is setup, follow the usual Go and OpenGL installation instructions for your chosen distribution of linux.

Finally, add `export LIBGL_ALWAYS_INDIRECT=0` to your ~/.bashrc (or equivalent) if you see an error like `Error: creating window failed: VersionUnavailable: GLX: Failed to create context: GLXBadFBConfig` when attempting to launch an OpenGL application from WSL.

## Cross Platform Build

Go supports cross platform build targets natively, but because pixel depends on [CGo](https://pkg.go.dev/cmd/cgo) it is necessary to specify a C cross-compiler that is compatible with the target.

### Linux to Windows

To build a windows executable on linux, you will need to install a windows C compiler, such as mingw. The following commands can be used to build for an amd64 architecture on windows.

Install mingw on linux with apt:
```sh
sudo apt update
sudo apt install gcc-mingw-w64
```

Build for windows amd64
```sh
GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CXX=x86_64-w64-mingw32-g++ CC=x86_64-w64-mingw32-gcc go build
```

## Contributing

Join us in the [Discord Chat!](https://discord.gg/n2Y8uVneK6)

Pixel is currently in a developmental phase, with many of its key features already in place, while others are still in the works. 
We genuinely appreciate and value contributions, as they can significantly expedite the development process. I invite everyone to 
contribute in any way they can, even if it's just sharing an idea. We especially value the submission of issues and pull requests.

That said, it's **important to remember that Pixel is being developed with a great deal of thought and attention to detail**. Each component 
has gone through numerous design iterations to ensure quality. We place a high premium on code and API quality, with an emphasis on simplicity and expressiveness.
When contributing, please bear these goals in mind. This doesn't mean that only flawless pull requests will be accepted. Rather, it 
means that there may be times when a proposal might not align with our vision, or when a pull request might require some revisions. 
This is completely normal and should not discourage you. After all, our shared goal is to achieve the best end result possible.

Take a look at [CONTRIBUTING.md](CONTRIBUTING.md) for further information.

## License

[MIT](LICENSE)

## Special Contributions

- A significant shoutout to the original author [faiface](https://github.com/faiface) for starting and growing the Pixel community. We would not be here if not for him.
- The active/inactive maintainers of the original Pixel repo:
 - [dusk125](https://github.com/dusk125)
 - [cebarks](https://github.com/cebarks)
 - [Benjyclay](https://github.com/Benjyclay)
 - [delp](https://github.com/delp)
 - [roipoussiere](https://github.com/roipoussiere)

Performance oriented 2D/3D math package for Go

# go3d

Performance-oriented 3D math library for Go, optimized for graphics programming, game development, and scientific computing.

[![Go Reference](https://pkg.go.dev/badge/github.com/ungerik/go3d.svg)](https://pkg.go.dev/github.com/ungerik/go3d)
[![Go Report Card](https://goreportcard.com/badge/github.com/ungerik/go3d)](https://goreportcard.com/report/github.com/ungerik/go3d)

## Features

- **Zero-allocation value types**: Stack-allocated arrays for maximum performance
- **Dual precision**: Both float32 and float64 versions of all types
- **Method chaining**: In-place operations return `*T` for fluent API
- **Immutable operations**: Past-tense methods return copies without modifying originals
- **OpenGL compatible**: Column-major matrices, right-handed coordinates
- **Cache-friendly**: Optimized data structures for modern CPU caches
- **Well-tested**: Comprehensive test coverage with benchmarks

## Installation

```bash
go get github.com/ungerik/go3d
```

## Quick Start

```go
package main

import (
 "github.com/ungerik/go3d/vec3"
 "github.com/ungerik/go3d/mat4"
 "github.com/ungerik/go3d/quaternion"
 math "github.com/chewxy/math32"
)

func main() {
 // Vector operations
 a := vec3.T{1, 2, 3}
 b := vec3.UnitX

 // In-place modification with chaining
 a.Add(&b).Scale(5) // a is now {10, 10, 15}

 // Immutable operations
 c := a.Scaled(0.5) // c = {5, 5, 7.5}, a unchanged

 // Matrix transformations
 var transform mat4.T
 transform.AssignPerspective(math.Pi/4, 16.0/9.0, 0.1, 1000.0)

 // Quaternions for rotations
 q := quaternion.FromYAxisAngle(math.Pi / 4) // 45° around Y
 rotated := q.RotatedVec3(&a)
}
```

## Package Organization

Every type has its own sub-package and is named `T`. Packages under `float64/` use `float64` instead of `float32`.

### Main Packages (float32)

| Package | Description | Type Size |
|---------|-------------|-----------|
| `vec2` | 2D vectors | 8 bytes |
| `vec3` | 3D vectors | 12 bytes |
| `vec4` | 4D vectors / homogeneous coordinates | 16 bytes |
| `mat2` | 2×2 matrices | 16 bytes |
| `mat3` | 3×3 matrices | 36 bytes |
| `mat4` | 4×4 matrices | 64 bytes (one cache line!) |
| `quaternion` | Quaternions for 3D rotations | 16 bytes |

### Float64 Packages

All types are available in float64 precision under `float64/`:

- `float64/vec2`, `float64/vec3`, `float64/vec4`
- `float64/mat2`, `float64/mat3`, `float64/mat4`
- `float64/quaternion`

### Utility Packages

- `generic` - Generic matrix/vector interfaces
- `hermit2` - 2D Hermite splines
- `hermit3` - 3D Hermite splines

### Float32 Math Functions

This library uses [github.com/chewxy/math32](https://github.com/chewxy/math32) for float32 math functions. Import it as:

```go
import math "github.com/chewxy/math32"
```

The math32 package provides float32 versions of Go's standard `math` library functions, offering better performance for float32-based graphics calculations compared to converting to/from float64.

## Core Concepts

### Naming Conventions

**Present tense methods** modify in place and return `*T` for chaining:

```go
v := vec3.T{1, 2, 3}
v.Scale(2) // v is now {2, 4, 6}
v.Add(&vec3.UnitX) // v is now {3, 4, 6}
```

**Past tense methods** return a modified copy:

```go
v := vec3.T{1, 2, 3}
v2 := v.Scaled(2) // v2 = {2, 4, 6}, v unchanged
v3 := v.Added(&vec3.UnitX) // v3 = {2, 2, 3}, v unchanged
```

### Method Chaining

```go
result := vec3.Zero
result.Add(&vec3.UnitX).Scale(5).Add(&vec3.UnitY)
// result = {5, 1, 0}
```

### Matrix Layout

Matrices use **column-major** layout (OpenGL convention):

```go
mat[column][row]
```

For DirectX (row-major), use `Transpose()`.

### Coordinate Systems

- **Right-handed coordinates**: X × Y = Z
- **Rotation direction**: Counter-clockwise (right-hand rule)
- **Angles**: Radians (use `math32.Pi` constants)

## Common Operations

### Vectors

```go
// Construction
v := vec3.T{1, 2, 3}

// Length
length := v.Length() // sqrt(x² + y² + z²)
lengthSq := v.LengthSqr() // x² + y² + z² (faster, no sqrt)

// Normalization
v.Normalize() // In-place
unit := v.Normalized() // Copy

// Arithmetic
v.Add(&other) // v += other
v.Sub(&other) // v -= other
v.Scale(2.5) // v *= 2.5

// Dot and cross products
dot := vec3.Dot(&a, &b)
cross := vec3.Cross(&a, &b)

// Distance
dist := vec3.Distance(&a, &b)
```

### Matrices

```go
// Identity and zero
m := mat4.Ident
z := mat4.Zero

// Translation
m.SetTranslation(&position)

// Rotation
m.AssignXRotation(angle)
m.AssignYRotation(angle)
m.AssignZRotation(angle)
m.AssignQuaternion(&quat)

// Scaling
m.AssignScaling(sx, sy, sz)

// Camera matrix
var view mat4.T
view.AssignLookAt(&eye, &center, &up)

// Projection matrices
var proj mat4.T

// Symmetric perspective (typical 3D game)
proj.AssignPerspective(fovy, aspect, znear, zfar)

// Asymmetric frustum
proj.AssignFrustum(left, right, bottom, top, znear, zfar)

// Orthographic (2D or CAD)
proj.AssignOrthogonalProjection(left, right, bottom, top, znear, zfar)

// Matrix multiplication
mvp := mat4.Ident
mvp.AssignMul(&projection, &view)
mvp.Mul(&model)
```

### Quaternions

```go
// Construction
axis := vec3.T{0, 1, 0}
q := quaternion.FromAxisAngle(&axis, math.Pi/4)

// Convenience constructors
qx := quaternion.FromXAxisAngle(angle)
qy := quaternion.FromYAxisAngle(angle)
qz := quaternion.FromZAxisAngle(angle)

// From Euler angles
q := quaternion.FromEulerAngles(yaw, pitch, roll)

// Rotate vector
v := vec3.T{1, 0, 0}
q.RotateVec3(&v) // In-place
rotated := q.RotatedVec3(&v) // Copy

// Combine rotations (order matters!)
q3 := quaternion.Mul(&q1, &q2) // Apply q2 first, then q1

// Smooth interpolation
halfway := quaternion.Slerp(&start, &end, 0.5)

// Convert to matrix
var m mat4.T
m.AssignQuaternion(&q)
```

## Performance Tips

### 1. Use Appropriate Precision

```go
// For graphics (sufficient for most cases)
import "github.com/ungerik/go3d/vec3"

// For scientific computing (higher precision)
import "github.com/ungerik/go3d/float64/vec3"
```

### 2. Prefer In-Place Operations

```go
// ✓ Good: Minimal allocations
v.Scale(2).Add(&other)

// ✗ Less efficient: Creates copies
result := v.Scaled(2).Added(&other)
```

### 3. Use LengthSqr for Comparisons

```go
// ✓ Faster: No sqrt
thresholdSq := threshold * threshold
if v.LengthSqr() < thresholdSq {
 // ...
}

// ✗ Slower: Uses sqrt
if v.Length() < threshold {
 // ...
}
```

### 4. Pass Pointers to Functions

```go
// ✓ Efficient: No copy
dot := vec3.Dot(&a, &b)

// The API uses pointers for better performance
```

### 5. Reuse Matrix Allocations

```go
// ✓ Good: Single allocation reused
var transform mat4.T
for i := range objects {
 transform.AssignTranslation(&objects[i].Position)
 // Use transform...
}

// ✗ Bad: Allocates every iteration
for i := range objects {
 var transform mat4.T // New allocation
 // ...
}
```

## API Reference

### Rectangle (vec2 package)

```go
type Rect struct {
 Min vec2.T
 Max vec2.T
}
```

**Operations:**
```go
r := vec2.Rect{Min: vec2.T{0, 0}, Max: vec2.T{100, 100}}

width := r.Width()
height := r.Height()
center := r.Center()
area := r.Area()

joined := r.Join(&other) // Bounding rectangle
clamped := r.Clamp(&point) // Clamp point to rectangle
contains := r.Contains(&point) // Point-in-rectangle test
```

### Box (vec3 package)

```go
type Box struct {
 Min vec3.T
 Max vec3.T
}
```

**Operations:**
```go
b := vec3.Box{Min: vec3.T{0, 0, 0}, Max: vec3.T{10, 10, 10}}

size := b.Size()
center := b.Center()
volume := b.Volume()

joined := b.Join(&other) // Bounding box
contains := b.Contains(&point) // Point-in-box test
```

### Migration Notes

#### Matrix Multiplication Order

Transforms apply **right to left**:

```go
// Mathematical notation: MVP = P × V × M
// In go3d:
var mvp mat4.T
mvp.AssignMul(&projection, &view) // mvp = P × V
mvp.Mul(&model) // mvp = (P × V) × M
```

#### Vec4 Homogeneous Coordinates

```go
// Point in space (affected by translation): w=1
point := vec4.T{x, y, z, 1.0}

// Direction vector (not affected by translation): w=0
direction := vec4.T{x, y, z, 0.0}
```

## Examples

### Complete Transform Pipeline

```go
// Object transform
position := vec3.T{10, 5, 0}
rotation := quaternion.FromYAxisAngle(math.Pi / 4)
scale := vec3.T{2, 2, 2}

var model mat4.T
model.SetTranslation(&position)
model.AssignQuaternion(&rotation)
model.ScaleVec3(&scale)

// Camera
eye := vec3.T{0, 10, 20}
center := vec3.T{0, 0, 0}
up := vec3.UnitY

var view mat4.T
view.AssignLookAt(&eye, &center, &up)

// Projection
var projection mat4.T
projection.AssignPerspective(math.Pi/4, 16.0/9.0, 0.1, 1000.0)

// Combined MVP
var mvp mat4.T
mvp.AssignMul(&projection, &view)
mvp.Mul(&model)

// Transform vertex
vertex := vec4.T{1, 0, 0, 1}
transformed := mat4.MulVec4(&mvp, &vertex)
```

### Camera Rotation with Slerp

```go
func SmoothCamera(start, end quaternion.T, t float32) quaternion.T {
 // Clamp t to [0, 1]
 if t < 0 { t = 0 }
 if t > 1 { t = 1 }

 // Smooth interpolation
 return quaternion.Slerp(&start, &end, t)
}
```

### Billboard Matrix

Make objects always face the camera:

```go
func CreateBillboard(objectPos, cameraPos, cameraUp vec3.T) mat4.T {
 // Calculate direction to camera
 direction := vec3.Sub(&cameraPos, &objectPos)
 direction.Normalize()

 // Calculate right vector
 right := vec3.Cross(&cameraUp, &direction)
 right.Normalize()

 // Recalculate up vector
 up := vec3.Cross(&direction, &right)

 // Build matrix
 var billboard mat4.T
 billboard[0] = vec4.T{right[0], right[1], right[2], 0}
 billboard[1] = vec4.T{up[0], up[1], up[2], 0}
 billboard[2] = vec4.T{direction[0], direction[1], direction[2], 0}
 billboard[3] = vec4.T{objectPos[0], objectPos[1], objectPos[2], 1}

 return billboard
}
```

## Design Philosophy

The package is designed for **performance over convenience** where necessary:

- **Pointer arguments**: Reduces allocations and copies
- **Stack allocation**: Value types (arrays) avoid GC pressure
- **Column-major matrices**: Direct GPU upload without transpose
- **Method chaining**: Fluent API without sacrificing performance

Performance comparison (see `mat4/mat4_test.go`):

```bash
cd mat4
go test -bench=BenchmarkMulAddVec4_PassBy*
```

## Contributing

Contributions are welcome! Please ensure:

1. All tests pass: `go test ./...`
2. Code is formatted: `go fmt ./...`
3. Documentation is updated
4. Benchmarks show no regressions

## License

MIT - see [LICENSE](LICENSE) file for details.

go3d

GPU application framework with windowing, input, and rendering built on WebGPU — reduces 480+ lines of GPU code to ~20, zero CGO (GoGPU ecosystem: [gg](https://github.com/gogpu/gg), [ui](https://github.com/gogpu/ui), [wgpu](https://github.com/gogpu/wgpu), [naga](https://github.com/gogpu/naga))

The Best Go Libraries For Game Development (25)

raylib-go

termloop

tile

Pitaya

prototype

Pixel

engo

fantasyname

g3n

Leaf

nano

Oak

Harfang3D

gonet

Ark

Ebitengine

ecs

go-astar

go-sdl2

goworld

grid

Pi

Pixel

go3d

gogpu