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.


  • 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
FILTER Dynamic
IMAGE BitmapData
LIST Array
MAP Map<String,Dynamic>
OBJECT Dynamic
SHADER Dynamic
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.

Print Article Edit Article How to Edit an Article
Disclaimer: Use comments to provide feedback and point out issues with the article (typo, wrong info, etc.). If you're seeking help for your game, please ask a question on the forums. Thanks!


Can you provide us with a tutorial on how to code in Stencyl? The Drag and Drop system is great but I like to have more control over what goes on.
0 3 months, 3 weeks ago
what are the advantage of usin the scripting code, can you declare variables, use data structure an so on ????
1 2 years, 1 day ago
To answer all the questions, you cannot switch between design and code mode. 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. Which turns out to be quite a popular use case.
1 2 years, 3 months ago
How do you switch the design to code
0 2 years, 4 months ago
Suggestion for Code/Design mode:
Make the Code Mode with blocks of code available for the user the input, but the relevant parts show up in Code Mode greyed out. That way the user can decide if he wants to optimize or not.

If not, the user can always select to not permanently alter the code. If would be VERY fun to learn this way :)

0 3 years, 5 days ago
How to switch design/code mode?

2 3 years, 6 months ago
"int" or integers, as the name states are integer numbers. In other words, numbers like, ...-2,-1,0,1,2....
With ints you cannot store fractions such as 3.14.

"uint" are unsigned int. They only store positive numbers.

-1 3 years, 10 months ago
What are "int" attributes?
0 3 years, 11 months ago
How to switch design/code mode?
5 4 years, 4 months ago

Sign In to Comment