PushButton Engine Lesson #2: Adding a Simple Shape
The goal of this lesson is to guide the user through adding a simple shape to be drawn to the screen.
These lessons are structured in a series of steps -- small milestones that will provide focused short-term goals for incrementally understanding PushButton Engine.
These lessons are targeted at someone who is new to PBEngine, but not necessarily new to programming.
Tutorial Resources:
To follow along with the tutorial, you can download the starter project and use it as your base to implement the tutorial:
- Lesson2Base.zip (1KB)
Loading up the starter project.
As covered in Lesson 1, extract the example .zip into a personal project folder, and ensure that it builds in your build environment.
This will give you a bare-bones starter project that includes the most basic PBE project file structure with an empty Actionscript file for creating the game.
When you build the empty project, it should create an empty Flash file with a light blue-gray background.
Now we will cover setting up a basic PBE scene, and adding a circle to be drawn in the center of it.
Editing our Source File
At first blush, our game looks like a fairly standard empty Flash project.
File: /Lesson2Base/src/Level2Base.as
... [SWF(width="800", height="600", frameRate="60")] public class Lesson2Base extends Sprite { public function Lesson2Base() { PBE.startup(this); // Start up PBE } } ...
In this example, we will be adding all of our entities and components by hand. PushButton Engine has some excellent tools for building levels in XML and loading them at runtime, but in the interest of keeping things simple, we will be creating our entities and components in Actionscript.
Entities don't have much functionality in and of themselves -- the way they gain behavior and properties in the context of a game is through components. Components are modular building blocks that add snippets of functionality to entities, and can often be combined and re-used in powerful ways.
We will add two entities in this example, each with two components. The first entity will be our Scene, and the second entity will be our Hero.
Let's continue by editing our source file as follows:
File: /Lesson2Base/src/Level2Base.as
... [SWF(width="800", height="600", frameRate="60")] public class Lesson2Base extends Sprite { public function Lesson2Base() { PBE.startup(this); // Start PBE. createScene(); // Set up a simple scene entity createHero(); // Create a simple avatar entity }
First we set up our SceneView which is basically the canvas that objects are drawn upon that make up the scene.
Now we will create the Scene itself through the PBE.initializeScene helper function.
private function createScene():void { var sceneView:SceneView = new SceneView(); // Make the SceneView sceneView.width = 800; sceneView.height = 600; PBE.initializeScene(sceneView); // This is just a helper function that will set up a basic scene for us }
Next we will create our hero entity. Just as the Scene entity had two manager components, this entity will have two components -- one to be tracked by each manager component.
The first component is the spatial component -- it tells the spatial manager where the entity is located.
The second component is the render component -- it registers itself with the render manager, and tells the manager how the entity is to be drawn to the screen. We are just using a simple circle for this lesson, but there are many more powerful options available.
private function createHero():void { var hero:IEntity = allocateEntity(); // Allocate an entity for our hero avatar var spatial:SimpleSpatialComponent = new SimpleSpatialComponent(); // Create our spatial component spatial.position = new Point(0,0); // Set our hero's spatial position as 0,0 spatial.size = new Point(50,50); // Set our hero's size as 50,50 spatial.spatialManager = PBE.spatialManager; hero.addComponent( spatial, "Spatial" ); // Add our spatial component to the Hero entity with the name "Spatial" var render:SimpleShapeRenderer = new SimpleShapeRenderer(); // Create a renderer to display our object render.fillColor = 0x0000FF0; render.isCircle = true; render.lineSize = 2; render.radius = 25; render.lineColor = 0x000000; render.scene = PBE.scene; // Set which scene this is a part of // Point the render component to this entity's Spatial component for position information render.positionProperty = new PropertyReference("@Spatial.position"); // Point the render component to this entity's Spatial component for rotation information render.rotationProperty = new PropertyReference("@Spatial.rotation"); hero.addComponent( render, "Render" ); // Add our render component to the Hero entity with the name "Render" hero.initialize("Hero"); // Register the entity with PBE under the name "Hero" }
And we're done! At this point, things should be all ready to compile and see your new entity displayed on the screen!
Seeing it in action.
After compilation, you should produce a .swf like the following (click to load):
In Review
To summarize, to create an entity in Actionscript, one uses the following pattern:
var newEntity:IEntity = PBE.allocateEntity(); // Allocate an entity // Add components and set properties. newEntity.intialize("EntityName"); // Register the entity with PBE under the name "EntityName"
This creates an entity, stored in the variable newEntity. All entities and components must have string names registered with PushButton Engine, and the call to initialize() registers that entity with PushButton Engine under the name "EntityName".
Creating components in Actionscript is a few more lines of code.
var newComponent:IEntityComponent = new WhateverComponent(); // Create a new component newComponent.field = value; // Set values. newEntity.addComponent(newComponent, "TheComponentName"); // Add the component to the entity container // Repeat the component block for each component and its values.
Conclusion
Congratulations! You have finished lesson #2, loaded your first entities and components into the game, and seen the results. Future lessons will do more complicated things, but we hope this got you off on the right foot of tinkering with the engine.
You can download the completed project source files for this project.
- Lesson2Final.zip (2KB)