This is the official Plastic SCM Source Control Provider plugin for Unreal Engine 4 & 5 (UE 4.11 to 4.27, and UE 5.0). An old version of it has been integrated in Unreal Engine 4.24 and is shipping with it since then (equivalent to 1.4.6+). But if you have a project of a certain size, chances are you need to upgrade manually to a version we provide from Github in order to benefit of all the performance improvements we have made since then. See the Status section bellow for more details.
It is not intended to replace Plastic SCM GUI or command line interface "cm". It is a complementary tool improving efficiency in your daily workflow with assets in Editor.
It automates tracking of assets, brings common SCM tasks inside the Editor, and provides visual diffing of Blueprints. It also helps importing an existing Unreal Project into source control, with appropriate ignore.conf file. Since Unreal does not manage C++ source code, but only assets, the plugin is especially useful for GDs and artists.
An old version of this PlasticSCM plugin has now been integrated in Unreal Engine and is shipping with it since UE4.24 and UE5.0.
Why: This is the easiest way to get started with Plastic SCM in Unreal Engine, but it will always be lagging behind the latest release here.
Why: if you want the latest features, performance improvements and bug fixes that are missing from Unreal integrated plugin.
- Download the latest binary release UE4PlasticPlugin-x.x.x.zip targeting your UE4 version.
- Either:
- Unzip the content of the ZIP directly at the root of your project folder. This creates a "Plugins/UE4PlasticPlugin/" subdirectory into your project. This is the way to go to use Plastic SCM only on a specific project.
- Unzip the content of the ZIP in the Engine/ directory of UE4.x directly for all your projects (for instance "C:\Program Files\Epic Games\4.25\Engine") This creates a "UE4PlasticPlugin" folder into the "Plugins/" subdirectory. This is the way to enable Plastic SCM for all Unreal Engine projects.
- Then, launch you Unreal project, click on the Source Control icon "Connect to Source", select "Plastic SCM".
Why: If your project is already a C++ project, you only have to re-generate Visual Studio project files (step 4 bellow) and the plugin will get rebuild the next time you compile your project.
Else, if you want to rebuild the plugin for a Blueprint project:
- You need Visual Studio 2015 or 2017 with C++ language support (free Community Edition is fine).
- Launch the Unreal Engine Editor, create a new C++ Basic Code Project (No Starter Content), for instance UnrealPlasticSCM. This should launch Visual Studio, build the game project, and open it into the Editor.
- Close the Editor, then using the file explorer, create a new Plugins directory at the root of your project.
- Clone the source code of the plugin into this Plugins directory (for instance Plugins\UE4PlasticPlugin).
- Right-click on your project's .uproject file, Generate Visual Studio project files.
- In Visual Studio, Reload All and Build Solution in Development Editor mode. That's it, the plugin is built (resulting dlls are located in Plugins\UE4PlasticPlugin\Binaries\Win64).
To release the plugin, zip the Plugins folder. But before that, remove the Intermediate, Screenshots and .git folders, and also the big *.pdb files in Plugins\UE4PlasticPlugin\Binaries\Win64.
Start by saving your connection credentials with the Plastic SCM GUI
Launch you Unreal project, look at the Source Control menu at the bottom-right
Launch you Unreal project, click on the Source Control icon "Connect to Source"
Then select "Plastic SCM" plugin
Source Control Login window, to create a new workspace/a new repository, click on "Initialize workspace" (example of a cloud repository):
Or on a server running on premise, using ip:port:
This creates an appropriate ignore.conf file, add all relevant files to source control (.uproject, Config & Content subdirectories) and can also do the initial commit automatically at the end.
Wait for this to succeed before accepting source control settings to not lock the UI & mess with the initialization!
Source control settings can be changed using the Source Control menu,
and are saved locally in Saved\Config\WindowsEditor\SourceControlSettings.ini.
In order to share this with the team, copy and rename this file into Config\DefaultSourceControlSettings.ini,
add it to source control and submit it.
The minimal useful setting would be selecting the proper provider, but it can be useful to set a few settings if different than the defaults:
[SourceControl.SourceControlSettings]
Provider=Plastic SCM
[PlasticSourceControl.PlasticSourceControlSettings]
BinaryPath=cm
UpdateStatusAtStartup=False
UpdateStatusOtherBranches=True
EnableVerboseLogs=FalseUnreal Engine allows you to configure project-related settings. TODO: Some are not yet supported by the plugin (eg Delete on Revert)
The plugin allows you to configure project-related settings.
There are 3 settings available at the moment:
- User Name to Display Name
- For each entry in this dictionary, the Editor will replace the user name in the key with the display value you specify.
- Hide Email Domain in Username
- This setting toggles the visibility of domain names in user names, if the user name is an email.
- Prompt for Checkout on Change
- Unchecking this setting will make the Editor consider all files as already checked out. In that case, you won't get any notifications when you modify assets, and the "Checkout Assets" dialog won't show when you save those changes. This mimics how Git works, i.e. allowing the user to perform changes without worrying about checking out items. Note: Changelists don't currently support locally changed assets (ie not checked-out)
Official documentation from Epic Games:
Plastic SCM forums:
- New, unsaved asset (not yet present on disk).
- Private, the asset is not in source control.
- Added to source control.
- Source Controlled but not checked-out nor locally changed
- Locally Changed without checkout, or Private ie not source controlled
- Checked-out exclusively to prevent others from making modifications (if Locks are enabled on the server)
- Redirector added by a Move
- Moved or Renamed
- Locked somewhere else, by someone else or in another workspace (if Locks are enabled on the server)
- Not at head revision, the asset has been submitted with a newer revision on the same branch
- Changed in an other branch, the asset has been changed in a newer changeset in another branch
- Merge conflict, the asset has been changed in two separate branches and is pending merge resolution
Source Control status tooltip, when hovering the Source Control icon in toolbar:
Source Control top Menu, extended with commands specific to Plastic SCM:
Source Control Menu and status tooltip, extended with commands specific to Plastic SCM:
Using the Content Browser context source control sub-menu, you can call in specific actions and windows:
Submit Files to Source Control window, to check-in selected assets directly (see also Changelists below):
Changelists are the new way to group checked-out files by topic in Unreal Engine 5.0, to submit them in coherent batches.
UE5.0 includes Validation checks to ensure there are no missing dependancies outside a changelist, and that all assets are saved on disk before submitting.
File History window, to see the change-log of an asset:
Visual Diffing of different revision of a Blueprint:
Textual Diffing of a Material:
When Source Control is enabled Unreal creates a redirector whenever an asset is renamed or moved, so that other developers relying on it's old name / location can still work with other assets referencing it.
This means, you end up with two files that you have to submit, even if by default they don't show up in the Content Browser.
You can show them in the Content Browser using a dedicated filter:
You can also delete them recursively using the context menu "Fix Up Redirectors in Folder":
If you are making use of multiple branches, either for releases and patches, or for tasks or features, you can enable an option to check for changes in all other branches.
Tooltip in the Content Browser when an asset is already checked-out somewhere else:
Tooltip in the Content Browser when an asset has been modified in another branch:
Warning when trying to checkout an asset that has been modified in another branch:
Warning when trying to modify an asset that has been modified in another branch:
In case you ever use branches with binary assets without relying on exclusive checkouts (file locks) (see Workflows below) you will encounter case of merge conflicts on binary assets. You have to trigger the resolve in the Plastic SCM GUI, but then skip it without saving changes in order to let the Editor presents you with a visual diff.
Branch explorer showing the merge pending with an asset in conflict:
Corresponding icon in the Content Browser (only showing after the resolved has been triggered in Plastic SCM):
Right click on the asset in conflict to open the Merge Tool (just a conflict solver with 3-way Visual Diff, no merge):
Visual diff of Blueprint properties in conflict:
Visual diff of a Blueprint Event Graph in conflict:
The most common workflow with Unreal Engine binary assets is the one taught by Perforce: It relies mostly on one main branch (stream) for everyone with exclusive checkouts (locks) for the whole Content/ subdirectory, in order to prevent merge conflicts on a uasset or a umap file.
This typical workflow would work the best with the workspace in partial mode configured using Gluon GUI. The reason is that a partial workspace enables you to checkin assets without the need to update the workspace before.
- update the workspace (get latest) using Gluon GUI, with the Unreal Editor closed (since the Editor is locking assets, but also .exe & .dll files that might be in source control)
- start the Editor, make modifications and checkout assets
- then checkin (submit) the assets, either from withing the Editor, or from the GUI after closing the Editor (the benefit of closing is you ensure that everything is saved)
- when needed, close the Editor and update the workspace again
If you try to use a full workspace (with Plastic SCM GUI instead of Gluon) you will often need to update the workspace before being able to checkin.
Handling of binary assets works best in only one branch (regardless of the source control used) since they cannot be merged, and since they increase the cost (time/bandwidth) of switching between branches.
But with Plastic SCM you can use branches that are easy and cheap to create and merge: using them for code will enable you to leverage the built-in code review on these branches.
Note that some studios also use task branches for assets, and include them in their code reviews. Plastic SCM locks extend to all branches, preventing two people from working at the same time on the same assets regardless of the branch they are one. The Plastic plugin also offer some branch support to warn users if an asset has been changed in another branch.
To use branches, you would need to also close the Editor before switching from a branch to another, and before merging a branch into another:
- create a child branch from main using Plastic GUI
- switch to it, updating the workspace, with the Unreal Editor closed
- start the Editor, make modifications and checkout assets
- then checkin the assets (remember to save everything, or close the Editor to make sure of it)
- close the Editor
- create a code review from the branch
- create a new task branch from main or go back to main to merge branches
The plugin also leverages the visual diff merge conflicts resolution tool from the Editor but this is a pain and isn't working as expected currently (as of 1.5.0 & UE5.0)
The plugin works with the command line interface "cm" that currently requires your credentials to be stored. Use the Plastic SCM or Gluon GUI to enter and save your credentials before enabling Plastic SCM in Unreal.
Administrator guide - Chapter 7: Configuring exclusive checkout (Lock)
Binary assets should be locked for exclusive access to avoid merge conflicts.
To lock all assets on the whole Content directory, you need to put a lock.conf in your server directory (for instance C:\Program Files\PlasticSCM5\server) with this content:
rep:<repname> [lockserver:[<server>:<port>]]
/Content
For instance the more generic one would be:
rep:*
/Content
or to be more specific to one repository:
rep:UE4PlasticPluginDev lockserver:localhost:8087
*.uasset
*.umap
On Plastic Cloud, you can just setup lock rules like that:
/Content
In "Preferences -> Diff tools" add a new config for uasset and move it up before the existing $binary one:
The command line needs the quoted path to the UE4Editor.exe, the quoted patch to your ".uproject" file, -diff, than the source & destination files variables also quoted
"C:\Program Files\Epic Games\UE_4.27\Engine\Binaries\Win64\UE4Editor.exe" "C:\wkspaces\MyProject\MyProject.uproject" -diff "@sourcefile" "@destinationfile"
or for Unreal Engine 5:
"C:\Program Files\Epic Games\UE_5.0\Engine\Binaries\Win64\UnrealEditor.exe" "C:\wkspaces\MyProject\MyProject.uproject" -diff "@sourcefile" "@destinationfile"
This version here is the development version, so it always contains additional fixes, performance improvements or new features compared to the one integrated in Engine.
- manage connection to the server
- show current branch name and CL in status text
- display status icons to show controlled/checked-out/added/deleted/private/changed/ignored/not-up-to-date files
- display locked files, and by who
- branches support, to check outdated files vs. remote across multiple branches
- add, duplicate a file
- move/rename a file or a folder
- revert modifications of a file (works best with the "Content Hot-Reload" option since UE4.15)
- check-in a set of files with a multi-line UTF-8 comment
- migrate (copy) an asset between two projects if both are using Plastic SCM
- delete file (but no way to check-in them, see known issues bellow)
- update workspace to latest head (Sync command)
- show history of a file
- visual diff of a blueprint against depot or between previous versions of a file
- manage Changelists in Unreal Engine 5: create, edit, move files, delete (no shelves yet)
- initialize a new workspace to manage your UE4 Game Project.
- make the initial commit with a custom message
- create an appropriate ignore.conf file as part of initialization
- also permit late creation of the ignore.conf file
- show conflicted files and 3-way visual diff
- solve a merge conflict on a blueprint
- top-menu global "Sync" instead of on folder's context menu
- top-menu global "undo unchanged" and "undo all checkout"
- Partial Workspace (Gluon, for artists) see also
- Plastic Cloud is fully supported
- xlinks sub-repositories (for Plugins for instance)
- Toggle verbose logs from the Source Control settings UI
- Run 'cm' CLI commands directly from the Unreal Editor Console, Blueprints of C++ code.
- Windows only
- Unreal Engine 5.0 full support
- Shelves of Changelists
- Mac OS X Support
- add a setting to bypass checkout and let the user directly modify the assets like Git
- add a setting to configure Plastic SCM to use "read-only flags" like Perforce
- add a setting to pass the --update option to "check-in"
- add a "clean directory" or "check-in deleted files"
- add dedicated icon for Changed files
- add dedicated icon for Ignored files
- add dedicated icon for Conflicted files
- add dedicated icon for Replaced/Merged files
- Merge conflict from cherry-pick or from range-merge cannot be solved by the plugin: use the Plastic SCM GUI
- Merge Conflict: "Accept Target" crash the UE4.11 Editor (same with Git Plugin)
- #18 Error messages with accents are not correctly handled/displayed (for instance connection error in French)
- the Editor does not handle visual diff for renamed/moved assets
- History does not show which revision is the current/checkout one
- Editing an asset that is "Changed" but not checked-out pop up a "Files need check-out!" (UnrealEdSrv.cpp) that does nothing when clicked!
- the Editor does not show folder status and is not able to manage them
- Branch and Merge are not in the current Editor workflow
- tags: get labels (used for crash when the full Engine is under Plastic SCM)
- annotate: blame (used for crash when the full Engine is under Plastic SCM)
You can always ask for support in:
- Plastic SCM support
- Plastic SCM Unreal Engine forum
- Unreal Engine forums
- Unreal Slackers Discord community
To help diagnose any issue related to the underlying Plastic SCM "cm" Command Line Interface, enable logging for Plastic SCM.
To report an issue, please use the Github issue-tracker.
- Have a look at existing issues (Open and Closed ones)
- Specify your Engine & Plugin versions, and if either are built from sources
- Describe precisely your issue
- Add reproduction steps, if possible on a basic template project
- Post log files when applicable (or the corresponding redacted section)
- Unreal Log file ProjectName/Saved/Logs/ProjectName.log
- cm debug log file typically from \plastic4\logs\cm.log.txt see enabling-logging-for-plastic-scm
If you want to help, Github Pull Requests are welcome!
Copyright (c) 2016-2022 Codice Software Developed by Sébastien Rombauts (sebastien.rombauts@gmail.com)