For the month of July, I decided to take part in Floppy Jam as my games jam for that month. Floppy Jam was a small jam with a novel idea, make a game that could fit on a single floppy disk with the total memory capacity of 1.44 MB. I decided to take part but there is an issue, most of my typical development environments could not make a game that small, even if I made a completely procedural game. So I decided I should make a new engine, where it has the most basic elements (graphics, sound and input) in its smallest possible code. That’s when I decided to make a games engine using the command prompt.

The command prompt looks simple, there isn’t much you can output to the console and it’s typically slow, at least not fast enough for real-time smooth rendering. However, that’s if you use the standard iostream or stdio functions. The Windows library actually treats the console window like any standard window, with a handle for both input and output, as well as a screen buffer.

HANDLE hConsole = GetStdHandle(STD_OUTPUT_HANDLE);
CONSOLE_SCREEN_BUFFER_INFO csbi;

GetConsoleScreenBufferInfo(hConsole, &csbi);

SMALL_RECT rectWindow = { 0, 0, 1, 1 };
SetConsoleWindowInfo(hConsole, TRUE, &rectWindow);

COORD coord = { (short)SCREEN_WIDTH, (short)SCREEN_HEIGHT };
SetConsoleScreenBufferSize(hConsole, coord);

SetConsoleActiveScreenBuffer(hConsole);

It is possible to resize the window by shrinking the screen buffer to the smallest possible size, before scaling it up to the size you want. Frustratingly you cannot set the console to any size you want, as there appears to be a restriction that the size cannot be larger than 800×600 pixels. For the game, I ended up using 108×60 characters to make the game the largest widescreen resolution. You can also set the font and the font size, the window title and window position as well, which is enough customization you need even if it’s not possible to get fullscreen or “high resolution”.

Input can be read from the input handler, including focus, mouse and keyboard events. You can also use GetKeyAsyncKeyState() to get real-time input handling. Mouse positions can only be accessed from the input handler.

HANDLE hConsoleIn = GetStdHandle(STD_INPUT_HANDLE);

INPUT_RECORD inBuf[32];
DWORD events = 0;
GetNumberOfConsoleInputEvents(hConsoleIn, &events);
if (events > 0)
	ReadConsoleInput(hConsoleIn, inBuf, events, &events);

for (DWORD i = 0; i < events; i++)
{
	switch (inBuf[i].EventType)
	{
	case FOCUS_EVENT:
	{
		windowFocus = inBuf[i].Event.FocusEvent.bSetFocus;
	}
	break;

As mentioned earlier, using standard text input/output isn’t fast enough for real-time rendering, it’s also rather limiting. What we need is a way to render a full array of characters to the console screen, so how do we do that? And how do we display colour? Well, the best way deals with both birds with one stone, WriteConsoleOutput(). This function writes a full set of characters to the console, but you do not input strings, but a special Character format that allows you to set either ANSI or Unicode Characters, as well as what foreground and background colours for that element in the array. Command Prompts (as well as most pre-installed terminals) give you a maximum of 16 foreground and background colours each, although with the right character sets and other tricks you could create more colours. Once you have set up an array, you just call WriteConsoleOutput, using your console output handler, the array, the size of the array in width and height as well as the area you wish to draw to. A lot of this info I first discovered from the One Lone Coder through his ConsoleGameEngine tutorial series, as well as a header-only roguelike engine called rlutil.

///Buffer Screen
CHAR_INFO *bufScreen;

void drawChar(int x, int y, short c, int color, int bgColor = 0)
{
	if (x < 0 || y < 0 || x >= SCREEN_WIDTH || y >= SCREEN_HEIGHT)
		return;

	bufScreen[y * SCREEN_WIDTH + x].Char.UnicodeChar = (short)c;
	bufScreen[y * SCREEN_WIDTH + x].Attributes = color | (short)(bgColor * 16);
}

///Drawing the full buffer screen array to the console.
HANDLE hConsole = GetStdHandle(STD_OUTPUT_HANDLE);
WriteConsoleOutput(hConsole, bufScreen, { (short)SCREEN_WIDTH, (short)SCREEN_HEIGHT }, { 0,0 }, &rectWindow);

///Clearing the buffer is as simple as setting all the elements to 0.
void clearScreen()
{
	memset(bufScreen, 0, sizeof(CHAR_INFO) * SCREEN_WIDTH * SCREEN_HEIGHT);
}

For timekeeping, an easy way to get efficient time tracking would be to use the standard library chrono. However, to avoid overhead and allow support with older systems, I needed a more specialised solution. Fortunately, I remembered a Windows-specific method of timekeeping from a video by a game developer going by the name TheCherno. While in more recent videos he recommends newcomers to use chrono, in a C++ game engine tutorial he used QueryPerformance functions. Essentially, you call QueryPerformanceCounter(), which will return you a timestamp accurate to the nearest microsecond of the PC’s performance counter. You can get the timestamp from the start of your loop, and another at the end to work out the total time to process a loop. While it is platform specific, because it’s part of the Windows API there is little overhead, and it’s extremely accurate.

bool StartCounter()
{
	LARGE_INTEGER li;
	if (!QueryPerformanceFrequency(&li))
		return false;

	PCFreq = double(li.QuadPart);

	QueryPerformanceCounter(&li);
	CounterStart = li.QuadPart;
	return true;
}

float GetCounterNanoseconds()
{
	LARGE_INTEGER li;
	QueryPerformanceCounter(&li);
	return (float)((li.QuadPart - CounterStart) / PCFreq);
}

float GetCounterMilliseconds()
{
	return GetCounterNanoseconds() * 1000.f;
}

Finally, for sound, I only wanted the simplest implementation I could find. All I needed was the ability to load Wav and Ogg files, and play them in parallel. Fortunately, that is possible with a single library and a header file. Randy Gaul developed a large collection of self-contained systems, each could be used with a single header. This included cute_sound, which does exactly what I wanted. It does have some minor faults such as crashing if you tried to delay a sound, and needs a significant updated to be friendly with modern compilers because of how it uses goto statements, and unfortunately because of how the Vorbis library works you cannot make it header only, but it’s not complex.

void loadAudio(const char* name, unsigned int id)
{
	freeAudio(id);

	const char *dot = strrchr(name, '.');
	if (!dot || dot == name) return;

	if (!strcmp(dot, ".ogg"))
		load_sound[id] = cs_load_ogg(name);
	else if (!strcmp(dot, ".wav"))
		load_sound[id] = cs_load_wav(name);
}

void playAudio(int id, bool loop, float volume, float pitch, float pan, float delay)
{
	cs_play_sound_def_t def = cs_make_def(&load_sound[id]);
	def.looped = loop ? 1 : 0;
	def.volume_left = volume;
	def.volume_right = volume;
	def.pitch = pitch;
	def.pan = pan;
	def.delay = delay;
	cs_play_sound(ctx, def);
}

The engine’s structure is that the user simply defines preprocessors for constant values, and includes a single header to get the engine’s full functionalities. All they need to do is to set up a function for handling updates and rendering (if they want to use real-time functioning) or event handling, and then call a function called run to start the engine. Keeping it like this basically means it’s possible to create tiny demos and games with whatever external tools they want.

When the jam actually started (yes I built a two-header library about a week before the jam began), I wrote basic state management system for the two scenes I wanted (title and game), as well as renderable objects. Each interactable object used a game object struct that had basic physics for movement and collision checks. The pinball environment was achieved by assigning each wall an ID, and that ID also corresponded with the angle of the slope as well as how it appeared. While most other game objects were defined as sprites, an overridden game object that has an array to represent a single static image, the flippers was a special sprite that manipulated that array based on how long a button was held down for. It also had special collision responses based on what stage the flippers were in, which proved a challenge when sprites could easily go through them.

What made working on this engine quite exciting was it really encouraged you to work with proper limitations. Unlike pico-8, where the limitations are hard-coded into the engine and its fantasy console, the command prompt had a small resolution and a limited colour palette purely because it was not intended for real-time rendering and gameplay, and the 1.44MB meant I had to think outside the box to find ways not to use too much memory, although, in the end, PEWBALL was under 400KB (possibly smaller still if I could get a compress heavy linker like crinkler to work).

One way to optimise was to replace having a particle emitter with particle objects with the rand() function and lots of basic maths to work out where particles would be over time. This technique was used for the starfield at the beginning as well as the explosions enemies and the player has in the game. Guns used a simple fixed sized array as an object pooling system, a similar one was also used for the enemies, which had their own struct that could be overridden for unique behaviour. Ogg files were compressed to their lowest quality, which gives them a small file size as well as gives a slightly distorted retro feel, helped by the 8-bit inspired music and sound effects that I used.

While I could have carried on development up to the deadline on August 10th, I needed to get a game finished for July, so I decided to stop on July 31st and submit it, announcing it’s release on August 1st. Little did I know, there was also a voting session that went on for a while. Out of the 25 submissions managed to achieve 7th, and the overall winners were Floppy Bug (In Quality and Design) and Crates in a Crate (in Gameplay). I’m pretty happy with where I placed considering the challenge I had in creating an entire engine, although I’m definitely impressed with Floppy Bug because the team behind it decided to one-up me and create a full 3D OpenGL engine in two weeks that took up 440KB.

Regardless, this one was a rather fun challenge. It kind of makes me want to look into development for other primitive systems, maybe I could try developing for an old console next, who knows? As for Linux, that might not be as possible as I hoped it would be. The problem with Linux Terminals is that they don’t have the same level of control as the Windows Command Prompt. It is possible to do things like resizing the terminal window, draw characters at certain positions and set the colours of characters using ANSI escape sequence strings, however, it isn’t as stable as I once thought, and there isn’t much documentation on getting it to work.

If you want to check out the engine itself, it’s called KitConsole and can be found on Github, and you can check out PEWBALL on Itch.io.