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.

So on the left is the map view, where you see a really, really hiddeous jumble of a test map. The interesting thing there is the little heart with lips (a placeholder icon I borrowed from a casual game I made a couple years ago). That’s the entity icon, which in this case is a player spawner. That is where the player will start in this map. Yellow means that’s the selected entity, and the white square is where the cursor is (though the mouse pointer isn’t visible since pressing Print Screen doesn’t capture it).

On the right side, things are a little more fun. Those entity properties you see are generated dynamically. This is a really cool thing that I have wanted to try for a long time. The entity’s components define what is exposed and editable in the editor. The editor then builds the UI based on that. So I don’t have to add code to support editing new components; I just add the property definitions to the component, and the rest is magic. I’m hoping this will save me time in the long run. So far? It rocks.

In case it didn’t slap you in the face, the editor is an AIR application, which means I get to do all kinds of file system stuff like load and save maps and assets without security restrictions.

(Maybe in the next post I will finally show a map that isn’t just random lines.)

Have a look-see: regular expression cheat sheet.

One little snafu in Flex, specifically, is to remember the second parameter when you create an instance of RegExp. If you need something like “g” (global) in a plain regular expression, you’ll want that in the “flags” parameter or it won’t do much.

I admit it: this is butt ugly. It’s just plain old Flex. I didn’t add any styling at all. Who has time for that?! And the screenshot is tiny (better ones will be bigger, promise).

Anyway, what you see is the new map dialog, where you enter some parameters for your new map. To the right you see the edit bar, a tile set, etc. This is laid out like the Lila Dreams editor, but the code is only slightly based on stuff I did previously (handling user prefs, finding asset directory, etc). It won’t actually make a new map yet, but I just need to hook that up to the UI.

Let me summarize: five hours of trying to figure out why Flex didn’t like my custom components and associated .as files. Finally I just decided to inline all the code, to hell with keeping it separate. I have always thought Flex is very tedious to use. It’s a love/hate relationship. Maybe in seventeen thousand years, after I have used it a little bit, I will feel more on the love side. Today… not so much.

On the positive side, it is coming together pretty fast despite these kinds of frustrations. There’s a chance I can achieve my goal! More updates to come.

Addendum:
http://www.adobe.com/cfusion/communityengine/index.cfm?event=showdetails&productId=2&postId=7142

*Screams*

Well, at least now I know that you can’t subclass Canvas and expect it to behave like when you subclass UIComponent if you are trying to add a child Sprite to it. What I mean is, if you create a custom component that subclasses Canvas, it will throw an exception when you try to addChild() a Sprite. But if you subclass UIComponent, it will let you addChild() a Sprite.

*Slaps self silly, then gets back to work*