TermAsteroids

An Asteroids-like game, running in a terminal, written in PHP.

TermAsteroid is a horizontal scrolling Asteroids-like game which has the following particularities:

it runs in a terminal emulator.
it is fully implemented in PHP (except for the alternative and optional rendering backend described below).
it features 2 rendering backends (and can switch between the 2 at runtime):
- one implemented in PHP.
- one implemented in C and called through FFI.
it highlights:
- the benefit of using FFI in order to reimplement a tight loop, as long as it significantly outweighs the PHP / FFI communication overhead. This is the case here since the main data movement is between the renderer and PHP's output buffer.
- PHP's JIT benefits for such (CPU-bound) application and especially how it boosts the PHP rendering backend, making it 2 times faster and reducing the frame time by 40%.
- PHP's cycle collector fairness for such application. Back in PHP 5 or even early PHP 7 versions, it was still a big issue for long-running processes with high load of object creations & destructions.
it renders early 90s style 2D graphics featuring:
- 300x144 true color (24bpp) screen reaching 2+ million of pixel changes per second.
- tens of animated medium/large sprites rendered per frame.
- transparency, distortion and persistence effects.
- procedural bitmap / animation generation via Perlin noise.
- pre-rendered sprite rotations.
- adaptive performance in order to preserve a minimal framerate of 35 FPS.

Requirements

GNU/Linux distro
Docker
A fast terminal emulator with unicode & true color support and an adjusted font size so that a maximized window will render at least 300 columns x 77 rows
- xterm meets these requirements and is embedded in the Docker image

Getting started

git clone https://github.com/NoiseByNorthwest/term-asteroids.git
cd term-asteroids
make run

The first make run execution will take some time (building the Docker image, warming up some caches...) before starting the game, but the next executions will start instantly.

Controls

UP arrow: move the spaceship up
DOWN arrow: move the spaceship down
LEFT arrow: move the spaceship left
RIGHT arrow: move the spaceship right
Esc or q: quit
s: reset

Goals

Survive as long as possible:

use the arrow keys to move the spaceship
avoid collision with the asteroids
collide with bonuses, they give one third of your health and improve one of your 3 weapons

Other running mode

Game modes

Default mode (native renderer + JIT)

make run

Run it without JIT

make run.nojit

Run it with PHP renderer

make run.full_php

Run it with PHP renderer and without JIT

make run.full_php.no_jit

Dev mode

The dev mode gives nearly infinite health and more controls (see below). The difficulty level also increases faster.

make run.dev

Additional controls:

r: toggle renderer
a: toggle adaptive performance
w: show bounding and hit boxes
d: increase blue laser's level
c: decrease blue laser's level
f: increase plasma ball's level
v: decrease plasma ball's level
g: increase energy beam's level
b: decrease energy beam's level

Benchmark

This game comes with a benchmark mode which allows to highlight the performance differences between the four optimization levels (PHP/native renderer combined with JIT on/off).

Running it

To run all benchmark and generate the Markdown report:

make run.benchmark.all

Results

PHP version: 8.2.6

CPU: Intel(R) Core(TM) i7-9850H CPU @ 2.60GHz

	Native Renderer + JIT	Native Renderer	PHP Renderer + JIT	PHP Renderer
Execution time	20.7s	20.9s	20.7s	20.9s
Rendered frames	909	746	609	369
Average frame time	22.7ms	28.0ms	33.9ms	56.7ms
Average framerate	44.0 FPS	35.7 FPS	29.5 FPS	17.6 FPS
Average gameplay+physic time	7.0ms	11.0ms	7.8ms	13.5ms
Average rendering time	15.8ms	17.0ms	26.1ms	43.2ms
Average drawing time	1.7ms	1.9ms	7.6ms	20.7ms
Average update time	1.1ms	1.2ms	5.4ms	11.1ms
Average flushing time	13.0ms	13.9ms	13.1ms	11.4ms

Time breakdown explanation:

frame time: the elapsed time between 2 frames (i.e. the inverse of frame rate). It is compound of gameplay+physic and rendering times.
gameplay+physic time: this the time spent doing anything other than rendering the new frame, it mainly includes the gameplay & physic (moves, collisions) management.
rendering time: this is the time spent for the new frame rendering, it is compound of drawing, update and flushing times.
drawing time: the time spent drawing something (mainly bitmaps) to the frame buffer.
update time: the time spent generating the stream of characters to the buffered output in order to update the terminal based screen.
flushing time: the time spent flushing the output buffer. It may counterintuitively increase with a faster rendering loop since a faster rendering loop means a higher character changes throughput and thus more work for the terminal (and consequently a higher output blocking time).

NoiseByNorthwest / term-asteroids