Home

Awesome

**Important Notice **

Revived fork of the original Pixel library by 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!

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

Pixel 2

Go Reference Go build status Coverage Status Go Report Card Discord Chat

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

Tutorial

The Wiki of this repo contains an extensive tutorial covering several topics of Pixel.

For the tutorial walking through the basics of Pixel, check out The Basics!

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!

LightsPlatformer
LightsPlatformer
SmokeTypewriter
SmokeTypewriter
RaycasterGizmo
RaycasterGizmo

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.

Related repositories

Here are some packages which use Pixel:

Missing features

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

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.

OpenGL development libraries are needed for compilation. The dependencies are same as for GLFW.

The OpenGL version used is OpenGL 3.3.

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.

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. 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 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:

sudo apt update
sudo apt install gcc-mingw-w64

Build for windows amd64

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!

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

License

MIT

Special Contributions