(Note that this information is in reference to PushButton Engine build r625.)

The key takeaway here is that for a component to be tickable, it must implement the ITickedObject interface and then tell the ProcessManager to start and stop calling onTick() every tick.

Oh, there’s one other key takeaway here: how to use PropertyReferences. You get a property of a component by way of the owning entity. You create a PropertyReference instance for each data member that you need to access. In this example, we’re accessing the rotation field on the SpriteRenderer component we added in Angry Explanations #1.

In a bit more detail, the PropertyReference is constructed with a special string: "@Sprite.rotation" (see line 11 in the code below). That means, this is a reference to the component of this entity with the name “Sprite” (recall that we gave it that name when we created the SpriteRenderer component instance), and the field “rotation” of the SpriteRenderer class. It’s quite simple once you realize what it’s doing (but I’m no less angry, mind you!).

I thought that a SpatialComponent might be necessary to alter the sprite’s position, but apparently that component has been removed (since r470, which is the current packaged release). That data seems to now be handled by the renderer component itself.

Add this one line to the end of showLogo() from the previous example:

spriteEntity.addComponent( new SpinController(), "spinner" );

Then add the following new class in a sub-folder (components/controllers/).

package com.yourcompany.yourgame.components.controllers
{
	import com.pblabs.engine.core.ITickedObject;
	import com.pblabs.engine.core.ProcessManager;
	import com.pblabs.engine.entity.EntityComponent;
	import com.pblabs.engine.entity.PropertyReference;

	public class SpinController extends EntityComponent implements ITickedObject
	{
		// Cache the PropertyReference instance here to avoid a bunch of temporary allocations.
		private var _rotProp:PropertyReference = new PropertyReference( "@Sprite.rotation" );

		// Nothing to do in the constructor because this is such a simple example.
		public function SpinController()
		{
			super();
		}

		// When the component is added to the sprite entity, we want to register to
		// get tick updates by the ProcessManager.
		protected override function onAdd():void
		{
			super.onAdd();

			ProcessManager.instance.addTickedObject( this );
		}

		// When the component is removed from the sprite entity, we want to unregister
		// from the ProcessManager so tick updates will stop.
		protected override function onRemove():void
		{
			super.onRemove();

			ProcessManager.instance.removeTickedObject( this );
		}

		// Each tick, we just change the rotation of the sprite renderer a little bit.
		public function onTick(tickRate:Number):void
		{
			// Get the current rotation.
			var rotation:Number = owner.getProperty( _rotProp ) as Number;

			// Add 1 degree to it.
			rotation += 1;

			// Store the new rotation back in the sprite.
			owner.setProperty( _rotProp, rotation );
		}
	}
}

As an addendum, I should point out that the rotation will probably not be smooth. To fix that, you should have the SpinController implement IAnimatedObject instead of ITickedObject. The registration with the ProcessManager is the same, except you call addAnimatedObject() instead of addTickedObject().

The difference is that IAnimatedObject will update when Flash draws a frame instead of when the ProcessManager ticks, and the motion will appear a lot smoother.

And you’ll want to normalize the rotation based on delta time since the last frame. Er, like this:

public function onFrame( elapsed:Number ):void
{
	var rotation:Number = owner.getProperty( _rotProp ) as Number;

	// Rotate 15 degrees per second, nice and slow.
	rotation += 15 * elapsed;

	owner.setProperty( _rotProp, rotation );
}

So, yeah, I got started with PBE at a bad time, I think.

It’s in transition between some major changes, and so all the docs and tutorials to this point are out of sync and kind of very… confusing. Because of that, I really struggled to figure this out, and in fact couldn’t get an image on the screen without professional help (I’ll let you interpret that however you’d like).

This information is relevant for PBE r625 and up.

(This isn’t to say the engine is poorly designed–it’s simply not accurately documented in places because it has been changing so quickly. And to be fair, it’s still in beta. I wouldn’t use the engine if I didn’t think it was great.)

A frustrated noob’s guide to getting a freakin’ image on the dang screen using Flex 3

Here’s the MXML which will reference the code.

<?xml version="1.0" encoding="utf-8"?>
<game:Game
	xmlns:mx="http://www.adobe.com/2006/mxml"
	xmlns:game="com.yourcompany.yourgame.*"
	width="750"
	height="600"
	layout="absolute">

</game:Game>

Now define a resource in a ResourceBundle subclass, which is the image you want to display, and let PBE automagically make it accessible through the resource manager.

package com.yourcompany.yourgame
{
	import com.pblabs.engine.resource.ResourceBundle;

	public class EmbeddedResources extends ResourceBundle
	{
		// The path is magically also the name of the resource.
		[Embed(source="../assets/images/logo.png", mimeType="application/octet-stream")]
		public var logoImage:Class;
	}
}

Put that image into action! It’s a simple notion, but somewhat complicated if you’re new to the engine and its gooey innards.

package com.yourcompany.yourgame
{
	import com.pblabs.engine.PBE;
	import com.pblabs.engine.entity.IEntity;
	import com.pblabs.engine.resource.ImageResource;
	import com.pblabs.engine.resource.ResourceManager;
	import com.pblabs.rendering2D.DisplayObjectScene;
	import com.pblabs.rendering2D.SpriteRenderer;
	import com.pblabs.rendering2D.ui.FlexSceneView;

	import mx.containers.Canvas;
	import mx.core.Application;
	import mx.events.FlexEvent;

	public class Game extends Application
	{
		public var resources:EmbeddedResources;

		// We need access to this in a couple of functions.
		private var _scene:DisplayObjectScene;

		public function Game()
		{
			super();

			// Let the Flex Application initialize fully before we muck with it.
			addEventListener( FlexEvent.APPLICATION_COMPLETE, onStartup );
		}

		// This is called once the Flex app (stage, in particular) is initialized.
		private function onStartup( e:FlexEvent ) : void
		{
			// Load our embedded resources (the image to show).
			resources = new EmbeddedResources();

			// Tell PBE to initialize and pass it our instance so it can get the stage.
			// (Remember, Application is a subclass of Sprite, which PBE needs.)
			PBE.startup( this );

			createPbeScene();

			showLogo();
		}

		private function createPbeScene():void
		{
			// Create a new IEntity for the scene view.
			var sceneEntity:IEntity = PBE.allocateEntity();
			sceneEntity.initialize( "sceneEntity" );

			_scene = new DisplayObjectScene();

			// Since this is Flex, we need the appropriate scene view class.
			var sceneView:FlexSceneView = new FlexSceneView();

			// Set up the view size.
			sceneView.width = 750;
			sceneView.height = 600;

			// FREAKIN' IMPORTANT: add the view as a child to our display list!
			this.addChild( sceneView );

			// Connect the view to the display object scene (a component).
			_scene.sceneView = sceneView;

			// Add the display object scene to the scene entity.
			sceneEntity.addComponent( _scene, "renderer" );
		}

		private function showLogo():void
		{
			// Create a new IEntity instance for the sprite to be displayed.
			var spriteEntity:IEntity = PBE.allocateEntity();
			spriteEntity.initialize( "logoEntity" );

			// Add a sprite rendering component.
			var sprite:SpriteRenderer = new SpriteRenderer();

			// Tell the renderer to draw (and load) this image resource.
			sprite.fileName = "../assets/images/logo.png";

			// Tell the renderer to draw to the display object scene.
			sprite.scene = _scene;

			// Add the component to the sprite entity.
			spriteEntity.addComponent( sprite, "sprite" );
		}
	}
}

So, what the heck just happened? Pfft! Don’t ask me! I’m still a freakin’ noob!

I know a couple of things, though. The SceneView is like a “canvas” where all DisplayObjectRenderers are drawn. So you create entities and fill them with components (like a SpriteRenderer) and tell the renderer component about the scene view. Magically, the sprite appears! It’s not too much to understand if you just want to know the API and how to use it.

To really understand it, you’ll need to look under the hood and figure out the connections. A good bit of hidden work is being done to simplify the API, but possibly at the expense of understanding. It’s neither good nor bad. It’s just The Way of PBE (for now).

Feel free to post here to help fill my gaps in comprehension. I haven’t used the engine enough to write a thorough explanation, and I’m not too proud to accept help.