Usage

For Users

Once Genesis is added as a package, configuring and leveraging Genesis is very easy. At a high level, it involves:

• Setting the Genesis CLI path and installing it
• Creating a GenesisSettings asset and configuring it.
• Using any of the pre-included Genesis plugin attributes to decorate your existing code where code generation is desired.
• Running code generation runner to create the desired script files.

Installing the Genesis CLI and configuring Genesis Project Settings

In order for Unity to find the Genesis.CLI CLI executable for code-generation, we need to configure the Genesis project settings. Open up the project settings at Edit -> Project Settings.

1. Set the Installation Folder to a path outside of the Unity Assets folder (it's important that it's outside of the Assets folder as Unity cannot handle .Net Core assemblies or exes). Once this is done, Click the Update Genesis CLI button. This will extract the Genesis.CLI executable and dependencies to that folder.
2. If any PluginInstallerConfigs are present, click the Install or Update All Plugins button.

Genesis.CLI application

Code generation is executed by a .Net Core console app Genesis.CLI. Each Genesis release contains the most up-to-date version of this application in a zip file named Genesis.CLI.zip located in the External folder. The contents of this zip file are extracted to your installation directory specified in the Project Settings for Genesis when clicking the Update Genesis.CLI button. This enables the Unity project to locate and execute code generation using this console app.

On subsequent updates of the Genesis package, a new version of this CLI will be included in that zip and whenever scripts are reloaded if the existing installation is out of date with the package version a prompt will request to perform this update step. If code generation is attempted with an out of date installation, this will be halted and a console warning about this issue will be sent to the console instead until the installation is updated.

Configuring Code Generation

The first thing you will want to do is to create a GenesisSettings asset in the project. This will enable you to configure which plugins should generate code, where it should be output to, and other per-plugin settings. A Unity project can have a single or multiple GenesisSettings assets to generate different subsets of code. An example of how this can be useful might be using two different GenesisSettings instances with one for generating production code and another for generating fixtures for Unit Tests.

Create a GenesisSettings asset by either:

• Selecting the menu item Assets => JCMG => Genesis => GenesisSettings.

• Right-clicking in the Project window and selecting Create => JCMG => Genesis => GenesisSettings.

There are several plugins included by default in Genesis that help to facilitate common code-generation functions such as merging files with the same name, converting line endings, and writing code-generated files to disk. Their settings are exposed for users to configure on the GenesisSettings asset.

Plugin Settings

General Code Generation

This section houses core project settings for Genesis to execute code generation.

• Auto Import Plugins This button enables a user to import all plugin settings into the GenesisSettings instance. This should typically be done when first creating a new GenesisSettings instance and when adding/creating new IConfigurable plugins.

Each of the mask fields below it enables confguring which plugins should be enabled on an individual basis when a code generation run takes place using this GenesisSettings instance. This can be useful for disabling undesired plugins or for troubleshooting how specific plugins behave.

For example, disabling the "Write Code Gen Files to Disk" IPostProcessor plugin enables running the code generation process without writing any of the generated CodeGenFile instances to disk.

Assemblies

This section enables a user to limit the scope of types for data providers and other plugins to an array of white-listed assemblies. By default, this feature is turned off, but is recommended to limit the scope of types enhance the performance of code generation runs, particularly in larger projects where there may be many assemblies.

• Do Use Whitelist: If enabled, searching via Roslyn for Data Providers will be limited to the array of assemblies below. Otherwise all loaded assemblies will be searched.

• Assembly Whitelist: The comma delimited array of assemblies that searching via Roslyn for Data Providers should be limited to.

Convert Line Endings

This allows a user to configure the line endings all code-generated files generated from this GenesisSettings instance. This can be useful where one line ending type is preferred over another or plugins create files with mixed line endings which often causes Unity to warn about in the console.

Output Directory

This allows a user to specify the root folder all code-generated files will be written to directly or in a subfolder to.

Running Code Generation

Once you have a GenesisSettings asset created and configured, there are multiple ways to easily kick off a code-generation run:

• Running the menu item "Tools/JCMG/Genesis/Generate Code" will execute code-gen for all GenesisSettings assets in the project. There is also a hotkey to execute this command via pressing Ctrl + Shift + G or CMD + Shift + G.
• Selecting one or more GenesisSettings assets in the Project window, right-clicking, and selecting the context menu item Genesis => Generate Code will execute-code gen just for those assets/.
• When selecting a single GenesisSettings asset, on its inspector underneath Actions you can click a button labeled Generate Code to execute code-gen just for that asset.

Where there are multiple GenesisSettings instances, a code generation run will be executed for the steps listed above in sequence of when they were discovered. During that time Unity's compilation and AssetDatabase will be locked until either all code generation runs have completed or an error occurs, at which point both will be unlocked.