Get SpatialOS

Sites

Menu

The code generator

This document relates to both MonoBehaviour and ECS workflows.

The SpatialOS GDK for Unity comes packaged with a custom code generator. This doc will detail how the code generator works on a high level and describe how to make changes to it. The source code for the code generator can be found in the code_generator directory in the root of the repository and is written in C#.

High-level breakdown

JSON AST parsing

The code generator operates on the JSON AST that is generated by the schema compiler. A pre-built dll parses this JSON AST and converts it to C# objects.

The parsing stage, shown in the code snippet below, is in CodeGenerator.cs:

    var schemaFilesRaw = SchemaFiles.GetSchemaFilesRaw(options.JsonDirectory, fileSystem).ToList();
    var schemaProcessor = new UnitySchemaProcessor(schemaFilesRaw);

The code generator then does post-processing on the collection of C# objects that represent the schema.

  1. It flags each type and component as blittable or not blittable. This information is required as blittable and non-blittable components need to be generated in a different manner. You can find the source for this in BlittableFlagger.cs.
  2. It marks data types that are used as event, command request, and/or command response payloads. You can find the source for this in PayloadMarker.cs.

T4 templates

The code generation is done with T4 templates. All the templates used in code generation are located in the Templates directory.

Note: the transformation of T4 to C# is in a pre-build step which is defined in GdkCodeGenerator.csproj. The relevant section is reproduced below:

  <ItemGroup>
    <T4Files Include="Templates\UnityCommandPayloadGenerator.tt" />
    <T4Files Include="Templates\UnityComponentConversionGenerator.tt" />
    <T4Files Include="Templates\UnityComponentDataGenerator.tt" />
    <T4Files Include="Templates\UnityComponentGenerator.tt" />
    <T4Files Include="Templates\UnityEnumGenerator.tt" />
    <T4Files Include="Templates\UnityEnumContent.tt" />
    <T4Files Include="Templates\UnityEventGenerator.tt" />
    <T4Files Include="Templates\UnityTypeGenerator.tt" />
    <T4Files Include="Templates\UnityTypeContent.tt" />
  </ItemGroup>

  <UsingTask TaskName="Improbable.TextTemplating.TransformAllTask" AssemblyFile="dependencies/Improbable.TextTemplating/Improbable.TextTemplating.dll" />

  <Target Name="Code Template Generation" BeforeTargets="BeforeBuild">
    <TransformAllTask InputFiles="@(T4Files)" ProjectDirectory="$(MSBuildProjectDirectory)" Imports="Improbable.CodeGeneration.Jobs" ClassNameSpace="Improbable.Gdk.CodeGenerator">
      <Output TaskParameter="OutputFiles" PropertyName="GeneratedFiles" />
    </TransformAllTask>
    <ItemGroup>
      <Compile Include="$(GeneratedFiles)" />
    </ItemGroup>
  </Target>

Each T4 template is paired with a hand-written partial class that defines the data used in the template. These partial classes can be found here.

Code generation jobs

After post processing, a code generation job is run on each C# object that represents a single schema file. This job is defined in SingleGenerationJob.cs. This job enumerates all the enums, types, and components in a single schema file and runs the correct generator for each.

Editing the code generator

The process of editing the code generator is simple:

  1. Make the code and/or template changes.
  2. Reload scripts within Unity to see your changes in action! The code generator will automatically be rebuilt.

Spatial Codegen configuration

If any changes you make change the input parameters or add new ones, you should add them to Packages/com.improbable.gdk.tools/GenerateCode.cs so it runs correctly!

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums