Flex Open Source Project Launch: The Tilde Developer Console

Flex developers rejoice! Once only reserved for advanced games engines, the tilde-activated developer console has finally arrived to empower Flex coders everywhere.

I am proud to announce the long-delayed release of the Tilde Developer Console open source project into the wild. This Flex library makes powerful development tools from the PushButton Games Engine available to all Flex developers.

[June 21, 2010 - Update: Check out the Tilde Console demo application here.]

I do enterprise Flex RIA development for a living and extracted this powerful tool set for my own use a few months ago after attending Nate Beck's presentation on the aforementioned games engine at 360|Flex 2010 in San Jose, California. The console quickly became one of my most important tools, in particular when saving my bacon multiple times during user acceptance testing for a large, complex project. Because I wrote so little of it myself, I intended to release the source code to the public from the outset but have been altogether too busy to even think about it.

This week, things have started quieting down again (I know, I know... it won't last) so I fetched and merged in the latest code from the PushButton Engine (which contains some very cool new optimizations to the console display) and polished it all up for public consumption. Given how much I've personally benefited from using the console, I'm excited to finally be able to share this with my fellow Flex developers. If I wasn't confident that many of you will appreciate these tools every bit as much as I have, I wouldn't have bothered to create a logo. (Using Inkscape, I might add... a fine, free, open source SVG tool.)

The key tools in this package are:

Developer Console

A versatile "tilde-activated" console similar to that found in many 3D games engines (e.g. Unreal, Source, etc.)
Tab-based command auto-completion, command history and built-in help
Powerful ability to register custom call-back commands at run-time. These are treated identically to the built-in commands.
Utility functions for serializing object information to the console
Integrated "Hi-ReS! Stats" graph from Mr.doob

Client-Side Trace Logging

Statements are logged to both the console and the Flash Player debugging trace.
Multiple logging-levels are supported and entries are color-coded by severity in the console. (e.g. DEBUG, INFO, WARN, ERROR)
Logging verbosity can be set using a simple console command.
Deferred logging: even if log statements are sent before a Logger instance is created, they will be stored until one does exist, allowing log entries to be submitted from the moment the application starts.
Explicitly turning off logging causes all logging calls to be disregarded so they don't impede application performance. (All pending deferred log calls are also discarded.)

Give Credit Where Credit is Due

As mentioned above, the Tilde Console is built almost exclusively using code from the PushButton Games Engine and all due credit goes to the original developers for their fine work. My contribution to the source has been minimal. Because of the nature of their work, games developers are the very best in the business at getting every last drop of performance out of their code and that fact is evident throughout the work of the PushButton team. It was a personal pleasure working with their code which is clearly the work of professionals: it is elegant, readable and although eminently clever, always easy to follow.

I'd like to thank the PushButton team for making their excellent work freely available and for the many tricks I've picked up while working my way through their code. If you are at all interested in learning how to write well-optimized Actionscript code, I strongly suggest that you check out their promising project.

Adding The console To Your Project

The simplest way to integrate the console into an application is to add the following line to your Application "creationComplete handler:

Logger.startup(Logger.LOGGER_UI_MODE);

This will add the event listener for the tilde key (i.e. "~") which toggles the console and will cause all deferred Logger calls to be processed. The other mode is called "LOGGER_TRACE_MODE" which only provides debugging trace logging functionality and not the graphical UIConsole.

The Logger can be explicitly turned off (which also frees up memory by discarding any deferred trace statements and blocks any subsequent Logger calls from being handled) by adding this line to your application:

Logger.disable();

The Console Display

As you can see in the example image, the console color-codes the trace statements by severity. There are five levels, including the vanilla "print" level which has no severity and is always displayed, regardless of the Logger's verbosity setting. The colors are as follows: grey for DEBUG, green for INFO, orange for WARN and red for ERROR. Plain old print calls are displayed in white.

To log an entry, add the following to your source:

Logger.error(<the class that's logging>, <the name of the method where the loggincall is made, as a String>, <the statement to log, as a String);

e.g.

Logger.error(MyClass, "myMethod", "This is an error log entry!");

Built-In Commands

The commands that come built-in are the following:)

help

This command lists all available commands, including developer-added custom commands (see below), along with their descriptive text.

clear

This clears the contents of the trace.

copy

This command copies the contents of the console to the system clipboard. Another way to do this is to double-click on the console.

fps

This adds Mr.doob's Stats graph to the screen. This can be handy in determining, among other things, frame rate, memory usage and when garbage collection is fired by the Flash Player.

listDisplayObjeccts

This outputs the indented tree structure of all display objects in the display list.

verbose

This command takes one parameter (a number between 0 and 2) to set the verbosity level of the console output. This allows you to filter down the level of detail of the entries that are captured (e.g. drops the fully qualified package of the "logged from" Class).

version

Outputs the operating system and current Flash Player version to the trace.

Hotkeys

When in the console, a few hotkeys are available to you. They are as follows:

TAB / SHIT+TAB

This allows you to cycle forward and backwards through all of the available commands. If you type in one or more of the first few characters of an existing command and hit TAB, the command name will be auto-completed, much like in some command-line shells.

CTRL+HOME / CTRL+END

This allows you to jump directly to the beginning or end of the trace.

PGUP / PGDN

Jumps one page up or down in the trace.

double-click on the trace

This will copy the contents of the trace into the system clipboard.

Adding Custom Commands

One of the most powerful pieces of functionality included is the ability to wire callback functions into the console. These functions are then available at run-time as commands in the console, indistinguishable from the built in commands. It is even possible to feed parameters to these functions.

Here is an example of how this is done:

Note that though the method takes a parameter, if none is provided, the default will be used. If you don't provide a default then, no harm no foul, an exception will be traced at the "ERROR" level in the console.

How I Use It

In my most recent Flex projects, I've set up the application to be configured at run-time from XML-based resource bundles. This allow me to set up an application to run in different contexts, based on the contents of a configuration file. For instance, the application can be set to run in either "LIVE" or "TEST" context. Furthermore, the console is only activated and the callbacks are only ever declared in "TEST" mode.

Having access to the trace has been a godsend during quality assurance and user acceptance testing because we don't ever use the debugging Flash Player for this kind of testing. By using the console, if a failure does occur, testers can still provide developers with the application trace as part of their bug report. This trace can often reveal specifics about an error that are otherwise invisible to the user and that would be irretrievable in a non-debugging Flash Player.

Where To Get It

The source code is available through Google code at: http://code.google.com/p/tildeconsole/ It is licensed through the MIT open source license which you'll find included in the project.

Compiling it for yourself is the best way to go but if you prefer you can grab one of the following untested SWC binaries: Flex 3.3 Flex 3.4 Flex 3.5. I'll try and upload a Flex 4.0 SWC as soon as I have time to build one.

Since seeing is believing, I also intend to make a test application available in the next few days so that people can see the console in action before downloading the project. I'll worry about that later because for now I really have to get some well-deserved rest.

[June 21, 2010 - Update: Check out the Tilde Console demo application here.]

Thanks for dropping by and please feel free to leave me a comment. It's always gratifying to hear from my visitors.