Code Generation

Why do I need it?

It's a good question because many developers like to rewrite such things in every project.

Here are some reasons for you to consider:

1. Why would you spend your precious time on a monotonous job? Such things should've been automated a long time ago.
2. Human mistakes excluded. A game designer or programmer often misspells a word, and parsing doesn't work as expected. Such a problem might take some time to be found.
3. Whenever a game designer changes a parameter or a Template, all of that will be instantly reflected in the code after the generation. A programmer will remember to apply those changes.
4. Code generation is tightly connected with other Balancy excellent features, like Localization. Using them all together gives your team a huge boost.
5. You can remember JSONs and how to parse them. Balancy will do that for you, so you can only work with convenient classes.
6. When a document refers to another document, developers usually use some ID to create those links. Balancy will do that for you. It automatically resolves all links and gives you direct access to the Documents you expect.

How to generate code

1. In Unity, select Tools ► Balancy ► Config, enter your email and password for balancy.dev, and press Generate Code button.
2. It might take some time, depending on your connection and the number of Templates you have.
3. Generated classes will be placed in Assets/Balancy/AutoGeneratedCode.
4. Please DO NOT change anything in this folder because your changes will be overwritten with the next generation.

How does it work inside?

Balancy server-generated JSON files based on your Documents and puts them in the CDN storage. Balancy plugin automatically checks for the updates of those JSON files and downloads only updated files. After that, it parses the data from JSON to the generated classes and finds all dependencies. The programmer doesn't have to download, parse, or understand JSON. There is also no need to find any links if any of the Documents refers to another one - Balancy will automatically resolve the link, so you will get direct access to the Documents you expect.

How to get access to the documents

1. Let's say you have a Template ItemModel and several Documents of this Template. Use Balancy.DataEditor.ItemModels to access the list of those Documents.
2. Let's say you have a Template RecipeModel, which has a Parameter Item of type ItemModel. Once you get an instance of that RecipeModel as recipeModel, you can get access to its Item as recipeModel.Item. As simple as that!
3. If your Template GameConfig is a Singleton, you can access it by writing Balancy.DataEditor.GameConfig.

How to work with the generated code

Every developer has his style, and it's really up to you how to work with the game data. Below we list a couple of examples that we would use:

Extension Method

Let's say you have a generated code for items:

public class ItemModel : BaseModel
{
    public string Name;
    public string Description;
    public string IconName;
    public string AssetName;
    public int MaxStack;
}

If you want to add a check on whether an Item can be stacked in inventory, you can write it in a separate file:

public static class ItemModelExtension
{
    public static bool CanStack(this ItemModel item)
    {
        return item.MaxStack > 1;
    }
}

So later, if you have an instance of ItemModel as item, you can call the new method:

item.CanStack();

Facade Pattern

Let's say you have a generated code for inventory:

public class Inventory : BaseData
{
    public SmartList<ItemSlot> ItemSlots;
}

First, you create a new class called InventoryController, which has the property Inventory in it. Instead of working with Inventory directly, your game has access only to the InventoryController. So if you want to add a check if there are any empty slots, you can write:

public class InventoryController
{
    public Inventory Inventory;

    public bool HasEmptySlot() {
        foreach (var slot in Inventory.ItemSlots)
        {
            if (slot.IsEmpty())
                return true;
        }
        return false;
    }
}

This is just a simple example. This logic can be rewritten using the first approach (Extension Method) recommended for this situation.

Partial Classes

If you activate the partial checkbox for your Template in the CMS, the generated class will be marked as partial. You can add as many methods and properties for this class in a separate file as you want.

Recommendation

The first approach is the best one. It suits all simple Templates (which don't have any references as parameters). For more complicated Templates, you should use combinations of the first and the second approaches. The last approach of Partial classes might look attractive, but it's not recommended use. Many developers prefer to avoid this feature for many reasons. The same can be implemented using the first or the second approaches.

Of course, there are many other ways to implement such logic. If you like one, please share it with us; we might add it to the documentation.