Skip to content

Home

Jump to bottom
Javidx9 edited this page May 10, 2020 · 22 revisions

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.

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?

  1. Include the header file "olcPixelGameEngine.h" from a source file
  2. Derive a sub-class from olc::PixelGameEngine
  3. Implement a constructor for your derived class, and name your application
  4. Optionally override the OnUserCreate() function
  5. Override the OnUserUpdate() function
  6. Optionally override the OnUserDestroy() function
  7. Create an instance of your derived class somewhere, typically main()
  8. Call the Construct() function and specify the screen and pixel dimensions
  9. Call the Start() function to, well, start the engine 😂

Example olcPixelEngine "Hello World"

#define OLC_PGE_APPLICATION
#include "olcPixelGameEngine.h"

class Example : public olc::PixelGameEngine
{
public:
	Example()
	{
		sAppName = "Example";
	}

public:
	bool OnUserCreate() override
	{
		// Called once at the start, so create things here
		return true;
	}

	bool OnUserUpdate(float fElapsedTime) override
	{
		// called once per frame
		for (int x = 0; x < ScreenWidth(); x++)
			for (int y = 0; y < ScreenHeight(); y++)
				Draw(x, y, olc::Pixel(rand() % 255, rand() % 255, rand()% 255));	
		return true;
	}
};


int main()
{
	Example demo;
	if (demo.Construct(256, 240, 4, 4))
		demo.Start();

	return 0;
}

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)
Clone this wiki locally