GameObjects and components

Unity Forma relies on several GameObjects and components that you must use to set up the system to create configurators.

Configurator

In Unity Forma architecture, the Configurator is the top GameObject in your Unity project. The Configurator GameObject has several components and a specific hierarchy. They include:

References to runtime components. These include the ConfigurationManager and the Switcher.
The Product data model.
Settings for choosing different Provider engines.
Staging settings the multiple Products share.

You can attach additional metadata at the Configurator level, such as company, brand, and version information.

Configurator GameObject

Configurator Hierarchy tab

Components

Property	Description
Transform	(No specific use)
Configurator	Instantiates the product. See Configurator component, below.
State Conductor	State conductor
Configurator Settings	See Configurator Settings component
Mixed Product Source	Holds references to products available in the editor and in your configurator.
Product Preview	Lets you preview the product in your Scene as it appears when you edit it. See Product Preview component.
Environment Preview	Lets you preview the environment in your Scene.

Child GameObjects

GameObject	Description
Staging Manager	The Staging manager.
Switcher	The Switcher.
Configuration Manager	Defines the current Variant selection for the product.
Spawn Point	Materializes the coordinates where the 3D model of the product instantiates in the scene. The Configurator instantiates the Product under this GameObject.
RuntimeUICreator	The Runtime UI creator.
IRuleEngine	The Rule Engine that defines Variant logic.
IPricingEngine	The Pricing Engine.
IInfoEngine	The Analytics Engine.

Configurator component

The Configurator component instantiates the product that the Configurator Settings component references. If the Product exists in your scene, you can find it under the Product Spawn Point GameObject, which is under the Spawn Point GameObject in the Configurator GameObject hierarchy.

Properties

Property	Description
Settings	A link to the Configurator Settings script component.
Staging Settings	Staging settings. This includes a list of environments, cameras, animations and events.
Create Camera before Play and Build	When building and entering Play Mode, create a main Camera if there isn't one present.
Active Configurator Profile Reference	Reference to the Active Profile
Staging Manager	Link to the Staging Manager script component.
Build Profiles	List of available Build Profiles.
Current Context	Link to the current context, if any.
Spawn Point	A link to the Configurator Spawn Point GameObject.
Splashscreen Prefab	A link to the Prefab that the configurator will use as a loading screen.

Buttons

Button	Description
Open Configurator Setup	Opens the Unity Forma interface.

Product Preview component

If it isn't already there, add the Product Preview component to the same object where the Configurator Component exists. It instantiates a Product in your Scene while you work from the Unity Editor (different than the Unity Forma interface).

Property	Description
Auto Load Product	Enable to make the system automatically load the Product in your Scene. It can be useful to disable this property if your product is large or you are working on an Environment.
Unload Before Play	Enable to automatically unload the Product Preview before you switch from Edit mode to Play mode. This property is useful if you want to replicate the same environment that the consumer will see. If the Product is Dirty, the system saves it before it unloads the Preview. If your product is large, this can increase the time it takes to switch modes.
Remove on Build	Removes the preview from the built product so that it is only loaded by the player.
Product Dropdown	Use dropdown to select a Product to preview.

Configurator Settings component

The Configurator Settings component lets you customize different behaviors in the application and set default behaviors. Before you build a project, Forma moves the Configurator Settings component to an Addressable Asset Prefab so that you can export them separately as a Products Only build.

Configurator Settings properties are organized into these sections:

Product Sources

The system uses Product Sources to find and pre-load Addressable products for the configurator.
Once ready, the configurator detects the assets that are available. It can load Products from multiple locations under different conditions.

The system uses Unity Forma catalogs to separate Products from the project and reduce the size of the resulting build. It can load Projects from any location.

Product Source Type	Product Reference Type	Environment	Addressable Assets	Description
Reference	AssetProductReference	Editor Only	True	Product references will not be available in the final build. The system loads products from the Asset Database (depending on the Addressable Load Mode).
Catalog	CatalogProductReference	Editor & Build	True	Automatically loads the products from the Streaming Assets folder, and from local and remote paths (depending on the Addressable Load Mode). URLs must point to a `.json` file.
Mixed (Reference & Catalog)	AssetProductReference & CatalogProductReference	Editor & Build	True	This is the default component when creating a configurator. Editor: Loads products from Asset Database (depending on the Addressable Load Mode). Build: Automatically loads the products from the Streaming Assets folder and from local & remote paths (depending on the Addressable Load Mode).
Cloud Content Delivery	CatalogProductReference	Editor & Build	True	Use a badge to load the latest Products from the Unity Cloud Content Delivery server. You must provide a `Project Id`, `Bucket Id` and a `Badge`. The default value is latest.
Prefab	PrefabProductReference	Editor & Build	False	Use direct Prefab references instead of the Addressable Assets System. Automatically includes Products in the final build.
Scene (Experimental)	SceneProductReference	Editor & Build	False	Experimental / Not Fully Supported: Use a scene product instance in the configurator. This can be useful for previewing a merged mesh model.

Product Reference Options

Reference options tell the configurator how it should handle the products to avoid destroying or breaking their asset unexpectedly.

Experimental: by default, theSceneProductReference is the only reference that is destroyed and removed from its product source on configurator unload.

Option	Default	Description
Destroyable	True	Product can be destroyed and unloaded completely.
Deactiveable	True	Product can be deactivated and can stay in scene / memory.
UseProductCache	True	Product can use the cache and can be deactivated.
UseSpawnPoint	True	Product can be moved and re-parented under the spawn point gameObject.

Event Tree

Product Sources - Editor Color Code

Color Code	Description
Green	The catalog is loaded and ready to be used.
Orange	Loading the catalog and its dependencies.
Red	Not yet loaded or could not be loaded.

Product Prefabs

The Product Prefabs property lists the different Product Prefabs that the configurator uses. Any Product Prefab in the list must conform to requirements in the Product.

Provider Engines

The Provider Engines property lets you link to different Provider Engines that the configurator will use to relay information selections and products to the consumer in response to requests from Forma. Provider Engines offer extensibility that lets you customize the behavior of the configurator.

Property	Description
Rule Engine	Link to the Prefab that implements your Rule Engine. The Prefab must include a script component that implements the IRuleEngine programming interface. Note: By default, the Configurator uses the DummyRuleEngine.
Runtime UI Data Engine	Link to the Prefab that implements your Runtime UI Data Engine. The Prefab must include a script component that implements the IInfoEngine programming interface.
Pricing Engine	Link to the Prefab that implements your Pricing Engine. The Prefab must include a script component that implements the IPricingEngine programming interface.
Analytics Engine	Link to the Prefab that implements your Analytics Engine. The Prefab must include a script component that implements the IAnalyticsEngine programming interface.

Runtime UI

Use Runtime UI properties to configure the Runtime UI that the Configurator uses. See Runtime UI.

Property	Description
Create Runtime UI	Note: Other Runtime UI properties are only displayed when Create Runtime UI is selected.
Runtime UI Type	The type of runtime UI to be created. By default, there is a single entry, ProductUGUIRuntime, which is our example UI.
Custom Resource Provider	Link to the Custom Resource Provider, if any.

Product

When a prefab is converted into a product, a folder with that product's name is created that contains all the prefabs required to fully define a product.

Prefab Type
ModelSet	Model geometry and the Queries prefab.
Product Definition	See Product Definition
Product Prefab	Contains the Product component and the Product Settings prefab.
Queries	Resolves material, playable and renderer differences between Variant Profiles
Product Settings	Configuration and variant details

The fully defined Product GameObject lets you define a Product that consumers will customize in the configurator. For convenience, it features the following:

A Nested Prefab that lets you re-import a Product.
A Debug Mode for inspecting the Variant Table. (Use the API to make changes to the Variant Table.)
Staging overrides that let you set Environment, Camera, and Animation settings for an individual Product. Forma adds or replaces Staging settings with the Product Settings when it builds the configurator.
Addressables
Controls for setting the position of the Product in the Environment (the Spawn Point).
Controls for setting different Hotspots on the Product and defining what the configurator shows for each.
A component for defining the default configuration of the Product in the configurator.

ModelSet

The model set prefab contains the product geometry along with its queries. It contains a Model Set component that holds a reference to the Queries gameobject.

Product Prefab

The product prefab contains the Product component and the Settings prefab.

Component	Description
Transform	The transform for the Prefab component.
Product	See Product Component

Product Component

Property
Settings	Link to the Product Setting script.
Model	Link to the top-level GameObject in the model geometry.
Model Set	Link to the ModelSet GameObject in the Scene hierarchy.
Model Set Prefab	Link to the ModelSet prefab in the Asset library.
Definition	Link to the Product Definition.
Open Product Settings	Opens the Product Setup tab in the Configurator window.
Cache Queries	Refreshes the Variant Table queries
Add Version of Product	Add a new product Variant Profile.

Product settings Prefab child GameObjects

Component	Description
Variant Table	Defines and stores all Variants for a Product. See Variant Table.
Context Collection	Regroups and defines the schema for Contexts. See Context Collection.
Spawn Point	Coordinates where the center of the Product will materialize in a Scene. Forma matches the coordinates of the Product Prefab spawn point with the coordinates you specify for the Configurator.
Presets	Specify different configuration presets that you can save for a Product. No other components use the presets.
Defaults	Default configurations specify the initial state of the product in a given Context. For each Context, specify the default configuration for the Product. You must set a default configuration for each Context. Typically, consumers do not select all Variants that you define for a Product; they open the configurator to see a default configuration and make selections to customize the Product further.

Product Settings

Property	Description
Variant Table	Link to the Variant Table component
Context Collection	Link to the Context Collection component
Staging Settings	Specify staging settings specific to the Product. Forma merges them with Staging settings you define for the Configurator when your product is instantiated. Specifying separate settings for the Product and the Configurator lets you add or override Camera Views or the Environment for a Product.
Spawn Point	Link to the Product Spawn Point GameObject.
Is Dirty	For internal use only (Specifies when there are modifications to the file that the system needs to Save.)
Rules	Link to the Rules component.

Product Runtime UI Data

The Product Runtime UI Data is a component used to set display information for the sample runtime UI that comes with Forma. Depending on your custom UI needs, you should modify or remove this component entirely.

Product Local Price

The Product Local Price component stores pricing information for this product.

Property
Product	Link to the Product component.
Context	Link the current Context, if any.
Default Price	The base price.
Custom Currency Culture	Culture group string for which type of currency should be applied to this product.
Feature Set Prices	Additional costs added by choosing specific variants. Total cost is the selected feature set prices plus the base price.

Rules

The Rules component contains all the rules defined in the Rule Engine. and translates them into a form that can be used by code.

Queries Prefab

The Queries Prefab contains a list of QueryNode GameObjects that link your product to physical assets in the project such as materials. Each QueryNode GameObject has a _ Query Node component, where the Query Node script is a class that inherit from the QueryNode base class. QueryNodes let you populate the target and value fields of an Assignment and reuse code between different product variants.

There are different strategies for determining which geometries a Variant affects, including the following:

You can define a placeholder Material (such as a Target Look in DeltaGen).
You can directly assign items to a VariantTable
You can use metadata to associate different items with a VariantTable

QueryNodes are designed to support each strategy. By writing custom QueryNodes you can query GameObjects for almost any type of property and define matching criteria, such as name, placeholder material, metadata, hierarchy position, and more. You can use the results of the query as a target or value for the Assignment. Only one Query component should be attached to a QueryNode.

Forma comes with the following Query types already defined:

Static Material Query Node: Used with Material Assignment. Holds a single material reference.
Static Bool Query Node Used with Visibility Assignment. Holds a boolean value.
Static List Material Slot Query Node Used with Material Assignment. Holds a list of material references.
Static List GameObject Query Node Used with Visibility Assignment. Holds a list of GameObject references.
Static Playable Query Node: Used with animation Directors. Holds a reference to a Playable Asset.

Examples of queries can include:

'Get GameObjects with assigned material t_carpaint'
'Get GameObjects whose name contains "PN23_"'
'Get GameObjects whose name satisfies the regular expression "^PN2[0-9]"'
'Get the first child of each GameObject whose name ...'

Refreshing queries and static queries

Queries are typically dynamic and can be refreshed so that they update the list of results (for example, as consequence of project updates).

To make the queries static, you can assign a GameObject to a QueryNode in a direct, static way. The queries are no longer dynamic or refreshable and they become static.

Variant Table

The Variant Table, found in the Product Settings Prefab, stores definitions of any Variant you create. It defines the different aspects of your product that consumers can interact with or customize.

The Variant Table does not contain Product logic. To define the logic that determines when different Variants are visible or available to the Consumer, you must use a Rule Engine.

Variant Table GameObject and component

Variant Table component

Properties

Property	Description
Feature Sets	List of feature sets that can be either Variant Sets or Pack Sets.
Force Standard Configuration	Enable to force all configurations to use a standard validation. Valid configurations have a default Variant selected in each Variant Set.

Variant Table GameObject hierarchy

The Variant Table GameObject has the following hierarchy of child GameObjects:

Variant/Pack Set 1
- Variant 1
  - Assignment (2 types: Material or Visibility)
- Variant 2
- Variant 3
- ...
Variant/Pack Set 2
Variant/Pack Set 3
…

Variant Table child GameObject types

Property	Description	Cardinality
Variant Set	Direct child of the Variant Table GameObject.	Unlimited
Variant	Direct child of the Variant Set GameObject	Unlimited
Material Assignment	Direct Child of a Variant GameObject when the Variant is a Material Variant	There can be only one Assignment GameObject per Variant GameObject
Visibility Variant	Direct child of a Variant GameObject when the Variant is a Visibility Variant	There can be only one Assignment GameObject per Variant Game Object.

Variant Set GameObject and component

The Variant Set GameObject includes a single Variant Set component. It also includes a Transform component which is for internal use only.

Properties

Property	Description
Code	Enter a code for the Variant Set.
Features	List of features (Variants) in this Variant Set.
Selected Feature	The currently selected Variant for this Variant Set.

Variant GameObject and component

A Variant defines a single characteristic of a product. For example, in a Car configurator, you might create different Variants for a seat, a rim, a car paint color, a seat type, or a material. Variants represent marketing concepts and do not always correspond to engineering concepts in the Product. A single Variant might include several different manufactured parts and a material definition that are all identified by a single marketing code.

Each Variant has Assignments that are made from a Value Query and a Target Query.

For information about creating custom Assignments and queries to support your configurator, see Variant Extensibility

Properties

Property	Description
Code	A string that uniquely identifies the Variant in the Configurator.
Feature Set	The feature set.
Assignments	List Assignments for this Variant

Material Variant

A Material Variant is a Variant that has only Material Assignments.

The system does not prevent you from adding Visibility or Custom Assignments to Material Variants.

Visibility Variant

A Visibility Variant is a Variant that has only Visibility Assignments.

The system does not prevent you from adding Material or custom assignments to Visibility Variants.

Variant Extensibility

Variants and the GameObjects associated with them (Variant Sets, Assignments, Queries, etc.) are extensible. You can extend them to support your own configurator requirements.

By default, Unity Forma only offers Material and Visibility Variants, and their related queries. The system is designed to let you create custom queries that meet the needs of your Variant Table.

Assignment GameObject and components

Assignments connect Variants to GameObjects in the Configurator. Each Assignment has the following:

A target query that indicates the objects that the Assignment affects.
The value query that indicates each object will have
The type of Assignment (Visibility, Material, etc.)

The behavior of each Assignment corresponds to the following principle:

'Variant V will assign Value A to GameObjectX'

A Variant can have several Assignments that let it influence GameObjects in different ways. An Assignment can also have multiple targets. For example, you can assign one car paint material to multiple car paint GameObjects.

By default, Forma supports Assignments that manipulate materials and visibility. If you need an Assignment to manipulate other GameObject properties, you can extend the Assignment class.

Properties

Property	Description
Target Query Id	The Id of the target query that fetches the target objects for this Assignment.
Target Query	Filled in automatically.
Value Query Id	The Id of value query that the system applies to target objects for this Assignment, such as a Material or Visibility Boolean value.
Value Query	Filled in automatically.

TargetQueryNode

TargetQueryNode returns a collection of GameObjects. You can extend the class with a different mechanisms that return GameObjects. See Examples.

ValueQueryNode (generic)

ValueQueryNode is a generic class type. Different Assignments can manipulate different value types (Boolean for VisibilityAssigment, Material for MaterialAssignment, and so on). ValueQueryNode can also return values that use any kind of algorithm you compose, including a static selection.

Material Assignment

Material Assignments handle Material Values and specifically manipulate the material that the system assigns to a GameObject.

A Material Assignment applies a value query that returns a material to a target query. The target query returns a list of render slots and acts as a renderer with a material index.

Visibility Assignment

Visibility Assignments manipulate the Visible status of a GameObject. They handle Boolean values (on/off).

A Visibility Assignment is an Assignment type that sets the target query objects to the value of a value query, such as on or off.

Context collection

The Context Collection GameObject groups and defines a schema for contexts.

Context collection GameObject

Components

Component	Description
Transform	(Internal use only)
ContextCollection	See Context Collection

Context Collection component

Properties

Property	Description
Contexts	List of Contexts
Keys	The schema for each Context

Because a Context is a series of values without meaning for each element, you must use the Context Collection Keys attribute to give each Context meaning. Each Key represents the meaning of each Context value, in the same order.

For example:

Context Collection Key	Context value	Meaning
Element 0: "Engine"	Element 0: "V8"	V8 is an Engine
Element 1: "Market"	Element 1:"United Kingdom"	The market is the United Kingdom

Context GameObject and component

A Context is a series of your own custom data that various components in the Configurator can use to determine behavior. Alone, Contexts do not have a function.

The runtime UI typically sets each Context to add extra information about the user or the user environment to the Configurator.

The Rule Engine can use Contexts to determine which features are available to a user. Other Provider Engines can also use Contexts.

A Configurator project typically contains a complete dataset (150% model) for each Product. The dataset includes Variants that are available under very different conditions, and for different markets.

For example, a right-hand drive steering wheel and a left-hand drive steering wheel would be available for different markets.

The dataset can even account for different product lines, such as a sedan and convertable.

The initial state of the product (the default configuration) cannot be the same for each Context. For each market or product line, you need to specify a different default configuration.

Contexts let you select groups of features that uniquely identify a subset of a product, such as the number of doors, engine type, transmission, fuel, and more. They let you create default configurations by linking each to a different Context.

Component overview

Properties

Property	Description
values	List of data points. You define the meaning at each index of a Context in the Context Collection

Configuration

A Configuration arranges Product Variants so that the configurator can easily recall them.

Configurations are especially useful when:

A Product has a default Configuration (for example, a car with basic features and white car paint).
A Product has specialty (hero) shots that are designed to arrange different Variants in an appealing way for marketing purposes.
A consumer defines a configuration to open later.

Configurations cluster Product Variants and let you switch between them without needing to set each Variant again.

Runtime UI

The Runtime UI is the user interface that the consumer sees with they open your configurator application.

Deployment

Deployment describes the process of building your configurator and publishing it to a target destination where consumers can access it.

Build settings

You can define separate builds for the different platforms and devices that consumers will use to access your configurator application. Builds can also support different quality profiles for the various resolution settings on consumer devices. See Build Setup for more details.

Note: You can only see Addressable Asset settings in the Unity Editor interface. They do not appear in the Unity Forma interface.

Working Platforms

Unity Forma can create builds for consumers using these platforms:

Windows
MacOS
Linux
Android
iOS
WebGL

Addressable Assets - Output Build (Products only)

AddressablesLink is used for code stripping by the addressable package (not required at runtime).
default contains your product builds catalogs and asset bundles (this data can be moved to a remote server).
DefaultData contains the Default Local Group data and users' custom addressable data.
catalog.json and settings.json are generated by the addressable assets system and needed for the runtime to work (this should always stay in the StreamingAsset folder)
FormaCatalogIndexer.json contains the relative paths to the catalogs subfolder (for example: default and DefaultData). File detection is not always possible on iOS, Android or CCD so Forma uses this file for data discovery.

Notes

Forma only supports addressable products.
Each Addressable Asset Group has 4GB file size limit.
Untracked Forma assets will automatically go to Default local group.
The Addressable Assets system cannot compile new scripts. An Addressable Asset can be a Prefab, texture, material, audio clip, animation, and more.

For more information, see

User interface

The Forma user interface is an application that runs on top of the Unity Editor. For some tasks, you need to switch between the Unity Editor and the Forma interface.

To change interfaces, go to the Forma menu and a select Switch Mode.

Extending

You can extend several features, such as the runtime UI, in Unity Forma.

Runtime UI

To customize the Runtime UI, you can do one of these things:

Customize Runtime UI resources
Create your own Runtime UI from scratch

Customizing the existing runtime UI

To specify your own custom resource provider for the Runtime UI or to select an object that implements the class 'ProductRuntimeUI', you can edit the Runtime UI section under Configurator Settings.

The Custom Resource Provider field lets you specify any assets that implement the iResourceProvider interface. The default runtime UI lets you use a CustomResource Privider property that you can use to customize the UI with Prefabs.

Creating your own runtime UI

To create your own custom UI, you can use the 'ProductRuntimeUI' abstract class. You can select the ProductRuntimeUI class in the Runtime UI Type field in the Configuration Settings.

Importer

To create a custom importer, use the following example package: https://unity3d.atlassian.net/browse/CC-491

Info Engine

To create a custom Info Engine, create a class that implements the IInfoEngine interface.

<--! ## Deep Dive [TBD]-->

Configuration change flow

This table shows the main parts of a Configuration change:

Actor	Actions
Runtime UI	Select feature Consumer does an action that requests a change to a feature, such as the paint color.
Configuration Manager	QueryConfigurationChangeValidity (Configuration change) The Configurator manager queries the Rule Engine to check if the Configuration is valid.
Rule Engine	QueryConfigurationChangeValidity (Product, Context, Configuration, ConfigurationChange) The Rule Engine verifies that the Configuration is valid and returns a list of availabilities for each modified Variant, Variant Set, or Pack.
Configuration Manager	ApplyVerifiedConfigurationChange (VerifiedConfigurationChange) The verified Configuration that the Rule Engine returns is applied to the current Configuration and all selected Variants are sent to be switched on or off.
Switcher	SwitchConfiguration (VerifiedConfigurationChange)
Assignment Switcher	Apply Assignment (Assignment) For each Variant Assignment, the Assignment Switcher selects: Custom Action Conceptually, the Assignments value is applied to the corresponding target. For a Material Assignment Switcher, the Material is applied to the object renderers.
Runtime UI	Update Feature Availabilities The Runtime UI uses various events to update feature availabilities and its state.