Clients Login
Search tips and advanced search
Lets Socialize
Hybrid Mindset on Twitter  Hybrid Mindset on LinkedIn  Hybrid Mindset on Facebook  Hybrid Mindset RSS Feed 
Unlock The Possibilities, Call 602.456.0433
Blog Page Heading
Featured Blog

My PushButton Engine Experience Week 3...7

Serialization, Serialization...

Posted Date: 2010-08-24   Posted Time: 01:24:59
Print Blog PostPrint  Tweet Blog PostTweet This Comment On Blog PostComment 

Blog Posts

View All

My PushButton Engine Experience Week 3...7

Created: Tuesday, August 24, 2010 @ 01:24 AM  

I've been a bit busy lately so I haven't had a lot of time to play with the engine but I've learned a few more key things that have helped my understanding of how the engine works. These concepts may evolve as the engine continues to evolve so just take this information as an overview of some PBE concepts.

Serialization & Levels

This concept alluded me a bit at first because I saw the examples of what a pbelevel file looks like and the documentation talks about how there are Entities, Template, Components, and Groups in a level file but I was not sure how that all worked with loading a level. So after poking around the and classes I've got a better understanding of how those two mechanisms work hand and hand.

The LevelManager is the class that manages all the information about a level and takes care of loading and unloading levels. The TemplateManager is used by the LevelManager and is where all the contents of the .pbelevel file will live for the life of the PBE engine as objects built from the level xml ready to be created when you need it. You can use the TemplateManager directly to load your entities and templates if you would like.

The Contents of the PBELevel File

So the .pbelevel file is the core location of where pretty much all of the serialized xml information about specific entities and components live. It is pretty much an xml file but I name my level files '.pbelevel'. This file is powerful in that you can declaratively specify all your entities and their children components, you can specify groups to be created at once, you can create a template for an object , and you can build templates off of other ones. A Template is pretty much an entity but it is meant for cloning/replication and therefore it can be instantiated multiple times using the same template name, or explicitly used as the template attribute reference on an entity declaration. So preferably each level of your game should have its own .pbelevel file. You can see the specific structure of the file and read more here. One thing to note also is that your entities will not be instantiated if they are not placed in a group in the level file.

PBE Levels & the LevelManager

The LevelManager in PBE is used to keep your levels organized and is able to be referenced using a level number, like level 1, 2, 3, etc. The LevelManager is used to declare which .pbelevel file(s) belongs to which level and which groups should be instantiated on a specific level. So if I have one level and I want three groups of entities created for that level I would write something like such in as3:

// Add file and group references, You can not make calls to add information to a level while it is currently loaded
LevelManager.Instance.AddFileReference(1, "/Levels/level.pbelevel");
LevelManager.Instance.AddGroupReference(1, "SpriteSheets"); //These groups should not be declared in as3 if it is already declared in the level file
LevelManager.Instance.AddGroupReference(1, "Objects");
LevelManager.Instance.AddGroupReference(1, "Everything");

// Load level 1 and start game. This will unload any current level information and load the new one. Except for shared level data.

Its that easy, and you can place a listener to find out when the level is loaded to notify the player to start playing or maybe go to a tutorial screen or something.
If you want to do the above using just an xml file and declare multiple levels in one file, then the code above would be represented in a levelsDescriptor.xml file like such:

     <level index="1" name="Level1">
          <file filename="/Levels/level.pbelevel" />
          <group name="SpriteSheets"/>
          <group name="Objects"/>
          <group name="Everything"/>

To load the above xml level descriptor file into your game you would call


The PBE Serializer, Great Class!

Another useful method is the instantiateEntityFromXML(xmlObject) on the TemplateManager, which will deserialize the xml data, load it into the TemplateManager and return an entity object with the children components instantiated and everything for you. This method uses the Serializer class which is the underlying class that PBE uses to do all of its serialization and deserialization of game objects. If you wanted to serialize an entity you could just call Serializer.Instance.serialize(entity, xml), and off to the server it can go. You can add custom serialization to your custom PBE components just by implementing the ISerializable interface on your classes. The Serializer will check for this interface when doing its thing.

This is could be useful because the Serializer class only serializes public properties on a class but you could implement ISerializable to add custom information to your serialized entity and deserialize that custom information when you want to load that entity again. This will allow you to export out specific underlying state that you want to capture and read that information back in and have your component handle restoring that snapshot state.

External Resource Manager

There was recently a forum post from a PBE community member that came up with a solution for when you want to load external resources from an external swf that gets loaded as a module into your game only when the level it is for is currently loaded. His solution allows you to have all the resources broken out and defined in different external swf files and loaded at runtime as a module. It is based on the ResourceBundle concept but modularized so it can be loaded and unloaded freeing up memory for the next level. Who doesn't like freeing up memory, I mean come on... :) You can check out the forum post here. It is essential to help download times and performance to use something like this when your game uses a lot of resources and has multiple levels.

A Few Key Points

So a key thing to know about the onReset() method on your EntityComponent is that this method is called on each component in an entity anytime something changes on the Entity level. So this is a good place to maybe do sanity checks to make sure that if you may have been referencing a component in the entity and it was removed, you may want to do some clean up work and detach that removed component reference so there are no stale references or nasty null pointer errors, or maybe do some rewiring if needed.

the editor data metadata tag is used to tell the serializer, hey don't worry about serializing this public property or setter/getter. It is useful when you have properties that contain objects that do not need to be serialized because they will be set later on once the component is created.

The typeHint metadata tag helps the serializer to identify what type of object it is serializing. So if you have an Array with objects or Points in it you can tell the Serializer by placing the package in the type hint above the setter/getter of the public property.

Isometric Editor Coming Soon....

(which will become one editor of a suite of editors eventually)

So I've been working away on an isometric editor tool to be able to make isometric style games easily using Push Button Engine. I've made quite a bit of progress and I hope to have it in private beta by the beginning of September to get feedback from the community on whether it is a useful tool to create games. This editor will turn into a platformer editor, and eventually a 3D editor for Away3D and or Papervision in the future. I can't wait to release that one! Below is a quick little sneak peak video of the editor in action check it out.

 Twitter Feed