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.

What is Puppeteer (continued)

The main idea of Puppeteer is to create a simple tool for making games.

Create a few clips using MB or Blender; import them to Puppeteer; assign them to different characters; set up the transitions from one animation to another; attach keyboard/mouse/controller events to these transitions; and you are set.

Now you can load your assets to the testbed and play. The AI and animation are fully described by Puppeteer assets.

The process should be as simple as possible. At the same time Puppeteer should be able to handle a large number of assets and large memory amounts. It should not cause any problems when the project is growing.

That's the general requirements. At the same time I want to mention what Puppeteer is not:
1. Puppeteer is not an animation or skeleton editor. Blender, Maya, or MB do it better.
2. Puppeteer doesn't do skinning and rendering. That might change in the future releases, but I don't see it coming soon.

What is Puppeteer

As I mentioned before, the Puppeteer is an animation engine for video games. But not only the engine. It also has a visual pluginable tool for combining and blending animations, customizing transitions, editing scenes, and many more.

Puppeteer consists of 3 main parts: Puppeteer Asset Manager (PAM), Puppeteer Runtime (PR) and Puppeteer Modules (PM). The animation engine is implemented as a Puppeteer Module.

Puppeteer Asset Manager

What is asset management? Let's start by defining what the asset is. An asset is a program data resource that:
1. Is unavoidably required for a normal application run.
2. Never changes during the application lifetime.

The examples of assets are:
1. Config files.
2. Icons and dialog layouts.
3. Meshes and animations in video games.

the best known and the simplest Asset Management software is the Visual Studio resource editor. However, when it comes to video games the assets can be quite big to be linked to the game executable or dll. They are normally shipped as separate files, and the game loads and unloads them as required.

Ideally, an asset manager software should:
1. Allow grouping assets for an easy visual navigation.
2. Provide a simple way to edit assets of different types.
3. Provide a 3-d preview for assets that can be previewed in a 3-d space. For example, meshes, skeletons and 3-d animations.
4. Maintain assets relationships including referencial integrity and constrains.
5. Be extendable. It should provide a clear plugin API for creating new asset types on top of the existing ones. For example creating an asset that references two or more animations and blends them together using different weights. Or an asset that references a number of animations and plays them in a sequence.
6. Provide assets grouping and packaging into the runtime files, which are the asset packages loaded by an actual game.

There is a number of asset management engines for video games on the market. However I am not aware of any good open source asset managers. Collada Asset Manager has announced plans to go open source. But it's not there yet. There are some additional reasons why I think Puppeteer is better than than Collada's product, but I would rather not go into the details just yet.

Puppeteer Runtime

The PR is a static C++ library. As I have mentioned already PAM packs assets into the runtime files, and the PR provides API for loading/unloading these files. It also provides an interface for Puppeteer Plugins for instantiating assets.

Once a game loads a puppeteer runtime file, it can create assets using asset IDs provided by PAM. Puppeteer runtime doesn't make any assumptions of how these assets are used. It's up to the modules to provide the code that uses the data. All PR is doing is loading/unloading and making sure the assets are correctly delivered from the PAM.

Puppeteer Modules

Every Puppeteer Module consists of two parts:
1. A dot net DLL to be used with the PAM.
2. A static C++ lib file to be linked into the game.

Both libraries implement the same assets. The standard Puppeteer package comes with two modules:
1. Animation Core Module.
2. Animation Standard Module.

I also have plans for adding Rendering Core Module. But not in the first release.

Animation Core Module implements the following assets:
1. ChannelsAsset. Defines a set of animatable channels. Every channel has a type, which is either: float, weight, translation, scale, rotation, rotation-translation, or scale-rotation-translation.
2. SkeletonAsset. Defines a skeleton hierarchy and attaches every joint to one of the channels of the ChannelsAsset. It references ChannelsAsset for it.
3. AnimationAsset. A set of key-frames that animate a subset of channels from the ChannelsAsset. Note that Animation doesn't reference Skeleton. They both reference Channels instead. So Animation can animate different Skeletons as long as they belong to the same Channels.
4. ControllerAsset. A base class for all animation controllers. AnimationAsset is the only controller in this package. Standard Puppeteer Plugins will be focusing on implementing controllers.
5. CharacterAsset. Represents a game character. It bounds Skeleton and a set of Meshes with a static scaling array. (The Meshes will not be implemented in the first release, so currently it only bounds skeleton with scaling).
6. TransformationAsset. I don't know mush about this asset yet ;) I didn't implement is yet. May be I will change the name later on, the "transformation" is too long. Anyway, this is a base class for transformation assets.
The runtime calls them after controllers do their job. Transformation assets correct the pose before sending it to the rendering part of a game. Possible implementations are: HumanIkTransformation, FootPlantingTransformation, PhysicsTransformation. And more specific transformations like head tracking, setting emotions/attitude, etc. None of these will be implemented in the first release. But they all are on the to-do list.
7. SceneAsset. A set of character assets with initial positions. It also attaches an initial animation controller to every character. And sets Transformations.

Animation Standard Module currently implements only one asset - the BlendController. It blends a number of animations together. Animators can set a synchronization points for every animation, and the BlendController makes sure all animations reach this point at the same time.

For example animator may want to blend fast running character with a slower running character. The problem is that the steps in two animations are usually not synchronized. So animators may set a sync point when the foots touch the ground. And the controller will slow down or speed up certain animations to make sure they reach these frames at the same time.

Additional controllers I'm planning to add to the Standard Plugins in the nearest future are: BlendArray, BlendSpace and Locomotion. They all will be wrapping BlendController.

Current Status

1. Asset Manager - completed. I am working on optimizations and stress testing.
2. Runtime - almost completed. Everything is implemented but not tested yet.
3. Modules - under development. Channels, Skeleton and Animation are done. I'm working on a Controller, Character and Scene.