Livecoding is a method of writing and monitoring applications when logic is updated in a working app just as you write the code, without restarting (while common practice requires starting the app again after a new compilation). Data and status of the app are also saved.

Code Orchestra Livecoding Tool (COLT) is a tool for livecoding in Flash created by the Code Orchestra company. COLT is the first tool of this kind for Flash. Several new approaches made livecoding possible for the Flash runtime environment. There used to be a belief that it's impossible to implement livecoding for Flash environment since it doesn't support classes restart.

COLT is an special utility that monitors alterations of resources of a Flash application — source code (AS, MXML), images and the rest. When the tool registers an alteration in the code, the latter is delivered into the working app. It needs to be compiled and started in COLT in order to receive code updates.

Download a COLT version for your OS at Code Orchestra's website

• Win: Start the installer and follow instructions.
• Mac: Start the .dmg file and move the COLT folder into the Applications folder.

Install Java if necessary.

If you're using Firewall, add the 6126 and 8091 ports to the list of open ones.

• Java is not installed.
• Port “6126” and/or “8091” is inaccessible. Firewall needs to be set up.
• The app or compiler doesn't start. The current user needs permissions to write in the app's or project's folder (Windows). Set all necessary permissions for the folder and it's sub-directories.
• The Flash app doesn't start. Standalone Flash Player isn't installed. Install it from www.adobe.com
• Unexpected compilation errors. Turn autobuild off in your IDE. Some editors automatically start the process of app assembly (Flash Builder) as the code is edited. Since you're assembling the application through COLT, this feature of the editor is unnecessary.
• Paths to sources contain symbols not supported by the runtime environment of COLT (like “#”)

##Starting an app in livecoding mode

Start any example of a COLT project. You can find these in the “Projects” folder in the COLT application directory. Click the “Run” button in the top bar of COLT. The app will be compiled and a player window will pop up. If a green icon of the session started lights up down there in the status bar, and an additional tab with the application logs appears — everything is going right. Your Flash app is working in livecoding mode. If compilation went wrong, read compiler's messages — the “FCSH” tab (hidden by default).

Read the “readme.txt” attached to each project. There's a suggestion of opening files with classes in a text editor and changing lines of code there. As the code is altered and changes are saved, the Flash app should change too.

Pay attention to project settings. They're in “Project Paths”, “Compiler Settings” and “Live Settings” tabs. We'll look through these in more detail soon.

##The process of editing an application in livecoding mode

As you click the “Run” button, a specific compilation starts. It alters the source code of the app in a way that each method that will later deliver changes (live-method) is moved to a separate class.

##Glossary

Livecoding session - starts as you click “Run” in COLT. The app is assembled in a specific way, and a socket connection opens between COLT and the Flash app.

Livecoding client - a Flash application started in livecoding mode for a livesession. A livecoding session can have several active clients at the same time. When a new one is added, all changes made during the current session are delivered.

Connection - a new connection is opened when a client is added. As it happens, a new tab with logs appears.

Basic build - a build of an app for starting to run it in livecoding mode and then beginning a session. A basic SWF.

Incremental compilation - compilation of only those changes to the code that the user has made. After this kind of compilation is complete, an .swf file (“package_N”) is created and placed next to the basic SWF in the “Livecoding” folder.

Live-class - a class whose all methods have the live behavior.

Live-method - a method with the behavior of delivering code updates to the client.

Live Code Update Listener - a specific method that tracks code changes.

Method registry - a registry of live methods. An ActionScript class that stores a registry of methods.

Livecoding annotations - specific metadata that makes it possible to manage regulations of what method or class will have the livecoding behavior.

##Managing regulations of covering the livecoding code

Most projects don't require livecoding of the whole code. If you try, compilation takes longer and effects caused by trapping exclusions can occur, along with other errors. You're most likely to work with just a few classes or methods. And what matters is delivery of changes to exactly those methods you care about.

If you want all methods of your code to have the behavior of livecoding, select the “All Methods” mode in the “Live Settings” tab. But we recommend the manual selection mode.

You can turn livecoding on in methods by specifying a [Live] annotation.

In order to activate all methods in a class (most common practice), specify a [Live] annotation for the whole class.

In order to turn livecoding off for a separate method, add the [LiveCodeDisable] annotation. This one is also suitable for marking a whole class (like when you work in “All Methods” mode and want to turn separate classes off).

When the class has it's implementation changed, the app won't do magic and alter its status and appearance on the screen. You should describe the logic of this update. The most common thing is to perform a specific code in all items of this class to update the object's status. Like, for example, re-drawing it on the screen. The easiest way to do this is adding a method with the [LiveCodeUpdateListener] annotation:

[LiveCodeUpdateListener]
public function codeUpdate() : void {
  trace ("code update!!!");
}

When you add this handler method, restart the current live session.

This method shouldn't have parameters. Otherwise you'll get a compilation error.

The example shown above reacts to all code changes within the current class. Of all methods.

The [LiveCodeUpdateListener] annotation is an easier way to add a handler of changes delivery. But in some cases it's better to use the live methods registry and get the handler in a common way, through “addEventListener()”. In order to do it, add “colt.swc” to your project. (“colt.swc” can be found inside the COLT application installation folder, in “lib” folder.)

To subscribe to the event of code delivery add the following:

...
LiveCodeRegistry.getInstance().addEventListener(MethodUpdateEvent.METHOD_UPDATE, handleLiveMethodUpdate);
...

private function handleLiveMethodUpdate(event:MethodUpdateEvent):void {
  if (event.classFqn == "com.myPackage.MyClass" && event.methodName == "myMethod") {
    // your logic
  }
}

As a matter of fact the COLT compiler turns the [LiveCodeUpdateListener] annotation into the same kind of code. But we recommend using the annotation itself. You can specify the name of the class or method as parameters:

[LiveCodeUpdateListener(classFqn="com.myPackage.MyClass", method="myMethod")]
public function codeUpdate() : void {
  trace ("code update!!!");
}

Along with code alterations, COLT supports delivery of images and other files that you've specified in the fields with an [Embed] annotation.

In order to handle an event of delivery of any resource described in the fields of the current class, add the [LiveAssetUpdateListener] annotation.

[Embed(source="../assets/live_pic.png")]
private var myEmbedField : Class;

[LiveAssetUpdateListener]
public function assetUpdate() : void {
  trace "asset updated";
}

To subscribe for changes of a specific Embed field, specify the “field” parameter.

[Embed(source="../assets/live_pic.png")]
private var myEmbedField : Class;

[LiveAssetUpdateListener(field="myEmbedField")]
public function assetUpdate() : void {
  trace "embedField updated";
}

You can also use subscription through AS3:

...
LiveCodeRegistry.getInstance().addEventListener(AssetUpdateEvent.ASSET_UPDATE, handleLiveAssetUpdate);
...

private function handleLiveAssetUpdate(event:AssetUpdateEvent):void {
  if (event.source == "../assets/live_pic.png") {
    // your logic
  }
}

The AssetUpdateEvent class exposes following properties:

source (String) - a path to asset file, corresponding to source parameter in [Embed(...)] annotation;

mimeType (String) - asset MIME type, corresponding to mimeType parameter in [Embed(...)] annotation;

assetClass (Class) - a class with updated asset (such as Bitmap, ByteArray, etc).

[Live] - Add behavior to a live method or to all methods of the class.

[LiveCodeDisable] - forbid livecoding of a method or class.

[LiveCodeUpdateListener] - a handler method for the event of delivering a code update to the Flash app.

classFqn - a full name of the class where changes took place. The current class by default. The “*” value is supported — all classes.

method - the name of the method to whose changes the listener should react. By default the listener responds to any method of the current class. You can specify several methods separating them with a comma.

weak - a soft link during subscription. “True” by default. Using other values of the parameter isn't recommended — in order to avoid memory leaks.

priority - sometimes you need to manage the order of handling events of code update.

[LiveAssetUpdateListener] - a handler method for the event of delivering changes of EMBED resources.

field - name of the EMBED field (in the current class).

[LiveConsole] - same as [LiveCodeUpdateListener] where the 'method' parameter contains the method marked with this annotation. This approach is useful when you need to perform a specific code once and then delete it. Kind of console.

There are some limitations of the Flash virtual machine that make it harder to send changes to a working application. Let's overview these cases.

• Code in class constructor. The code in class constructor is executed only once(as you want to create object only once, and then update it), so, in order to support code changing inside of constructor, you should take this code out as a separate method.
• Private methods that have been “re-loaded” in subclasses. That is, subclasses of a class have methods with the same names as in the super class. The subclasses methods will have the livecoding behavior while those in the superclass will not.
• Code whose local variables have the [Embed] annotation.
• Getters and setters don't have livecoding behavior by default (you can turn it on in the “Live Settings” tab).
• Methods with referring to the current method — arguments.calle. The code is extracted into a separate method from among class methods, and you can't use arguments.calle in livecoding. In this kind of methods Live behavior will be turned off automatically.

While writing a new code with the live method, you can make a logical mistake that may cause your app to stop. Like an endless loop, infinite recursion etc. COLT can help you avoid this.

What kind of code transformations take place to avoid these cases? COLT automatically turns the code in live methods into a 'try/catch' block. When “Exception” is trapped, the COLT log shows a message (double-clicking it exposes stacktrace errors). COLT limits the number of loop iterations (10000 iterations by default). Calling infinite recursion causes stack overflow, and the Flash player generates an error which gets trapped and then sent to the log.

There are 3 launch options in “Live Settings”. By choosing the 3rd one - “AIR” - you'll turn on the mode of starting a live app on an iOS device.

Connect the iOS device via USB.

In the AIR app settings specify paths to the Apple certificate and your username and password. Specify other parameters (documentation on launching an AIR app can be found at adobe.com).

Make sure your iOS device is in the same wi-fi network as your work computer.

An app will be installed on the iPad/iPhone as the livecoding session begins. A tab with logs of your application will appear in COLT. You can alter the source code of the app and the Embed graphics like in a common Flash app.

Some additional information for better understanding of how livecoding works on an iOS device.

The app on a device is launched in development mode. You can't use the live mode in “production”.

AIR works in interpreter mode. This might mean that in a real app the speed of code execution will be higher.

The app on the device communicates with your computer through the local network. When the live session starts, you can disconnect the USB, but the device should be in the same local network and your computer should allow access through http (port 8091) and a socket (port 6126).

You can start several devices with COLT (click the “+” button next to “Run” in the top bar, COLT will start the installation process on the next device).