3 methods to implement (called by the API), 1 for the game engine and 2 for the level editor (minimal implementation).
1 method to call from the game engine (minimal implementation).
Technical constraints
Here is the list of constraints you will have to deal with in your game and in your editor, to make them work with the BL interface. Those constraints are mainly those you have when you deal with a .swf embedded in another .swf.
Constraints, All Flash versions
Frame rate should be set to 30 fps, as that will be the frame rate of the common UI that loads the external game swf files.
The background color of the common UI will be white (#FFFFFF). Therefore you will need to include a rectangle filled with the color you wish to appear as the background, and of the same size of your stage, on your main timeline.
Preloading your game will be handled for you, therefore you do not need to include a preloader with your game.
If your game is using the mouse, you have to call the BL API function cursorOverBLGUI() to check if the mouse cursor is over the BL graphic interface (BL menus, information popups, etc...). When the user presses the mouse button while the cursor is over a BL graphic interface, that should not trigger an action in your own swf.
Constraints, Actionscript 2 only (Flash 8 and below)
Static variables. Don't use the exact same static variable names in your game and in your editor. The game and the editor will write and read the same static variable when both are loaded, which is usually not what you wish.
Classes. If the game and teh editor use the same class file, make sure to recompile and resubmit both the game and the editor when you change your class file.
Sounds. When instantiating new Sound objects you must pass a reference to the movieclip that's doing the instantiation, such as:
var mysound = new Sound(this);
If you leave out "this" your game will have no sound when loaded.
Some issues with hitTest... In some cases, you might have troubles with the hitTest function (it depends on the size of your game and editor, if they are different, the less large one will have to be horizontally centered inside the BL swf). This is the turn around (thanks to bit-101):
MovieClip.prototype.oldHitTest = MovieClip.prototype.hitTest; MovieClip.prototype.hitTest = function(x, y, sf){ var obj = {x:x, y:y}; _root.localToGlobal(obj); return this.oldHitTest(obj.x, obj.y, sf); }
You may not use references to _level anywhere in your code. (If you do not know what this means, you probably don't have anything to worry about.)
Constraitns, Actionscript 3 only (Flash 9 and over)
When an AS3 swf (your game or editor) is loaded into another AS3 swf (the BL APi swf), the main object of this swf is not added to the display list until after the constructor is called. Whereas when loaded directly the main object is already attached to the display list. This results in the stage and parent properties being set to "Null" (and likely resulting in null object references). This can usually be worked around by moving any code that needs to interact with the stage being moved to an event listener. Event.ENTER_FRAME, Event.INIT, or Event.ADDED_TO_STAGE events are good candidates for this.
When you have to display hundreds of display objects on the stage, for performance matters you should prefer using Bitmaps instead of MovieClips.
Still for performance and memory matters, when you don't need several frames, use Sprites instead of MovieClips. MoveiClips are heavy and slow.
Before accessing the stage property of your swf, you will have to wait for the Event.ADDED_TO_STAGE event. Otherwise stage is null.
More generally speaking, becareful when using the stage property in your swf. Be aware for example the stage's size is not the size of your swf when it is embedded. The mouse cursor can be outside your swf while being inside the stage (the MOUSE_LEAVE event will not be triggered in this case).
