pixel

A hand-crafted 2D game library in Go

4,448

246

4,448

View on GitHub

Top Related Projects

ebiten

10,770

Ebitengine - A dead simple 2D game engine for Go

raylib-go

1,540

Go bindings for raylib, a simple and easy-to-use library to enjoy videogames programming.

gg

4,378

Go Graphics - 2D rendering in Go with a simple API.

Quick Overview

Pixel is a 2D game development library for Go, focusing on simplicity and performance. It provides a minimalistic API for drawing sprites, shapes, and text, as well as handling input and audio, making it suitable for creating simple 2D games and graphical applications.

Pros

Simple and easy-to-use API
Good performance for 2D graphics
Pure Go implementation with minimal dependencies
Active community and ongoing development

Cons

Limited features compared to more comprehensive game engines
Lack of built-in physics engine
Steeper learning curve for beginners compared to some other game development tools
Documentation could be more extensive

Code Examples

Creating a window and drawing a circle:

package main

import (
    "github.com/faiface/pixel"
    "github.com/faiface/pixel/imdraw"
    "github.com/faiface/pixel/pixelgl"
)

func run() {
    cfg := pixelgl.WindowConfig{
        Title:  "Pixel Rocks!",
        Bounds: pixel.R(0, 0, 1024, 768),
    }
    win, err := pixelgl.NewWindow(cfg)
    if err != nil {
        panic(err)
    }

    imd := imdraw.New(nil)
    imd.Color = pixel.RGB(1, 0, 0)
    imd.Push(pixel.V(512, 384))
    imd.Circle(100, 0)

    for !win.Closed() {
        win.Clear(pixel.RGB(1, 1, 1))
        imd.Draw(win)
        win.Update()
    }
}

func main() {
    pixelgl.Run(run)
}

Loading and drawing a sprite:

pic, err := loadPicture("sprite.png")
if err != nil {
    panic(err)
}
sprite := pixel.NewSprite(pic, pic.Bounds())

// In the main loop:
sprite.Draw(win, pixel.IM.Moved(win.Bounds().Center()))

Handling keyboard input:

if win.Pressed(pixelgl.KeyLeft) {
    // Move left
} else if win.Pressed(pixelgl.KeyRight) {
    // Move right
}

Getting Started

Install Go and set up your Go workspace.

Install Pixel and its dependencies:

go get github.com/faiface/pixel
go get github.com/faiface/glhf
go get github.com/faiface/mainthread
go get github.com/go-gl/gl/v3.3-core/gl
go get github.com/go-gl/glfw/v3.3/glfw
go get github.com/pkg/errors

Create a new Go file and import Pixel:

import "github.com/faiface/pixel"
import "github.com/faiface/pixel/pixelgl"

Implement your game logic in a run() function and call it using pixelgl.Run(run) in your main() function.
Build and run your game: go build && ./your_game

Competitor Comparisons

ebiten

10,770

Ebitengine - A dead simple 2D game engine for Go

Pros of Ebiten

More active development and larger community support
Cross-platform support, including mobile and web browsers
Better performance for complex games and applications

Cons of Ebiten

Steeper learning curve for beginners
Less flexibility in low-level graphics operations
More opinionated design, which may limit customization options

Code Comparison

Pixel example:

win, err := pixelgl.NewWindow(pixelgl.WindowConfig{
    Title:  "Pixel Rocks!",
    Bounds: pixel.R(0, 0, 1024, 768),
})

Ebiten example:

func (g *Game) Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int) {
    return 320, 240
}

ebiten.SetWindowSize(640, 480)
ebiten.SetWindowTitle("Ebiten Rocks!")

Both libraries offer simple ways to create windows and handle basic game loops. Pixel provides more direct control over window creation, while Ebiten uses a more structured approach with separate layout and window size functions.

Ebiten's design encourages a clear separation of game logic and rendering, which can lead to more maintainable code for larger projects. Pixel, on the other hand, offers more flexibility for developers who prefer a less opinionated framework.

go-sdl2

2,197

SDL2 binding for Go

Pros of go-sdl2

More comprehensive multimedia support, including audio and input handling
Closer to native performance due to direct SDL2 bindings
Wider platform support, including mobile devices

Cons of go-sdl2

Steeper learning curve due to lower-level API
Requires external SDL2 library installation
Less idiomatic Go code compared to Pixel

Code Comparison

Pixel example:

win, err := pixelgl.NewWindow(pixelgl.WindowConfig{
    Title:  "Pixel Rocks!",
    Bounds: pixel.R(0, 0, 1024, 768),
})

go-sdl2 example:

window, err := sdl.CreateWindow("SDL2 Rocks!", 
    sdl.WINDOWPOS_UNDEFINED, sdl.WINDOWPOS_UNDEFINED,
    1024, 768, sdl.WINDOW_SHOWN)

Both libraries provide game development capabilities in Go, but they cater to different needs. Pixel focuses on simplicity and idiomatic Go code, making it easier for Go developers to get started with 2D game development. On the other hand, go-sdl2 offers more comprehensive multimedia support and potentially better performance at the cost of a steeper learning curve and additional setup requirements.

oak

1,541

A pure Go game engine

Pros of Oak

More comprehensive game development framework with built-in scene management and entity-component system
Better documentation and examples, making it easier for beginners to get started
Active development and community support

Cons of Oak

Steeper learning curve due to more complex architecture
Less flexible for non-game applications compared to Pixel's simpler design
Potentially higher overhead for simple 2D games

Code Comparison

Oak example:

type player struct {
    oak.Entity
}

func (p *player) Init() {
    p.SetDimensions(32, 32)
}

Pixel example:

type player struct {
    pos pixel.Vec
    sprite *pixel.Sprite
}

func newPlayer() *player {
    return &player{pos: pixel.ZV}
}

Oak provides a more structured approach with built-in entity management, while Pixel offers a simpler, more flexible design for custom implementations. Oak's code tends to be more concise due to its built-in features, whereas Pixel requires more manual setup but allows for greater customization.

Both libraries are suitable for 2D game development in Go, with Oak being more feature-rich and opinionated, while Pixel provides a lightweight foundation for building custom game engines or graphics applications.

raylib-go

1,540

Go bindings for raylib, a simple and easy-to-use library to enjoy videogames programming.

Pros of raylib-go

More comprehensive feature set, including 3D graphics and audio support
Closer to native performance due to C bindings
Larger community and more frequent updates

Cons of raylib-go

Steeper learning curve due to more complex API
Less idiomatic Go code, as it's a wrapper around a C library
Potentially more challenging to debug due to C integration

Code Comparison

raylib-go:

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

for !rl.WindowShouldClose() {
    rl.BeginDrawing()
    rl.ClearBackground(rl.RayWhite)
    rl.DrawText("Congrats! You created your first window!", 190, 200, 20, rl.LightGray)
    rl.EndDrawing()
}

Pixel:

cfg := pixelgl.WindowConfig{
    Title:  "Pixel Rocks!",
    Bounds: pixel.R(0, 0, 1024, 768),
}
win, err := pixelgl.NewWindow(cfg)
if err != nil {
    panic(err)
}

for !win.Closed() {
    win.Update()
}

gg

4,378

Go Graphics - 2D rendering in Go with a simple API.

Pros of gg

Simpler API with fewer concepts to learn
Better support for vector graphics and SVG output
More active development and maintenance

Cons of gg

Less focused on game development features
Fewer built-in primitives and shapes
Limited animation capabilities out-of-the-box

Code Comparison

gg example:

dc := gg.NewContext(1000, 1000)
dc.DrawCircle(500, 500, 400)
dc.SetRGB(0, 0, 0)
dc.Fill()
dc.SavePNG("output.png")

pixel example:

imd := imdraw.New(nil)
imd.Color = pixel.RGB(0, 0, 0)
imd.Push(pixel.V(500, 500))
imd.Circle(400, 0)
win.Clear(colornames.White)
imd.Draw(win)

Both libraries offer straightforward ways to draw shapes, but gg's API is slightly more concise. pixel provides more game-oriented features like windowing and input handling, while gg focuses on general-purpose 2D graphics. gg excels at vector graphics and SVG output, making it more suitable for creating scalable illustrations. pixel, on the other hand, is better suited for game development with its built-in game loop and sprite handling capabilities.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

NOTICE

This repo is not under active development anymore and has been archived. Continued development has been migrated to Pixel2. A big thank you to 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.

Pixel

A hand-crafted 2D game library in Go. Take a look into the 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 for the list of libraries necessary for compilation.

All significant changes are documented in CHANGELOG.md.

Tutorial

The Wiki of this repo contains an extensive tutorial covering several topics of Pixel. Here's the content of the tutorial parts so far:

Examples

The 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	Platformer

Smoke	Typewriter

Raycaster	Gizmo

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 (circles, rectangles, lines, ...)
- Optimized drawing with Batch
- Text drawing with text package
Audio through a separate 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()
- ...
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
- 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 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
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 package

Related repositories

Here are some packages which use Pixel:

TilePix Makes handling TMX files built with Tiled trivially easy to work with using Pixel.
spriteplus Basic SpriteSheet and Animation implementations
PixelUI Imgui-based GUIs for Pixel
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 on the wiki.

PixelGL backend uses OpenGL to render graphics. Because of that, OpenGL development libraries are needed for compilation. The dependencies are same as for 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 for full details.

The combination of Go 1.8, macOS and latest XCode seems to be problematic as mentioned in issue #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!

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 for further information.

License

MIT

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of Ebiten

Cons of Ebiten

Code Comparison

Pros of go-sdl2

Cons of go-sdl2

Code Comparison

Pros of Oak

Cons of Oak

Code Comparison

Pros of raylib-go

Cons of raylib-go

Code Comparison

Pros of gg

Cons of gg

Code Comparison

Convert designs to code with AI

README

*****NOTICE*****

Pixel

Tutorial

Features

Related repositories

Missing features

Requirements

Contributing

License

Top Related Projects

Convert designs to code with AI

NOTICE