Protecting Unity Games
Note: The following instructions cover both Dotfuscator Professional and Dotfuscator Community.
The following instructions will walk you through using Dotfuscator to protect apps made with Unity. You can apply these steps to each platform your app supports, creating an app with a proven, layered protection strategy, no matter what device it's running on.
In order to follow along with these instructions you will need the Unity-supplied Space Shooter example project or you can follow along with your own project and use this guide as a reference for adding protection.
You will also need to install Dotfuscator if you do not already have it. To do so, see Dotfuscator Editions to learn which edition is best suited for your project, and see the Dotfuscator Downloads page to get the latest version of your selected edition of Dotfuscator.
If you already have Dotfuscator, please verify that you have a version that supports Unity.
Minimum Version Requirements
Dotfuscator Edition | Minimum Version for Unity |
---|---|
Professional | 4.31 |
Community | 5.31 |
Note: These versions are required for apps made with the .NET scripting backend. If you are using the Mono scripting backend it is possible to use older versions of Dotfuscator.
- Supported Platforms
- Example Project
- General Process to Add Protection
- 1. Build the App
- 2. Add Input to Dotfuscator
- 3. Configure Dotfuscator
- 4. Build
- 5. Replace the Assembly
- 6. Build the Protected Version of the App
- 7. Verify App Behavior
- 8. Add More Protection
- Standalone Platform Details
- iOS Platform Details
- Android Platform Details
- Windows Store Platform Details
- Further Reading
Supported Platforms
Dotfuscator supports Unity projects that target the following platforms:
- PC, Mac, and Linux Standalone
- iOS
- Android
- Windows Store
Example Project
After you have Dotfuscator installed you will need to set up the example project. This guide uses the Space Shooter tutorial available on Unity's website.
Set up
Download the Assets
On the Asset Store page:
- Click the "Add to Downloads" button
- Click the "Open in Unity" button
- This will bring up the Unity window for opening projects
Create a Project
- Create a new project by clicking on the "New" button
- Give the project the a name and location to save.
This example assumes the name is
SpaceShooter
and the location isC:\Unity\
. - Add the Asset Package: "Space Shooter tutorial"
- Create the Project
Add Scene to Project
Find the _Complete-Game directory in the Assets directory of the project.
Click on the _Complete-Game
scene to bring it into the Scene tab, and then click the play button.
Take a moment to play the game in the preview so you will be able to tell if anything is not working later in the protected version.
In the file menu click on Build Settings
to open the build settings window.
Add the _Complete-Game
scene to the "Scenes the Build" by clicking the add open scenes
button.
General Process to Add Protection
The general process for protecting Unity applications with Dotfuscator is the same across all the supported platforms, with the exception of a few platform specific steps. There are links to platform specific instructions from these general instructions when they are necessary.
Steps 1-7 will give basic protection to the application. Step 8 will add more protection to harden the app even further.
1. Build the App
To build the application that will be protected by Dotfuscator, first select the platform to build, then set the necessary player settings for the selected platform, and lastly build and save the Unity produced app.
Select Platform
To change the build platform in Unity, select File
-> Build Settings
to open the build settings window.
The list of platform options will be on the left.
Select the desired platform and click the 'Switch Platform' button.
Set Player Settings
Select a Scripting backend
Unity offers the option of three different scripting backends depending on target platform: Mono, .NET and IL2CPP.
The first two scripting backends, Mono and .NET, produce managed code which can be easily reversed engineered. (See the Reverse Engineering page to see how easy it is.)
The Mono and .NET scripting backends combine all the C# scripts written for the project into one dynamic linked library, called Assembly-CSharp.dll. The Assembly-CSharp.dll is what needs to be protected with Dotfuscator.
IL2CPP as a scripting backend does not produce output that can be used as an input to Dotfuscator.
The scripting backend can be set by clicking on the Player Settings...
button in the Build Settings window.
Under the "Configurations" section is the drop down menu for selecting the scripting backend.
Select the appropriate scripting backend for your project.
See the Unity documentation for more information on scripting backends.
Platform Specific Player Settings
The iOS Platform and the Android Platform require additional configuration. Please see the following sections for details:
Build and Save the Output
Once everything for the build is configured in Unity, press the "Build" button in the "Build Settings" window. See the section on Building for Windows Store Inputs for platform specific details.
If you haven't built for another platform already, create a new directory in C:\Unity\SpaceShooter
called "Builds" where we will store the build output for all the platforms we build in this example.
Inside C:\Unity\SpaceShooter\Builds
create a directory with the name of the platform and select this directory as where to save the build output.
Set the file name to be SpaceShooter if it is required for building on your current platform.
For example the output for a Standalone platform build will be in C:\Unity\SpaceShooter\Builds\Standalone
and the executable will be named SpaceShooter.exe
.
Then build the project for the specified platform by pressing "Save".
2. Add Input to Dotfuscator
Open the Dotfuscator Config Editor and add the input by following instructions for Dotfuscator Professional or Dotfuscator Community. The correct input will depend on the target platform. See the following sections for details:
- Standalone Input to Dotfuscator
- iOS Input to Dotfuscator
- Android Input to Dotfuscator
- Windows Store Input to Dotfuscator
If you are following along with your own app the input will be in a similar location.
3. Configure Dotfuscator
If you are using Dotfuscator Professional go to the settings tab, under the Advanced section, and change "Use only Mono-compatable-transforms" from 'No' to 'Yes'.
Save the Dotfuscator config file in C:\Unity\SpaceShooter\Builds\<Platform>
, and give it any name you would like.
See the Windows Store Dotfuscator Configuration section for an additional setting for Windows Store Universal 10 apps.
4. Build
Now, you are ready to press the build button in the Dotfuscator Config Editor. Verify that the build was successful by looking in the output at the bottom of the Dotfuscator Config Editor.
5. Replace the Assembly
Next to the build button is a button with an arrow on it. Pressing this will take you to the location of Dotfuscator's Output.
After you've found the output from Dotfuscator, copy it and go back to the original location of the input Assembly-CSharp.dll
.
Replace the unprotected Assembly-CSharp.dll
with the protected version you copied from Dotfuscator's output.
The Windows Store platform skips this step.
6. Build the Protected Version of the App
Now that we've built a protected version of the Assembly-CSharp.dll
, we need to build the entire app that uses it.
Instructions on how can be found in the platform specific sections:
- Build the XCode Project in the iOS-specific section
- Build and Sign the APK in the Android-specific section
- Build the Appx in the Windows-specific section
The Standalone platform skips this step.
7. Verify App Behavior
Try out the app on your computer, device, or emulator to verify the app's behavior with protection added. If there are issues, this most likely means that you need to add additional renaming exclusions beyond library mode. Please see the protection exclusions page for additional details on the workflow for identifying renaming exclusions.
8. Add More Protection
Now that your app is working with basic protection, you can increase the strength of the protection by following the steps below.
Turn off Library mode
First, in Dotfuscator you will want to turn off library mode for the Assembly-CSharp.dll
.
This step will make the obfuscation on the assembly more aggressive.
In Dotfuscator Professional, click the plus sign next to the assembly to expand the options. Then uncheck "Library" to turn off library mode. If you are using Dotfuscator Community, click on the assembly, and then to the right in the properties section uncheck Library mode.
Add Renaming Exclusions
We can improve protection by turning off Library Mode, but that will un-exclude some things that need to be excluded, so we need to add specific exclusion rules to cover those things.
For more information on renaming in Dotfuscator Professional see:
For information on renaming in Dotfuscator Community see:
Exclusions for all Platforms
It is necessary to exclude:
- All public types
- All the Start() methods
- All the methods that have to do with updating: Update(), FixedUpdate()
- All the methods that occur on an event : OnEnable(), OnTriggerEnter(), OnTriggerExit()
After this, all public methods that weren’t specifically excluded will be renamed, which is an improvement over when we had Library Mode turned on. To add these exclusions follow the steps bellow. When you are done your renaming tab page should look like the following:
To add the necessary renaming exclusions:
- Add a type rule by pressing the "Add Type" button and set the name to
*
. - Select the
+public
attribute in the Attribute Specifier for that type. This takes care of excluding all public types in the assembly. - Add another type rule by pressing the "Add Type" button and set the name to
*
. - Uncheck the "Exclude Type" box for this type.
- Right click on the type that you just added, and select 'Add Method'. Repeat this step two more times, so you have three methods listed on the type.
- For each method, click on the method and set the name.
The names will be
Start
,On.*
, and.*Update
. The names are regular expressions so they will cover all the methods listed above. For example.*Update
will cover both Update() and FixedUpdate() methods.
You can verify this by selecting the method and then pressing "Preview". In the tree view of the inputs on the left you will see both of those types highlighted.
These exclusion rules aren't just important for the Space Shooter app, they can and should also be excluded from renaming in your own apps you build with Unity. See the general workflow for identifying renaming exclusions for finding and configuring additional renaming exclusions that may also be needed for your own app.
Since not all the methods are able to be renamed its important to keep this in mind when you are writing the scripts for your project. Try to keep any critical code out of methods that have to be excluded so it is not as easy to find.
See the Windows Store specific exclusions if you are targeting that platform.
Standalone Platform Details
Dotfuscator Input
For the Standalone platform you will need to add the Assembly-CSharp.dll as the input to Dotfuscator.
For the Space Shooter example this can be found in the C:\Unity\SpaceShooter\Builds\Standalone\SpaceShooter_Data\Managed
directory.
iOS Platform Details
These instructions assume you are using Unity on Windows but all the steps should be similar if you are using Unity on a Mac.
Unity Configuration Settings
After the platform and scripting backend are set, you will also have to configure the build for the device you plan to test the app on. In Player Settings below where the scripting backend was set in the 'Configuration' section, change the Target SDK to either Simulator or Device depending on which you are going to test the application on.
Dotfuscator Input
For the iOS platform you will need to add the Assembly-CSharp.dll as the input to Dotfuscator.
For the Space Shooter example this can be found in C:\Unity\SpaceShooter\Builds\iOS\Data\Managed
.
Build the XCode Project
Unity produces an XCode project which you use to build the actual iOS app.
Before you can build the XCode project you need to update the Assembly-CSharp.dll.s
in C:\Unity\SpaceShooter\Builds\iOS\Libraries
by using Ahead of Time Compilation or AOT on the protected version of the Assembly-CSharp.dll.
To create a compatible version of the Assembly-CSharp.dll.s
- Locate the mono-xcompiler tool that comes with Unity.
- If you are using Unity on Windows, then it will typically be located at
C:\Program Files\Unity\Editor\Data\PlaybackEngines\iOSSupport\Tools\Win\mono-xcomiler.exe
. The steps below assume you have Unity installed on Windows. - If you are using Unity on Mac, then the "mono-xcompiler" will typically be located at
/Applications/Unity/PlaybackEngines/iOSSupport/Tools/OSX/mono-xcompiler
and you can run a similar version of the following steps. Note you will need to useexport
instead ofSETX
in step 3.
- If you are using Unity on Windows, then it will typically be located at
- From your unity project directory (
C:\Unity\SpaceShooter\Builds\iOS
) open a new command prompt. - Run mono-xcompiler as follows:
SETX MONO_PATH "Data\Managed" SETX GAC_PATH "Data\Managed" "C:\Program Files\Unity\Editor\Data\PlaybackEngines\iOSSupport\Tools\Win\mono-xcompiler.exe" --aot=full,static,nodebug,asmonly,outfile="Libraries/Assembly-CSharp.dll.s" "Data/Managed/Assembly-CSharp.dll"
- Check that a new
Assembly-CSharp.dll.s
is located inC:\Unity\SpaceShooter\Builds\iOS\Libraries
.
Now that there is a new version of the Assembly-CSharp.dll.s
, you'll need to copy C:\Unity\SpaceShooter\Builds\iOS\
over to a Mac in order to be able to build the XCode project.
Open the XCode project called Unity-iPhone.xcodeproj
located in C:\Unity\SpaceShooter\Builds\iOS\
.
If XCode suggests you "Update the project to recommended settings", don't do it. For this example updating may cause the app not to work.
Build the XCode project and from here you can also test the app on a device or an Emulator to see that Space Shooter works as expected.
Android Platform Details
Unity Configuration Settings
Open the player settings window by clicking on the 'Player Settings' button in the "Build Settings" window.
The player settings window will be to the right in the regular Unity window.
In the player settings window, set the Package Name in the Identification section above the Configuration section (where you set the scripting backend) to be com.Company.SpaceShooter
.
Then at the top of the Player Settings change the company name to Company and the product name to SpaceShooter.
Dotfuscator Input
To access the Assembly-CSharp.dll you will have to decompile the APK that Unity produced.
Download and set up Apktool with the instructions from the Apktool install page.
In a command prompt in the directory that the APK is in, C:\Unity\SpaceShooter\Builds\Android
, run the command:
apktool d SpaceShooter.apk
The Assembly-CSharp.dll can now be found in C:\Unity\SpaceShooter\Builds\Android\SpaceShooter\assets\bin\Data\Managed
.
Build and Sign the APK
After replacing the unprotected assembly with the protected assembly, you must rebuild and re-sign the APK with the protected assembly.
- Rename or delete the old APK
In the command prompt window from when you decompiled the APK run the following command to rebuild the APK
apktool b SpaceShooter -o SpaceShooter.apk
Sign the app using your keystore and the jarsigner tool If you don't already know how to do this, for this example project you can enter the command:
keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000
Remember the password you set, and fill in appropriate values for your project.
Sign the APK by executing:
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore my-release-key.keystore SpaceShooter.apk alias_name
Once that is done, you can install the APK on your Android device or Emulator and test out the Space Shooter app verify its behavior.
Windows Store Platform Details
Build in Unity
For the Windows store platform instead of using the "Build" button, use the "Build and Run" button. The input used for Dotfuscator will be created by doing this instead and you won't have to manually open up Visual Studio to build the Appx.(You can still build from Visual Studio if you want to).
Dotfuscator Input
If you built and ran the application from Unity then the input can be found in the directory C:\Unity\SpaceShooter\Builds\Windows\SpaceShooter\bin\x86\Master\AppX
.
If you build yourself from visual studio, the AppX
directory will be located similarly based on what configuration you built the project in.
See the Windows store inputs page for instructions on adding this input.
Exclude everything from the package except the Assembly-CSharp.dll by left clicking on the assemblies and selecting "Exclude assembly from package". You should see all the assemblies you excluded show up in "Package Artifacts".
Dotfuscator Configuration
If you are using the Universal 10 SDK for the Windows Store platform there is an additional configuration setting required.
In the "Settings Tab", add the Config Property ilreader.alias_system_runtime.never
with the value 0
.
See the Properties section for details on how to add Config Properties.
Build the Appx
For a more permanent solution you can follow this article on integrating Dotfuscator into the Appx build.
To test protecting a Windows Store app in development:
To build the Appx from the output from Dotfuscator, first locate the MakeAppx tool, usually it can be found somewhere like C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe
.
Then open a command prompt and execute the command
"C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe" pack /d "C:\Unity\SpaceShooter\Builds\Windows\Dotfuscated" /p "C:\Unity\SpaceShooter\Builds\Windows\Space_Shooter.appx" /l
This will save the Appx in the C:\Unity\SpaceShooter\Builds\Windows
directory.
Note: Make sure you don't include your map file in with the Appx.
Sign the Appx
The next step is to sign the Appx so you will be able to install it to test it. You can see the Microsoft documentation for help on this step.
Next, use SignTool to sign the application with the certificate.
Install the Appx
In the Administrator PowerShell command prompt execute the following command to install the Appx to test:
add-appxpackage -path "C:\Unity\SpaceShooter\Builds\Windows\Space_Shooter.appx"
Windows Store Specific Exclusions
Windows Store platform apps need a few extra renaming exclusions that the other platforms don't need.
It is necessary to additionally exclude:
- All types
- The namespace
UnityEngine.Internal
in the Assembly-CSharp.dll - The namespace
UnityEngine.Internal.Types
in the Assembly-CSharp.dll
To exclude all types:
- Select the type rule you made named
*
- Check the "Exclude Type" box.
To add the namespaces to the renaming exclusions:
- In the tree view on the left expand the
C:\Unity\SpaceShooter\Builds\Windows\SpaceShooter\bin\x86\Master\AppX
node , then Assembly-CSharp.dll below it, then expand the Assembly-CSharp.dll listed under that - At the bottom of that node are the two namespaces that need to be excluded. Check their boxes to exclude them.
Further Reading
If you have any trouble finding the necessary settings mentioned in these instructions in Unity, please refer to the Unity Documentation.
These instructions focused mainly on renaming exclusions, but Dotfuscator offers additional protections beyond renaming. Check out and explore the Professional documentation and Community documentation for information on all the other protection available for your apps.
We on the Dotfuscator team are always adding new features to improve the protection provided by Dotfuscator, as well as making the configuration process easier. Stay up-to-date with the latest Dotfuscator version by visiting the Dotfuscator Downloads page. For announcements and other information, keep an eye on our blog and follow our Twitter account, @PreEmptive.