Partitions

Partitions is a puppeteer term for the runtime files. These files that are generated by the Asset Manager by compiling assets. They are containing the minimum asset data. Minimum means that all unnecessary information like asset names, tool tips, etc have been stripped. The game loads and unloads them using Puppeteer Runtime library.

Partitions can be created in the Asset Manager. Users can assign their assets to a different partitions to put them to the different runtime files. The rules for the partitions are:

1. Partitions can depend on each other. The dependencies are acyclic. Basically Puppeteer shows partitions in a form of a tree. For example:

Here the Scenes 1, 2 and 3 depend on the Base. Which means, the partition Scene 1 can't be loaded into the game before the Base is loaded. The game can work like this:

• User starts the game. It loads all the assets from the Base.
• User enters the first scene. The game loads the Scene 1.
• User leaves the first scene and enters the second. The game unloads the Scene 1 and loads the Scene 2.
• User leaves the second scene. The game unloads the Scene 2.
• User leaves the game. The game unloads the Base.
  

The depth of the tree is not limited. There might be sub-scenes and sub-sub-scenes. As many as needed to use memory most efficiently.

The assets from Scene 1 can reference the assets from the Base, but they can not reference assets from the Scene 2. Because there is no guarantee Scene 2 is loaded when the Scene 1 assets are trying to use the reference. There is a guarantee that the Base is loaded though.

For the same reasons the Base assets can not use any assets from any Scenes. Puppeteer Asset Manager always enforces these rules. It just denies creating the references that violate them.

2. Every asset can be assigned to only one or zero partitions. When an asset has no partition, it inherits the partition from the container it belongs to. If the container doesn't have it, it inherits it from the upper level container. Etc, etc. The root container is always assigned to a partition.

Why does the Asset Manager not allow assigning an asset to many partitions? Because of the complexity. The rules become too hard to maintain. What if user is trying to assign an asset to the Base and to the Scene 1 at the same time? Assets from Base are allowed to use this asset because it is a member of Base, but they can not use it because it is a member of the Scene 1. At the same time the asset can use other assets from the Scene 1 because it is a member of the Scene 1, but it can not use them because it is a member of the Base.

I decided to make it simple. An asset can be assigned to only one partition. However, there are exceptions.

3. There is a special partition - Free Partition. If an asset is assigned to a Free Partition, the Asset Manager puts it to every partition that references this asset. Thus such assets can get to more than one partitions.

Let me illustrate the usage of the Free Partition with an example:

Suppose you have a fantasy game. The main character is a hero who fights orcs, trolls and goblins. The Scene 1 is populated by the orcs; Scene 2 - by the goblins; Scene 3 - by the trolls.

You have the next skeletons:

• Hero Skeleton.
• Orc Skeleton.
• Goblin Skeleton.
• Troll Skeleton

You also have the next animations:

• Walk
• Run
• Jump
  
• Hit
• Shoot
  
• Block a hit
• Block a shot
  
• Dodge a hit
• Dodge a shot
  

Suppose your hero can walk, run, hit, block a hit and block a shot. The hero is needed in all three scenese, so the hero assets should be placed to the Base partition. The Base contains:

• Hero Skeleton.
• Walk
• Run
• Hit
• Block a hit
• Block a shot

The orks can walk, run, hit, dodge a hit and dodge a shot. Walk, Run and Hit are already in the Base. The Base is always loaded when the Scene 1 is loaded, so there is no need to put them to the Scene 1:

• Orc Skeleton
• Dodge a hit.
• Dodge a shot.
• Scene1 Asset. Don't mix up with the partition Scene 1. This is an asset that references all the assets used in the scene. It organizes them to work together.

The goblins can walk, jump, shoot and dodge a hit. That makes the Scene 2:

• Goblin Skeleton
• Shoot
• Dodge a hit
• Dodge a shot
• Jump
  
• Scene 2 Asset
  

Wait a second. "Dodge a hit" has been already assigned to the Scene 2. An asset can be assigned to only one partition. A possible solution is to assign it to the Base. It solves the problem . Now both Scene 2 and Scene 1 can use it. But what if trolls can not dodge a hit?

This means that the animation "Dodge a hit" is not used by any other asset in the Scene 3, but it is still loaded into the memory. The right solution is to put it to the Free Partition. In this case the Asset Manager finds that Scene1 Asset and Scene2 Asset are both referencing "Dodge a hit", and it puts it to the Scene 1 and the Scene 2 partitions. The Base and the Scene 3 do not have any assets that reference "Dodge a hit", so it is not included.

The trolls can walk, run, jump, dodge a shot, block a hit and hit:

• Troll Skeleton
• Dodge a shot
• Jump
  
• Scene3 Asset
  

Note that all three scenes are using "Dodge a shot" animation. If we put it to the Free Partition, the Asset Manager puts it to all three Scene partitions. This is not good because this animation is unloaded and loaded every time the hero changes scenes. Unfortunately the current version of Puppeteer is not smart enough to move it to the Base. It is in my plans but there are many tasks with a higher priority. Thus we need to move Dodge a shot to the Base manually.

The final asset assignments are:

• Hero Skeleton - Base.
  
• Orc Skeleton - Scene 1.
  
• Goblin Skeleton - Scene 2.
  
• Troll Skeleton - Scene 3.
  
• Walk - Base.
  
• Run - Base.
  
• Jump - Free.
  
• Hit - Base.
  
• Shoot - Scene 2.
  
• Block a hit - Base.
  
• Block a shot - Base.
  
• Dodge a hit - Free.
  
• Dodge a shot - Base.
  
• Scene1 - Scene 1.
  
• Scene2 - Scene 2.
  
• Scene3 - Scene 3.

Basically you can simplify it by putting all assets except the Scene Assets to the Free Partition, and let the Asset Manager create all the right partitions using asset dependencies. But as I already mentioned, the current version does not distribute them in the most optimal way.