The Powder Toy에서는 자신이 모드를 직접 만들 수 있으며 그것을 모드 포럼에 배포할 수도 있다. 이 문서에서는 The Powder Toy에서 모드를 코딩하기 위한 방법을 보여줍니다. 이 문서의 내용 외에 추가적인 질문이 있다면 이곳에서 확인할 수 있다.

EDITOR NOTE: Please do not edit this guide without consulting with TPT developers first; you risk your changes being mercilessly rolled back without prior notice otherwise.

Windows용으로 컴파일하기

Windows 10 이상에서 테스트됨.

요구되는 환경 준비

• Git을 이곳에서 다운로드하여 설치합니다.
  • 설치할 때 옵션을 변경하면 안 됩니다.
• Python을 이곳에서 다운로드하여 설치합니다.
  • Python 설치 완료를 안내하는 창이 표시되면 Path 길이 제한을 비활성화하고, 설치가 끝난 후 PATH 환경 변수에 Python을 추가하는 것을 권장합니다.
• Windows Terminal을 관리자 권한으로 실행한 뒤 다음 명령을 실행한다. 다 끝났다면 닫아도 된다.

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

• 관리자 권한이 없는 명령 프롬프트를 다시 열고 다음 명령을 실행한다.
  • replace [wherever you keep your repositories] with the actual path, taking care to remove the [] characters also; if the path has spaces in it, add "" around it
    • example: if your repositories are in C:\Users\Powder Toy Fan\Development, this path will be "C:\Users\Powder Toy Fan\Development"

cd /d [wherever you keep your repositories]

git clone https://github.com/The-Powder-Toy/The-Powder-Toy

MSVC를 사용하여 빌드 준비

MSVC는 Microsoft에서 제작된 Windows용 C/C++ 컴파일러로써, Visual Studio와 함께 제공됩니다. Using MSVC is the recommended way to build TPT on Windows if you are new to modding or have any reason whatsoever to prefer MSVC over MinGW (for which a separate guide is provided below).

• Visual Studio를 이곳에서 다운로드하여 설치합니다.
  • Visual Studio Installer에서 데스크톱 개발 워크로드를 선택한다.
  • The Powder Toy를 컴파일할 때에는 "MSVC"와 "Windows 11 SDK"만 필요하기 때문에 Visual Studio를 다른 용도로 사용하지 않을 것이라면 다른 항목의 선택을 모두 해제해도 무방하다.
• 설치가 완료되었다면 "x64 Native Tools Command Prompt for VS"를 실행한 다음, 다음 명령들을 실행한다.
  • 이 명령 프롬프트는 앞으로 매우 많이 쓰이게 될 것이기 때문에 작업 표시줄에 고정하는 것을 권장한다.

cd /d [복제된 리포지토리의 경로]
cd The-Powder-Toy
meson build-debug
cd build-debug
ninja

• 컴파일 과정에서 몇 가지 사소한 오류가 표시되지만 그냥 넘어간다. 문제가 발생한다면 이곳에 질문하면 된다.
  • 제대로 실행되었는지 확신하지 못하겠다면, Ninja를 다시 실행하면 된다. "No work to do."가 표시된다면 제대로 컴파일된 것이다.
• 컴파일이 완료되면 VS 프롬프트에서 컴파일된 The Powder Toy를 실행할 수 있다.

powder.exe

Visual Studio를 사용하여 빌드

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 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 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

MinGW를 사용하여 빌드 준비

MinGW는 Windows에서도 The Powder Toy를 GCC로 컴파일할 수 있도록 도와주는 패키지입니다. 이 문단은 MSVC보다 MinGW를 더욱 선호하는 사람들을 위해 작성되었습니다(MSVC로 컴파일하는 방법에 대해서는 윗문단을 참조하세요). this guide makes no effort to list possible ones.

• (이곳에서 MinGW를 내려받아 설치합니다.)
  • this comes in multiple "flavours", you will need "x86_64-posix-seh"
  • this guide has been tested with version 8.1.0
  • you will be asked for a directory to install MinGW to; decide on a directory and make note of it for later
    • even if you do not plan on doing anything with MinGW right now other than building TPT, you may need to install other flavours later, so it is recommended to install the required flavour to a location that will not interfere with others, e.g. include the version number and the flavour in the path
• find "Git Bash" (or similar, hereafter referred to as "bash 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
  • replace [your MinGW bin directory] with an actual path, taking care to remove the [] characters also
    • the "bin directory" will most likely be the path to whatever directory you installed MinGW to, with /bin appended to it, all backward slashes replaced with forward slashes (/ instead of \), and using the MinGW root notation (/c/ instead of C:\)
    • you do not need to add "" around the path if it contains spaces
    • example: if you install MinGW to C:\mingw-w64\mingw64-x86_64-8.1.0-release-posix-seh-rt_v6-rev0, the path to the bin directory will be /c/mingw-w64/mingw64-x86_64-8.1.0-release-posix-seh-rt_v6-rev0/bin
  • replace [wherever you keep your repositories] with the actual path, taking care to remove the [] characters also; if the path has spaces in it, add "" around it
    • the same applies to the format of the path of this directory as to that of the bin directory
    • example: if your repositories are in C:\Users\Powder Toy Fan\Development, this path will be "/c/Users/Powder Toy Fan/Development"

export PATH="[your MinGW bin directory]:$PATH"
cd [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 bash prompt should be possible

./powder.exe

• note that this executable depends on the MinGW runtime, which you will have in PATH due to the first command executed in the prompt
• a debugging session can be initiated like so (GDB cheat sheet):

gdb ./powder.exe

macOS용으로 컴파일하기

macOS Catalina 및 Big Sur에서 테스트됨.

요구되는 환경 준비

• 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
sudo -H python -m pip install --upgrade pip # if you get "No module named pip", try python3
sudo -H pip install --upgrade meson ninja
brew install pkg-config luajit fftw sdl2
cd [wherever you keep your repositories]
git clone https://github.com/The-Powder-Toy/The-Powder-Toy

최초 빌드

• 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용으로 컴파일하기

Ubuntu 20.04 및 Raspbian 10에서 테스트됨.

요구되는 환경 준비

• make sure your package lists are up to date (e.g. sudo apt update)
• install a C++ compiler (e.g. sudo apt install g++)
• 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 --upgrade meson ninja)
• optionally, install ccache (e.g. sudo apt install ccache)
• install a library utility (e.g. sudo apt install pkg-config)
• 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
• download the source code (e.g. git clone https://github.com/The-Powder-Toy/The-Powder-Toy)

최초 빌드

• 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

다음 단계(모든 플랫폼)

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). 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 these libraries on their own.

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).

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

It used to work, but it broke

Each platform has its own set of quirks that need to be worked around (mostly looking at you, microsoft and apple). Fortunately, our build system takes care of most of these. Unfortunately, the workarounds come in the form of upgrades to the build system, which are not installed automatically, and even if they are, affected build sites may need to be reconfigured manually. If you had at some point gotten TPT to build successfully, but since then your build sites somehow broke, you can try one of the following methods to fix them.

The most straightforward way to fix a single build site is to reconfigure it. To check if this worked, try running Ninja.

cd /d [wherever you keep your repositories]
cd The-Powder-Toy
meson --reconfigure --wipe build-debug # or whatever you named your build site
ninja

You will have to do this with every broken build site.

If this does not help, you can upgrade pip, Meson and Ninja. Like when setting them up for the first time, add sudo -H on linux and macos, and run this in an elevated command prompt on windows.

python -m pip install --upgrade pip # if you get "No module named pip", try python3
pip install --upgrade meson ninja

Once you are done with this, reconfigure your build sites (see above).

If not even this helps, that is your cue to start from scratch, following the guide as if you are building TPT for the first time, except you already have the repository, so you do not need to clone that again. In fact, this is where your changes to TPT are stored, so you should never delete it. Deleting your local clone of the repository never solves any problem, it only results in loss of code. Do not even consider doing it.

As a last resort, you can ask us on the forum.

빌드 옵션

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