Templ

Integrates Scriban template engine with the Unity Editor.

• Template based asset generation, including scripts, prefabs, scriptable objects, or any text asset.
• Automatic generation when input assets or templates change.
• Generation of scaffold tree structures with folders and files.
• Extensible design allows custom inputs and template functions.
• Public API allows full control of asset generation.

Follow the step-by-step guide for a more detailed introduction to the capabilities.

Unity version support

Tested to work with Unity 2020.3, 2021.3, 2022.3 and 6000.0 on Windows and macOS.

How to install

Install the latest version of OpenUPM CLI, browse to your project directory and run:

openupm add com.willykc.templ

Getting started

After installation completes, a prompt will show up in the Unity editor. When clicking on Proceed, the TemplSettings asset will be created under the Assets/Editor/TemplData directory.

TemplSettings can always be located by clicking on the Windows/Templ/Settings menu. In case TemplSettings is removed, clicking on the same menu will create a fresh copy at the default location shown above.

Create new templates by right-clicking anywhere in the project hierarchy and selecting Create/Templ/Scriban Template.

Live Entries

Live entries allow reactive generation of assets whenever the input asset or template change.

Add and configure live entries in TemplSettings by specifying input, template, directory and output filename (target output file extension must be included in filename). The default entry types are ScriptableObjectEntry and AssemblyDefinitionEntry.

ScriptableObjectEntry takes as input any scriptable object. The scriptable object is exposed to templates as scriptableObject.

AssemblyDefinitionEntry takes as input any assembly definition. The compiled assembly (not the assembly definition asset) is exposed to templates as assembly.

Scaffolds

Scaffolds are tree structures representing hierarchies of folders and files that can be generated anywhere in the project hierarchy on demand.

Create new scaffold definitions by selecting Create/Templ/Scaffold Definition or Create/Templ/Dynamic Scaffold Definition

Use the toolbar in the standard scaffold inspector to create, clone or delete directory and file nodes under the Root node.

Nodes can be moved by dragging and dropping them anywhere in the scaffold tree.

Double-click on any node to open it for edits. Node names support Scriban statements and will be rendered during generation. Templates can be assigned to file nodes in edit mode.

Every scaffold change can be undone/redone as any other operation in the Unity editor.

Generating a scaffold

Add any scaffold to the Selectable Scaffolds list in TemplSettings to enable it for generation.

Right-click on any existing asset in the project hierarchy and select Generate Templ Scaffold from the context menu. A selection menu will be shown with all valid scaffolds in the Selectable Scaffolds list.

Select the scaffold you wish to generate. If the selected scaffold is configured with a default input, a dialog will be shown where input values can be edited before generation. Press the button below to generate the scaffold. If the selected scaffold is not configured with a default input, then the scaffold will be generated immediately after selected.

The selected asset in the project hierarchy will be exposed to the scaffold as Selection, and can be accessed in templates and node names.

Scaffolds can be regenerated in the same directory. Just before regeneration, a dialog will be shown to allow selecting which assets should be overwritten or skipped.

Default Input

Create any scriptable object to define a default input for a scaffold.

Any value contained in the serialized scriptable object instance will be shown as a default value when generating the scaffold.

Custom inspectors for default input scriptable objects will be shown when generating scaffolds.

Dynamic Scaffolds

Dynamic scaffolds enable more flexibility by allowing the tree structure be adjusted dynamically based on input values.

Instead of an editable tree structure in the inspector, dynamic scaffold only require to be configured with a tree template whose output should be a YAML representation of the scaffold tree.

The following is a sample of a scaffold tree represented in YAML format:

- DirectoryName:
    - file.txt: Path/To/Template.sbn
    - SubdirectoryName:
        - anotherFile.txt: Path/To/AnotherTemplate.sbn
          variable: value
- rootLevelFile.txt: Path/To/RootLevelTemplate.sbn

When a dynamic scaffold is generated, the tree template must output a YAML tree compliant with the data structure shown in the sample above.

Any key/value pairs defined under templates in the YAML tree, such as variable: value in the sample, will be exposed to the template as is.

Templates can be referenced in YAML by asset paths or GUIDs.

Any standard scaffold can serve as the basis for a dynamic scaffold by opening the context menu in the scaffold inspector and selecting Copy YAML Tree or Copy YAML Tree with GUIDs.

YAML is parsed using SharpYaml. The license can be found here.

Reserved template keywords

• OutputAssetPath: Exposed to both live entry and scaffold templates, it is the asset path of the generated asset.
• Input: Exposed to scaffold templates only, it is the scaffold generation input object.
• Selection: Exposed to scaffold templates only, it is the selected asset when generating the scaffold.
• Seed: Exposed to scaffold templates only, it is a new GUID shared across all templates in the scaffold.
• RootPath: Exposed to scaffold templates only, it is the root path of the scaffold generation.

Scriban

The Scriban language syntax is well documented.

It is recommended to use Visual Studio Code and Scriban syntax highlights to write and edit templates.

By default, new templates will be created with .sbn extension. For script templates, change the extension to .sbncs for better syntax highlights.

Note that, by convention, properties are exposed to templates in snake case. For example, a property named myProperty will be exposed as my_property in templates. The only exceptions are the Reserved template keywords listed above, and Custom template functions explained further below, which are all exposed exactly as they are defined.

The include function is supported. A template can be included in another template by specifying its asset path or asset GUID. Live entries will not render automatically when an included template changes.

The Scriban license can be found here.

Samples

The included samples showcase some of the capabilities.

The following output file extensions should be used when configuring live entries from samples:

• ScriptableObject to XML: .xml
• ScriptableObject to Code: .cs
• ScriptableObject to ScriptableObject: .asset
• AssemblyDefinition to Code: .cs
• AssemblyDefinition to ScriptableObject: .asset
• AssemblyDefinition to Prefab: .prefab
• Extensions: .txt
• Multiple Inputs Entry: .txt
• Custom JSON Entry: .yml

Extensibility

The sample Extensions contains a custom entry type that takes as input a TextAsset. It also contains custom template functions exposed to Scriban when rendering templates. It is recommended as a starting point for creating custom entries and/or custom template functions.

Custom Entries

To add a custom entry, extend and implement the TemplEntry abstract class. Apply the [TemplEntryInfo] attribute and specify changeTypes, Deferred and DisplayName parameters. The changeTypes parameter determines which type of changes should the entry respond to: Import, Move and/or Delete. The Deferred property determines whether the template should be rendered before or after assembly reloads and defaults to false. The DisplayName property determines how the custom entry should be displayed in the dropdown menu when adding it in the TemplSettings. If no value is specified for DisplayName, the dropdown menu will display the custom entry class name. The custom entry class must not be abstract, must provide a public default constructor, and the containing assembly name must not start with Unity.

Apply the [TemplInput] attribute to the desired input field. By default, the input field value is exposed to templates as the field name itself. To define exactly how to expose input values to templates, use the ExposedAs property. Using special or whitespace characters in the ExposedAs property will require the special variable 'this' in