Building Plasma
Plasma uses PlasmaBuild to compile the engine and generate IDE workspaces. Start with Building for Windows or Building for macOS for installation and your first editor build.
Build Platforms
| Platform | --platform | Host | Notes |
|---|---|---|---|
| Windows x64 | Windows | Windows | Editor, tools and games. See Building for Windows. |
| Linux x64 | Linux | Linux, or Windows through WSL | Editor, tools and games. |
| macOS | Mac | macOS | Editor, tools and games with Apple Clang, .dylib libraries and Objective-C++ sources, rendering through Metal. See Building for macOS. |
| Android arm64 | Android | Windows, Linux, macOS | Engine libraries and APKs. Packaging rules live in Code/BuildSystem/PlasmaBuildAndroid.pb.cs. To ship a project to Android, use the editor's export; see Android. |
A platform appearing in a generated workspace does not mean every target supports it.
PlasmaBuild itself runs on .NET 10 (SDK 10.0.303). The setup scripts (Setup.cmd on Windows, Setup.sh on Linux and macOS) build it from Utilities/PlasmaBuild and download that SDK for you, so the PlasmaBuild you use always matches the build rules of your checkout. Run the setup script again after pulling changes to PlasmaBuild.
Build System
Run commands from the engine repository root. Build metadata lives in C# rule files:
| File | Purpose |
|---|---|
*.module.cs | Source files, include paths, definitions, and module dependencies. |
*.target.cs | Executables or libraries, dependencies, and build steps. |
*.workspace.cs | Targets included in an IDE workspace. |
PlasmaEngine.workspace.cs selects PlasmaEditor. Its target rules include editor dependencies and runtime tools such as Player, Inspector, ShaderCompiler, and Fileserve.
Generate a workspace:
plasmabuild generate workspace --workspace PlasmaEngine --ide vs2026
Or build directly without generating a solution:
plasmabuild build PlasmaEditor --platform Windows --arch x64 --configuration Development
The repository includes workspace scripts for Visual Studio, VS Code, Rider, CMake and, on macOS, Xcode (GenerateWorkspace_xcode.sh, which runs plasmabuild generate workspace --workspace PlasmaEngine --ide xcode). Generated CMake files provide IDE integration backed by PlasmaBuild. Make persistent build changes in the rule files, then regenerate the workspace.
Build Types
Use the full configuration names in commands:
| Configuration | Intended use |
|---|---|
Debug | Investigating C++ problems with a debugger. |
Development | Everyday editor and engine development; the default configuration. |
Release | Optimized profiling and performance measurements with development diagnostics. |
Shipping | Final runtime builds with development facilities disabled. |
Both Development and Release map to the engine's internal Dev build type. Release retains assertions, profiler scopes, Tracy, and diagnostic statistics while enabling optimization. Use it for performance comparisons instead of assuming a Development build has release performance.
Older PlasmaBuild installations or generated workspaces may list only Debug, Development, and Shipping. Use a PlasmaBuild version compatible with the checkout and regenerate the workspace if Release is unavailable.
Shipping disables facilities such as profiling and allocation tracking. Debug-symbol generation is controlled by build rules; do not assume Shipping builds can never produce symbols.
Build Outputs
Binaries are written to Binaries/<Platform>_<Configuration>: Windows development binaries to Binaries/Windows_Development (including PlasmaEditor.exe), Mac binaries to Binaries/Mac_Development, and so on. Intermediate build data and generated project files live under Intermediate/.
Keep companion executables, DLLs, and deployed runtime files together. Copying only the editor executable does not produce a usable engine installation.
Vulkan
Vulkan headers are included in the engine's third-party sources, so compiling the Vulkan renderer does not require the Vulkan SDK. Install the SDK when you need validation layers or Vulkan development tools.
The renderer loads Vulkan dynamically. Running it still requires a compatible GPU and Vulkan driver/runtime; an optional SDK does not make the runtime optional.
Use the Vulkan-Hpp dispatch configured by RendererVulkanDLL.h. Direct calls to Vulkan C entry points can cause linker errors because the renderer uses dynamic dispatch.
Static Linking
Static linking can remove apparently unreferenced registration code. Follow the relevant platform and module rules when integrating statically linked code. The current Android packaging workflow uses shared libraries for NativeActivity; it does not require all engine code to be statically linked.