Code Mode
by captaincomic (Updated on 2016-03-18)
Stencyl supports Code Mode, a way to write behaviors entirely using code (currently, Haxe).
This article surveys the interface and explains how to accomplish crucial tasks, such as defining attributes through annotations.
Contents
- The Basics
- The Interface
- Using External Editors
- Switching Between Design and Code Mode
- How to Define Attributes
- The Future
The Basics
You have three options to write code in Stencyl:
- Use code blocks in Design Mode behaviors. This is this easiest option to include short pieces of code in your behaviors.
- Create behaviors written in code in Code Mode.
- Write arbitrary classes in Freeform Mode.
This article is about the latter two options. Code Mode behaviors are just like normal behaviors, you can attach them to your scenes and actors. For a scene behavior, write a class that extends SceneScript; for an actor behavior write a class that extends ActorScript. You can also define attributes in Code Mode behaviors (explained later in this article).
In Freeform Mode, you can write arbitrary classes. They are not behaviors, so you cannot define attributes or attach them to your scenes or actors. In order to make use of a Freeform Mode class, you will need to call the code from another behavior.
The Interface
Top Tool Bar
This area has three separate buttons: Refresh Attributes, Open in External Editor, and View API.
- Refresh Attributes: This updates the attributes in your Behavior by running an annotation parser over it. (Only available in Code Mode.)
- Open in External Editor: This allows you to use an IDE of your choosing, such as Eclipse, Notepad++, FlashDevelop, etc.
- View API: Lets you view Stencyl's Haxe API.
Attributes Pane
The Attributes Pane stores all attributes currently defined by this behavior. To define attributes, you have to annotate them. Scroll down to the How to Define Attributes section below for further details.
In Freeform Mode you cannot define attributes, so this area does not exist.
Editing Area
In this area you write your code. Syntax highlighting and find/replace are supported. For more advanced features use an external editor.
Using External Editors
Stencyl plays nicely with external editors such as Notepad and FlashDevelop.
Configure this setting inside Preferences > Workspace. It will open up the editor on demand and auto-sync the changes when you save in that external editor.
Switching Between Design and Code Mode
At this point in time, we don't support switching between these two modes. A behavior is designated as always being in one or another and cannot be changed after the fact.
If you want to mix the two, you need to make a design mode behavior and stick in code blocks.
How to Define Attributes
In order to expose a class member for a Code Mode Behavior as a configurable attribute, you need to annotate it. This is using the Metadata feature of the Haxe language. The easiest way to learn the syntax is by example.
//Expose your attributes like this:
@:attribute("id='1' name='Display Name' desc='A Text Attribute'")
public var attributeName:String;
@:attribute("id='2' name='My Color' desc='A Color Attribute' type='color'")
public var color:Int;
@:attribute("id='3' name='Action 1' desc='A Control Attribute' type='control'")
public var action1:String;
// The "type" property can be in uppercase too, like a constant
@:attribute("id='1' name='Move Speed' desc='A Number Attribute' type='NUMBER' default='20.0'")
public var moveSpeed:Float;Accepted Properties
| Name | Description | Required? |
|---|---|---|
| id | Must be a unique integer | Yes |
| order | What order it appears in the Behavior page | No |
| desc | Display name on the Behavior page | Yes |
| dropdown | Name=Value pairs for Dropdowns | No |
| type | Use this if specify the type of your attribute | Yes, for certain types |
| default | Default value for the attribute | No |
The type is necessary for attributes that don't have a distinct type in Haxe. For example a Control is stored as a String, the same type used for Text attributes. So to define a Control attribute without ambiguity, you need to provide the type parameter. The parameter is case-insensitive.
Note: After exposing a new attribute to a behavior, you need to reload the scenes or actors to which the behavior is attached for the changes to take effect.
The following types are supported, listed with the corresponding type in Haxe.
| Attribute Type | Haxe Type |
|---|---|
| ACTOR | Actor |
| ACTORGROUP | Group |
| ACTORTYPE | ActorType |
| ANIMATION | String |
| BOOLEAN | Bool |
| COLOR | Int |
| CONTROL | String |
| FILTER | Dynamic |
| FONT | Font |
| IMAGE | BitmapData |
| IMAGE_INSTANCE | BitmapWrapper |
| INT | Int |
| JOINT | B2Joint |
| LIST | Array |
| MAP | Map<String,Dynamic> |
| NUMBER | Float |
| OBJECT | Dynamic |
| REGION | Region |
| SCENE | Scene |
| SHADER | Dynamic |
| SOUND | Sound |
| TEXT | String |
The Future
Down the road, we'd like to significantly enhance the coding experience. The best way is to improve integration of code with external editors rather than trying to build better (but still inferior) support into Stencyl itself.
For the time being, sending code mode behaviors to an external editor of your choosing is the best way to edit code in Stencyl.