Initial setup and compiling
Getting the required tools and building doukutsu-rs from source.
Last updated
Getting the required tools and building doukutsu-rs from source.
Last updated
While you can modify the data files of the base engine using a compatible editor such as Booster's Lab (much like you'd do with Cave Story freeware), a lot of times you might want to tweak the engine's behavior to your needs.
In freeware Cave Story, you'd accomplish advanced modifications of the engine by patching the executable file. This is known as Assembly (ASM) hacking.
It is important to note, however, that none of the Assembly hacks that are compatible with the freeware game will work with doukutsu-rs. However, patching the executable is not needed, since the project is open-source, meaning you can clone it, modify it, and compile it to fit your needs.
In this guide, you'll be able to learn what tools you'll need for the task, how to get them, and how to compile the engine from source. The process itself is fairly straightforward and shouldn't take more than 30-40 minutes.
While the engine itself is written in Rust, some underlying components have C/C++ bindings, therefore you will need to have the C++ build tools installed to download and build the dependencies.
You can download the build tools from Microsoft's website.
Once you open the installer, you should select "Desktop development with C++" in the list of workloads, then press "Install" to start the installation. You don't need the other components. You may also install the build tools from the Visual Studio installer, if you're already a Visual Studio user.
This process will take a while, as it needs to install many components (around 7-8 GB).
Once the installation process has completed, you can close the installer.
TL;DR: Install "Desktop development with C++" from the Visual Studio C++ build tools.
You can download the rustup installer from Rust's website. Unlike the build tools, Rust doesn't have a graphical installer, but the whole process will only take three keystrokes in total.
Once you've downloaded the executable, double clicking it will open up a command prompt. At the bottom, it will ask you to select an installation option. For our purposes, the default installation settings are sufficient, so you can type 1 and press Enter.
This process will also take a bit, but once it's done, it will ask you to press Enter to quit the installer.
TL;DR: install Rust with the default settings.
CMake is a build tool for C and C++ projects. You will not need to use CMake directly, however, some of the dependencies we will compile require it to be installed.
Go to the CMake download page, scroll down to "Binary distributions" and download the MSI installer.
Once you reach to the install options, it's very important to add CMake to PATH, so you must enable this setting, otherwise CMake will not be recognized by Cargo during dependency building.
Once CMake is installed, we have installed all of the tools we need to compile the project. Woohoo!
Install CMake and make sure to select the option to add it to the PATH when prompted.
Since doukutsu-rs uses Git for version control, you'd normally want to clone the repository using git, however, to make it simpler, in this guide we will just download the source code as a ZIP file.
Head over to our GitHub repository, click on the green "Code" button and select "Download ZIP".
You may extract the contents of the ZIP archive wherever you want, however, we advise you to not extract it:
in a system directory, or any directory that requires administrator access (such as Program Files)
in a cloud sync directory (such as directories synced to OneDrive) - this is because there will be lots of files, which will not only waste your cloud storage, but such folders are known for not being able to handle many smaller files too well (and efficiently)
TL;DR: download the source code from GitHub and extract it to a non-administrator directory.
We will do most of the work in a terminal/command line, therefore, the next step is to right click the directory you've just extracted and select "Open in Windows Terminal" (or Command Prompt/Powershell).
A window like this should pop up:
...and we've finally reached the most exciting part of the process - compiling the engine. Run the following command to create a debug build:
This process is going to take a while, as it needs to download and compile all the dependencies that are required by doukutsu-rs. It's important to note, however, that this will only take so long on the very first time you compile the engine. Any builds after that should be fairly quick.
Once the build has finished, you should be seeing the following:
TL;DR: open the extracted directory in a terminal and run
cargo build.
doukutsu-rs doesn't bundle the game's data files, therefore you will need to obtain them yourself. There's a detailed guide on how to do that in the README of the GitHub repository.
If you go back to your file explorer now, you'll be able to see a new directory called "target", with another directory called "debug" inside. If you see a file called "doukutsu-rs.exe" there, that means everything went smoothly! You must copy your "data" directory into this directory. You should be seeing the following file structure:
From here, you can double-click the doukutsu-rs.exe file to run the game. You can also run the following in the terminal if you want to build and run from one place:
TL;DR: copy your data files to the build directory and run the executable.
Naturally, most of the installation process will happen through your distribution's terminal. Since there's many flavors of Linux and desktop environments made for Linux operating systems, we can't go into too many details about doing it "the GUI-way", however, we will try to generalize as much as possible. Doing everything from the terminal helps in this process.
To get started, we will need to following software:
gcc or clang: for compiling the project's C/C++ dependencies
cmake: the build system used by some dependencies
git: for cloning the source files and the game data files
rust: to compile the project
How you're going to install these dependencies depends on what Linux distribution you're using. We will cover the three most popular ones.
Note: on a regular desktop Linux installation, these tools should be enough, as everything else should already be installed. However, if you're trying to do this on a server or Windows Subsystem for Linux, you will need to install additional dependencies:
Debian: libasound2-dev libudev-dev pkg-config
Arch: alsa-lib
Red Hat: alsa-lib-devel
Please also note that the project will not run unless you have a valid video device connected to your computer. Thus, while you may be able to compile doukutsu-rs on a server, you will not be able to run it. Newer versions of WSL support proxying video input to Windows if you configure the X Window System on your WSL container.
Installing Rust should be identical on every Linux distribution. Just run the following command:
Press 1 and the Enter key, when prompted for installation options.
Once the installation has completed, you might want to add the Rust binaries to your PATH environment variable. To do this, you want to edit your shell configuration file.
Add the following at the end of the file:
Press Ctrl+S and Ctrl+X when done, then run:
Add the following at the end of the file:
Press Ctrl+S and Ctrl+X when done, then run:
Add the following at the end of the file:
Press Ctrl+S and Ctrl+X when done, then run:
...and just like that you should be ready to go. We can start cloning the repository!
You may cd in a directory of your choice and use git to clone the repository from GitHub:
Once you're in the doukutsu-rs directory, run the following command to fetch all dependencies and compile the project in debug mode:
This process will take a while, as it has to fetch and compile lots of dependencies. Once you see the following message, you should be good to go:
This will build the project in debug mode, so you will find the executable in the target/debug subdirectory.
You can use git to acquire the data files needed to run the game.
To run the project, just run the following command:
Similarly to Linux, we will do most of the initial setup process and compilation through the Mac OS terminal. You can search for the Terminal app in the Launchpad or Spotlight.
While you could install Xcode as a whole from the App Store, it will take a long time (sometimes up to a few hours, even) and you will likely not need most of the tools from there anyway, so it would be a waste of storage space as well. Luckily, Mac OS provides a way to install just the command line tools, without Xcode itself and all the extra tools that comes with it.
To do this, run the following command in the terminal:
You will see a prompt where you'll have to confirm the installation. After confirming it, the installation will take around 8 to 10 minutes, but it could take longer on older devices.
This will install many things, but in our scope, it's responsible for installing the following:
C/C++ compiler
git
We will also need to install Homebrew, which will let us install additional packages more easily. To do this, use the following command:
Once brew is installed, we can install CMake using the following command:
To install Rust, the process is identical to how you'd install it on Linux. Run the following command to set up rustup:
Type 1 when prompted and press Enter:
After that, you need to add the Rust binaries to your PATH. The Linux guide contains instructions for zsh (Mac OS default shell) and other shells. If you haven't done any development on your Mac before, it's very likely that you need to follow the zsh guide. To check, you can run the following command:
The initial xcode-select command will also install Git, which we will use to clone the doukutsu-rs repository.
Using the cd command, navigate to the directory where you want to clone the project, then run the following commands in succession:
Type ls -ahg to confirm that the cloning was successful. You should be seeing something like this:
Run the following command to compile doukutsu-rs in debug mode:
This process will take a while, as it has to fetch and compile lots of dependencies. Once you see the following message, you should be good to go:
This will build the project in debug mode, so you will find the executable in the target/debug subdirectory.
You can use git to acquire the data files needed to run the game.
To run the project, just run the following command:
