Skip to main content
Version: Next (dev)

Sharing C++ Projects

A project with C++ code builds its plugin into the project itself, in Bin/<Platform>_x64_<Configuration>. You commit the plugin with the project, so a designer or artist who clones it gets working components without installing a compiler. Every process that loads the project finds the plugin there: the editor, its engine process, the EditorProcessor, the Player and the project's own game. The project's copy is searched before the engine's binaries.

Programmers build as before, from the editor or their IDE. The editor records every build and tells everyone whether the committed plugin still matches the sources and the engine.

What Is in the Project​

PathCommitWhat it is
CppSource/**yesSources and PlasmaBuild rules. CppSource/.gitignore keeps Intermediate/, .plasmabuild/ and IDE files out.
Bin/Windows_x64_Development/<Name>Plugin.dllyesThe plugin every process loads.
Bin/…/<Name>Plugin.plPluginBundleyesA copy of the bundle, so a checkout of Bin/ alone is enough to find the plugin.
Bin/…/<Name>Plugin.plCodeStampyesThe build record: engine ABI tag, configuration, source and binary hashes, the project's editor plugins, who built it, on which computer and when.
Bin/…/<Name>Plugin.pdboptionalDebug symbols. Off by default; see Sharing debug symbols.
Bin/…/*.lib, *.exp, *.ilk, *.rspnoOnly the programmer's own link needs them.
Bin/…/loaded/noCopies that the plugin loader runs, so the original stays writable while the editor is open.

<Name>Game.exe stays in the engine's Binaries folder. It finds the engine's libraries next to itself, and only programmers run it.

After every build the editor writes a section into the project's root .gitignore (and .dvignore, when the project has one) and .gitattributes. Everything between the # >>> Plasma Engine: project code and # <<< Plasma Engine: project code lines is replaced; the rest of the files is yours. Bin/** is marked binary, so a plugin is never merged as text. On Git, consider Git LFS for Bin/**.

The State of the Project's Code​

Every document shows the state in its status bar as C++: …. Hover over it for the engine version the plugin was built for and the binaries folder. Click it for the C++ actions.

StatusMeaning
C++: up to dateThe plugin matches the sources and this engine.
C++: sources changedThe plugin loads, but the sources changed after it was built (or it has no build record).
C++: not builtThe project has code but no plugin for this configuration.
C++: wrong engine versionThe build record names another engine ABI. The plugin is not loaded.
C++: not loadedYou chose not to run code built on another computer.

When something needs attention, a banner appears below the toolbar of every open document, for example The project's C++ plugin is older than its sources. or The project's C++ plugin was built for another engine version. Its buttons depend on the computer:

ComputerButtons
With a C++ compilerBuild now, Open in IDE, Dismiss
Without a compilerShow folder, Dismiss. The banner names who built the plugin last, so you know whom to ask.
Code not loadedLoad the code, Dismiss

Dismiss hides the banner until the state changes.

The engine version check is strict: a plugin built for another engine never reaches the loader. A plugin whose sources changed still loads; refusing it would block designers every time a programmer pushes sources before binaries.

A plugin built against an engine source checkout passes the version check on a release install of the same version, but can still differ. The build record says so, and the banner warns on a computer that has a release install.

Opening a Project​

The editor never asks a designer to compile. On a computer with a compiler, Preferences > C++ Projects > Build On Open decides what happens when the plugin is not up to date:

ValueBehaviour
Ask (banner) (default)The banner offers Build now.
Always buildThe build starts a second after the project opened.
Never buildNothing happens; the status bar still shows the state.

Running code built elsewhere​

A cloned project runs libraries that someone else built. The first time a computer opens a project whose plugin was built on another computer, the editor asks Run the compiled C++ code that came with this project? and names who built it and where. The answer is remembered for this project on this computer. With No, the project opens without its code: its components are unknown, and assets that use them do not transform. Load the code in the banner changes your mind later.

Headless runs (EditorProcessor, -nostartupdialogs, unit tests) do not ask and load the code.

Building​

  1. Build from Project > C++ Project > Compile Plugin, from Build now in the banner, or in your IDE.
  2. The editor writes the build record and the bundle next to the plugin. A build from the IDE is recorded the next time the editor looks, as long as the plugin is newer than its record and this computer can build.
  3. Commit Bin/ together with the sources.

The C++ Project menu also has Reload Code (restarts the engine process with the plugin as it is on disk now) and Show Binaries Folder (opens the folder that holds the plugin and its build record).

When a teammate's plugin arrives​

When a sync brings in a new plugin while the editor is open, a banner says New project code arrived and who built it. The engine process restarts with it as soon as no document keeps it from restarting. Reload now does it right away.

Project editor plugins​

A project can also have editor plugins of its own (the project template has none). They build into the project's Bin folder together with the runtime plugin and are recorded in the code stamp. The engine process can restart with new code, but the editor itself cannot: when an editor plugin changes, the editor asks:

The editor process must be restarted. Reason: 'The project's editor plugin changed.' Do you want to restart now?

With No, the status bar shows Restart the editor to apply changes. until you do. See Editor Plugins.

Merge conflicts on the plugin​

When two programmers both built, their plugins conflict. Never merge them: take either side, then rebuild after the merge. The build record names who built each, and the next build resolves it.

Sharing debug symbols​

Project > C++ Project > Share Debug Symbols (also in the status bar's C++ menu) commits the plugin's .pdb with it, so crashes on a designer's computer have call stacks. The setting is saved with the project, in Editor/CppProject.ddl, because it decides what the whole team commits. PDBs are often 30 to 300 MB.

Headless Builds and CI​

The EditorProcessor builds the plugin only when it is not up to date:

EditorProcessor.exe -project <path> -transform PC

On a computer without a compiler, a plugin that loads is used as it is (with a warning when the sources changed). A missing or wrong-engine plugin is an error with exit code 3 that says who can fix it. -nocppbuild makes a computer with a compiler behave like one without, to try the designer's side.

For builds outside the editor, the engine SDK is found without storing its path in the shared rules:

  1. PLASMA_SDK_ROOT, when set to a nonblank value.
  2. CppSource/.plasmabuild/sdk-root.txt, which the editor writes during C++ setup, workspace generation and builds.
$env:PLASMA_SDK_ROOT = 'E:\SDKs\PlasmaEngine'
plasmabuild generate workspace --ide vs2026
plasmabuild build MyProjectGame -c Development

The SDK folder must contain Code/Engine/Foundation/Basics.h. An environment variable takes precedence over the editor's local file.

Export​

The export ships the plugin from Bin/<Platform>_x64_<Configuration> into the exported Bin folder, and fails with a clear message when it is missing. Bin/ is never exported as data. A Linux export takes the plugin from Bin/Linux_x64_<Configuration>. See Project Export.

Moving an Existing Project​

Projects pick up the new rules through the editor's versioned template update the next time the editor builds them. That build removes copies of the plugin that an older build left in the engine's Binaries folder. If one is left anyway (the folder is read-only, or another checkout put it there), the project's copy still wins, and the log says Plugin '…' exists in more than one place.

An editor older than 0.12 rewrites the rules back to the engine's folder when it builds the project. Update every teammate's editor before the first shared build.

Troubleshooting​

SymptomCauseFix
Components are unknown, the banner says the plugin is not in the projectBin/ was not committed or not synced.Commit Bin/<config>/<Name>Plugin.dll, .plPluginBundle and .plCodeStamp.
C++: wrong engine version after an engine updateThe plugin was built for the old engine.A programmer rebuilds and commits.
The build succeeds but nothing appears in Bin/The project's rules come from an older editor.Build again from this editor; the log names the missing file.
exists in more than one place in the logA stale copy in the engine's Binaries.Harmless; the project's copy is loaded. Delete the other one.
Set PLASMA_SDK_ROOT to your Plasma Engine SDK directory ...A build outside the editor cannot find the SDK.Set PLASMA_SDK_ROOT, or regenerate the C++ workspace in the editor.

See Also​