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 https://github.com/thurn/spelldawn-site/issues/new 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:

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.

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.

3) Install Rust and Cargo

Spelldawn is written in the Rust programming language and uses the standard cargo package manager. https://www.rust-lang.org/tools/install gives information about how to set it up using rustup.

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.

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 https://github.com/thurn/spelldawn/fork 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 git@github.com:{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 0.0.0.0:50052

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

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:

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

  [target.x86_64-unknown-linux-gnu]
  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:

• just build Builds the server binary
• just run Runs the server
• just watch Runs the server and re-builds on file changes
• just code-review Runs lints, tests, and other checks which should be completed before sending a pull request.
• just test Run tests
• just benchmark Run benchmark tests. With an argument runs only a specific named benchmark.
• just matchup Command line tool to run a game between two AI agents.
• just nim Command line tool to run the Game of Nim between agents or between an agent and a human player.
• just update-cards Automatically adds new card definitiions to the master card definition list.
• just protos Regenerates protocol buffer definitions
• just screenshot-tests Runs screenshot tests, comparing results to known-good canonical images.
• just record Records new canonical images for screenshot tests.
• just fix Attempts to automatically fix common lint and errors.
• just machete Tool to automatically remove unused crate dependencies.