alkimeegames / codeoptimizationsymbols

Automatically sets preprocessor directives based on the Code Optimization mode set in the Unity Editor

Code Optimization Symbols

Automatically sets preprocessor directives based on the Code Optimization mode set in the Unity Editor.

What are Code Optimization Symbols?

The Code Optimization Symbols tool automatically creates Compiler Symbols based on the Unity Editor's Code Optimization mode. These compiler symbols can then be used in your code to change behaviour based on the currently active Code Optimization mode.

Why use the Code Optimization Symbols?

Having compiler symbols for both the Debug and Release Code Optimization modes allows you to write code that is only available when either of these modes are available.

For example, you may have a class which writes logs to the Unity Console when actions occur. You could use the pre-existing 'UNITY_EDITOR' symbol which would result in logs being sent to the console whenever you're running the game in the Editor. However, if you don't need these logs all the time and only need them whilst debugging, surrounding the code with the 'UNITY_EDITOR_DEBUG' symbol will make those logs only appear when the Editor is in Debug Code Optimization mode.

Naturally, the symbols set by this tool can be used for more than just logging. You could also instantiate entirely difference classes based on the Code Optimization mode for performance reasons.

Whats wrong with #if UNITY_EDITOR et al?

The Platform Dependant Compilation symbols already provided by the Unity Editor are excellent for targeting specific platforms or code you only want to run in the Editor. However, it provides no means for determining which Code Optimization mode the Unity Editor is currently in. This means you currently cannot have code run in the Editor when only in the Debug Code Optimization mode.

Setup

The Code Optimization Symbols tool works out of the box, automatically and in the background with no dependencies other than Unity itself. It's pure CSharp and the public API has complete XML documentation.

How does this work?

The Code Optimization Symbols tool adds two new compiler symbols determined by which Code Optimization mode the Editor is in. Because of this, they can never both be set at the same time.

• Debug Mode introduces the "UNITY_EDITOR_DEBUG" symbol.
• Release Mode introduces the "UNITY_EDITOR_RELEASE" symbol.

Automatic Behaviour

• When building your project the symbols will be automatically removed and re-added once the build is complete.
• Switching platforms via the Build Settings window or via script will automatically remove the symbols from the previous platform and add them to the now active platform.
• Exiting the Editor will remove either of the symbols.

Example Usages

As a preprocessor directive

public sealed class Bullet : MonoBehaviour
{
    private void OnCollisionEnter([Collision other)
    {
        if (other.gameObject.CompareTag("Player")) {

#if UNITY_EDITOR_DEBUG
            // You will only see this log in the Editor AND if the Editor is in Debug Code Optimization mode.
            Debug.Log("Destroying " + other.name);
#endif

            Destroy(other.gameObject);
        }
    }
 }

Using the Conditional Attribute

using System.Diagnostics;
using static AlkimeeGames.CodeOptimizationSymbols.Symbol;

public sealed class PlayerState
{
    private void PerformingAction()
    {
        Log("I performed an action.");
    }

    [Conditional(CodeOptimizationDebug)]
    private void Log(string @string)
    {
        Debug.Log(@string)
    }
}

Using the Conditional Attribute with Code Stripping disabled or set to Low will result in the call site to the method being removed from the build. With Code Stripping set to Medium or High, the call site and the method definition will be removed from the build (except in the case of classes deriving from MonoBehaviour or ScriptableObject where Unity tends to be more pessimistic in stripping code from those derived classes).

API and Extensibility

There are two public events available to subscribe to from your own Editor scripts.

• SymbolSetter.SettingSymbols
  • Raised before setting the symbols.
• SymbolSetter.SetSymbols
  • Raised after setting the symbols.

Both pass an ISet to the subscribed method which contains all the symbols being applied.

You can also access the names of the symbols directly in your code.

• Symbol.CodeOptimizationDebug
• Symbol.CodeOptimizationRelease

Installation

Install via OpenUPM

The package is available on the openupm registry. It's recommended to install it via openupm-cli.

openupm add com.alkimeegames.codeoptimizationsymbols

Install Via Package Manager

Via the Package Manager, you can add the package as a Git dependency. Follow the instructions for Installing froma Git URL and further information around Git dependencies in Unity. We advise specifically locking to the main branch.

Install Via Manifest.json

Open Packages/manifest.json with your favorite text editor. Add the following line to the dependencies block.

{
    "dependencies": {
        "com.alkimeegames.codeoptimizationsymbols": "https://github.com/AlkimeeGames/CodeOptimizationSymbols.git#main"
    }
}

Git Updates

The Unity Package Manager records the current commit to a lock entry of the manifest.json. To update to the latest version, change the hash value manually or remove the lock entry to re-resolve the package.

"lock": {
  "com.alkimeegames.codeoptimizationsymbols": {
    "revision": "main",
    "hash": "..."
  }
}