Tool Documentation

See below for details on how to use the level breakdown tool in your unity project.

Introduction

The Level Breakdown tool is a project organization and control solution developed by game designers for game designers. However, its functionalities can benefit all members of the development team.

The goal of the tool is to provide useful and

up-to-date information about the project with low maintenance costs, replacing the use of some external spreadsheets for control.

The tool offers:

Estimates of difficulty, duration, and resource economy for levels and the game as a whole.
Easy access to game level scenes for the entire team.
Listing of registered activities with quick access to corresponding documentation.
Ease of locating in which game scenes the registered activities are present.
Accounting for the use of registered activities in levels and throughout the game.
Tracking the projection of the player's learning curve.
Locating registered activities within a specific scene.
Bonus: Includes all functionalities of the Draw Charts asset, allowing the creation of customizable charts in editor windows.

The Level Breakdown has been developed with a focus on linear games, but its application can be adapted to various types and genres of games with minor abstractions.

It is important to highlight that all information provided aims to assist in control and decision-making during game development. However, it does not replace the need for testing and validation. Estimates of difficulty, time, XP, and currency should be interpreted as approximate values, serving as a thermometer for analyses and decisions about the project. Many of these values can vary according to the player's profile.

If you’re ready, let’s get started!

Category Data

The first step to configure the tool in your project is to fill out the Category Data.

This file contains a list of activity categories that you can create. You can add as many categories as needed, depending on the type of game you are developing and your requirements.

However, there should only be one CategoryData in the project.

To find it, search your project for Category Data, or navigate to the folder:

Assets/LevelBreakdown/Scriptables/CategoryData

Creating a Category Data

If your project does not yet have a Category Data, you can easily create one.

Just right-click in the project window and select

Create > LevelBreakdown > CategoryData.

By default, the Category Data comes with some example categories, which you can customize as you prefer.

Once configured, it does not need to be changed again unless you want to add new categories.

Interaction Data

With the Category Data configured, you can now register your first activity through an Interaction Data.

The InteractionData is responsible for storing all the standard information of an activity, which will be consulted by the tool for future analyses.

Creating an Interaction Data

You can create a new Interaction Data in a few ways:

Right-click in your project and select:
- Create > LevelBreakdown > InteractionData

Duplicate an existing Interaction Data and change its values.

Or, in the Tools window, go to
- Zero Tools > Level Breakdown > Create InteractionData.

After that, you will have access to a window to create Interaction Datas, where you need to fill in the indicated fields. With just a name, you can create a new activity.

Once you finish filling it out, click

"Create Interaction Data"

to close the window and create the file, or

"Continue Creating InteractionDatas"

to create the file and clear the fields to continue creating new data.

Remember: there should not be more than one InteractionData with the same name in the project.

Setup up an InteractionData

Setup up an Interaction Data

Icon

Select an icon to represent your activity (optional).

Interaction Name*

Define a name for this activity.

There should not be activities with the same name in the project.

Description

Briefly describe the registered activity, sufficient for others to understand what it refers to (optional).

Documentation Link

Add a link to the official documentation of that activity, such as the GDD page (optional).

Category*

Select the category to which this activity belongs. The list of options derives from the Category Data configured earlier. After selecting the category, it will be registered above the selection field.

Define Difficulty

If the activity contributes to the difficulty of the player overcoming a level, check this option and assign a value below. This value is an abstract number that represents the level of threat of the activity compared to others in the game. The scale should be determined by you and your team. Defining a value is optional.

Different values can be set at the activity instance if necessary. Negative values are also accepted if the activity aims to decrease the player's difficulty (optional).

Define Time

If the activity affects the time the player takes in a level, check this option and assign a value in seconds, representing the average time the player will take to complete the activity. Defining a value is optional; different values can be assigned at the activity instance if necessary (optional).

Define XP

Define the XP value that this activity offers the player upon completion (optional).

Currency

Define how much money is offered to the player for completing this activity (optional).

Remember that these values are only for feeding the analyses conducted later and do not directly affect the functioning of the reward system implemented in your project.

With this, you can register all the activities you want the tool to track and consider during analyses, such as enemies, items, objectives, NPCs, special interactions, and everything else you can imagine.

Icon Pack

If you don’t have or don’t plan to develop exclusive icons for each activity, you can access this link to obtain a Free pack with over 120 varied icons to use with the tool.

Scene Data

Now that we have registered activities, it's time to register the game levels.

For this, we will use a Scene Data, where all the information and data collected about this level will be stored.

To locate the Scene Datas, search your project for Scene Data or look in the folder:

Assets/Zero Tools/LevelBreakdown/Scriptables/SceneData

Creating a Scene Data

To create a new Scene Data, simply right-click in the project window and select:
Create > LevelBreakdown > SceneData.

Alternatively, if you have the scene you want to create the Scene Data for open, you can select:
Tools > Zero Tools > Level Breakdown > Create SceneData from Current Scene

to automatically generate data with the current scene.

Setting up a Scene Data

Setting Up a Scene Data

Once the Data is created, fill in the relevant fields for the level it represents.

Scene Reference and Extra Scenes *

In Scene Reference, you should reference the main scene of the level that this Data represents. If there are sub-scenes or additive scenes, they should be added to the Extra Scenes list.

This way, the tool will have visibility of all necessary scenes to encompass that level. Without these references, it won't be possible to perform analyses on this level in the future.

Level Image

In Level Image, you can link an image to the level. If there is no defined image and there is an image in the project named after your scene followed by “_Cover,” it will be automatically associated with this Data (optional).

Level Name*

Here, you should define the name of the level for this Data. There should not be more than one Data with the same level name in the project.

When referencing a scene in Scene Reference, if this field is empty, the name of the scene will be automatically assigned.

Documentation Link

You can add a link to the official documentation for this level, such as a GDD page (optional).

Zone Name List

Zones are specific areas within that level. Registering zones is only necessary if your project has large levels enough for analyses to require more detailed information, separating by these zones.

If you decide that this information is essential, be aware that it will require more maintenance and attention from developers when adding activities to levels in the future (optional).

Functions in Scene Data

Function in Scene Data

Level Overview
After the tool performs analyses on this level, a brief summary of the information will appear below Level Overview.

Scene Data Buttons
At the bottom of the Scene Data, you will see two shortcut buttons. The first opens the scenes referenced in the SceneData, and the second opens the documentation link in the browser.

Scene List

This is the list where you should add the Scene Datas you want to track in analyses.

Scene List Buttons
At the bottom of the Scene Datas list, you will find the following buttons:

Add All Objects: This button adds all the Scene Datas from the project to the list. The list is cleared before being filled again.

Clear Scene List: This button removes all Datas from the list.

Interaction Object

To register the presence of an activity in a scene, the Interaction Object component is used.

This component can be added to any GameObject in the scene or, ideally, to the prefab of the activity it represents, such as a prefab for spawning an item, enemy, hazard, NPC, among others.

This way, you reduce the need to add the Interaction Object every time you use these prefabs.

When a GameObject has one or more Interaction Objects, it will be identified in the analyses, and the configuration made in it will be computed.

Interaction Data Info

At the top of the component, you can see an overview of how that instance is being read, with all the information of the registered activity, such as icon, zone, name, category, difficulty, time, XP, and currency. Additionally, some customization options can be made for each Interaction Object.

Interaction Object Settings

Interactio Object Settings

Interaction Data

Here, you should reference the Data of the desired activity. This way, the Interaction Object will extract all relevant information from that Data, such as icon, name, category, difficulty, time, XP, and currency, if they exist.

Scene Data

Here, you should reference the Scene Data of the scene where this Interaction Object is located. Normally, this reference is made automatically, unless a Scene Data that contains the current scene is not found.

Zone

If the current scene has a Scene Data with registered zones, it will be possible to choose, via the slider, which zone this activity should be associated with. Use zones only if you deem it essential to have the level information divided by different areas, generally used in very large levels.

Multipliers and Override Settings

Multipliers and Overrides

Multipliers
It is possible to manipulate the values of difficulty, time, XP, and currency through multipliers if some contextual factor influences the default values of the activity in this instance.

Quantity

Allows you to define how many times this activity is being represented by this component. All values will be multiplied by the value assigned here.

Typically used when it is necessary to group several activities in one object, such as tying them to a spawn of multiple enemies or manually registering how many of that activity are present in the level if there is no dedicated prefab or Game Object.

Difficulty Multipliers

Allows you to set a value that multiplies the default difficulty value. Decimal values are accepted.

Time Multipliers

Allows you to set a value that multiplies the default time value. Decimal values are accepted.

XP Multipliers

Allows you to set a value that multiplies the default XP value. Decimal values are accepted.

Currency Multipliers

Allows you to set a value that multiplies the default currency value. Decimal values are accepted.

Interaction Object Buttons

Find Activity In Scene

This button will open the Interaction Object Finder window already with the activity that is listed in this component.

Set Gizmo Icon

This button allows the icon associated with this activity to be referenced as the gizmo icon of the Game Object. You can attach it directly to the current object or create a child object with the icon if you prefer to have free control to position it differently from the main object's point.

Interaction Object Finder

The Interaction Object Finder is a window that allows you to easily locate the Interaction Objects present in the active scenes.

You can open it via the menu

Tools > Zero Tools > Level Breakdown > Interaction Object Finder

Or by clicking the Find Activity In Scene button on any Interaction Object.

With the window already open, you can select the activity you are looking for, and the tool will display a list of all Interaction Objects in the scene related to that activity.

By clicking the name of the Game Object, it will be highlighted in the hierarchy and in the scene tab.

Levels Breakdown Windows

The Levels Breakdown Windows is where you can access all the analyses provided by the tool, navigating freely between the available tabs to view different types of information. To access it, go to

Tools > Zero Tools > Level Breakdown > Levels Breakdown Windows

Or simply use the keyboard shortcut Ctrl + F12.

At the top of each tab, you'll find a brief summary of its functionality, followed by buttons:

Update Values

This button opens the Update Values Window, which allows you to request the update of analysis values in all tabs.

Show SceneList

Opens the Scene List in the Inspector and highlights it in the project tab.

Show CategoryData

Opens the Category Data in the Inspector and highlights it in the project tab.

Update Values Window

In this window, you request the tool to scan the scenes registered in the Scene List and update all necessary values in the PersistenteData and the Scene Data of each level. You can select which scenes to scan either manually or using supporting buttons:

Select All

Selects all scenes listed in the Scene List.

Select Current Scene

Selects only the currently open scene.

Select Dirty:

Selects all "dirty" scenes in the Scene List.

Unselect All:

Deselects all scenes in the Scene List.

After selecting the scenes, you can verify the number of chosen scenes and the estimated time to update the values, which may vary based on the size and number of scenes.

To avoid long waiting times, it's best practice to execute an Update Values for each scene after making changes or to use the Select Dirty option to update only scenes identified as potentially changed. While performing an Update Values on all scenes might take longer, it's advisable to do this periodically for greater precision.

To request the update, press the Check Errors button to see if there are any issues. If everything is clear, the Update Values button will become available to start the process. Any identified errors will appear in this window; simply resolve the issues and request a new.

Common Errors

Common Erros

To avoid or correct errors, pay attention to the following usage rules:

Select at least one scene to perform the update.
The Category Data must have at least one registered category.
There shouldn't be two activities registered with the same name in Interaction Datas.
There shouldn't be levels with the same name in Scene Datas.
There shouldn't be two zones with the same name in the same Scene Data.
There shouldn't be null references in the scene references of Scene Datas.

How Update Values Works

During the update, the selected scenes will open, and all Interaction Objects within them will be counted, considering customized values.

Relevant information for the analyses of that level will be recorded in the Scene Data of the level, while global information will be registered in the Persistente Data.

Therefore, when you open the Levels Breakdown Windows, all reports will be based on this content.

If you're using an external version control system, make sure to commit both the Scene Datas and the PersistenteData to keep the latest information saved.

Dirty Scenes

Dirty Scenes are those with Scene Data that the tool has identified as having changes since the last Update Values.

Scene Datas are marked as dirty when created or when an alteration occurs in an Interaction Object.

Additionally, if an Interaction Data is changed, all associated Scene Datas will be marked as dirty.

Some changes, such as deleting an object with an Interaction Object, might not be detected by the system.

Game Progression

The Game Progression tab provides insights into the overall game progression. Here, you have access to various progression graphs and global estimates for the game and each level. Available graphs include:

Estimated Total Difficulty Chart

Line graph showing estimated difficulty values for each level, highlighting the lowest, highest, and average difficulty.

Estimated Total Time Chart

Line graph displaying estimated durations for each level, including average duration and total game duration estimate.

Estimated XP Gain Chart

Line graph depicting estimated XP values for each level.

Estimated Total Accumulated XP Chart

Line graph showing cumulative estimated XP values for each level.

Estimated Total Currency Gain Chart

Line graph showing estimated currency values for each level.

Estimated Total Accumulated Currency Chart

Line graph representing cumulative estimated currency values.

Below the graphs, you'll find a list of the levels in the Scene List and the number of registered levels.

Each line displays the estimated values for that level along with quick access buttons:

Open the Scene Data of the level in the inspector.
Open the referenced scenes of the level.
Open the documentation link for the level in the browser (if referenced).

Game Breakdown

The Game Breakdown tab lists all registered activities with Interaction Datas organized by category, allowing you to view individual information and averages based on each category.

At the end of each line, there are two easy access buttons leading to the respective Interaction Data or documentation link. This tab is read-only for consultation purposes and assists the team in quickly locating documentation for each game activity.

Activity Overview

In the Activity Overview tab, you can access information on the distribution and usage of activities throughout the game.

This allows you to extract relevant insights, such as whether an activity is being utilized properly, locate levels that contain a specific activity, or count the average instances per level for each activity.

Activity Usage Overview

This chart enables you to compare the usage quantity of each registered activity side by side.

Category Overview

In this section, you can view activity completion values grouped by category.

Activities in Levels

Below this, there's a list of all game activities, indicating how many times they were used and in which levels. For each activity, you can see usage counts and averages per level, along with totals by category.

You can filter levels by activity using the button at the start of each activity's line, making it easy to identify which levels contain the activity.

Multiple activities can be filtered, but the filters are not cumulative; all levels with at least one of the filtered activities will appear.

You can toggle between filtered and unfiltered views using the button at the top of the list.

Player Learning

The Player Learning tab simulates the player's learning progression. This tab is especially useful for linear game projects, where the order of level encounters is predictable.

New Concepts Introduction Charts

This chart displays the number of new activities presented to the player in each level, allowing you to identify if there’s a sudden spike in new information.

Learning Curve Chart

This line chart simulates the potential learning curve of the player, showing cumulatively how many activities the player has been introduced to at each level.

Player Introduction Overview

Below the charts, you'll see detailed relationships between all activities and levels, showing how many and which activities are first introduced in each level, divided by categories.

Each level column also contains easy access buttons for the Scene Data, scenes, or documentation links (if available).

Levels Breakdown

In the Levels Breakdown tab, you can view detailed information about each level.

When you select a level from the dropdown or use navigation buttons, analyses and information extracted from the level's Scene Data are displayed.

Initially, you’ll see the level number and a summary of estimates, separated by zones (if applicable).

Below these values, the total sum is presented with an icon indicating whether it's above, below, or average compared to other levels.

Level Activities Resume

This section provides a general overview of all activities used in the level, categorized with usage counts and the estimates they generate.

Each row has a button to open the scene and the Interaction Object Finder for the corresponding activity, facilitating the location of listed activities.

Level Activities Detailed

Level Activites Detalied

If the level is divided into zones, this section lists each zone along with associated activities and estimates, enabling the identification of activities responsible for the presented results.

Remove Interaction Object Component

Within the menu

Tools > Zero Tools > Level Breakdown > Remove Interaction Object Components

you’ll find the option to remove all Interaction Object components from your project.

This will scan all scenes and prefabs, removing the component from all.

This procedure should be used only when necessary, as it may take a long time depending on the project's file quantity.

It cannot be undone without an external version control system.

Quick Access Buttons

Quick Acees Buttons

Quick access buttons allow you to:

Open the Scene Data of the level.
Open the referenced scenes of the level.
Open the link to the documentation (if available).

Draw Charts

By acquiring the Level Breakdown, you also gain free access to all functionalities of Draw Charts, a script that allows you to easily create custom charts in editor windows, enabling the development of other analysis tools like Level Breakdown.

Details about this tool can be found in the documentation within the Assets/Draw Charts folder.