XP and Levels

👍

Reminder - Keep Daily Backups

When working on a strategy game with a kit as big as the Complete Kit - always keep a working daily backup! Save yourself the trouble of rolling-back changes and losing work.

❗️

Evolution.XML is not working at the moment.

A codebase refactor is needed to incorporate this feature.

Levels HUD screenshot. Click to view closer.

What is XP?

XP (also known as Experience Points) are what most games use to track player progress in addition to unlocking higher levels. In the City Building Complete Kit you can use levels to limit the number of structures your players can build of a certain type, like caps on total gold mines or defense structures: two cannons max at level 1, three cannons max at level 2, five cannons max at level 3 and so on...

For unrestricted building limits, test at Level 11

Open the Stats GameManager and set the Level to 11 as seen in the screenshot below when testing to access the unrestricted developer test level. You can build 100 of each building on this level, earlier sample levels 0-10 have limits restrictions for the number of certain buildings you can build until you increase your level.

Why do we do this? This way you have examples for how to do this in the kit, but also an easy way to test your game without restrictions. Make sure to remove Level 11 from the Stats before you release your game unless you really want 100 structure limits.

Level 11, the debugging demo level for developers. Click to view larger.

Where do we edit XP Levels?

Open Assets/CityBuildingKit/Resources/Assets/BuildingsCategory.asset to see the data for XP levels for economy buildings.

BuildingsCategory.asset

All the level data is stored in the ScriptableObject files for every unit (MilitaryCategory.asset, BuildingsCategory.asset, WeaponCategory.asset, etc), located at Assets/CityBuildingKit/Resources/Assets/

Look at this example below for a WizardAcademy (MilitaryCategory.asset)

The data is taken by Stats.cs script (UpdateBuildingData()) :

C#

//Excerpt of UpdateBuildinData()	
	foreach (var lvl in ShopData.Instance.MilitaryCategoryData.category)
		{
			foreach (MilitaryCategory militaryCategory in lvl.levels)
			{
				if (militaryCategory.level == 1)//At the moment it is forced to take always the same value (level 1 value)...	
				{
					maxBuildingsAllowed.Add(militaryCategory.MaxCountOfThisItem);	
				}
			}
		}

There are 4 elements of your game you can limit the maximum number per level:

Level Max Objects
Buildings - for example one gold mine for level 1, three for level 2, five for level 3, and so on ....
Weapons - for example two cannons max at level 1, three cannons max at level 2, five cannons max at level 3 and so on...
Walls - for example ten wood walls max at level 1, twenty wood walls max at level 2, thirty wood walls and ten stone walls max at level 3, and so on...
Decorations - however you design, could follow the same as buildings. Decorations are not attacked in battle and you can charge whatever currency for them (even in-app purchase gems)

How are level limitations used in the store?

These XP level limitations are used by the UpdateLabelStats() function in the Scripts/Creators/BaseCreator.cs script. This function changes the labels in the store depending on different problems, such as not enough currency or in this case - your current level restricts the building limit and you've reached that limit. (DEPRECATED - UNUSED FUNCTION)

In the below images from the store, you can see in the first example image we can still build the item in the store as we have build 0/2 of the gold forge. The button and store item looks normal.

Can still purchase gold forges, level limit not yet reached.

However in the second example, the text in the store item shows 2/2 in the corner, which means for our current level we can only have a maximum of 2 gold forges and we've already created these. The store item turns grey and the button text black. (DEPRECATED - UNUSED FUNCTION)

Clicking the button returns an error that your XP level needs to be higher (read the next section below for how to award XP points to your player - we already have setup a few examples like training units, building other structures, or removing trees and objects on the map)

Level limit reached (2/2 gold forges), the store item turns grey and cannot be purchased.(DEPRECATED - UNUSED FUNCTION)

How to award XP points to your players

There are a few different scripts. Search for XPAward or experience in the Scripts folder to locate the references in scripts. There are a few references to the XPAward element in each of the ScriptableObject files (Assets/CityBuildingKit/Resources/Assets/).

Gain XP Points creating Buildings, Weapons, Walls

the ScriptableObject files (Assets/CityBuildingKit/Resources/Assets/) -- these all include an element which you can use to award players with a certain amount of XP when they create their buildings.

For example, creating a gold vault mine gives the player 100 XP each time.

For example, in Walls.xml, building one stone corner tower gives the player 2 XP per segment.

Gain XP Points Training Units

Players can also get XP points training units. If you don't want to offer this, change the value to 0.

For example, creating an archer gives the player 100 XP.

Gain XP Points from Removing Terrain Objects

Also, your game players can get XP by removing terrain objects. Like all the other SO files, we make this easy to change.

Visual example of gaining 2 XP from removing a random terrain object called ClamC. Click to view larger.

For example, in Removables.xml (XML/Removables.xml), removing one of the random TreeA objects awards the player 2 XP.

XML

<Removable>
		<Name>TreeA</Name>		
		<RemoveTime>5</RemoveTime>
		<Currency>Mana</Currency>				
		<RemovePrice>100</RemovePrice>
		<XpAward>2</XpAward>
	</Removable>

Adjust the actions Scripts/Creators/Removables/RemovableTimerSelector.cs

RemovableTimerSelector.cs

//Adds the xpAward value to the player stats.
	((Stats)stats).experience += xpAward;		

	GameObject gainExperienceIco = (GameObject)Instantiate(GainExperience);
                          				gainExperienceIco.transform.SetParent(GameObject.Find("GroupEffects").transform;
    gainExperienceIco.transform.position = transform.position;
    gainExperienceIco.GetComponent<FadeOutGain> ().SetValue (xpAward);

Setting a Starting Level for Testing

Open the Game scene and in the hierarchy, select Game Manager > Stats. On the right side inspector you can change the Level from 1 (default) to any number. Save and play the scene.

Select Stats. Click to view larger.

Edit the starting level and experience. Click to view larger.

How is XP updated in the menu bar?

Look for UpdateUI in Scripts/Menus/Stats.cs. This adjusts the UISlider value for the experience, sets the Player name (right now just a placeholder) and also the current level plus text values for the experience.

Stats.cs

public void UpdateUI()//updates numbers and progress bars
	{

		PlayerData data = Player.Instance.GetPlayer();
		data.PlayerName = "Player Name";
		data.LevelData.Level = level;
		data.ExperienceData.CurrentExp = experience;

		data.PlayerResources.Dobbit.Type = GameResourceType.Dobbit;
		data.PlayerResources.Dobbit.CurrentValue = occupiedDobbits;
		data.PlayerResources.Dobbit.MaxValue = dobbits;
		
		data.PlayerResources.Housing.Type = GameResourceType.Housing;
		data.PlayerResources.Housing.CurrentValue = occupiedHousing;
		data.PlayerResources.Housing.MaxValue = maxHousing;
		
		data.PlayerResources.Gold.Type = GameResourceType.Gold;
		data.PlayerResources.Gold.CurrentValue = gold;
		data.PlayerResources.Gold.MaxValue = maxGold;
		
		data.PlayerResources.Mana.Type = GameResourceType.Mana;
		data.PlayerResources.Mana.CurrentValue = mana;
		data.PlayerResources.Mana.MaxValue = maxMana;
		
		data.PlayerResources.Crystal.Type = GameResourceType.Crystal;
		data.PlayerResources.Crystal.CurrentValue = crystals;
		data.PlayerResources.Crystal.MaxValue = maxCrystals;

		data.CloakData.RemainingCloakTime = remainingCloakTime;
		data.CloakData.PurchasedCloakTime = purchasedCloakTime;
		
		
		Player.Instance.PlayerEvt.Invoke(data);
	}

📘

Remember to call ((Stats)stats).UpdateUI(); when done updating any stats

The kit is optimized so that UI updates are not made without purpose. If you ever update the stats in any of your scripting - make sure to add ((Stats)stats).UpdateUI(); at the end to make sure your changes are visible.

How is player XP saved and loaded when the game closes?

Like other player stats - XP is saved and loaded from Player data in the Scripts/Save files. By default, this is manual in the game settings panel until you activate automatic savings (see documentation page in Game Settings section)