Prerequisite: Setting Up Your Plugin Development Environment
To build a plugin for GBS you need to build classes that plug into the underlying game engine and then write UI classes in Adobe Flex code to integrate into the GBS application. This provides visual controls for the end user to use your plugin. We recommend going through the tutorial videos in the "Underlying Game Engine" section of this site to get a basic understanding of how to write code for the game engine. You can download the sample code for this tutorial here.
Create A Basic Game Component
Lets start by creating a basic game component class that extends the EntityComponent base class from the engine. All components in GBS will have this basic structure. You can access the parent entity by referencing the "this.owner" property. The owner property implements the IEventDispatcher interface so you can add listeners to the owner (" this.owner.addEventListener('EventName', onEventHandler); ") to listen for events that other components may broadcast or even broadcast an event from within your own component.
Updating A Component Value Every Game Tick
Ok I have my component setup but what if I need to update some value in my component every frame of the game? All you have to do is change the super class from EntityComponent to TickedComponent and that will give you access to method called onTick() that will be called consistently on every tick update of the game engine.
Its important to note here that the game engine has two different types of updatable components. A TickedComponent and AnimatedComponent. The TickedComponent as an onTick() method that gets updated sequentially every frame. The game engine manages this process and helps you get around the well known elastic racetrack issue. This is also cool for doing things like speeding up your game or slowing it down based on the tick rate. The AnimatedComponent has an onFrame() method that gets called every frame of the flash player but there is no guarantee that some frames will not get dropped. So the onFrame method on the AnimatedComponent class is primarily used when you are not concerned if it gets updated consistently.
In the example above we grab the position property from the "Spatial" component assuming that there is a component on the entity called "Spatial" and has a property called position. The way we do this is by using a property reference.
Building A UI For My Custom Component
Now that we have a basic game engine component setup, we need to build a ui skin to allow the end user to manipulate this component inside of GBS. We will write this ui skin in Adobe Flex code. In FlashBuilder create a new mxml component with the settings above.
Add HostComponent MetaData
Make sure that your new component skin class looks like the one above. You need to have the HostComponent metadata tag defined to point to the ComponentPanelUIContainer and also make sure you have the minimum required skin states. By extending the BaseComponentPaneUISkin your ui component will be injected with the correct component data and provide some base methods for you to override and update this ui with the proper values.
Basic Methods Used In The UI Component
There are a few basic methods that need to be implemented to work with your game engine component. The updateView(), panelRemoved(), and updateComponentValues() methods. There are other methods available for you to use but you will use the preceding methods the most.
Adding A Basic User Input Control
The GBS Plugin SDK provides a number of default ui components for you to save you time. You will need to import the gbs component namespace in order for you to reference these components in your mxml markup. Add this:
to the top of your mxml ui component skin.
You also want to import the PluginUtils which you will pass to the AutoStoreTextInput component so that it can store the users input on your custom component object auto-magically for you. By setting the inputType on an AutoStoreTextInput to "PropertyReference" or "Expression" you will provide a property browser or expression editor to the end user. This feature will be available in a future release. For now the input control just displays a small icon to indicate to the user what type of input it accepts. The storeIn property and storeKey property allow you to specify which object and/or property you want to save the resulting input value to. In the image above the storeKey is blurred out but make sure you set it to the "referencePositionOnSpatial" property that we created earlier in this tutorial on the CustomGameComponent.