Write an Initial Game Version

Now that we have a working foundation, let’s implement the first version of our game!

Note

You don’t need to type everything by hand. After each code listing, there’s a link to download the full source file.

Geometry Classes

We’ll start with some basic data structures that serve as building blocks for the game.

robot-escape/src/Geometry.hpp

#pragma once

#include <functional>
#include <array>
#include <random>
#include <thread>

inline auto randomInt(int minimum, int maximum) noexcept -> int {
    thread_local std::mt19937 rng(std::random_device{}());
    return std::uniform_int_distribution<int>{minimum, maximum}(rng);
}

struct Position {
    int x{};
    int y{};

    Position() = default;
    constexpr Position(int x, int y) noexcept : x{x}, y{y} {}
    auto operator==(const Position &other) const noexcept -> bool = default;
    auto operator!=(const Position &other) const noexcept -> bool = default;
    auto operator+(const Position &other) const noexcept -> Position { return {x + other.x, y + other.y}; }
    auto operator-(const Position &other) const noexcept -> Position { return {x - other.x, y - other.y}; }
    [[nodiscard]] auto distanceTo(Position other) const noexcept -> int {
        return std::abs(x - other.x) + std::abs(y - other.y);
    }
};

constexpr static std::array<Position, 4> cPosDelta4 = {
    {{1, 0}, {0, 1}, {-1, 0}, {0, -1}}};

struct Size {
    int width{};
    int height{};

    Size() = default;
    constexpr Size(int width, int height) noexcept : width{width}, height{height} {}
    [[nodiscard]] auto fitsInto(Size other) const noexcept -> bool {
        return width <= other.width && height <= other.height;
    }
    [[nodiscard]] auto area() const noexcept -> int { return width * height; }
    [[nodiscard]] auto center() const noexcept -> Position {
        return {width / 2, height / 2};
    }
    [[nodiscard]] auto contains(const Position& pos) const noexcept -> bool {
        return pos.x >= 0 && pos.y >= 0 && pos.x < width && pos.y < height;
    }
    [[nodiscard]] auto index(const Position& pos) const noexcept -> int {
        return pos.y * width + pos.x;
    }
    [[nodiscard]] auto randomPosition() const noexcept -> Position {
        return {randomInt(0, width - 1), randomInt(0, height - 1)};
    }
    template<typename Fn> void forEach(Fn fn) const {
        for (int y = 0; y < height; ++y) {
            for (int x = 0; x < width; ++x) {
                fn(Position{x, y});
            }
        }
    }
    template<typename Fn> auto filterPositions(Fn fn) const -> std::vector<Position> {
        std::vector<Position> result;
        result.reserve(area());
        forEach([&result, &fn](const Position& pos) {
            if (fn(pos)) { result.push_back(pos); }
        });
        return result;
    }
};

Download Geometry.hpp

In this file, we define the classes Position and Size with a minimal set of utility methods. These will be used throughout the game code.

Additionally, we define the function randomInt() and the directional offset array cPosDelta4, which will help with movement logic.

The Canvas

Instead of building a complex graphical interface, we use a simple Canvas class that renders the game world as colored text in the console.

robot-escape/src/Canvas.hpp

#pragma once

#include "Geometry.hpp"

#include <vector>
#include <iostream>
#include <numeric>
#include <ranges>
#include <algorithm>
#include <cstdint>

enum class Block : uint8_t {
    Empty,
    Wall,
    Room,
    Exit,
    Player,
    PlayerTrail,
    Robot,
    RobotTrail,
};

struct Canvas {
    Size size;
    std::vector<Block> data;
    Position topLeft;

    constexpr static auto cDefaultSize = Size{40, 20};

    explicit Canvas(Size size = cDefaultSize) noexcept : size{size}, data(size.area(), Block::Empty) {}
    void setTopLeft(Position pos) noexcept { topLeft = pos; }
    void setBlock(Block block, Position pos) noexcept {
        if (!size.contains(pos + topLeft)) { return; }
        data[size.index(pos + topLeft)] = block;
    }
    template<typename... PosArgs>
    void setBlocks(Block block, PosArgs... pos) noexcept {
        (setBlock(block, pos), ...);
    }
    void fillRect(Position rectTopLeft, Size rectSize, Block block) noexcept {
        rectSize.forEach([&](Position p) { setBlock(block, p + rectTopLeft); });
    }
    [[nodiscard]] auto blockAt(Position pos) const noexcept -> Block {
        return blockFromOrigin(pos + topLeft);
    }
    [[nodiscard]] auto blockFromOrigin(Position pos) const noexcept -> Block {
        if (!size.contains(pos)) { return Block::Empty; }
        return data[size.index(pos)];
    }
    void renderToConsole() const noexcept {
        std::cout << "\x1b[0m";
        auto lastBlock = Block::Player;
        for (int y = 0; y < size.height; ++y) {
            for (int x = 0; x < size.width; ++x) {
                renderBlockAt({x, y}, lastBlock);
            }
            std::cout << '\n';
        }
        std::cout << "\x1b[0m\n";
    }
    void renderBlockAt(Position pos, Block &lastBlock) const noexcept {
        static std::array<std::string_view, 16> walls = {
            "■", "╺", "╻", "┏", "╸", "━", "┓", "┳", "╹", "┗", "┃", "┣", "┛", "┻", "┫", "╋"
        };
        auto block = blockFromOrigin(pos);
        if (block != lastBlock) {
            switch (block) {
            case Block::Empty: std::cout << "\x1b[90m"; break;
            case Block::Wall: std::cout << "\x1b[32m"; break;
            case Block::Room: std::cout << "\x1b[0m"; break;;
            case Block::Exit: std::cout << "\x1b[92m"; break;
            case Block::Player: case Block::PlayerTrail: std::cout << "\x1b[93m"; break;
            case Block::Robot: case Block::RobotTrail: std::cout << "\x1b[91m"; break;
            }
        }
        switch (block) {
        case Block::Empty: std::cout << "░"; break;
        case Block::Wall: std::cout << walls[matchBlocks4(pos, Block::Wall)]; break;
        case Block::Room: std::cout << " "; break;
        case Block::Exit: std::cout << "⚑"; break;
        case Block::Player: std::cout << "☻"; break;
        case Block::Robot: std::cout << "♟"; break;
        case Block::PlayerTrail: case Block::RobotTrail: std::cout << "∙"; break;
        }
        lastBlock = block;
    }
    [[nodiscard]] auto matchBlocks4(Position pos, Block block) const noexcept -> uint32_t {
        return std::accumulate(cPosDelta4.rbegin(), cPosDelta4.rend(), 0U, [&](uint32_t acc, Position delta) {
            return (acc << 1) | (blockFromOrigin(pos + delta) == block ? 1 : 0);
        });
    }
};

Download Canvas.hpp

The World

Next, we define the data structures that represent the game world.

robot-escape/src/World.hpp

#pragma once

#include "Geometry.hpp"
#include "Canvas.hpp"

#include <ranges>
#include <algorithm>
#include <vector>

template<Block tElementBlock, Block tTrailBlock = tElementBlock>
struct ElementWithPos {
    Position pos{};
    std::vector<Position> trail;
    std::string name;

    void moveTo(Position newPos) noexcept {
        trail.push_back(pos);
        if (trail.size() > 3) { trail.erase(trail.begin()); }
        pos = newPos;
    }

    void render(Canvas &canvas) const noexcept {
        canvas.setBlock(tElementBlock, pos);
        for (auto trailPos : trail) {
            auto currentBlock = canvas.blockAt(trailPos);
            if (currentBlock == Block::Room || currentBlock == Block::RobotTrail) { canvas.setBlock(tTrailBlock, trailPos); }
        }
    }
};

using Player = ElementWithPos<Block::Player, Block::PlayerTrail>;
using Robot = ElementWithPos<Block::Robot, Block::RobotTrail>;
using Exit = ElementWithPos<Block::Exit>;

struct Field {
    Size size{};
    void render(Canvas &canvas) const noexcept {
        canvas.fillRect(Position{-1, -1}, Size{size.width + 2, size.height + 2}, Block::Wall);
        canvas.fillRect(Position{0, 0}, size, Block::Room);
    }
};

struct World {
    Field field;
    Player player;
    std::vector<Robot> robots;
    std::vector<Exit> exits;

    explicit World(Size fieldSize) : field{fieldSize} {}
    template<typename T>
    [[nodiscard]] static auto tooNear(Position pos, int distance, const std::vector<T> &elements) {
        return std::any_of(elements.begin(), elements.end(), [&](const auto &element) {
            return element.pos.distanceTo(pos) <= distance;
        });
    }
    [[nodiscard]] auto isValidPlayerMovement(Position pos) const noexcept -> bool {
        return field.size.contains(pos);
    }
    [[nodiscard]] auto isValidRobotMovement(Position pos) const noexcept -> bool {
        return field.size.contains(pos) && !tooNear(pos, 0, robots);
    }
    [[nodiscard]] auto isPlayerOnExit() const noexcept -> bool {
        return std::ranges::any_of(exits, [&](const Exit &exit) -> bool { return exit.pos == player.pos; });
    }
    [[nodiscard]] auto isRobotOnPlayer() const noexcept -> bool {
        return std::ranges::any_of(robots, [&](const Robot &robot) -> bool { return robot.pos == player.pos; });
    }
    template<typename Fn>
    auto randomValidFieldPosition(Fn fn) const -> Position {
        auto validPositions = field.size.filterPositions(fn);
        if (validPositions.empty()) {
            throw std::logic_error{"Could not find a valid position"};
        }
        return validPositions[randomInt(0, validPositions.size() - 1)];
    }
    void addExitAtRandomPosition() {
        auto exit = Exit{randomValidFieldPosition([](Position pos){return true;})};
        exits.emplace_back(std::move(exit));
    }
    void setPlayerToRandomPosition() {
        player.pos = randomValidFieldPosition([&](Position pos) {
            return !tooNear(pos, 3, exits);
        });
    }
    void addRobotAtRandomPosition() {
        auto robot = Robot{randomValidFieldPosition([&](Position pos) {
            if (player.pos.distanceTo(pos) <= 4) { return false; }
            return !tooNear(pos, 4, exits) && !tooNear(pos, 1, robots);
        })};
        robot.name = std::format("Robot {}", robots.size() + 1);
        robots.emplace_back(std::move(robot));
    }
    void render(Canvas &canvas) const noexcept {
        canvas.setTopLeft(canvas.size.center() - field.size.center());
        field.render(canvas);
        for (const auto &exit : exits) {
            exit.render(canvas);
        }
        player.render(canvas);
        for (const auto &robot : robots) {
            robot.render(canvas);
        }
    }
};

Download World.hpp

This file introduces the main game elements: Player, Robot, and Exit. These are placed within the Field class, which defines the map the game is played on. All of these are grouped into the World structure—a complete model of the game’s state.

This abstraction allows us to easily render the game state and apply game logic to it.

Game Logic

So far, we’ve only set up static structures. Now it’s time to make things dynamic.

robot-escape/src/Logic.hpp

#pragma once

#include "Canvas.hpp"
#include "World.hpp"

#include <iostream>
#include <map>
#include <string>
#include <vector>
#include <limits>

struct PlayerInput {
    Position movement;

    auto operator==(const PlayerInput &other) const noexcept -> bool = default;
    auto operator!=(const PlayerInput &other) const noexcept -> bool = default;
};

constexpr auto cQuitInput = PlayerInput{Position{99, 99}};

[[nodiscard]] inline auto inputFromConsole() noexcept -> PlayerInput {
    static const auto validInputs = std::map<std::string, PlayerInput>{
        {"e", {Position{1, 0}}},
        {"s", {Position{0, 1}}},
        {"w", {Position{-1, 0}}},
        {"n", {Position{0, -1}}},
        {"q", cQuitInput},
    };
    PlayerInput playerInput;
    while (playerInput == PlayerInput{}) {
        std::cout << "Enter your move (n/e/s/w/q=quit): ";
        std::cout.flush();
        std::string input;
        std::getline(std::cin, input);
        auto it = validInputs.find(input);
        if (it != validInputs.end()) {
            playerInput = it->second;
        } else {
            std::cout << "Invalid input. Please try again.\n";
        }
    }
    return playerInput;
}

enum class GameState {
    Running,
    PlayerWon,
    RobotsWon,
};

struct PlayerLogic {
    void advance(PlayerInput input, World &world) {
        auto newPlayerPos = world.player.pos + input.movement;
        if (world.isValidPlayerMovement(newPlayerPos)) {
            world.player.moveTo(newPlayerPos);
        } else {
            std::cout << "Could not move in this direction. You lost one move.\n";
        }
    }
};

struct RobotLogic {
    void advance(Robot &robot, World &world) {
        if (robot.pos == world.player.pos) { return; }
        int bestDistance = std::numeric_limits<int>::max();
        std::vector<Position> bestMoves;
        for (auto delta : cPosDelta4) {
            auto pos = robot.pos + delta;
            if (!world.isValidRobotMovement(pos)) continue;
            auto dist = pos.distanceTo(world.player.pos);
            if (dist < bestDistance) { bestMoves = {pos}; bestDistance = dist; }
            else if (dist == bestDistance) { bestMoves.push_back(pos); }
        }
        if (bestMoves.empty()) return;
        robot.moveTo(bestMoves[randomInt(0, bestMoves.size() - 1)]);
    }
};

struct Logic {
    World world;
    PlayerLogic playerLogic;
    RobotLogic robotLogic;

    explicit Logic(World &&initialWorld) : world{std::move(initialWorld)} {}

    void advance(PlayerInput input) {
        playerLogic.advance(input, world);
        for (auto &robot : world.robots) {
            robotLogic.advance(robot, world);
        }
    }

    [[nodiscard]] auto gameState() const noexcept -> GameState {
        if (world.isPlayerOnExit()) { return GameState::PlayerWon; }
        if (world.isRobotOnPlayer()) { return GameState::RobotsWon; }
        return GameState::Running;
    }

    void render(Canvas &canvas) const {
        world.render(canvas);
    }
};

Download Logic.hpp

The game logic includes:

• inputFromConsole() — handles user input.

• PlayerLogic and RobotLogic — define movement behavior for players and robots.

• Logic — combines everything and drives the game forward by updating the world based on player actions.

Using the Game Classes

We’re ready to glue everything together.

robot-escape/src/Application.hpp

#pragma once

#include "Canvas.hpp"
#include "Logic.hpp"
#include "World.hpp"

#include <erbsland/all_conf.hpp>

#include <filesystem>
#include <iostream>

using namespace el::conf;

struct Application {
    std::filesystem::path configPath;
    DocumentPtr config;
    Size canvasSize = Canvas::cDefaultSize;

    constexpr static auto cMinimumSize = Size{10, 10};

    void parseArgs(int argc, char **argv) {
        if (argc < 2) {
            std::cout << "Usage: " << argv[0] << " <config-file>\n";
            exit(1);
        }
        configPath = std::filesystem::path{argv[1]};
    }

    void readConfiguration() {
        try {
            Parser parser;
            const auto source = Source::fromFile(configPath);
            config = parser.parseOrThrow(source);
        } catch (const Error &error) {
            std::cerr << error.toText().toCharString() << "\n";
            exit(1);
        }
    }

    [[nodiscard]] auto buildWorld() const -> World {
        try {
            auto fieldSize = Size{
                static_cast<int>(config->getIntegerOrThrow(u8"field.width")),
                static_cast<int>(config->getIntegerOrThrow(u8"field.height"))};
            if (!cMinimumSize.fitsInto(fieldSize)) {
                std::cerr << std::format("Field size must be at least {}x{}\n", cMinimumSize.width, cMinimumSize.height);
                exit(1);
            }
            if (!fieldSize.fitsInto(canvasSize)) {
                std::cerr << std::format("Field size must be at most {}x{}\n", canvasSize.width, canvasSize.height);
                exit(1);
            }
            World world{fieldSize};
            world.addExitAtRandomPosition();
            world.setPlayerToRandomPosition();
            for (int i = 0; i < 3; ++i) {
                world.addRobotAtRandomPosition();
            }
            return world;
        } catch (const Error &error) {
            std::cerr << error.toText().toCharString() << "\n";
            exit(1);
        }
    }

    void renderLogic(const Logic &logic) {
        Canvas canvas{canvasSize};
        logic.render(canvas);
        canvas.renderToConsole();
    }

    void run() {
        auto initialWorld = buildWorld();
        std::cout << "----------------------------==[ ROBOT ESCAPE ]==-----------------------------\n";
        std::cout << "Welcome to Robot Escape!\n";
        std::cout << "You (☻) must run to the exit (⚑) before any robot (♟) catches you.\n\n";
        auto logic = Logic{std::move(initialWorld)};
        renderLogic(logic);
        auto state = logic.gameState();
        while (state == GameState::Running) {
            auto playerInput = inputFromConsole();
            if (playerInput == cQuitInput) {
                std::cout << "Goodbye!\n";
                return;
            }
            logic.advance(playerInput);
            renderLogic(logic);
            state = logic.gameState();
        }
        if (state == GameState::PlayerWon) {
            std::cout << "You won!\n";
        } else {
            std::cout << "You lost!\n";
        }
    }
};

Download Application.hpp

The Application class handles the full game flow:

• Parses command-line arguments.

• Loads the configuration file.

• Builds the initial World state.

• Starts and runs the game loop.

The loop displays instructions, initializes the game logic, renders the world, waits for input, processes the input, and repeats—until either the player or the robots win.

Replacing the Old Main Function

With the new Application class in place, we can simplify our main function dramatically:

robot-escape/src/main.cpp

#include "Application.hpp"

int main(int argc, char **argv) {
    Application app;
    app.parseArgs(argc, argv);
    app.readConfiguration();
    app.run();
}

Download main.cpp

Adding the New Files to CMake

Finally, we have to add the new source files to our CMake file.

robot-escape/CMakeLists.txt

cmake_minimum_required(VERSION 3.25)
project(RobotEscapeApp)
add_executable(robot-escape
        src/Canvas.hpp
        src/World.hpp
        src/Geometry.hpp
        src/Logic.hpp
        src/main.cpp)
target_compile_features(robot-escape PRIVATE cxx_std_20)
target_link_libraries(robot-escape PRIVATE erbsland-configuration-parser)

Recap

That was quite a bit of code! But with it, we now have a functioning game loop and a flexible foundation you can build on.

We’ve kept things as simple as possible while still providing enough structure to be engaging and fun to extend. Try tweaking parts of the game and see what happens—you’re in full control!

Compile and Run our Game →