Contributing Code - Getting Started

Spelldawn is implemented using a 'thin client' model, with a small Unity application implemented in C# providing a front-end and a game server written Rust providing the game logic itself. This page describes how to set up a development environment to contribute to the project.

If you run into any problems with this documentation, please feel free to submit an issue via to request an update or send a pull request to fix it yourself!

Server Development Environment

Throughout this section, these icons give OS-specific information about the setup process:

Set up information for Windows
Set up information for Mac OS
Set up information for Linux

1) Install Command Line Tools

The build system for Spelldawn assumes basic UNIX command line tools will exist, such as sh, rm, mv, mkdir, cp, and grep.

A simple option to set up a command line environment on Windows is the Cmder console emulator, which bundles standard UNIX tools with a nice terminal. A more comprehensive alternative is to install Windows Subsystem for Linux, which includes a complete Linux distribution. If you use this option, follow the options below instead.
These tools should already be installed on your system.

2) Install Git

Spelldawn uses the Git version control system to manage code, so you will need a copy of it. The Installing Git section of the Git website gives information about how to do this.

Note: You can use Github Desktop if you'd like, but you will get an authentication error after cloning the repository and need to manually add it again from your filesystem. This is because Github Desktop always fetches submodules, there is no way to disable this behavior.

The Cmder environment includes Git for Windows. Otherwise, you can download it from the link above.
The git command is bundled with Mac OS, although you can consider installing a newer version via Homebrew.
Linux package managers include Git, e.g. sudo apt install git

3) Install Rust and Cargo

Spelldawn is written in the Rust programming language and uses the standard cargo package manager. gives information about how to set it up using rustup.

For windows, you will also need a copy of the MSVC compiler. The Rust installer should prompt you to install Visual Studio Community Edition.

4) Install CMake

We use the gRPC RPC Framework to communicate between the server and the client. gRPC depends on the CMake build tool being on your system $PATH for compilation. provides a Windows MSI installer. You should be prompted to add CMake to your PATH system variable, which is required for the code to compile.
You can install CMake via the Homebrew package manager: brew install cmake
Linux package managers should contain CMake, e.g. via sudo apt install cmake.

5) Install Just

Just is a command runner. It's a useful way of bundling together scripts for a project. If you followed step #1 correctly, running cargo install just should set it up for you.

6) Clone the project files

Navigate to to create a fork of the project for your changes. You will need to create a GitHub account if you don't already have one. Then run

git clone{your_username}/spelldawn.git

to download a local copy of the project, replacing {your_username} with your Github account name.

7) Build the Server

If you followed all of the previous steps correctly, you should be able to cd spelldawn to change to the spelldawn directory and then compile and run the game server via:

just run

If everything is working correctly, you should get the message

Server listening on

Client Development Environment

1) Install Unity & Unity Hub

Once you've completed setting up the server development environment, you can set up the client and connect it to your running server. To start you will need to install Unity. The best way to do this is to install Unity Hub, which manages Unity installations.

Once Unity Hub is installed, you must install the version of the Unity Editor currently listed in the project's ProjectVersion.txt file. You may need to visit the Unity Download Archive to find a copy of the correct version.

Once you have installed the correct verison of Unity, use the "Add Project" button in Unity Hub to select the spelldawn directory, and then click on the project name to open it. The initial project import process will take some time to complete.

2) Open the Game Scene

Once the project is open, expand the "Scenes" directory and click on the scene called "Game". This is the primary Unity scene used for gameplay.

3) Camera Alignment

Select the "Main Camera" in the scene hiearchy, and then select "Align View to Selected" in the Unity GameObject menu. This step enables you to see what is going on in the scene view while the game is running.

4) Configure Simulator

Navigate to the "Game" view and click the dropdown in the tab name. Switch it to "Simulator". Select an iPhone SE (2nd Edition) simulator and rotate it to landscape. This lets you view the game as it will appear on-device.

Note: You will only see the development 'graybox' assets in the simulator. This is expected. The production art assets are separately licensed under the terms of the Unity Asset Store License and are not included in the github repository.

5) Run the Game

If you click the Play button, the game should begin. In the terminal where you invoked just run, you should see the message

WARN server::requests: received_connection

6) Start a new game

Click the debug button on the top-left of the screen. After a small delay, you should see the debug controls menu appear

You can click "New Game" here to start a new game. There are also several other useful commands, for example you can use "Flip View" to change the player whose perspective you are viewing. You can also assign an AI Agent to be your opponent in the new game, change action and mana values, and use the 'save state' and 'load state' buttons to snapshot the current game state to return to it later.

After clicking "New Game", you should see an opening hand. The game has started!

No AI Agent is assigned for your opponent by default, so nothing will happen initially. You can assign one yourself or switch back and forth between players using the "Flip View" command to manually play out a game.

Optional Setup

There are a few more optional setup steps for an improved overall development experience.

Install Rust Nightly

Nightly rust is not used for compiling the project itself, but it provides useful tooling features such as expanded rustfmt capabilities. Install it via rustup

rustup toolchain add nightly-x86_64-pc-windows-msvc
rustup toolchain add nightly-aarch64-apple-darwin (or nightly-x86_64-apple-darwin)
rustup target add nightly-x86_64-unknown-linux-gnu

Install Criterion

Criterion is a fantastic benchmarking tool which powers our benchmark tests. In order to run the tests, you should run cargo install cargo-criterion

Install a custom linker

Using a custom linker can significantly improve compilation speed. The lld linker on Mac OS and Windows and the mold linker on Linux are good options that can be installed from standard package managers.

Create a ~/.cargo/config.toml file on your system and then add a custom linker configuration for your build target:

  rustflags = ["-C", "link-arg=-fuse-ld=/opt/homebrew/opt/llvm/bin/ld64.lld"]

  linker = "clang"
  rustflags = ["-C", "link-arg=-fuse-ld=/path/to/mold"]

Appendix: Other Just Commands

The Just command runner offers a few different commands which can be used during development: