• Description
• Prerequisites
• Installation
• Program usage
• Running the tests
• Built With
• Authorship

Description

The Corewar project is a computer simulation game where programs called "Champions" fight to become the last one standing. Champions share a virtual machine’s memory and manipulate it through a set of instructions. The winner is the last champion to execute a live instruction.

Prerequisites

• gcc
• make
• ncurses
• criterion (if you want to run the tests)

Fedora

sudo dnf install gcc make ncurses-devel

Ubuntu / Debian

sudo apt-get install gcc make libncurses5-dev libncursesw5-dev

Arch

sudo pacman -S gcc make ncurses

macOS

brew install gcc make ncurses

Installation

Clone this repository and enter it:

git clone https://github.com/lelouchzr/corewar.git && cd corewar

Compile the project:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
cd ..

This builds:

• libcorewar.a — shared utility library
• asm — assembler (in asm/asm)
• corewar — virtual machine (in corewar/corewar)
• visualizer — ncurses UI (in bonus/visualizer)

Program usage

Below are quick start examples for both assembling and running the VM. First see the concise commands, then detailed descriptions follow.

Quick examples

# Assemble a source file
./asm/asm champion1.s

# Run the virtual machine
./corewar/corewar champion1.cor champion2.cor

# (Bonus) Launch the visualizer
cd bonus && ./visualizer champion1.cor champion2.cor

Assembly part

USAGE
    ./asm/asm file_name[.s]

DESCRIPTION
    Convert a Redcode source file into a `.cor` binary for the VM.

Example:
    ./asm/asm champion1.s

Virtual machine part

USAGE
    ./corewar [-dump nbr_cycle] [[-n prog_number] [-a load_address] prog_name] ...

DESCRIPTION
    -dump nbr_cycle dumps the memory after the nbr_cycle execution (if the round isn’t already over) with the following format: 32 bytes/line in hexadecimal (A0BCDEFE1DD3...)

    -n prog_number sets the next program’s number. By default, the first free number in the parameter order

    -a load_address sets the next program’s loading address. When no address is specified, optimize the addresses so that the processes are as far away from each other as possible. The addresses are MEM_SIZE modulo

Example (no flags):

# Assemble first
./asm/asm champion1.s

# Run VM
./corewar/corewar champion1.cor champion2.cor champion3.cor champion4.cor

Running the tests

Note: To build and run tests, uncomment add_subdirectory(tests) in the root CMakeLists.txt and rebuild.

Functionality tests are provided using Criterion.

# From project root
./tests/unit_tests            # basic run
./tests/unit_tests --verbose  # verbose output

Built With

• C — Main language used
• ncurses — Used for the bonus visualizer UI

Authorship

We have decided not to display personal names or email addresses in this project repository. To maintain privacy, no co-author metadata was added to commits. Each team member has independently published this project in a repository under their personal GitHub profile.