Templates¶
Template describes the structure and behavior of your game object (item, monster, construction,...). As a programmer, you can think of it as a class. The template has to have a unique name and may contain a set of parameters.
-
Open the Data Structure section, you'll land on the Templates subsection by default. Click on the Create Template button.
-
Each Template has several parameters.
Name Description Name This very name is used for class generation. To keep everything in style, we advise using CamelCase naming.
For example: ItemModel, GameConstruction, MonsterData,...Display Name The name will be displayed in Balancy. Usually, it's the same as the name, but the words are separated.
For example, Item Model, Game Construction, Monster Data,...Description Helps other team members to understand what this Template is used for easily. Base Template It's used if your Template inherits from another one. Type Can be Document, Component, or Singleton:
* Component Documents of this Template are always embedded into other Documents. For example, the Vector3 component template has parameters: x, y, and z. Suppose a Document "Hero" has a Parameter "position" of type Vector3. In that case, you'll be able to edit the x, y, and z values of "position" right inside of the "Hero" Document.
* Singleton Only one of such Documents will be available from the code. It's usually used for settings and configs.Flags Optional settings for the Template Custom Display format Defines the display rules for Documents of the Template. It's handy for complex Templates. You can read more here)
Flags¶
You can set optional flags for the template.
| Flag name | Description |
|---|---|
| Abstract | Generated class for this template will be abstract. |
| Partial | Generated class for this template will be partial. Helpful when you want to extend functionality of the class. |
| Don't generate any code | Class will not be generated and the code in Editor class will not be generated. |
| Don't generate class file | Class for this template will not be generated. |
| Can't inherit | Prevents inheritance from this template. |
| Hide from navigation | Hides documents section from the left navigation menu. |
| Internal | Makes template visible only inside the namespace, if it is used in template name. |
| Hide id | Hides id from the document display name. |
| Static in clones | If set, template will replace existing template on the package import. |
| Generate as enum | Will generate additional enum to list all the documents of that template for easy referencing in client code. |
| Don't generate JSONs | Allows to save memory, if JSON format will never be used for these documents. |
| Prevent access outside package | Similar to Internal, but on package level. |
| Don't generate on Deploy | Useful for parameters which are just personal helpers for Balancy users, such as Comment or Description. |
Documents¶
The document is a unique instance of a Template (Specific Item: Hunter's Bow, Gold Bar,...) with its parameter values. Think of it as an instance of a Class as a programmer.
A new section in the left navigation appears when you add a new Template (Not a Component). If you select any of the Document sections, you can add new Documents there. Each document can have a unique value for all its Template parameters.
Singletons¶
A Singleton is a special type of Template in Balancy that ensures only one instance of the Template is created and accessible in the game. This type of Template is typically used for global configurations or settings that should be consistent across the game, such as a game’s difficulty settings, general preferences, or meta game rules.
Singletons are generated as static classes, making them globally accessible from any part of your game's code. When the game launches, Balancy synchronizes the Singleton data automatically, allowing developers to reference these values without manually initializing or retrieving them.
Some common use cases for Singletons include:
- AdConfigs: Control how many ads players can see, who can view them, and when they are shown.
- Levels Order/Difficulty: Manage the sequence of game levels, their difficulty settings, and progression rules.
- Game Settings: Store global preferences like
MaxPlayers,StartingGold, or general gameplay configurations.
We strongly recommend using ConditionalTemplate as the base template for ease of operations and experimenting.
To create a Singleton document, just select the corresponding template Type. By default, Balancy will make it inherited from Conditional Template, but you may change it.
Components¶
The component is a simple Template, which doesn't have its Documents and can exist only inside another Document.
For example, the ItemActionWeapon (inherited from ItemAction) component template has parameters: damage and reload. If a Document "Item" has a Parameter "action" of type ItemAction, you'll be able to edit the damage and reload values of "action" right inside of the "Item" Document.
Injected Components¶
Obsolete feature!
Injected Components are currently not supported for use in new templates. Previously created Injected Components work as intended. It is possible to change Injected Component type into Component in template editor. This will help you to solve exceptions 1, 2 and 3 listed below.
Injected components are similar to Components, except the following:
- You can Override or A/B Test only internal parameters of Injected Components, not a component as a whole.
- You cannot override parameters that are lists of Injected Components.
- Inheritance doesn't work for Injected Components
- Injected Components don't create an independent JSON file when the data is Deployed. Instead, they inject the parameter right where they are used.
- Injected Components work slightly faster.
For example, the Vector3 component template has parameters: x, y, and z. If a Document "Hero" has a Parameter "position" of type Vector3, you'll be able to edit the x, y, and z values of "position" right inside of the "Hero" Document.
Templates Diagram¶
For better understanding of connections between templates and of inheritance structure Balancy provides Visual Diagram, which can be opened from Templates tab of Data Structure page.
Parameters¶
Parameter describes a part of a Document, storing some value. Each parameter has a name and a type. Type can be simple, like string, int, float, bool, or a reference to any other Template. As a programmer, you can think of a parameter as a field or property of the class.
-
After creating a template, you can add parameters to it.
-
On the parameters page, you can view/edit all existing parameters and add a new one.
-
Each Parameter has several fields:
Name Description Name This very name is used during Class generation. To keep everything in style, we advise you to use CamelCase naming.
For example: MainTag, ConstructionId, HeroType,...Display Name This name will be displayed in Balancy for your convenience.
For example, Main Tag, Construction Id, Hero Type,...Description Helps other team members to understand what this Parameter is used for easily. Default Value The value assigned by default upon creating a new document. Type A Data type of the parameter. All types are below. Type Description Integer A Number that can be written without a fractional component. For example, 1, 2, 999, -200 Float A Number with a fractional component. For example, 1.32, -0.7432 Boolean Logical value: true or false String Any Text. For ex: "Hello World", "-+ ta-ta_!! 55" Enum Provides a selection from predefined possible values. Document A reference to an existing document List An Array(list) of other type values Asset A reference to an existing Asset. It's usually a prefab, sprite, or other Object stored in a Unity game as an Addressable. Sprite A reference to an existing Sprite, that you can upload to the CDN using Balancy. Date Time A date with time. E. g. 1970-01-01T00:00. Have a nice picker inside the table. Duration Similar to integer, but have a nice UI to separate days, hours, minutes, and seconds. Product Reference to in-game purchase item.