The tutorial project
Floppy Bird is the C++ reference game that New game creates for Unreal Engine. The FloppyBird module builds the bird, an orthographic camera, a seeded field of pillars and a score display from engine primitives. It needs no Blueprint and no downloaded art.
It was first built on Unreal Engine 5.8.4 on Windows. It is now built and tested on the 5.9 preview on macOS, and it still compiles on 5.8.
Layout
| Path | Contents |
|---|---|
FloppyBird.uproject | The project file. It enables the Remote Control and Python Editor Script plugins. |
Config/ | Engine, input and Remote Control settings. DefaultEngine.ini assigns the game mode. |
Source/FloppyBird/ | The game module. |
Source/FloppyBird/Tests/ | The automation tests. |
Scripts/ue.mjs | Build, test, editor and replay commands. See the ue.mjs reference. |
Scripts/run-to-rrd.py | Builds the recording that the Lou view shows. |
Scripts/fork-here.py | Runs a fork for the Lou view’s Fork from here. |
agent/trainer.json | Tells the Lou view how to read this game’s runs. |
.unrest/gamegen.json | GameGen’s settings for the project. |
.unrest/agents/unreal-simulation/ | The Unreal QA agent for this project. |
README.md | Setup, the source map, record and replay, and the exercises. |
Saved/, Binaries/ and Intermediate/ are ignored by git.
Source files
File under Source/FloppyBird/ | Responsibility |
|---|---|
FloppyTypes.h | World state and tuning constants, in centimetres with Z up. |
FloppyGameState.h/.cpp | The fixed-step simulation: seed, score, collision and restart. |
FloppyBirdPawn.h/.cpp | The bird, the camera and player input. |
FloppyPillarPair.h/.cpp | Pillar actors that mirror the simulation. |
FloppyGameMode.h/.cpp | Selects the pawn, game state and HUD classes. |
FloppyHUD.h/.cpp | The score and the state hints. |
FloppyRunRecorder.h/.cpp | The run recorder and the headless re-simulation. |
FloppyReplayCommandlet.h/.cpp | The command that Scripts/ue.mjs replay starts. |
The simulation is deterministic. The game state advances in fixed steps of 1/60 of a second, and the actors mirror that state. This is what makes time travel possible.
Automation tests
node Scripts/ue.mjs test builds first, then runs every test under the FloppyBird prefix without a window. There are ten.
| Test | Checks |
|---|---|
FloppyBird.Bird.NoInputGameOverWithin3s | With no input, the run ends within three seconds. |
FloppyBird.Bird.FlapGivesPositiveVelocity | A flap gives the bird upward velocity. |
FloppyBird.Pillars.SameSeedSameGaps | The same seed gives the same gaps. |
FloppyBird.Pillars.SpawnAndScroll | Pillars spawn and scroll. |
FloppyBird.Scoring.PassGap1Score1 | Clearing the first gap scores one point. |
FloppyBird.Collision.HitPillar1GameOver | Hitting the first pillar ends the run. |
FloppyBird.Restart.RestartResetsScoreTickPillars | A restart resets score, tick and pillars and keeps the seed. |
FloppyBird.Replay.RecordingIsOptInAndPassive | Recording is off unless asked for and does not change a run. |
FloppyBird.Replay.ReplayReproducesRecordedFrames | An unedited replay writes the same frames, byte for byte. |
FloppyBird.Replay.ForkChangesOneInput | A fork with one input changed keeps the frames before it. |
Results are written to Saved/Automation/:
| File | Contents |
|---|---|
floppy-result.json | The result report that the Unreal view reads. |
floppy-build.log | The build output. |
floppy-tests.log | The latest test output. |
Run one group of tests with a filter:
node Scripts/ue.mjs test --filter FloppyBird.RestartAutomation tests verify state. They do not show that the score is drawn on screen or that the keyboard and mouse work. Check those yourself by playing in Unreal Editor.
Play it
Open FloppyBird.uproject, select a level that uses the project’s default game mode, and press Play. Click the viewport to give it focus. The bird starts falling as soon as play begins. Space or a left click flaps. The score appears at the upper left.
Exercises
The project’s README.md ends with three exercises to give to GameGen, one at a time:
- Add a best score for the session and show it.
- Add a gentle difficulty preset with a wider gap.
- Add a pause command.
Each one names the tests to add and what to check by eye.