🎮 TikTakToe

A TikTakToe game written for the nRF-51 microcontroller with an arm-cortex-m0 CPU.

Tip

We recommend viewing this and any other markdown file using our documentation page which provides improved formatting!

[TOC]

✨ Features

• 🎮 PVP and PVE modes
• 🖥️ Cross-Platform Compatibility
• ⚙️ Highly Customizable
• 🐳 Docker Support for 0 dependency execution

📚 Documentation

Check out our documentation to learn more about the code and for an improved version of this file!

🛠️ Build and Run

🖥️ Using CMake and qemu

To build the project using CMake and qemu some dependencies, which can be found under dependencies are required.

• 🐧 Linux

  # 1. Configure the cmake project
  cmake --preset arm-cortex-m0-unix
  
  # 2. Build the project
  cmake --build --preset arm-cortex-m0-unix
  
  # 3. Run the project
  qemu-system-arm -M microbit -device loader,file=build-cortex-m0/TikTakToe.elf -nographic -s -serial mon:stdio

• 🪟 Windows

  # 1. Configure the cmake project
  cmake --preset arm-cortex-m0-mingw
  
  # 2. Build the project
  cmake --build --preset arm-cortex-m0-mingw
  
  # 3. Run the project
  qemu-system-arm -M microbit -device loader,file=build-cortex-m0/TikTakToe.elf -nographic -s -serial mon:stdio

  Due to a problem with the TIMER device on Windows, functionality regarding turn time limits are disabled when building with the MinGW generator!

🛠️ Using the provided Makefile

• 🐧 Linux

  The provided Makefile can be used to easily build and run the project using a single command.

  # Configure, build and run the project
  make run
  
  # Configure and build the project
  make 
  
  # Remove the build directory
  make clean
  
  # Generate doxygen documentation (requires doxygen installed)
  make generate_documentation

• 🪟 Windows

  The provided Makefile was created with Linux in mind, while it may be possible to use it on Windows with small modifications, we recomend using CMake directly!

🐳 Using Docker

Docker can be used to build and run the application without the need for external dependencies. For this you have to options:

☁️ Use Dockerhub

# Using DockerHub
docker run -it definitelynotsimon13/tiktaktoe:latest
# Using GitHub Container Registry
docker run -it ghcr.io/softwareengineeringone/tiktaktoe:latest

🏗️ Build locally

docker build -t [TAGNAME] .
docker run -it [TAGNAME]

Important

In either case the -it flags are required to properly capture input from stdin!

🍎 MacOS

We are currently unable to test the game under MacOS. Since it's unix based, it's assumed that, provided all dependencies are available, you can proceed as described in the Linux sections.

However no guarantees regarding functionality or possible bugs can be made.

⚙️ Configuration

The project has a few options that can be changed before compilation.

• Number of rows (default is 4)
• Number of columns (default is 4)
• Ticks per turn (default is 20)
• Tick speed (default is 12, lower is faster)
• Unicode support (default is "ON")
• ASCII Art (default is "ON", may look broken on small screens)

Caution

No restrictions have been set on any of the configurations. Beware that extrem deviation from the default values, may result in a degraded playing experience

These can be set by:

• Using CMake

  When configuring the project the default command cmake --preset arm-cortex-m0-{unix/mingw} can be appended by:

  • for the number of rows: [...] -DCELLS_PER_COL=$(NUMBER)
  • for the number of cols: [...] -DCELLS_PER_ROW=$(NUMBER)
  • for ticks per turn: [...] -DTICKS_PER_TURN=$(NUMBER)
  • for tick speed: [...] -DTICK_SPEED=$(NUMBER)
  • for unicode: [...] -DENABLE_UNICODE=$(ON/OFF)
  • for ascii art: [...] -DENABLE_ASCII_ART=$(ON/OFF)

  All options can be combined.

• Using the Makefile

  When using the Makefile to configure/build the project variables can be passed like this:

  • for the number of rows: make ROWS=$(NUMBER)
  • for the number of cols: make COLS=$(NUMBER)
  • for ticks per turn: make TICKS_PER_TURN=$(NUMBER)
  • for tick speed: make TICK_SPEED=$(NUMBER)
  • for unicode: make UNICODE=$(ON/OFF)
  • for ascii art: make ASCII_ART=$(ON/OFF)

  All options can be combined.

  Due to the way the Makefile is structured, these may also be passed when using e.g. make run. However please note, that in order for changes to take affect the build directory may have to be deleted. This can be done using make clean or by manually deleting the directory.

📦 Dependencies

• Ubuntu/Debian

  sudo apt install gcc-arm-none-eabi cmake qemu-system-arm

• Nix / NixOS

  You can either use the provided Flake, or add the following packages:

  gcc-arm-embedded
  cmake
  qemu
  

• Arch

  sudo pacman -S arm-none-eabi-gcc cmake qemu-system-arm

• MacOS

  brew install gcc-arm-embedded cmake qemu

• Windows

  • CMake

  # Using Winget
  winget install CMake.CMake
  
  # Using Chocolatey
  choco install cmake --pre 
  
  # Or manually using the link above

  • MinGW Makefiles (we recommend using MSYS2, but other prebuilt options are available)

    1. Install MSYS2
    2. Open MSYS2 UCRT64 shell
    3. Install Make pacman -S mingw-w64-ucrt-x86_64-make
    4. Ensure C:\msys64\ucrt64\bin is added to PATH
       • Directory may differ based on your choice during installation

  • Qemu

    1. Install MSYS2
    2. Open MSYS2 UCRT64 shell
    3. Install Make pacman -S mingw-w64-ucrt-x86_64-qemu
    4. Ensure C:\msys64\ucrt64\bin is added to PATH
       • Directory may differ based on your choice during installation

  • GNU Toolchain for arm-eabi

    1. Install from link above
    2. Ensure installation location is added to PATH

🏗️ Architecture

To learn more about the the architecture we used to create this game check out Architecture.md!

📜 Conventions

If you want to know about the coding convection we used when creating code check out Conventions.md!

👥 Authors

• Simon Blum
• Ben Oeckl
• Paul Stöckle
• Max Rodler

🙏 Acknowledgements

• arm-cortex-m0-cmake-start - Base template used for the project