Language:	English  • 한국어 • 中文

This is a guide to get you started on coding for The Powder Toy. If you have any questions, just ask in the Development Assistance section on The Powder Toy forums.

Windows (tested on Windows 10)

Required environment setup

• install Git (get it here)
  • options should be left as is
• install Python (get it here)
  • it is recommended to allow the installer to add Python to PATH and to disable the path length limit (the latter is offered near the end of the installation process)
• open an elevated command prompt (search for "cmd" the Start Menu, right-click the most sensible result, click "Run as administrator") and execute the following commands

python -m pip install --upgrade pip
pip install meson ninja

• install Visual Studio (get it here)
  • select the Desktop Development workload
  • you really only need "MSVC" and "Windows 10 SDK", so you can uncheck everything else in the list on the right
• find "x64 Native Tools Command Prompt for VS" (or similar, hereafter referred to as "VS prompt") in the Start Menu and execute the following commands
  • it is recommended to pin the resulting window to your taskbar; you will be using this a lot to build TPT

cd /d [wherever you keep your repositories]
git clone https://github.com/The-Powder-Toy/The-Powder-Toy

Building for the first time

• open a VS dev prompt (see above) and execute the following commands

cd /d [wherever you keep your repositories]
cd The-Powder-Toy
meson build-debug
cd build-debug
ninja

• you may see a few warnings throughout all of this, but no errors (if you do at any stage, do not try to skip it; ask us about it on the forum instead)
  • if you are not sure, run Ninja again; if it says "no work to do", everything worked fine
• at this point, running TPT from the prompt should be possible

powder.exe

Using the Visual Studio IDE

The method above does not let you use the 'Visual' part of Visual Studio, the IDE. Although Meson has limited support for this use case, if for some reason you wish to use the IDE, you can ask Meson to generate a build site that uses Visual Studio instead of Ninja.

• open a VS dev prompt (see above) and execute the following commands

cd /d [wherever you keep your repositories]
cd The-Powder-Toy
meson --backend=vs -Dbackend_startup_project=powder build-debug-vs

• you will not need the VS dev prompt beyond this point

This will generate a build site with a Visual Studio solution inside (the-powder-toy.sln). You can use this as any other solution, except for a few key differences:

• the IDE can only be used for more comfortable editing and debugging and not much else, including changing the project structure; you will have to familiarise yourself with Meson and work with the meson.build files in order to do that
• once you actually change meson.build files, Meson will automatically regenerate the solution the next time you try to build it; Visual Studio will give you a scary popup about the solution having been changed, which is perfectly normal, just click 'Reload Solution'
• the configuration you currently see (most likely debug|x64, if you are following this guide exactly) is the only configuration the solution has, and it is not recommended to add other configurations as Meson will just overwrite them the next time it regenerates the solution; instead, you have to generate separate build sites with Meson

MacOS (tested on MacOS 11)

NOTE: MacOS 11 users should consult this thread on installing required libraries in a way that lets our build system find them. Sadly, this process has been reported to be more complicated on MacOS 11 than on previous versions, due to problems with pip, brew, and pkg-config. We hope that these problems will be resolved soon, but we have no control over when that happens, hence this note. If you succeed in building TPT with the help of the aforementioned thread, please post a comment there. Library installation steps aside, this guide still applies. But not all Macs require this.

Required environment setup

• install Homebrew (get it here)
• in the next step, xcode-select is used; note that you do not need to install Xcode to run that command
• in a terminal, execute the following commands

xcode-select --install # asks you for confirmation, installs compilers
brew install pkg-config luajit fftw sdl2
brew install meson ninja
cd [wherever you keep your repositories]
git clone https://github.com/The-Powder-Toy/The-Powder-Toy

Building for the first time

• cd to the repository root and execute the following commands

meson build-debug
cd build-debug
ninja

• you may see a few warnings throughout all of this, but no errors (if you do at any stage, do not try to skip it; ask us about it on the forum instead)
  • if you are not sure, run Ninja again; if it says "no work to do", everything worked fine
• at this point, running TPT from the prompt should be possible

./powder

Linux (tested on Ubuntu 20.04)

Required environment setup

• make sure your package lists are up to date (e.g. sudo apt update)
• install git (e.g. sudo apt install git)
• install python (e.g. sudo apt install python3)
• install pip if not present (consult their guide)
• upgrade pip (e.g. sudo -H python3 -m pip install --upgrade pip)
• install Meson and Ninja if not present (e.g. sudo -H pip install meson ninja)
• optionally, install ccache (e.g. sudo apt install ccache)
• install required libraries (e.g. sudo apt install libluajit-5.1-dev libcurl4-openssl-dev libfftw3-dev zlib1g-dev libsdl2-dev)
  • your package manager may package these under wildly different names; if unsure, skip this step and install whatever libraries Meson asks for when setting up the build sites

Building for the first time

• cd to the repository root and execute the following commands

meson build-debug
cd build-debug
ninja

• you may see a few warnings throughout all of this, but no errors (if you do at any stage, do not try to skip it; ask us about it on the forum instead)
  • if you are not sure, run Ninja again; if it says "no work to do", everything worked fine
• at this point, running TPT from the prompt should be possible

./powder

Next steps (all platforms)

Updating the binary

Now that you have successfully built TPT for the first time, you will probably want to change things in the code. To update the binary, build it again by executing

ninja

in the same prompt you executed it the last time. You will have to do this every time you change something and want the binary to reflect the change.

Release builds

So far, you have been building "debug" binaries. These make debugging significantly easier than "release" builds, but they also offer less performance. You can instead build a "release" binary, which is much more performant, but very difficult to debug. Only use these builds when you are certain that you have no more bugs to take care of. If a bug does appear later on, go back to building debug binaries.

To build a release binary, navigate back to the root of the repository in your prompt and create a new build site with Meson, then build with Ninja again

cd /d [wherever you keep your repositories]
cd The-Powder-Toy
meson -Dbuildtype=release build-release
cd build-release
ninja

Note that build-debug and build-release directories are independent "build sites", each of which you can update with Ninja when you set them as your current directory (by using cd, see the lists of commands above).

Static builds

Both the debug and release configurations above produce "dynamic" binaries, which means they depend on certain components of your system (libraries you have installed with apt on linux or with brew on macos) or files other than powder.exe (DLLs in the same directory as powder.exe on windows). You can get rid of most of these dependencies by building a "static" binary. This way, the binary will depend on very basic components of your system that are very likely to be present. It will also gain a few megabytes and linking it will take longer, which is why you would only do this when you are about to release it to the public.

To build a static binary, navigate back to the root of the repository in your prompt and create a new build site with Meson (see NOTE below!), then build with Ninja again

meson -Dbuildtype=release -Dstatic=prebuilt build-release-static
cd build-release-static
ninja

NOTE: On Windows, you will also need to add the -Db_vscrt=static_from_buildtype option to the Meson call above, otherwise the resulting binaries will be dynamically linked against the MSVC runtime (vcruntime.dll and similar). If you are a mod author, please make sure you are not shipping such binaries, as your users are used to TPT not depending on anything and thus are unlikely to have experience with installing the MSVC runtime on their own.

meson -Dbuildtype=release -Dstatic=prebuilt -Db_vscrt=static_from_buildtype build-release-static
cd build-release-static
ninja

Build options

Build options are passed to Meson at when you set up a build site (see examples above) or at any later time, when the build site is already in use. In both cases, they are passed as command line arguments of the form -D[name]=[value]. For example, to set up a build site that compiles TPT with Lua 5.1 instead of LuaJIT, you would issue the following command

meson -Dlua=lua5.1 build-debug-lua5.1

But you could also take an existing build site and change the relevant build option to do the same

cd build-debug
meson configure -Dlua=lua5.1

The next time you run Ninja, everything that needs to be rebuilt as a result of this change will be rebuilt. See the Meson quick guide for more on configuring build sites.

Below is a list of build options our Meson setup supports

Name	Type	Description
static	one of 'none', 'system', 'prebuilt'	Build statically using libraries present on the system ('system') or using prebuilt libraries official builds use ('prebuilt')
beta	boolean	Beta build
ignore_updates	boolean	Don't show notifications about available updates
install_check	boolean	Do install check on startup
http	boolean	Enable HTTP via libcurl
gravfft	boolean	Enable FFT gravity via libfftw3
snapshot	boolean	Snapshot build
version_major	integer	Major version
version_minor	integer	Minor version
version_build	integer	Build number
snapshot_id	integer	Snapshot ID, only relevant if 'snapshot' is true
future_major	integer	Future major version, used for debugging and in snapshots, only relevant if at least one of 'debug' and 'snapshot' is true
future_minor	integer	Future minor version, similar to 'future_major'
mod_id	integer	Mod ID, used on the Starcatcher build server; the build server will compile for all platforms for you and send updates in-game, see jacob1 to get a mod ID
lua	one of 'none', 'lua5.1', 'lua5.2', 'luajit'	Lua library to use
ssl	currently only 'openssl'	SSL library to use
x86_sse	one of 'none', 'sse', 'sse2', 'sse3', 'auto'	Enable SSE (available only on x86)
native	boolean	Build with optimizations specific to the local machine, may not run on other machines, overrides 'x86_sse'
ogli	boolean	Enable OpenGL interface rendering (currently defunct)
oglr	boolean	Enable OpenGL particle rendering (currently defunct)
build_powder	boolean	Build the game
build_render	boolean	Build the thumbnail renderer
build_font	boolean	Build the font editor
server	string	Simulation server
static_server	string	Static simulation server
update_server	string	Update server, only used by snapshots and mods, see 'snapshot_id' and 'mod_id'