Quick Shortcuts
NOTE: olc::PixelGameEngine 2.0 was released recently, thus this documentation is being compiled, and therefore not completed. However, the engine is intuitively easy to use, and there are plenty of examples in the main repo.
Getting Started
Learn By Example - BreakOut Clone
TUTORIAL - Requiring Player Skill
TUTORIAL - Advanced General Techniques
Core Classes
- The primary engine functions and drawing routines
- A single representation of colour
- A rectangular array of
s, forming an image
- A GPU accelerated wrapper for an
- An optional, lightweight, scrambled, virtual file system for packaging assets
(and olc::vi2d) - A built in 2D Vector type
Platform Specific Usage
Compiling on Windows with Other Compilers
- Code::Blocks, MinGW
What is it?
The olcPixelGameEngine is a single-file prototyping and game-engine framework created in C++. It is cross platform, compiling on Windows via Visual Studio and Code::Blocks, and on Linux with a modern g++. On Windows platforms it has no external dependencies outside those that come as standard with popular IDEs. On Linux, it relies on a couple which again, would typically come as standard. I created this tool due to the success of the olcConsoleGameEngine, and it draws heavily from that user experience. In fact, code written with olcConsoleGameEngine is trivially portable to olcPixelGameEngine.
What does it do?
olcPixelGameEngine allows you to rapidly develop prototypes and games. It does this by creating a window, and rapidly drawing to that window. It is sensitive to keyboard and mouse input. The Screen is considered to be an 2D array of Pixels. Pixels have a defined width and height in real screen-pixels. This means your application can be low or high resolution depending on the look and sophistication you are going for. Each pixel stores a 32-bit colour code, 8-bits each for red, green and blue, and 8-bits for transparency. Basic drawing tools for manipulating the Screen are provided.
By design, the olcPixelGameEngine requires no "boilerplate" effort from the user, i.e. the user can just focus on getting on with creating the fun parts of the application. The aesthetic the olcPixelGameEngine provides is suitable for both detailed applications and retro/indy looking titles. Image resources used by the engine are stored as PNG files.
What doesn't it do?
olcPixelGameEngine does not provide any implementation of typical game resources. For example, it does not provide tools to handle asset loading, collision detection, vector mathematics. As it is an educational tool, it is expected the user will provide this functionality.
But I want it to do things!
Fundamentally the olcPixelGameEngine is designed to support the output of the OneLoneCoder YouTube channel, alongside the olcConsoleGameEngine. On this channel, javidx9 explains concepts and algorithms regarding how to do things, and uses these engines to demonstrate the how and the why. Also, by not providing any explicit implementations, the user is free to make design decisions as they see fit.
However, olcPixelGameEngine supports the concept of extensions. These are convenience utilities created from and for the topics discussed on the OneLoneCoder YouTube channel. As these are developed, you can expect to see extensions to handle 2D geometry, 3D geometry, kinematics, collisions and other algorithms which may be useful. but the underlying principle of the olcPixelGameEngine is you can use whatever you prefer in order to create your application.
How do you use it?
Include the header file "olcPixelGameEngine.h" from a source file
Derive a sub-class from olc::PixelGameEngine
Implement a constructor for your derived class, and name your application
Optionally override the OnUserCreate() function
Override the OnUserUpdate() function
Optionally override the OnUserDestroy() function
Create an instance of your derived class somewhere, typically main()
Call the Construct() function and specify the screen and pixel dimensions
Call the Start() function to, well, start the engine 😂
Example olcPixelEngine "Hello World"
#defineOLC_PGE_APPLICATION #include"olcPixelGameEngine.h"classExample : publicolc::PixelGameEngine { public:Example() { sAppName = "Example"; } public:boolOnUserCreate() override { // Called once at the start, so create things herereturntrue; } boolOnUserUpdate(floatfElapsedTime) override { // called once per framefor (int x = 0; x < ScreenWidth(); x++) for (int y = 0; y < ScreenHeight(); y++) Draw(x, y, olc::Pixel(rand() % 255, rand() % 255, rand()% 255)); returntrue; } }; intmain() { Example demo; if (demo.Construct(256, 240, 4, 4)) demo.Start(); return0; }Am I allowed to use it?
YES! It is released under the OLC-3 license. This is very similar to the BSD license, but there are two slight changes. You must credit OneLoneCoder in a visible way, in both source code and binary form, so if your application makes use of this code, somewhere in there it must display that you have used it. Javidx9 makes these tools with the intention that they are fun and educational, and does so for no profit at all. So far the OneLoneCoder initiative has inspired and helped hundreds of programmers. Its important that derivative works reflect, and frankly advertise that this initiative exists.
Features
Customisable Pixel size
Customisable Screen size
Full 32-Bit Colour
Alpha Blending Transparency
Optimised drawing routines Points
Lines
Circles
Filled shapes
Sprites
Uses PNG assets
Supports Windows & Linux
Compiles in Unicode / ASCII modes
Requires minimal dependencies OpenGL 1.0
X11 (Linux)
libpng (Linux)
Keyboard input
Mouse input
Single file solution
Support for extensions (tba)