I made a plugin for the Vim text editor to highlight JavaScript code according to its scope. This was inspired by an idea by Douglas Crockford in his presentation at YUIConf 2012. See from around the 16 minute mark onwards. I can’t really claim to understand monads – apparently the curse is still in effect! – but this idea for highlighting functions in JS struck me as a really good idea, and something that I could do in Vim. Well, I finally got around to doing it. This is what it looks like in action:

Notice how functions defined inside other functions are progressively colored differently, making their scope clear. Also, closure variables are colored according to scope they were defined in. I find that this can help make such code easier to read and understand. It is particularly helpful when writing/reading code in a ‘functional’ style. The example code here is from a book I’m reading: Functional JavaScript by Michael Fogus.

Other Editors/Implementations

See this discussion on Google Plus for information on other implementations for other editors.

Installation

Check the README on the Github page

One of the common misunderstandings about JavaScript is that it does not provide encapsulation, and therefore is not fully capable of Object Oriented Programming. While EcmaScript 3 does not have syntax to specify which members of an object are private or read-only, this is addressed in EcmaScript 5, with the new Object API. However even without the new syntax, it is perfectly possible to achieve encapsulation in JavaScript objects.

The key is understanding how scope works in JavaScript. The main thing to keep in mind is that JavaScript is function scoped: variables are visible anywhere within a function, including within functions which are defined within that function. This is the property of ‘closure’.

The other important thing to understand is that JavaScript does not have Classes, but rather constructor functions. So when you say,

1

var dog = new Dog();

What really happens is that the Dog constructor function gets called, with ‘this’ set to the prototype of the constructor. The prototype is simply another object, which defaults to a plain old Object, but can be specified in code, eg.

1
2
3
4

Dog.prototype = {
        bark: function () {
    }
}

The effect of this is that the dog object will be able to use members which exist in the prototype object, so dog.bark() will work.

Encapsulating State

So how do we get ‘private’ members in objects? The trick is to use the closure property of the constructor function itself, and define some accessor methods within it:

1
2
3
4
5
6

function Dog (name) {

    this.getName = function () {
         return name;
    }
}

So now your dogs can be given a new name when they are created, but the name cannot be directly accessed or changed from the outside.

1
2
3

var fido = new Dog("Fido");
console.log(fido.getName());//"Fido"
console.log(fido.name);//undefined

If you want to make a private variables which are not arguments to the constructor, you can do that by simply declaring them at the top of the constructor function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

function Dog (name) {

    var age = 0;

    this.getName = function () {
         return name;
    }

    this.getAge = function () {
         return age;
    }

    //example of setter:
    this.setAge = function (newAge) {
          age = newAge;
    }
}

So we could continue in this way, and declare all the methods of the Dog inside the constructor function, and enjoy the benefits of having encapsulated properties. That would work fine, but the downside is that these functions are being re-created every time the constructor is called. This is a waste of memory.. not sure how much of an issue this is in reality unless you’re making thousands of them, but it is something to avoid if possible.

Preventing Memory Loss (What memory problem?)

While it is not possible to completely avoid some duplicate functions, the memory used can be mitigated as follows: if you make getters/setters for all your properties that you want to be private, then you can define the rest of the methods on the prototype to use the getters/setters. This way the only duplicated functions are the getters/setters, which should be very lightweight (couple lines each), and shouldn’t result in memory issues, unless you’re making a particle system or something.

Here is an example of this:

1
2
3
4
5

//...after previous code

Dog.prototype.getAgeInDogYears () {
    return this.getAge() * 7;
}

So this way you have the protection of encapsulated state, and avoid duplicating all your methods in every instance, thanks to prototypal inheritance. Now getters & setters may be distateful to you, but it is the best solution to this issue I can see, and it has the additional benefit of adding a layer of abstraction to your code, so you could change the way the state values are implemented, without changing a bunch of references to properties throughout the class.

Inheriting

As always, for inheritance to work with non-empty constructors, it is important that you explicitly call the prototype’s constructor:

1
2
3
4
5
6

function Daschund(name) {
    //...
    Dog.call(this, name);
}

Daschund.prototype = new Dog();

The Behaviour Encapsulation Dilemma

So we have private variables which can only be accessed by the get/set functions we declared in the constructor. But what about private functions? They too can be declared in the constructor function as inner functions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

function Dog (name) {

    var age = 0;

    //private function
    function scratch() {
        console.log("scratch");
    }

    this.getName = function () {
         return name;
    }

    this.getAge = function () {
         return age;
    }

    //example of setter:
    this.setAge = function (newAge) {
          age = newAge;
    }
}

The limitation here is that while such inner functions can be called by other functions which are defined within the constructor, they cannot be called by prototype methods. You could put all methods which need to access the private methods also inside your constructor, but then you’re back to the memory issue.

A way around this is to wrap the entire definition of the constructor and prototype in a closure function, which contains the private methods. This is basically the module pattern, and indeed if you are defining a constructor function inside a module, you can take advantage of the hiding effect of the module.

But there is an important gotcha here: these methods (and any other vars they access) are static: they are shared between all instances created with the constructor function contained within the same module. So you need to be aware of this. This is not a problem if you have static constants and ‘pure functions’ without side-effects encapsulated in your module. But it is potentially dangerous that one instance could call a method which could affect other instances… a kind of state contamination which is best avoided. Static and stateful just don’t go well together.

There’s also the issue that the module pattern may be too effective in preventing behaviour modification, and undermine the dynamic nature of the language.

Perhaps perhaps private instance methods are not absolutely necessary, and may be detrimental. AFAIK Smalltalk does not have them either, and takes a similar approach to that outlined here, of encapsulating state by only exposing methods (strictly speaking, ‘messages’, in Smalltalk), not properties. And Smalltalk is the archetypal Object Oriented language.

To be honest, I’ve never really found myself feeling the need for all this privacy, but I’m excited to have found a way to do it without using a third party Class system for JavaScript.

The 2.0 version is a nice Mac App, which I am using at home, but I also tried out version 1.x which is distributed as a RubyGem, and it worked fine on Ubuntu… and it apparently works fine on Windows too (after you have installed Ruby… see instructions on the GitHub readme).

After you have installed the app or gem, you can either embed a JavaScript on your page, or install browser plugins . I opted for the plugin route, which adds a button to your browser chrome allowing you to enable LiveReload for the current URL. Note that it is necessary to restart the browser completely for it to work. This means on Firefox you will need to restart twice: once to install the plugin, and again to get it working. Another issue I saw with Firefox was that the button didn’t show up on the addons toolbar, so I had to ‘customize’ my toolbars and add the ‘LR’ button which was now available as an option.

The other thing you need to do is tell LiveReload which folders to watch for changes. On the Mac App, you can use the Finder to select the folders, while with the RubyGem you need to give the folders as command line arguments.. or just type ‘livereload’ in the folder you want to watch, if there is only one.

Another benefit of LiveReload is that you can hitch multiple browsers up at once, to verify that your code behaves consistently across browsers. Great for cross-browser testing while you work.

Furthermore, when you are writing specs or unit tests for your code, you can have the tests running in another browser, and watch as they pass or fail, all without leaving your editor.

Finally, the version 2 has options to auto-compile SASS, Less, CoffeeScript and similar meta-languages which compile into HTML, CSS, or JavaScript. While the Mac App is initially free to use (it is still beta, but I did not experience any problems), I see that the update to the final 2.0 version will require some payment. However, if you just want auto-refreshing on changes, without pre-compilation, then you can continue to use the 1.0 version (or presumably the Beta App ?).

In case you are wondering how LiveReload works, I took a gander at the Javascript which the plugin embeds, and it uses WebSockets to receive notifications from the livereload app, which starts up a socket server

I think LiveReload is going to make my experience as a web developer much less annoying and more Zen-like :)

ps. I am not being paid by LiveReload to say any of this.. If you know of any other solutions to this perennial problem, I would certainly be interested to hear of them!

Here is how I do it …

Plugin management

I recommend using pathogen to manage plugins, as then you can simply clone the plugin repos into your .vim/bundle directory and you’re done. (and run ‘:Helptags’ to install help).

While this is not bad, I personally prefer another Javascript syntax definition file, which provides a more complete set of keywords (eg. browser events such as ‘onmouseover’), and thus highlights them differently. To use it, download and copy it to

~/.vim/syntax/javascript.vim

Now when viewing the same .js file, you will notice a few differences:

Folding

Another feature which this syntax file adds is the ability to fold functions. You can fold a function by positioning the cursor within it and typing ‘zc’. Then it will collapse to a single blue line with the function definition highlighted in it, and the number of lines contained within the fold. This can be a handy way to defocus attention from functions you are not interested in. It works in nested functions as well.

Whitespace settings

I generally want Javascript to have spaces instead of tabs, with 4 spaces for each indent level. This can be achieved by adding the following content as the file .vim/after/ftplugin/javascript.vim

" set whitespace for javascript to always use 4 spaces instead of tabs
setlocal expandtab
setlocal shiftwidth=4
setlocal shiftround
setlocal tabstop=4

Indentation

Vim’s default indent file for javascript merely sets the indentation to cindent… this is not very effective. For best results, go get the web-indent plugin.

Then you can use the builtin indent commands (essentially ‘=’ in command mode, combined with a motion, eg. ‘gg=G’ for the whole file, or just select some text in visual mode and hit ‘=’).

Here is a link to one of my favorite lifeforms, the Frothing Puffer:

In order to meet the size restriction of the competition, I had to leave out some functionality that I developed earlier, such as thumbnails of the lifeforms. So here is the uncut version, with thumbnails, and all of the lifeforms in it.

Actually, there are a couple of features in the competition version which are not in this version: The ability to link to a pattern using the URL, and also the ability to edit the seed pattern (albeit in text form). I have thoughts of making a version with a more visual editor, which would let you turn on cells by clicking on them, and perhaps save and share them with others. But I’m not sure if I’ll get around to it… life is short :P

I must give credit to the David Silver’s LIFE Lexicon, where I obtained the seed patterns. As always, Da Code is available on GitHub. Note that the competition version is in the JS10K branch.

HomeBrew

First I installed Homebrew, as I’m kind of sick of MacPorts and Fink (specifically how slow and out of date they tend to be). This was a matter of clicking on the ‘install homebrew today’ button, which linked me to their github page… where I found the following instructions.

/usr/bin/ruby -e "$(curl -fsSL https://raw.github.com/gist/323731)"

So as it turns out this did not work, and instead I got an error message about ca certs. Fortunately it did mention that I should add the -k option to turn to turn off strict cert checking. so I did this instead:

/usr/bin/ruby -e "$(curl -fsSLk https://raw.github.com/gist/323731)"

And it worked.

MongoDB

So I went over to the MongoDB site and specifically their Quickstart OS X page. Since I have homebrew now I did,

    brew update
    brew install mongodb

note that I did not need to use ‘sudo’ before either of these commands, which is nice. After installing, it instucted me to issue the following commands:

    mkdir -p ~/Library/LaunchAgents
    cp /usr/local/Cellar/mongodb/2.0.0-x86_64/org.mongodb.mongod.plist ~/Library/LaunchAgents/
    launchctl load -w ~/Library/LaunchAgents/org.mongodb.mongod.plist

Which I dutifully did. Note that the ‘launchctl load …’ command actually starts the ‘mongod’ database daemon, so there’s no need to start it manually. Simply typing ‘mongo’ starts the mongodb shell

    >: mongo
    MongoDB shell version: 2.0.0
    connecting to: test

Note that >: is my prompt, in case you’ve seen Lost you may get the joke :) Now I can create a ‘collection’ by saving an item to one, like so:

    > db.foo.save({a:1})

And I can query all the items of ‘foo’ like so:

    > db.foo.find()
    { "_id" : ObjectId("4e6ffd8928d02c8f55a09dbb"), "a" : 1 }

I’ve just got started with MongoDB, but I have to say it looks like it will be really nice to work with on personal projects. No more fussing around with database schemas! Yay!

Oh, yeah, to quit mongo, you just type:

 > quit()

First off, the conference has an Oregon Trail theme, which I did not understand until I saw this video by author Sloane Crosley, which explains the game’s appeal delightfully. (Skip to about the 2 minute mark for the actual reading)

Here are the ones I have checked out so far:

Bytes and Blobs (David Flanagan)

A really good explanation of the new Binary APIs for Javascript. Nice to see the author of the great Rhino book in person (at least virtually.) Kind of amusing to hear all the talk of BLOBs (Binary Large OBjects). This opens up a number of interesting possibilities, such as getting access to files from the user’s filesystem (with their permission, after they have selected it) without uploading them. Also image processing, and even audio processing and generation. However, browser support is still incomplete… Let’s hope IE supports these APIs in it’s next version.

The Future of Javascript (Rebecca Murphey)

This is a call to action to ensure that Javascript evolves properly, to prevent some of the quagmires we currently experience as developers. In a nutshell, we need to agree on common standards and protocols to prevent duplication of effort. Some of this work is underway, eg CommonJS, promisesA. Also some interesting facts about the history of the automobile and the road system which we take for granted.

The Future of JS and You (Alex Russel and Peter Hallman)

A look behind the scenes of the Traceur Javascript compiler, which lets you write futuristic Harmony flavored Javascript, and generates present-day Javascript. This reminds me a bit of CoffeeScript, though here you’re still writing Javascript, albeit a version which does not yet exist. The suggestion is that you can invent your own Javascript.next features and hack the compiler to support them. If you’re interested in writing a compiler in Javascript, this would be a good place to start.

‘Freestyle RPC for Node’ (James Halliday) An entertaining presentation on James’s dnode node module which allows seamless remoting between client and server code. perhaps not the most elucidating presentation (there is about 10min of random rapping towards the end) but DNode does indeed look awesome.

It seems like every single session from these conferences is available here. The only confusing thing is that the videos do not always have the same titles as the sessions at the conferences, so you may need to cross-reference with the jsconf programme

Ah, I am so nostalgic for the old NodeJS logo :/

First off, though, I should address the different terminology here: what is ‘behaviour driven development’ anyways? Why isn’t it called a Unit Testing framework? To understand why, you should read this article The idea that the names matter really rings true for me and it always seemed weird to me to try and test something which does not yet exist. Thinking of ‘specifications’ rather than ‘tests’ makes a lot more sense to me. Also, thinking about testing ‘units’ of code is more likely to make your tests closely coupled to your implementation, leading to maintenance headaches and unnecessary, verbose tests.

Installing Jasmine is ridiculously easy: I just downloaded the standalone project, and extracted it as the ‘specs’ folder in the Canvasteroids project. Inside it is a SpecRunner.html file.. opening up this in a browser will run the dummy tests which are there by way of example. Then I removed them so that I could run my own specs. I also installed some Jasmine Snippets for Vim to make writing specs even easier.

I created a new spec file called BreakoutSpec.js in the specs/ folder and added the following:

1
2
3
4
5
6
7
8
9
10
11
12
13

describe("Breakout Game Specs", function () {

    var game;

    beforeEach(function () {
        game = new breakout.Breakout();
    });

    it("should exist", function () {
        expect(game).toBeDefined();
    });

});

The describe() function defines a Suite of Specs. The function given to it as its second argument contains the specs themselves. Each spec is defined by an it() function call, which similarly takes a function as its second argument. The first argument to both describe() and it() is a descriptive string which will be shown in reports. Within the it() function there are calls to expect() which will check specific things to determine whether the Spec has been fulfilled. See the list of them here. In this case we are simply checking that the Breakout game instance was created successfully. Obviously, beforeEach() is run before each spec. We need to include the spec in the SpecRunner.html file, which now looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<!DOCTYPE html>
<html>
    <head>
        <title>Jasmine Test Runner</title>
        <link rel="stylesheet" type="text/css" href="lib/jasmine-1.0.2/jasmine.css">
        <script type="text/javascript" src="lib/jasmine-1.0.2/jasmine.js"></script>
        <script type="text/javascript" src="lib/jasmine-1.0.2/jasmine-html.js"></script>

        <!-- include spec files here... -->
        <script type="text/javascript" src="spec/BreakoutSpec.js"></script>

    </head>
<body>

<script type="text/javascript">
        jasmine.getEnv().addReporter(new jasmine.TrivialReporter());
        jasmine.getEnv().execute();
</script>

</body>
</html>

Refreshing the SpecRunner.html file, we see that this Spec fails. There are two failures, one which is the result of a run-time error while executing the spec (because the namespace ‘breakout’ in ‘breakout.Breakout’ is undefined, and because the expectation was not met (because ‘game’ was not defined).

So, I made a new folder called ‘breakout’ in the games folder, and copied the index.html file from Asteroids into it, renaming the reference to the Asteroids game class to be Breakout. I also created the new game class in a file alongside the index.html file, called Breakout.js, with the following Ext 4 class definition in it:

1
2
3
4

Ext.define('breakout.Breakout', {
    constructor: function () {
    }
});

So we have a Breakout class now, but how do we load it in our test runner? Why not use the Ext JS 4 Class loader, just as we do in the game itself? This is what the updated SpecRunner looks like (we also need to load the ext-foundation.js file).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<!DOCTYPE html>
<html>
<head>
    <title>Jasmine Test Runner</title>
    <link rel="stylesheet" type="text/css" href="lib/jasmine-1.0.2/jasmine.css">
    <script type="text/javascript" src="lib/jasmine-1.0.2/jasmine.js"></script>
    <script type="text/javascript" src="lib/jasmine-1.0.2/jasmine-html.js"></script>

    <!-- include Ext JS 4 Class framework -->
    <script src="../lib/extjs/ext-foundation.js" type="text/javascript" charset="utf-8"></script>

    <!-- include spec files here... -->
    <script type="text/javascript" src="spec/BreakoutSpec.js"></script>

</head>
<body>

<script type="text/javascript">
    Ext.Loader.setConfig({
        paths: {
            'breakout': '../games/breakout'
            },
            enabled: true
        });
        Ext.require('breakout.Breakout');
        Ext.onReady(function () {
            jasmine.getEnv().addReporter(new jasmine.TrivialReporter());
            jasmine.getEnv().execute();
        });
</script>

</body>
</html>

Note that we made the call to Ext.Loader.setConfig(), defining the required namespace ‘breakout’ to be the relative path of the directory containing the class file. And we wrapped the Jasmine code in a call to Ext.onReady(), which will only execute when the classes required have been loaded. This is handy, because we will not have to worry about adding them to the SpecRunner, which can be a chore with other Javascript Testing frameworks I’ve used. We will however need to update the paths of the namespaces used by any classes in the application, so that any namespaces are correctly resolved. And when we run the SpecRunner again … we get the green light! The spec succeeded.

So I admit this is a trivial spec… but it should be enough to get you started with Jasmine and Ext JS4.

Ext JS 4 is well modularized, and you can use as little or as much of it as you like. For the Canvasteroids game framework that I’m working on, I decided to use the ‘ext-foundation.js’ file which is the essential core of the library, which defines the Class management system, as well as a useful collection of utility methods for the core Javascript types. However no changes are made to the native object prototypes, so there will not be complications when combining Ext 4 with other frameworks.

The Ext JS 4 class system lets you define a class as follows:

1
2
3
4
5
6
7
8
9

Ext.define('some.Thing', {
    extend: 'some.ThingElse',
    constructor: function () {
        this.name = "Thing1";
    },
    greet: function () {
        alert("o hai");
    }
});

Obviously, the ‘constructor’ function is what becomes the class constructor. The ‘extend’ property will cause this class to inherit the given class. Note also the use of namespaces, eg ‘foo.Bar’ in the names of classes. In Ext JS 3 you had to explicitly declare all your namespaces, but in v4 this is handled automagically.

Mix it up with Mixins

Additionally, you can have ‘mixins’ which add in methods (or properties) of the given class. This is very helpful as it enables another way of re-using code besides inheritance. This is how you declare mixins (an example from Canvasteroids):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Ext.define('drawable.DrawableLine', {
    extend: 'geometry.Line',
    mixins: ['drawable.Drawable'],
    constructor: function (props) {
        this.callParent([props]);
        //this is a base drawable class -- set context (required property)
        this.initDrawable(this.context);
    },
    draw: function (ctx) {
        this.beforeDraw(ctx);
        this.ctx.beginPath();
        this.ctx.moveTo(this.start.x, this.start.y);
        this.ctx.lineTo(this.end.x, this.end.y);
        this.ctx.stroke();
        this.afterDraw(ctx);
    }
});

The initDrawable(), beforeDraw(), draw(), and afterDraw() methods all come from the Drawable mixin class (which is defined in the same was a regular class except it does not have a constructor). Drawing is a behaviour, and this is a good use case for using a Mixin. As with inheritance, you can override methods or properties from a Mixin class. In this case I overrode the ‘draw’ method with a custom implementation. In this way Mixins can act like Abstract Classes, but you are free to use more than one at a time.

callParent() is super!

Also note the call to callParent() : this is equivalent to super() in ActionScript.. it calls the same method from which it is called on the parent class. So in a constructor it will call the super-class’s constructor. Note that the arguments must be passed as an array.

Getting Loaded with Ext.Loader

If you’ve worked on a large scale Javascript application, you know it can become a pain to maintain a large number of script tags, and resolve dependencies. Every time you add a new class to the system, you have to add it to the list of scripts includes in your HTML page, and you have to figure out where in the list of includes it has to go in order to have all of its dependencies satisfied and to satisfy its dependents. This is usually done by trial and error and can be quite annoying. Ext.Loader to the rescue! Once properly configured, you will never need to add another script tag again! Here’s how to set up dynamic loading in your main HTML file:

1
2

<script src="../../lib/extjs/ext-foundation-debug.js" type="text/javascript"><!--mce:0--></script>
<script type="text/javascript"><!--mce:1--></script>

The ‘enabled:true’ attribute of the object passed to Ext.Loader.setConfig() is what turns on the dynamic loading of classes. When this is turned on, Ext JS will dynamically add a ‘script’ tag when it notices that it needs to load a class. By default, it will look for a file with the same name as the class (replacing ‘.’ with ‘/’) relative to the HTML file. If you wish to use a different path you will need to add a mapping to the ‘paths’ hash object. By default, the ‘Ext’ namespace is mapped to the ‘src’ directory of the library so it will load other classes from the framework if you are using them.

Then you load your main app using a call to Ext.require(). In this case I required the main Asteroids game class, which was in the same directory as the HTML file this code is in. The ‘Asteroids’ class itself has multiple dependent classes, and the Loader will recursively parse them until they are all satisfied.For example the ‘canvasutils.Context2D’ class will be resolved to ‘../../lib/canvasutils/Context2D.js’. NB: make sure you name your class correctly, or errors will occur in the loading process. In addition to any classes referenced in an ‘extends’ or ‘mixins’ definition, there is a ‘requires’ property which can be used to explicitly declare a class’s dependencies. For example in the Asteroids class, I have defined the requires as follows:

1
2
3
4
5
6
7

Ext.define('Asteroids', {
    extend: 'oop.InitProps',
    requires: ['eventbus.EventBus', 'controller.TouchPad', 'drawable.DrawableLine',
     'soundeffects.SoundEffects', 'sprites.Rock', 'sprites.Ship', 'sprites.ShipFragment',
     'sprites.Bullet', 'drawable.Layer', 'controller.Keyboard', 'ui.Button', 'ui.Text',
     'interactive.DraggableLayer'],
    //...

When the Loader is enabled, Ext JS will wait until all the dependent classes have been loaded before executing Ext.onReady(). At this point you can simply instantiate the class normally with ‘new’ as I have done. Alternatively, you can use Ext.create() with the class name as a string. This has the advantage that if for some reason the class was not loaded, the Loader will load the class synchronously. However, this is non-optimal for performance, and you will be warned in the console about this. Since I want to avoid this, and for ease of debugging, I tend to use the old fashioned form of instantiation with ‘new Xxx()’, and remember to add the class to the list of ‘requires’.

Note that the order of the classes in the ‘requires’ array does not matter.

Building a Deployment version

While loading .js files dynamically is nice for debugging, it is not optimal for deployment, due to all the additional HTTP requests. It is recommended to combine all the required Javascript files into one, and compress it by removing comments, whitespace, etc. If you have used the Ext.Loader as I describe above, this will be very easy. First you will need to install the free Sencha tools from here (see the links for the different platforms tools near the bottom of the page). Then use a terminal to go to the same directory as you HTML file and type the following command:

1

sencha create jsb -a index.html -p app.jsb3

This will create a .jsb3 (JSBuilder, Sencha’s JavaScript compression tool) configuration file for the application. If that worked then do this:

1

sencha build -p app.jsb3 -d .

And you should have a app-all.js file which will be the combined and compressed version of your app. You should create another HTML file for deployment which references this file, rather than the Ext.Loader config we used for develpoment. That’s it! Your Ext JS 4 app is ready to go.

This is a brief overview of the Class system, for more info see the excellent docs:

Class System docs

Ext JS 4 Getting Started

• score
• lives
• game over after 3 lives lost
• an animation when the rocket is being thrusted
• enhancements to the firing of bullets
• a new Text class for the framework (used to display the lives and score)

Some kind folks from the Chico State Open Source Team had picked my project to flex their programming skills. I was quite impressed with the quality of their contributions, and that they were able to dive into the project which I admit is not really documented at all.

This has inspired me to continue my efforts on Canvasteroids, as well as documenting it better, to enable further collaboration. I’ve since posted on my blog about one of the patterns I use in the framework: ‘State and Transition Oriented Programming’. I’ve also started on a second game, which I will hopefully be launching soon.

To summarize, in case you’re not done watching it yet.. States are a very important aspect of programming interactive systems, but they are often neglected and as a result can lead to nasty bugs. By dealing with states carefully and consciously it becomes a lot easier to develop more complex systems. Troy developed a framework in ActionScript to provide readymade support for state management and transitions.

It would be possible to port the framework to JavaScript, but the basic idea is so simple that it does not require a framework to implement and benefit from using it. This post is my attempt to describe how to do that.

Usually, from what I’ve seen, states are defined as constants, or enums or something like that, and assigned to some global variable…

1
2
3
4

if (isHoliday)
    STATE = "happy";
else
    STATE = "sad";

Then later on, there will be forks in the code to do different things depending on the state:

1
2
3
4

if (STATE === "happy")
    smile();
else if (STATE === "sad")
    frown();

While this works fine most of the time, you can quickly end up with a mess of duplciated conditional logic all over the place, as every time you need to do something, you have to check which State is active to decide if and how you’re going to do it.

It’s worth considering the difference between lowercase ‘state’ and uppercase State. The former is simply the values of variables that your application contains. This is vague and generalized and not what I’m referring to here. The uppercase State refers to a global condition which usually corresponds to a phase of activity of the application. For example a video player component might be ‘loading’ or ‘playing’ or ‘paused’. The State of the application fundamentally changes its behaviour, and how it will respond to events. Having said this, I’m not going to consistently capitalize ‘State’, but I’m always referring to the this more specific meaning of the word.

Events are things that happen in your application, whether it is user input or a result of processing or time passing. A collision between two objects is an example of a typical event in a game for example. Depending on which State the application is in, events will be handled differently. When events occur, we can send ‘messages’ or ‘signals’ to the currently active State, which can decide how to respond.

The idea that I’ve borrowed/stolen from Troy Gardner is to implement States as functions. Since they are essentially global constants, they are capitalized. This also indicates their special significance, and differentiates them from reqular functions. Here is how the two states of a light switch might be implemented (if we visualize the switch as having two buttons, ‘off’ and ‘on’):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

var state = OFF;

offBtn.onClick = function () {
    state("turn_off");
}

onBtn.onClick = function () {
    state("turn_on");
}

function OFF(msg) {
    if(msg === "turn_on") {
        turnLightOn();
        state = ON;
    }
}

function ON(msg) {
    if(msg === "turn_off") {
        turnLightOff();
        state = OFF;
    }
}

Notice how the event handlers did not have to know about the different States of the application, but simply sent a message to the currently active State function, which is dynamically assigned when the state is set. Assigning the State function to the ‘state’ variable effectively sets the State, and alters the behaviour of the system… Note how the OFF State does not respond to the ‘turn_off’ message, and the ON State does not respond to the ‘turn_on’ message. There is no switching on the state value - rather the State function will handle the messages it is sent, ignoring any it is not interested in.

Transitions

It is often necessary to perform actions when changing from one State to another. But it can be easily done by using ‘enter’ and ‘exit’ messages which are passed to every State when they are made active or deactivated. The way to make this happen is to use a ‘changeState()’ function to change from one state to another:

1
2
3
4
5

function changeState(newState) {
    this.state('exit');
    this.state = newState;
    this.state('enter');
}

Then you can manage your transitions by listening for these messages in your State functions:

1
2
3
4
5
6
7
8
9
10

function DAY(msg) {
    if (msg === "enter") {
        wakeUp();
    } else if(msg = "exit") {
        turnLightsOn();
    }
}

changeState(DAY);
changeState(NIGHT);//lights get turned on

Hierarchical States

If you want to nest States, eg. LUNCH within DAY, this can be done by passing on any unknown messages to the super-state:

1
2
3
4
5
6
7

function LUNCH (msg) {
    if(msg === "eat") {
        eatLunch();
    } else {
        DAY(msg);//eg "check_email" msg would be handled by DAY
    }
}

If you have events which need to be handled at any time, they can be put in a BASE state, and other states can pass on messages to it. For example, if the user resizes the browser window, there could be a ‘resize’ message which would be handled by the BASE State:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

function BASE (msg) {
    if (msg === "resize") {
        resizeGame();
    }
}

function PLAYING (msg) {

    if (msg === "scored") {
        increaseScore();
    }

    //always pass on messages to BASE
    BASE(msg);//resize will be handled

}

As you can see by comparing these two examples, you have the option of passing all messages to the super-state, or only passing on unknown messages.

This method of handling events by sending messages to State functions is very flexible and dynamic, and makes adding new States easy. It adds some abstraction between events and the response to them, which reduces coupling within your application. It also reduces duplication and conditional branching, and I think it also makes the code easier to read, as behaviours are grouped by State and message, which should be self-descriptive.

Finally, STOP programming is not opposed in any way to OOP, but is orthogonal to it. I have found it to be particularly useful in developing games, which tend to have many different states with different behaviours.

For a more complex example of this pattern in action, see the Asteroids game.

I want to write some more posts about some of the techniques I used to get the game working, especially the collision detection. I found a way to do this using the Canvas ‘isPointInPath’ method, which seems to perform quite well. The game uses keyboard for controls (left-right arrows for turning, spacebar to fire) and I also added some mouse/touch control inspired by Seb Deslisle’s JSTouchController. I don’t think the game is really well suited to touch, but at least I learned how to handle the touch events. If anyone has an iPad I’d be interested to know how it works.. unfortunately I heard the performance of Canvas is not great on iOS. However I’m really not into targeting one platform, and I’d like the games to be playable on any desktop or mobile device which has a decent browser (ie supports Canvas). For the IE < 9 users, I added Chrome Frame. For sound I used SoundManager2. The actual sounds were recorded off my Atari 2600 during gameplay, and edited in Audacity.

Anyways, enough nerdy banter.. here’s the game (warning LOUD sound effects!).

I used GitHub’s nifty new pages feature (plus a domain) to host a site here:

canvasteroids.com

And for all your source-y needs, the Github repo

Another benefit is performance.. loading scripts should be asynchonous for best usage of the network. Traditional <script> tags are synchronous and blocking, even if the code is not immediately required. Other approaches to loading code use XHR & eval() which makes debugging hard, and restrict to same origin (though there are workarounds). So RequireJS creates script tags dynamically, and appends them to the head of the document.

OK, how do you use it ? If you simply want to include an external script (whatever it may be), you can do this:

1
2
3

require(["some/script.js"], function () {
    //do stuff once it is loaded
});

So what is going one here is that the first argument to ‘require()’ is an array of dependencies, which are paths to Javascript files. The callback function is executed once the file has been loaded. Pretty simple. However the real power of RequireJS comes about when you also define your modules with a special define() function, which in turn declare their dependencies.. and so on, and so on, recursively. Usually, the Module Pattern is implemented with a closure function:

1
2
3
4
5
6
7
8

MyModule = (function () {
    function boo() {
        alert("boo!");
    }
    return {
        frighten: boo
    }
})();

With RequireJS you use the define() function instead of the anonymous closure:

1
2
3
4
5
6
7
8
9
10

define(['dependency/first', 'deependency/second'] , function (d1, d2) {
    //when this gets called, the dependencies are loaded and available as d1, d2
    function boo() {
        alert("boo!");
    }
    //you must return the module explicitly:
    return {
        frighten: boo
    }
});

If this was in a file called /scripts/scary.js, you could obtain an instance of the module as follows (in /index.html):

1

  <script type="text/javascript"><!--mce:0--></script>

Notice that there is no .js on the end of the filename. RequireJS will see that and look for a define() function in the file to get the module with. Note that if you omit the .js on the path, the module must be defined using the define(). Another option, which avoids using any inline script in your HTML, is to use a <script> tag with require.js as the ‘src’, and give a data-main attribute to indicate the entry point of your app.

1

 <script src="scripts/require.js"><!--mce:1--></script>

This would work if we had a script called ‘main.js’ in the scripts folder with something like this in it:

1
2
3

define(['scary'], function (scary)) {
    scary.boo();
};

Notice how the dependency is passed as an argument to the callback function. If there are more than one dependency, they will be passed as additional arguments, in the same order as the dependencies.

If you need to interact with the DOM, you should be aware that your dependencies may be loaded before the document itself is loaded, so you can use the require.ready() function which fires when the document is ready AND all dependencies have loaded…

1
2
3
4
5
6
7

define(['scary'], function (scary)) {
    require.ready(function () {
        //start app
        scary.boo();
        //do DOM stuff...
    });
};

Note that the module name is relative to the directory containing the ‘data-main’ module. Also note, require.ready() uses window.onload for browsers (mostly IE) which do not support the DOMContentLoaded event. This may be slow if you have a lot of stuff on your page.

An example of more advanced usage is that an object literal can be passed in as the first argument to the require() function, to add some additional customization, eg, setting a baseURL, or some paths which will be expanded in the names of the dependencies.

Advanced Usage: CommonJS Compatibility

CommonJS is a JS package standard, used by, eg. NPM (Node Package Manager – see previous post). Therefore it is desirable that RequireJS would grok CommonJS packages. However, you need to specify some additional configuration in you package.json for this to work, eg.

1
2

lib: 'some/dir', //the dir containing the modules, (default = lib)
main: 'script/app' //the name of the module in the lib dir which will be used when someone require() 's the packageName (default = lib/main))

NB: for the package’s modules to be loaded they must be wrapped in a define () function as below .. this can be done manually or with a script (RequireJS provides some scripts for mass conversion).

1
2
3
4
5

define(function(require, exports, module) {
    exports.boo = function () {
        alert("boo!");
    }
});

This must be exactly specified as above! (ie the parameters of the function must be ‘require’, ‘exports’, ‘module’ in that order). This seems a bit weird … how do you declare dependencies, if you must stick to this exact function signature? Well, the answer is that there is some magic at work… RequireJS looks for any ‘require()’ function calls in your module, and makes sure they are all loaded before the function is called! This is done because CommonJS has its own require() function, which is synchronous, so RequireJS essentially overrides it with its own asynchronous version. It is the ‘require’ parameter which triggers this behaviour. But what about the ‘exports’ and ‘module’ parameters ? Well, the exports argument is what will be returned when require() is called for this module. It is not necessary to return anything from the define() function, the value of ‘exports’ will be automatically returned. I’m not quite sure what the ‘module’ argument is for, as I haven’t seen it used anywhere, so its probably best to leave it alone.. perhaps it just provides backwards compatibility with CommonJS syntax? In fact, it is possible to leave out the ‘exports’ and ‘module’ arguments if you return the module explicitly from the function given to define() .. exactly as in normal non-CommonJS usage. See here.

Optimization

RequireJS provides an optimization tool, which uses UglifyJS as its compressor.

TO use it, clone or download the RequireJS source code as a sibling of your project and run the following command from the scripts (or lib, if in a CommonJS package) dir:

1

   ../../requirejs/build/build.sh name=main out=main-built.js baseUrl=.

And you will have a compressed main-built.js file with all your dependencies in it, so they can be required with a single HTTP request. Eg., you could change the script tag above to:

1

  <script src="scripts/require.js"><!--mce:2--></script>;

The RequireJS docs are excellent, and even nice to look at, so I recommend checking them out for more info, or if this becomes out of date…

API Docs

http://requirejs.org/docs/api.html

I’ve recently discovered some neat tools which help make Javascript development easier. Everyone is excited about HTML5, which Brendan Eich (the inventor of Javascript) describes as ‘The unicorn which craps skittles from its rear end’. The Javascript language awaits a much needed update with ES5 Harmony, but in the meantime it has access to some cool new APIs in the form of HTML5 features such as Canvas, Local Storage, etc.

But what about outside of the browser? There have been some attempts to use Javascript on the server, but they don’t seem to have gained much widespread adoption. Then came NodeJS. If you haven’t heard about NodeJS I recommend you checkout this video by Ryan Dahl, the creator of NodeJS:

NodeJS is revolutionary in that it give Javascript access to the filesystem and network, with a performance oriented event-based approach that solves concurrency elegantly without the pain of multithreading. In itself this might only be interesting to hardcore server geeks, but NodeJS is being used as the infrastructure for a lot of other projects. Some of them are deployed by NPM, the Node Package Manager, which (surprise!) is a package management system for NodeJS applications. So once you have installed NodeJS and NPM, you can easily install other libraries on the command line. And you can create your own projects, using the CommonJS package format. This is made easy by the ‘npm init’ command, which creates a package.json configuration file for you automatically (I will give an example later).

But what if you’re more interested in client-side applications which run in a web-browser? No problem! Teleport comes to the rescue. This is itself a NodeJS package which you can install using NPM. Now once you have created a basic NPM / Common JS app, you just include the teleport library as a dependency. Then you can write your Javascript just as you usually would for a web-app. To test the app in a browser you run ‘teleport activate’ and Teleported will spawn a nodeJS webserver with your app running in it.

Once you have an awesome app ready, you can publish it to the NPM repository library with a single command (npm publish), so that other people can install it. No fussing about with web servers or downloading code. I’m really excited about the possibilities this creates for sharing client-server applications where the server is your own machine. Suddenly Javascript becomes a viable language for serious desktop applications with access to the filesystem and the network, as well as all the new HTML5 GUI goodness. Because the app runs on your own system, you can run it offline, and performance is going to be way better than over the internet.

In order to demonstrate just how easy this all is I will break it down for you, assuming you have nothing installed. Here we go:

Prerequisites:

• Install Node JS and NPM
• Install Teleport:

sudo npm install teleport

Create a NPM app (I called mine frappuccino) using the command line:

mkdir frappucino
cd frappucino
npm init

At this point, you will go through a wizard to generate the package.conf file. It is just to provide metadata for your app, don’t worry too much about the answers, most of them are fine as they are. You can always edit it afterwards. For the ‘module entry point’ question I left it as default, and for the ‘where do your modules live’ I said ‘lib’ (this is standard, but not default). It actually guessed I was using a Git repo which I have in my home directory, which is not the repo I want to use, so I had to remove that reference afterwards. If you run it in a git repo, it will figure it out and use the info from that for the repository info. So if you want to do that, you should create the git repo first. After removing the incorrect repo info, my package.conf file looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
    "name": "frappucino",
    "description": "Frothy App",
    "version": "0.0.0",
    "author": "David Wilhelm ",
    "directories": {
        "lib": "lib"
    },
    "engines": {
        "node": "*"
    },
    "dependencies": {
        "teleport": "<=0.2.2"
    }
}

The other change I made was to add the “dependencies” config, which will ensure that Teleport is installed as a dependency. OK, there are now a couple of other files you need to create:

The index.html page. Mine looks like this:

1
2

<script src="support/teleport/teleport.js" type="text/javascript"></script>
<script type="text/javascript"></script>

Note the included teleport file (which npm will supply), and the application js file (which we will create next). Now create the /lib folder in the frappucino folder, and in it create a file called app.js. In it I have the following, as a test.

alert("Frappucino is the best!");

Ok, now you should have the following file structure:

frappucino/
    index.html
    package.json
    lib/
        app.js

Finally, to get npm to supply the dependencies, and register the app locally, type this within the ‘frappucino’ directory:

sudo npm link

I get some nice pink and green output with ‘npm ok’ at the end to let me know it worked.

Now, to run the app, do:

teleport activate

If all goes, well, it should say something like:

Teleport is activated: http://localhost:4747/frappucino

Now you can open another terminal window and type:

open http://localhost:4747/frappucino

And you will see your app in all its glory (or lack thereof, such as in this case.. just an alert window. But its a start :).

So check it out, and rate it ! It turns out that community voting is no longer considered for the Community Prize, but it will make me feel better :)

I posted the source code on github also.

One of my earliest experiences of computer programming was when my school acquired a computer lab, and we did some Turtle Graphics programming, probably in Logo. The school even had a robotic turtle which was used to draw lines on paper on the floor. I think one project we did was to draw the letters of the alphabet which made up the name of the school, or some other message. In any case I remember making the turtle go round drawing lines.

Earlier this year I read Mindstorms by Seymour Papert, which describes how computers can be used by children to learn about Mathematics and programming, and how the Turtle Graphics system is a better system for exploratory learning than the Math is conventionally taught. One of the reasons for this is that the child is able to identify with the turtle, and solve problems by walking out the path of the turtle, and performing the instructions of the program. There is a fascinating description of how younger children were actually better at figuring out how to get the turtle to draw a circle by going forward a bit and turning a bit repeatedly, than were older children who had already learned more objective facts about circles, such as that they have a radius and a center. Even older children who had learned the algebraic formula for a circle were actually incapable of solving the problem.

Recently I discovered the Holy Grail of the field, the definitive Turtle Graphics by Andrea di Sessa and Harold Abelson, who also co-wrote the Structure and Interpretation of Computer Programming. I’ve only just read the first chapter, but I was inspired to try out implementing a Turtle Graphics environment in Javascript, using Canvas as a rendering surface.

I started out typing my functions into the Javascript Console of Chrome, but I had a vision of a web-based interactive Turtle Graphics environment, where users could run their own code and see the results instantly. So this weekend I hacked together the Turtle Graphics Explorer. Its not going to work in any released version of IE (I’ll add Chrome Frame soon), but that will change when IE9 ships. A new version of Chrome, Safari, Firefox, or Opera should be fine, though I admit I’ve not tested thoroughly. Hopefully it is easy to understand.. load an example, or look at the procedures to see how they work. There is only very rudimentary error detection, so if it does not seem to be working, you may need to re-load a working example, hit ‘clear screen’, or just refresh the browser.

Here is a screenshoot of the application.. click on it to open it up, and start exploring ;)

All the code is available at the GitHub project.

flash 10 required

It is currently implemented as a base class which exposes the following methods:

    rotate(angleX, angleY, angleZ)
    draw(x,y,z)
    move(x,y,z)

    pushMatrix()
    popMatrix()

The x, y, z values here are relative to the current position. The current position (and rotation) is maintained by the modelViewMatrix. By calling pushMatrix() you can save the current state and return to it later with popMatrix(). If you have subroutines, it is generally a good idea if they return the modelViewMatrix to the same state. For example in this example the drawSquare() method does this:

private function drawSquare()
{
    draw(100,0,0);
    rotate(0,0,90);
    draw(100,0,0);
    rotate(0,0,90);
    draw(100,0,0);
    rotate(0,0,90);
    draw(100,0,0);
    rotate(0,0,90);//return to starting orientation
}

So this simply draws 4 lines of length 100, rotating 90 degrees around the Z axis. The final rotation isn’t necessary for the drawing, but it ensures that the state is not changed after the routine is called. To draw a cube, we call the drawSquare routine while rotating and moving in 3D.

private function drawCube()
{
    //draw cube
    //back
    drawSquare();

    //left
    pushMatrix();
    rotate(0,90,0);
    drawSquare();
    popMatrix();

    //top
    pushMatrix();
    rotate(-90,0,0);
    drawSquare();
    popMatrix();

    //right
    pushMatrix();
    move(100,0,0);
    rotate(0,90,0);
    drawSquare();
    popMatrix();

    //bottom
    pushMatrix();
    move(0,100,0);
    rotate(-90,0,0);
    drawSquare();
    popMatrix();

    //front 
    pushMatrix();
    move(0,0,-100);
    drawSquare();
    popMatrix();

}

finally, to draw the cubes, we call the drawCube() routine inbetween calls to push/popMatrix() and any changes in position we wish to make.

    pushMatrix();
    drawCube();
    popMatrix();

    pushMatrix();
    move(150,0,0);
    drawCube();
    popMatrix();

    pushMatrix();
    move(-150,0,0);
    drawCube();
    popMatrix();

Once you get the hang of this approach, it is quite intuitive, and reduces the need for calculating a lot of 3D coordinates. This is done behind the scenes in the draw() method, which adds the real 3D coordinates to a list of vertices, which ultimately get projected to 2D coordinates. It’s easy to rotate the objects in the scene by calling rotate() before drawing the objects in the scene.

I’ve used Haxe here because of the faster compile time. There is also an earlier ActionScript version which I’ll link to below.

Da Code

DrawCubes.hx

Draw3D.hx

MatrixStack.as (the AS3 prototype)

GitHub

flash 10 required

How it Was Done

The mechanics of this are essentially the same as the lighting of a sphere technique described in the normal map tutorial. However, since the shape of the heart is not the same as a sphere, I could not use the sphere formula to generate the normal map. So I just used the same formula to generate the normal map as I did to generate the geometry. For each point on the texture map, I determined the lat/lon of that point, and plugged it in to the formula to get its 3D position. I did the same for the pixel above and to the right. Since we now have three points, we have a triangle, and we can get the normal of the triangle by the cross-product of two of the sides (considered as vectors). This normal gets encoded as a color in the resulting normal map. This is a fairly intensive operation, but since it is only required once at the start, it doesn’t affect the running performance. I tried to optimize this process by using a PixelBender kernel to generate the normal map, but got some odd results, so returned to more familiar ActionScript territory. Using a shader to generate the normal map will become necessary if the geometry changes a lot.

I also refactored the code a lot so that it’s not all in one class. I’ve separated the model, shader and renderer into separate classes, and used a Scene to coordinate them. This is the beginnings of a primitive 3D engine, which I’ve dubbed DeepSee, so if that goes anywhere I may break it out as a separate project on GitHub.

Da Code

Heart2
DeepScene
Heart.as
IModel.as
NormalMapShader
NormalMapShader.pbk

Ctags, specifically exuberant ctags is a code-indexing system that creates files which summarize all the methods and properties in your classes. Its also the name of the command line utility that performs the indexing on source code and generates the tags files.

Ctags and Vim go hand in hand.. by specifying tags files to use in your .vimrc file, vim will be able to jump to the file where a class, method, or property is defined. Tags are also used for code-completion, and syntax highlighting.

Unfortunately ActionScript is not natively supported by ctags. Fortunately it is not hard to add support for it. I found out here how to do this for JEdit, but the process is much the same for Vim.

1. Download Ctags source. I used ctags-5.8.tar.gz which worked on my Ubuntu and Mac. I just put it in $HOME/ctags/ and extracted it with ‘tar zxvf ctags-5.8.tar.gz’

2. Ok , go into the source directory (ctags-5.8 or whatever your version is)

3. Add this actionscript.c file into the source directory (you’ll need to Save As… actionscript.c, as github doesn’t seem to have a per-file download link). I found that the version linked the JEdit example did not work in Vim, so I modified the RegEx expressions in it so that they produced more standard tags.

4. In source.mak, add a line that says “actionscript.c " under SOURCES and “actionscript.$(OBJEXT) " under OBJECTS.

5. In parsers.h, we need to add the following line under #define PARSER_LIST:

   ActionScriptParser, \ 

   (an easy way to make these changes is just copy the line and edit the language name)

6. Build it. Do the usual

   ./configure make

You may need to do a ‘make clean’ first to remove any previous builds.

1. Try ‘./ctags –list-languages’, and actionscript one should show up. Then if looks good, go ahead with the final ‘sudo make install’. Thats it.

Now for usage … to build a tags file for a AS3 project in a ‘src’ folder, just do the following:

ctags -R -f tags path/to/src

Eg. I made a tags file for the Flex SDK:

ctags -R -f ${FLEX_HOME}/frameworks/projects/framework/src/tags ${FLEX_HOME}/frameworks/projects/framework/src

ctags may not be happy about generating a tags file over an existing file, so you may need to remove a previous one first. It may also warn about some null references in source code.. this doesn’t seem to matter.

Then I added the line

set tags+=$FLEX_HOME/frameworks/projects/framework/src/tags

to my .vimrc, and I can jump to any Flex SDK file by ctrl-] on the name of a class, method, or property. (ctrl-t jumps back). I can also recommend the taglist plugin. This instantly makes tags for your current file and shows the symbols (organized by type) in a window split.

I also found that it was easy to add support for Haxe, by renaming a few things in the actionscript.c file and renaming it haxe.c (and making the other additions to sources.mak and parsers.h). You can probably figure it our yourself, or you can download the added and patched files here:

ctags_as3_haxe_patched_files.tar.gz

Augmented Reality (AR) was one of the big things to appear on the flash scene last year. AR has been around for a while, but it new in flash… The FLARToolkit, is an ActionScript port (by Saqoosha, whom I got to see at FITC last year) of a Java AR library (NyARToolkit) IIRC, which was itself derived from the original C version (ARToolkit).

As an interesting aside: ARToolkit isn’t the only AR library implemented in C, though it was the first… there is also ARTag which “uses more complex image processing and digital symbol processing to achieve a higher reliability and immunity to lighting”. For the limited processing power of Flash, ARToolkit was probably a good start, but perhaps some smart people may be able to enhance its recognition by improving the algorithms.

When I tried to use FLARToolkit, I’ll admit I had some trouble, as it seemed rather complex and not very well documented (at least not in English). But fortunately I found FLARManager which makes setting up an AR project in Flash a lot simpler. It also provides some optimizations to the recognition process.

However I feel it could be made still be simpler, and I’m working on that.. although the code still needs some refactoring, I have it basically working with a simple animated butterfly, which is simply a couple of bitmaps with Y rotations applied to them. The trick is to get the matrix that FLARManager gives you back when a marker is recognized, and apply that to your Sprite with 3D content. To use the app, you need to:

1. make sure you have a webcam attached to your computer and turned on. Most macs have them built-in by default. Don’t use any other application which uses the camera at the same time or it won’t work… thus you can also only run one AR enabled website at a time.

2. print out a AR Marker ( see here ) – right click and download any of the .png files or the .pdf, if you want a whole bunch at once, and print on white paper. At a pinch, you can use a black rectangle drawn on paper, as I did in the video below.

3. Go here for the AR Butterfly (but finish reading instructions first ;)

4. When the flash app starts, it will prompt you to allow access to the camera… click the ‘allow’ button. Now I have found this settings thingy to be very glitchy (it can also be accessed by right clicking on a flash movie and selecting ‘Settings…’). On my MacBook, I found it took a long time for the dialog to go away after clicking the ‘allow button’. I’ve also noticed similar problems on Linux. If you’re having trouble with it you can enable the site permission to access the camera by going here: flash player global settings Then you’ll need to find this site in the long list, select it, and click ‘always allow access’ for the camera. That way you won’t be bothered by the buggy dialog anymore (at least on this site).

5. Once you can see the output of the camera in the app, make sure you have decent lighting, hold up the marker to the camera, and adjust position so that there is enough contrast, but also no glare, as FLARToolkit does not handle that very well. Also make sure nothing is in front of the marker, breaking the outlines, or it won’t detect (this is something that ARTag can apparently handle). You should also not move too fast, or have shaky hands… If you’re lucky, you’ll see something like this:

flash 10 required

I noticed that the z-sorting on the butterly wings is inverted in this video… will have to sort that out. I’ll post a link to the code later, once it is a bit more polished. I have several ideas for AR applications, which I’ll hopefully get a chance to work on soon…