Shiki

Important: This tutorial is now deprecated due to the new and awesome, fully rewritten, rendering components. You can see some discussions about it here.

I’ve been working with PushButton Engine for a short while now but last night was actually the first time I tried integrating/using a MovieClip from a SWF into PBE. Unfortunately, there are no documentations on how do this at the moment. The examples mostly use images (pngs). I won’t btch about it because that is totally understandable. The PBE team are working their a*es off to get to 1.0 and the documentation is the least of their worries. I could at least thank them for doing such a good job — PBE’s a well thought-out framework, everything I learned from it made a lot of sense.

Anyway, what I wanted to do was simply to put my MovieClip in a SWF library into the stage. I am using FlexBuilder 3 + the latest PBE code from the SVN. I somehow got some ideas on how to do this when I was hanging out at the #pbengine IRC channel. And I did a lot of digging on the PBE code and did lots of experiments to try to understand how to use them. There are 2 different components we can use:

• com.pblabs.rendering2D.SWFSpriteSheetComponent. This one actually had a class description: “A class that is similar to the SpriteSheetComponent except the frames are loaded by rasterizing a MovieClip rather than a single image”. Assuming you’ve gone through the PBE examples, I think this means that instead of creating the frames from a sprite sheet image and have it used by SpriteRenderComponent, you’ll be getting your frames from a loaded MovieClip instead. Nevertheless, this isn’t what I was aiming for.
• com.pblabs.rendering2D.SWFRenderComponent. This component somehow works like SpriteRenderComponent, only it uses MovieClips. A little code investigation later, looks like this component will need to be subclassed in order for it to work. From that subclass, you can do what you want to do with your movieclip using a protected _clip variable.

Since I still wanted control over a movieclip, I used SWFRenderComponent. I’ll explain below how I did it. Please do note that I am still a novice with PBE (and Flex for that matter) so the method I used might not be good practice.

Requirements

• Latest PBE code. You can get it from the SVN here or download here. As of this writing, I’m at revision 470 (Sep 10, 2009)
• SWF. I have a compiled SWF containing exported assets (movieclip classes) that I want to use in PBE.
• Flex compiler / IDE / or whatever your preferred tool is. I’m using FlexBuilder + Flex Compiler.
• A PBE Project. Our team used the PBEngineDemo project as the base project.

Embed the SWF

In Resources.as, embed the SWF using the same method as the sample embedded resources in the PBEngineDemo project.

[Embed(source='../assets/gamemovieclips.swf', mimeType='application/octet-stream')]
public var _embeddedSWF:Class;

I thought that the above would be enough just like embedding images. However, I was getting this warning from the log:

WARN: Resources - ResourceBundle - No resource type specified for extension '.swf'.  In the ExtensionTypes parameter, expected to see something like: ResourceBundle.ExtensionTypes.mycustomext = "com.mydomain.customresource" where mycustomext is the (lower-case) extension, and "com.mydomain.customresource" is a string of the fully qualified resource class name.  Defaulting to generic DataResource.

This resulted to the gamemovieclips.swf not getting embedded in the final swf. I tried to look at the problem in ResourceBundle.as, and somehow, adding this to Resources.as fixed it:

public class Resources extends ResourceBundle
{
  ResourceBundle.ExtensionTypes.swf = "com.pblabs.engine.resource.SWFResource"; // added this line

  [Embed(source='../assets/gamemovieclips.swf', mimeType='application/octet-stream')]
  public var _embeddedSWF:Class; // our embedded swf

  // other embed files below
  ...

Subclass SWFRenderComponent

Next, I created a new class which inherits SWFRenderComponent and overrides the getClipInstance() method. For this example, let’s say in my embedded swf (gamemovieclips.swf in the example above) I have a car animation movieclip exported as CarMC. I will then need to have getClipInstance() return an instance of that movieclip. My class would then look like this:

package com.game.renders
{
    import com.pblabs.engine.resource.Resource;
    import com.pblabs.engine.resource.ResourceManager;
    import com.pblabs.engine.resource.SWFResource;
    import com.pblabs.rendering2D.SWFRenderComponent;

    import flash.display.MovieClip;

    public class CarRenderComponent extends SWFRenderComponent
    {
        public function CarRenderComponent()
        {
            super();
        }

        // override getClipInstance() and return a CarMC movieclip instance
        protected override function getClipInstance():MovieClip
        {
            // check if we are currently loading the movieclip or a CarMC instance was already loaded
            if (_clipInstance == null && !_loading) {

                _loading = true;
                // load CarMC from gamemovieclips.swf using PBE's ResourceManager
                //I'm also passing an anonymous function which gets called if gamemovieclips.swf is loaded
                ResourceManager.instance.load("../assets/gamemovieclips.swf", SWFResource, function(resource:Resource):void {
                    // reaching this part of the code means that gamemovieclips.swf was loaded
                    // we will then get an instance of CarMC by calling getExportedAsset below
                    _clipInstance = (resource as SWFResource).getExportedAsset("CarMC") as MovieClip;

                    if (_clipInstance) { // check if the class was actually loaded
                        // if it was loaded, you can now do whatever you want with it

                        // for example, I have a child movieclip in CarMC with instance name "wheel" and I want it stopped initially
                        _wheel = _clipInstance.getChildByName("wheel") as MovieClip;
                        _wheel.stop();
                    }

                    _loading = false;
                });

            }

            // return our CarMC instance that will be rendered to the scene/stage
            return _clipInstance;
        }

        private var _loading:Boolean = false; // set to true if we are currently loading a movieclip
        private var _clipInstance:MovieClip = null; // will temporarily hold the loaded movieclip
        private var _wheel:MovieClip = null;
    }
}

A problem with this method is that I’m using ResourceManager to load the swf and then the movieclip. This means that loading the movieclip is not instantaneous. I did try a different method for this but somehow couldn’t get the movieclip loaded into PBE.

Add the component to the level file

Now that I have a render class (CarRenderComponent). I can add it to any entity with a spatial component. (Please see PBEngineDemo for more info on this)

<entity name="car">
    <component type="com.pblabs.box2D.Box2DSpatialComponent" name="CarSpatial">
        ....
    </component>
    <!-- our render component here -->
    <component type="com.game.renders.CarRenderComponent" name="SWFRender">
        <loop>true</loop> <!-- set to TRUE. The SWFRenderComponent will destroy the CarMC once it's done playing if this is FALSE -->
        <positionReference>@CarSpatial.position</positionReference> <!-- set the spatial's position as the movieclip's position when rendering -->
        <scaleFactor>0.3</scaleFactor> <!-- you can resize/scale your MC using this -->
        <screenOffset> <!-- or you can offset it's render position from the @CarSpatial.position -->
            <x>0</x>
            <y>20</y>
        </screenOffset>
    </component>
</entity>

One thing I noticed was the properties <sizeReference> and <rotationReference> didn’t seem to have any effect on the render. I’ll have look at that another time. Maybe I’m just missing something.

That’s it. I was happy enough to see the movieclip embedded, rendered and animated on the scene. Hopefully, this will be of help to someone.