Skip to main content
Version: Next (dev)

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--platformHostNotes
Windows x64WindowsWindowsEditor, tools and games. See Building for Windows.
Linux x64LinuxLinux, or Windows through WSLEditor, tools and games.
macOSMacmacOSEditor, tools and games with Apple Clang, .dylib libraries and Objective-C++ sources, rendering through Metal. See Building for macOS.
Android arm64AndroidWindows, Linux, macOSEngine 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:

FilePurpose
*.module.csSource files, include paths, definitions, and module dependencies.
*.target.csExecutables or libraries, dependencies, and build steps.
*.workspace.csTargets 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:

ConfigurationIntended use
DebugInvestigating C++ problems with a debugger.
DevelopmentEveryday editor and engine development; the default configuration.
ReleaseOptimized profiling and performance measurements with development diagnostics.
ShippingFinal 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.

Note for C++ Developers

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.

See Also​