Soulwire » Open Source

Introducing Springboard

Soulwire — Mon, 21 Mar 2011 22:27:20 +0000

I love HTML5 Boilerplate and use it a lot as a basis for web projects. Sometimes however, I find it still does a little bit too much for my needs and I end up removing a lot before I can get started.

Most importantly for me though, it still currently doesn’t support building with Google Closure Compiler which I tend to use both for it’s advanced code optimisations and for coding better Object-Oriented JavaScript (not to mention generating JavaScript documentation from the very same comments I write for the compiler).

So What’s Springboard Then?

Springboard is an ultra minimal JavaScript / CSS and HTML project template (or springboard).

It features a very useful ANT build file which, among other things, can:

Refactor template files to match your project’s namespace so you’re ready to code in seconds
Combine JavaScript and CSS libraries to reduce HTTP requests
Compile JavaScript using the Google Closure Compiler (simple or advanced)
Minify CSS using the YUI Compressor
Generate JavaScript documentation using the JSDoc Toolkit
Sanitize HTML and inject variables at compile time

Also included is a simple JavaScript Model-View-Controller (MVC) template (based on Alex Netkachov’s) which can optionally be used as a basis for your project.

Hopefully No fluff – just the very basics you need to get a project or experiment started.

Check out Springboard on github

Quick Setup

To get started, first clone the repository:

cd /your/workspace
git clone git@github.com:soulwire/Springboard.git YourProjectName

Run the setup task and enter your project’s namespace when prompted:

cd YourProjectName
ant setup
Enter the full project namespace for this project: com.domain.project

This will refactor the project template to match your namespace. You’ll then be given the option to delete the GIT metadata and disconnect from the Springboard repository…

You can build your project with the default ANT task, build

ant build

And when you’re ready, generate documentation using the jsdoc task

ant jsdoc

You should also have a look at the build.properties file as here you can add your credentials and tweak the various build settings to your taste.

A Quick Note About Blocks

Springbard uses HTML comment blocks to figure out how it should build the project. There are different types of blocks you can use:

CSS:LIB » Third party CSS files (combined and minified)
CSS:SRC » Your project’s styles (combined and minified)
JS:LIB » JavaScript dependancies (combined but otherwise left untouched)
JS:SRC » JavaScript source files (combined and compiled)

Any linked JavaScript or CSS resources outside of these tags will simply be cloned into the build directory and left untouched for flexibility.

Springboard will look at all of your pages when it builds and combine all files in all blocks of the same type. There is then a generic document ready handler, which initialises scripts for a page based on the id tag of it’s body. This is best illustrated in this example.

A Quick Note About Externs

If you’ve used the Closure Compiler before, you’ll be familiar with Externs. Externs tell the compiler not to refactor certain methods and properties, because doing so may break your code if they reference a third party library or code not being compiled. Springboard currently ships with an externs file supporting JQuery 1.5, just to get you going. You can easily generate more for your favorite libraries using this great tool by Laurentiu Macovei or others like it.

What Springboard Doesn’t Do

The primary intention of Springboard is to provide a simple but powerful project template and build file, which integrates with the Closure Compiler as well as doing the basics which you would expect; such as file concatenation and CSS minification. It’s intended to be extremely light and minimal, allowing you to take the project kernel forward in whichever way you need; whether it’s a large site build or a quick JavaScript experiment. I would imagine that future updates will strip it back and optimise it even further, as opposed to adding features.

So to be clear, it is in no way intended as a replacement for the amazing projects out there such as HTML5 Boilerplate; simply an option if you need less rather than more in certain situations.

Now fork off and start making nice things…

What The Fuck Is My Mashup?

Soulwire — Mon, 07 Feb 2011 16:56:46 +0000

The fruits of a Sunday hangover; What The Fuck Is My Mashup? is an idea generator for ridiculous (but sometimes plausible) mashups.

Inspired by What The Fuck Should I Make For Dinner by Zach Golden, WTFIMM is a simple JavaScript based randomiser that takes a series of templates and a corpus of words and turns them into concepts that utilise the latest technologies, APIs and social media platforms.

I’ve abstracted the code into a simple framework which I’ve called the WTF Engine, that allows you to create a generator for any subject.

Here are a few of my favourite generative mashups so far:

Blackberry application that generates poetry based on Yelp data
Platform for building Wii controlled, memcached dashboard widgets for Open Frameworks enabled devices
Windows optimised GMail configurator for social microblogging
Podcast that generates poetry based on Google Earth data
Scalable, PHP based Feedburner API explorer with a hand tracking front-end
Feature detecting blogging platform for Lingo, Haxe and AS3
Pascal based kiosk to replace data visualisations and hook into GMail via Twitter and Google Maps
Multi-touch, open source Digg microblogging utility powered by Slashdot and the Google Gears C# API
Platform for building dynamic, Wii controlled iPad applications for MATLAB enabled devices
Python based Del.icio.us and GitHub mashup, designed for generative gaming
Objective C interpreter for creating dynamic microblogging experiences in JavaScript
Scalable, Wii controlled GitHub shopping utility powered by Foursquare & the Yahoo Pipes API
Ajax based platform for rapidly developing kiosks based on Google Gears data
Perl based platform for rapidly developing art installations based on GitHub data

The WTF Engine code and this particular implementation is available in my GitHub repository.

Have fun, and if for any bizarre reason you make one of them, let me know!

http://whatthefuckismymashup.com/

Simple Flash GUI Tool

Soulwire — Wed, 19 Jan 2011 17:32:24 +0000

Update: Keith himself has been working on a similar idea and has released MinimalConfigurator.

Keith Peter’s Minimal Components are an excellent tool for any Flash developer when it comes to adding realtime configuration to a SWF. I find myself using them a lot in my demos and prototypes but for sketches with many editable parameters it’s still a hassle writing boilerplate code to set up and arrange the components, as well as adding the appropriate event handlers.

Inspired by GUI tools for OpenFrameworks such as ofxSimpleGuiToo and ofxTweakbar, and ControlP5 for Processing; I thought it was time to have an equally fast and easy to use GUI tool for Flash AS3 projects.

Introducing SimpleGUI

SimpleGUI is a single Class utility designed for AS3 projects where a developer needs to quickly add UI controls for variables or functions to a sketch. Properties can be controlled with just one line of code using a variety of components from the fantastic Minimal Comps set, as well as custom components written for SimpleGUI such as the FileChooser.

SimpleGUI Currently exposes the following methods, as well as an open addControl method where any Class definition can be passed:

addColumn: Starts a new column of components
addGroup: Starts a new group of components
addLabel: Adds a TextField for labels or instructions
addToggle: Adds a CheckBox for Boolean values
addButton: Adds a PushButton for triggering callbacks
addSlider: Creates a slider for numerical values
addRange: Creates a range slider for two numerical values
addStepper: An alternative component to the slider for numbers
addColour: Adds a colour picker for integers
addComboBox: Adds a ComboBox box for any object
addFileChooser: Allow the user to load in data
addSaveButton: This triggers the save method for generating code

Other features include:

HotKey: Assign a hot key for showing / hiding the GUI
Context Menu: Toggle the GUI from a context menu item
Message: Pulse a message to the user in the toolbar
Show Toggle: Display a toggle when the GUI is hidden
Save Settings: Generate AS3 code to commit your current values

Using SimpleGUI

Each method takes an optional parameter called options, which is simply a dynamic Object from which you can pass values for any parameter the corresponding component has, as well as callback and callbackParams properties for triggering methods each time the component changes.

For example, to create a Slider for controlling a Number, set it’s width, execute a callback and display a custom label, you would write:

_gui.addSlider("myNumber", 0, 100, {label:"My Number", width:200, callback:onNumberChanged});

Although you can pass custom labels to each component, omitting this parameter will simply cause the variable name to be parsed and used as the label. For example, a variable called ‘myNumber’ will generate the label ‘My Number’.

SimpleGUI also supports nested properties, to any depth, using normal dot syntax. So you could control a particle’s position by writing:

_gui.addSlider("myParticle.position.x", 0, 1000);

Here is the code for the demo above. Only 27 lines of code to control the whole sketch.

_gui = new SimpleGUI(this, "Example GUI", "C");

_gui.addGroup("General Settings");
_gui.addColour("backgroundColour");
_gui.addButton("Randomise Circle Position", {callback:positionCircle, width:160});
_gui.addSaveButton();

_gui.addColumn("Noise Options");
_gui.addSlider("noiseBase.x", 10, 200);
_gui.addSlider("noiseBase.y", 10, 200);
_gui.addSlider("noiseSeed", 1, 1000);
_gui.addSlider("noiseOctaves", 1, 4);
_gui.addSlider("turbulence.x", -10, 10);
_gui.addSlider("turbulence.y", -10, 10);

_gui.addGroup("Wave Options");
_gui.addStepper("waveCount", 1, 20);
_gui.addStepper("waveSteps", 2, MAX_WAVE_STEPS);
_gui.addSlider("amplitude", 0, 200);
_gui.addColour("waveColour");

_gui.addColumn("Circle Options");
_gui.addRange("minCircleSize", "maxCircleSize", 10, 120, {label:"Circle Size Range"});
_gui.addSlider("rotationSpeed", -10, 10);
_gui.addComboBox("circle.blendMode", [

	{label:"Normal",	data:BlendMode.NORMAL},
	{label:"Darken",	data:BlendMode.DARKEN},
	{label:"Overlay",	data:BlendMode.OVERLAY},
	{label:"Difference",	data:BlendMode.DIFFERENCE},

]);

_gui.addFileChooser("Circle Texture", textureFileRef, textureLoaded, [
	new FileFilter("Image Files", "*.jpg;*.jpeg;*.png")
]);

_gui.addToggle("animateCircle");

_gui.addColumn("Instructions:");
_gui.addLabel("Press 'C' to toggle GUI");
_gui.addLabel("Press 'S' to copy setup code to clipboard");

_gui.show();

So, SimpelGUI is really just a timesaver for developers looking to quickly prototype something in Flash, or for releasing demos with controls. The actual hard work has been done by Keith in building and maintaining his deservedly popular Minimal Comps.

You can browse the source code or download the SimpleGUI class below. SimpleGUI is part of the Soulwire AS3 Framework.

Download: SimpleGUI

Recursive Polygon Subdivision

Soulwire — Thu, 27 May 2010 12:51:48 +0000

This is a little algorithm I sketched in my moleskin on the train and for once had the free time to build. The idea is to split a convex polygon between two line segments, creating two new polygons. Each shape is pushed into a queue ready to be subdivided itself. Despite the simplicity of the algorithm, the results are quite nice and with certain configurations often far removed from what I would have expected – surprise is always good.

The Subdivide Algorithm

Here are the basic steps used to create the sketch above:

Create the first polygon
Pick two adjacent vertices at random
Use linear interpolation to find a point between them (P1)
You now have a point on one line segment connecting the two vertices
Choose another line segment from the polygon
Find a point along this line segment (P2)
Build a new polygon by moving clockwise from P1 to P2
Build a second polygon by moving clockwise from P2 back to P1
Splice the original polygon from the list and insert the two new ones
Choose a polygon from the list and (↑repeat)

Very simple, but you can start to have fun with each of these steps to produce different results. Here are some of the variations which can be created with the demo.

Choose line segments to cut at random
Always subdivide between the two longest line segments
Always interpolate (choose points) half way along segments
Choose points at random positions along line segments
Only mark some polygons eligible for subdivision
Vary the minimum area of divisible polygons

Source Code

The Polygon class is a DisplayObject (it extends Sprite) and implements it’s own draw method. I’ve had a lot of fun filling the shapes with textures, but kept it minimal for the example. One technique which I found worked well was to choose two vertices and compute the angle between them. From this I created a transformation matrix to use with Graphics.beginBitmapFill, giving the sketch a more 3 dimensional feel as if the collection of polygons was a 3D mesh with textures mapped to it. I’ll put these examples on Flickr soon.

If you’re interested in the source code, it’s available in my code repository or you can download the archive below (for the demo GUI, I am using minimal comps courtesy of Keith Peters and for image encoding, Ian McLean’s asynchronous JPEG encoder – thanks guys :).

Download: Recursive Subdivision

Hello Dynamic Sprite

Soulwire — Fri, 21 May 2010 16:56:04 +0000

If you are building a multilingual application (or any application that requires dynamic, runtime loaded assets), swapping and managing assets can easily become tedious and messy.

Recently, for projects requiring special characters (such as Chinese, Arabic, Japanese and Hindi) and where dynamic or input text is not required, we have been creating library SWFs for each language and using static textfields to populate content. This saves file size, as unnecessary characters are not embedded, and it eases the process of including different character sets (and even fonts) for each language. It also means that we can include text in the same runtime loaded library as general display assets.

Introducing DynamicSprite

Using this process, a language specific library SWF is loaded at startup, or at runtime when the users selects a language, and once complete all dynamic assets are updated accordingly. This can get very messy for two reasons. Firstly, it means that each individual asset has to be destroyed and tidied up to release memory before it is replaced. Secondly, if you have a complex application architecture, you will end up dispatching a ton of events and implementing countless methods within every view or component, in order to rollout the update to each desired DisplayObject.

This is where DynamicSprite comes in handy. Using DynamicSprite you can effortlessly update any amount of DisplayObjects from any amount of library SWFs at runtime, whilst keeping the SWF loading logic centralised in your proxy or loader class. No events, no asset update APIs in your views and no cleaning up after yourself.

Bored? Skip straight to the examples and download

How It Works

The concept is very simple. Each instance of DynamicSprite is registered globally at a class level, you need only call a static update method once and all DynamicSprite instances will update themselves automatically. Each instance of DynamicSprite is given a class definition, which can be set or changed at runtime if desired. When a new library is loaded, it will look inside the SWFs applicationDomain and if it finds a matching asset, update itself and destroy any existing instances of that asset it might own. You can also create DynamicSprite instances at runtime anytime after an asset library has been loaded – they will check previously loaded libraries for their class definition when created. This works with any display asset, Sprites, MovieClips, Bitmaps (etc) – BitmapDatas are also detected and destroyed during the cleanup process.

Furthermore, you can load any amount of libraries per language, at different times if necessary – DynamicSprites will only update themselves when applicable, making it easy to manage your language specific libraries and even individual libraries per language if you choose to (each type of library has it’s own ID).

A DynamicSprite instance will also dispatch an event (named DynamicSprite.INSTANCE_UPDATED) when it has changed it’s asset. You can listen for this event if you need to respond to new asset dimensions. You can also listen for two events on the class itself (through a static, encapsulated EventDispatcher) which are dispatched when a library is added or updated but before all instances have changed (DynamicSprite.LIBRARY_UPDATE_START) and when all instances have finished updating themselves (if necessary) from the added / updated library SWF (DynamicSprite.LIBRARY_UPDATE_COMPLETE).

Example Implementation

Here is a simple example of how to use DynamicSprite. Although this example only loads one SWF (the code for the multi SWF example is included in the download), it demonstrates how DynamicSprite can also be useful for single language applications where you still choose to load your assets at runtime.

public function SimpleExample()
{
	// Create a DynamicSprite instance and provide a class definition for it's asset
	var example : DynamicSprite = new DynamicSprite("assets.example.HelloWorld");
	addChild(example);

	// Load a library SWF
	var loader : Loader = new Loader();
	loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoadComplete);
	loader.load(new URLRequest("assets_en.swf"));
}

private function onLoadComplete(event : Event) : void
{
	// Call the static update method once to update all DynamicSprites
	DynamicSprite.update("example", LoaderInfo(event.target).content);
}

Another advantage of DynamicSprite is that you need not worry about synchronising loading with the update process. Any existing DynamicSprite instance will be updated if required when a library is loaded, however you can also create new instances after a required library has been loaded (useful for highly dynamic content) and any loaded libraries will be searched for matching assets upon creation. This snippet demonstrates this feature.

public function SimpleExample()
{
	// Load a library SWF
	var loader : Loader = new Loader();
	loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoadComplete);
	loader.load(new URLRequest("assets_en.swf"));
}

private function onLoadComplete(event : Event) : void
{
	// Register this library
	DynamicSprite.update("example", LoaderInfo(event.target).content);

	// Creating a DynamicSprite after a library is loaded still works fine
	var example : DynamicSprite = new DynamicSprite("assets.example.HelloWorld");
	addChild(example);
}

Download DynamicSprite

You can download the DynamicSprite class and the demo below. Also check my code repository for updates. If you find any bugs or have any suggestions please leave them in the comments.

Download: DynamicSprite

ASE (Adobe Swatch Exchange) Encoder

Soulwire — Tue, 30 Mar 2010 14:00:52 +0000

The Adobe Swatch Exchange (ASE) is a useful file format for importing colour schemes into applications in the Creative Suite (Photoshop, Illustrator etc).

I’ve been optimising the BitmapData colour palette algorithm (coming shortly in another post) and for the demo thought that it would be nice to give you the option to save the extracted color palette (a feature that people have been requesting in the comments). I added an option for saving a TXT file containing the hexadecimal and RGB colour values, but thought it would be nice to offer the choice of downloading the palette in ASE format so you can quickly incorporate the colour scheme in your artwork or designs, one of the nice features of Kuler.

So the first step was to open up and existing ASE file (created by Photoshop) in a hex editor (I use 0xED which is an excellent and free editor for OS X). Looking at the bytes of the file showed that it was evidently a quite simple format and wouldn’t be difficult to reverse engineer. I also found the ASE file format specification and a PHP implementation over at Colour Lovers, both of which were quite helpful.

This AS3 code will take an Array of colours (adding Vectors to the

 tag seems to cause problems, though my local source code does use a Vector of uints) and encode the ByteArray of an ASE file, ready to save using FileReference of FileStream in AIR…
const FILE_SIGNATURE : String = "ASEF";

function encode ( pixels : Array ):ByteArray
{
	var swatch : ByteArray = new ByteArray();
	var ase : ByteArray = new ByteArray();
	var hex:String;
	var pix:uint;

	ase.writeUTFBytes (FILE_SIGNATURE);// header
	ase.writeInt (0x10000);// version
	ase.writeInt (pixels.length * 2);// blocks

	for (var i : int = 0; i < pixels.length; ++i)
	{
		pix = pixels[i];
		swatch.length = 0;

		// start of group

		ase.writeShort (0xC001);
		ase.writeInt (0);
		ase.writeShort (1);

		// swatch name

		hex = pix.toString(16);
		while (hex.length < 6) hex = "0" + hex;

		swatch.writeShort ((hex = "#" + hex).length + 1);
		for (var n : int = 0; n < hex.length; ++n) swatch.writeShort (hex.charCodeAt(n));
		swatch.writeShort (0);

		// colours

		swatch.writeUTFBytes ("RGB ");
		swatch.writeFloat ((pix >> 16 & 0xFF) / 255);
		swatch.writeFloat ((pix >> 8 & 0xFF) / 255);
		swatch.writeFloat ((pix & 0xFF) / 255);
		swatch.writeShort (2);

		// write swatch

		ase.writeInt (swatch.length);
		ase.writeBytes (swatch);
	}

	return ase;
}

I’ll put the full code in my repository along with the improved ColourUtils Class which prompted the ASEEncoder, though for now you can just copy and paste this snippet and play with the demo above to save the top colour schemes from Colour Lovers as ASE files, which you can then import into Adobe Creative Suite applications.
Here is an example of how to encode a palette and then save it to the file system:
var colours : Array = [0xFF0000, 0x00FF00, 0x0000FF];
var aseFile : ByteArray = encode( colours );
var fileRef : FileReference = new FileReference();
fileRef.save( aseFile, "swatch.ase" );

The AS3 ASEEncoder currently only encodes swatches as RGB, though saving CMYK should only be a matter of converting the colour space and then changing the swatch declaration.
Going in the other direction, it would be nice to provide a method to decode existing ASE files into a Vector of uints, something which I’ll look at once the new ColourUtils is online.


Related posts:
BitmapData Average Colours
BitmapData Colour Palette
Smack My Glitch Up

Smack My Glitch Up

Soulwire — Wed, 03 Feb 2010 21:37:51 +0000

Sometimes it’s good to break things…

During a recent project I needed to find a way of simulating digital interference on an image / video stream. At first, it seemed the best approach might be to use the graphics API or Bitmap effects, but why imitate when you can have the real thing.

The principle is incredibly simple. Corrupt / alter a byte (or several bytes) in the ByteArray of a JPEG and then load this back into a DisplayObject using Loader.loadBytes(). Because of the way in which JPEGs work, the image will still display but the corrupt bytes will mangle the output to varying degrees, depending on how many bytes have been corrupted. The result is an interesting glitch pattern, a bit like those which were accidentally created when my webcam drivers lost the plot.

It is also possible to corrupt other image formats (png, gif etc) in the same way, by first passing the image ByteArray through a JPEGEncoder.

I’ve implemented this technique in the Glitchmap class, which you can download and play with at the bottom of this post. I hope that it will provide a few moments of fun, if not a practical use (I’m thinking image gallery transitions or music visualisations).

The small gottcha is that it isn’t desirable to mess with the JPEG headers, so when the clean ByteArray is passed to the Glitchmap class, it will determine the length of the header by reading through the bytes until it finds the SOS (start of scan) declaration (0xFFDA). The next two bytes represent the length of the SOS, so it skips forward by this amount – the resulting position in the ByteArray should be the end of the header, and so between this point and the EOI (end of image) the data corruption takes place. I’m not sure whether this is the best way of determining the JPEG header size; perhaps any CS graduates / students out there can help me out?

After I posted the webcam glitch images, Jon used them in his title sequences for the 48 hour film gala. If you find a similar creative use for this script or the glitch generator then please let us all know.

I think the next step is to experiment with merging the bytes of multiple glitched images in order to create transition effects. I may also build an AIR app and see what the best way of outputting video might be (using NativeProcess for screen capture perhaps?).

Download: AS3 BitmapData Glitch Generator (Glitchmap)

You can also download the Glitchmap Class and the Glitch Generator source code from the soulwire code repository.

Fit DisplayObject into Rectangle

Soulwire — Mon, 25 May 2009 17:20:20 +0000

We’ve all been there. You’re building an image gallery and you need to create consistently sized thumbnails from a set of images, of various sizes and orientations and with differing aspect ratios – or you need a fullscreen background which always fills the stage, regardless of a user’s screen resolution and browser window size – or maybe you just need to fit a DisplayObject into a rectangular area whilst maintaining the correct proportions of the original image.

Introducing DisplayUtils

Since this is a common task, one that I find myself coding over and over, I’ve whipped up a little class called DisplayUtils which will help with the scenarios mentioned above and more.

The main method in DisplayUtils is FitIntoRect. FitIntoRect can work in several ways. You can use it to resize a DisplayObject to fit inside a rectangle, or you can use it to generate a transformation matrix, which can be applied to an object or used with the BitmapData.draw method to create thumbnail previews, or both. There is also another method called createThumb, which uses fitIntoRect to quickly and easily create nicely cropped and scaled thumbnails from a source image with any aspect ratio.

Have a play with the demo above to see what you can do with these methods.

Using DisplayUtils and fitIntoRect

There are several parameters to control how fitIntoRect works. Here’s what you can pass to the method:

displayObject : The DisplayObject to resize
rectangle : A Rectangle object representing the space the DisplayObject should fit into.
fillRect : Whether the DisplayObject should be transformed to fill the entire rectangle, or whether it should fit completely within it.
align : The alignment of the DisplayObject within the rectangle, for example Top Left or Middle.
applyTransform : Whether the calculated transformation matrix should be applied to the DisplayObject within the fitIntoRect method. If false, the DisplayObject will not be modified, but the Matrix returned by the fitIntoRect method can be used to transform objects or modify the draw command on a BitmapData object.

The download includes all necessary classes as well as several examples of how to use the fitIntoRect method. Here are some code snippets for getting started with…

Example Usage

Fit a DisplayObject into a Rectangle

var area:Rectangle = new Rectangle( 0, 0, 200, 100 );
DisplayUtils.fitIntoRect( myDisplayObject, area, true, Alignment.MIDDLE );

Create a fullscreen background image

stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;

function onStageResized( event:Event = null ):void
{
	var area:Rectangle = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );
	DisplayUtils.fitIntoRect( myDisplayObject, area, true, Alignment.MIDDLE );
}

stage.addEventListener( Event.RESIZE, onStageResized );
onStageResized();

Create a thumbnail

var thumb:Bitmap = DisplayUtils.createThumb( myBitmap.bitmapData, 100, 100, Alignment.MIDDLE, true );
addChild( thumb );

Download

You can download the DisplayUtils class, as well as the Alignment class, which simply contains enumeration for the various alignment options when using fitIntoRect and createThumb.

A example of some of the uses discussed above is also available in the zip.

Download: DisplayUtils

Flipping you the Boid

Soulwire — Tue, 05 May 2009 15:12:45 +0000

I’ve uploaded the Boid source code. Sorry for the delay. I’ve also included some basic examples of how you can create nice behaviors using the Boid class. If you set Main.as as your document class then you’ll see that within that you can specify the demo to run when you compile.

The basic demos included are:

Chase – Boids chase each other
Flock – Boids flock together with some wander
Graphics – How to use custom graphics with a Boid instance
Seek – Boids seek the mouse position
Wander – You guessed it, they wander

I’ve commented all of the methods and properties and there is also documentation (open index.html in the docs folder) to get you started. Before you mention it, yes, there is some redundant code ;) (such as the constrainToRect method which doesn’t really work) but I need to do some optimisations anyway so I just left it as is for now, rough and ready.

Download: AS3 Boid Class & Demos

It’s been a little while since I posted! I’m in the process of moving house and office, plus I’ve been repeatedly slammed at work. Apologies to those of you who’ve left comments and haven’t got much by way of reply. I’ll hopefully be visible again over the next few weeks.

I actually coded this experiment back in November, but only recently decided that enough was enough and hijacked an evening so I could tidy up the code and build a UI for the demo.

Since coming across Craig Reynold’s paper; “Steering Behaviors for Autonomous Characters” whilst I was researching complexity theory for a university project (it wasn’t as academic as it sounds!), I’ve found myself becoming fascinated by flocking and swarm beahviors and the notion that you can create complex systems from relatively simple components. Much like the Cellular Automata, you can program an agent to have only a limited set of abilities and awareness, define a set rules for it to follow, and then create a multitude of instances of the agent to see what patterns begin to emerge through their interactions.

Flocking is a great example of this, as Reynolds demonstrated. His agents, or “Boids”, could perform certain maneuvers, such as seeking a target, fleeing from a predator, avoiding obstacles or wandering randomly. Combine these behaviors though, and allow each Boid to consider it’s neighbors when deciding on its locomotion, and complex behaviors begin to emerge.

The most infamous of these combinations is that of separation, cohesion and alignment, as it can produce a swarm behavior reminiscent of flocking birds or shoals of fish.

Separation means that each Boid attempts to maintain a certain distance from its immediate neighbors, Cohesion ensures that each Boid attempts to stay close to the centre of the immediate flock and Alignment will calculate the average heading of the flock and steer towards this vector.

Each of these behaviors is fairly simple in isolation, but the results can give the impression that some significant AI is at work, when all that’s really going on is some simple vector math.

Robert Hodgin has done some amazing work with flocking behaviors, so too has Psyop, and of course Reynolds is the daddy of all this stuff. There are some good libraries out there too, such as OpenSteer, and Keith Peters talks about this too in Advanced Actionscript Animation.

I’ve been trying to sharpen up my mathematical skills lately though, and was eager to play around with the new (new when I created this experiment anyway!) Flash Player 10 API – the 3D aspects in particular. So at the core of the Boid class are the native Vector3D, Matrix3D and PerspectiveProjection classes. Ok, so we’ve all got our own Vector3D and Matrix3D class in our library, but I thought it’d be good to use Adobe’s, especially seeing you can then apply the Matrix3D directly to a DisplayObject’s transform property.

Another cool feature I came across was the Matrix3D.pointAt() method, which will rotate a Matrix around a given axis and in this case can be used to orientate the Boid to it’s heading vector… Nice!

I’ve had a lot of fun putting together the Boid demo anyway – tweaking various settings on the individual Boids as well as the group behaviors (my personal favorite is ‘Chase’ mode with ‘Number of Boids’ cranked right up!).

If you have a play with the settings though, you’ll quickly see what I mean about the plethora of different effects that can be accomplished, even by simply adjusting the locomotive abilities of the Boids.

Due to said lack of free time as of late, I haven’t documented the code fully, though I have started and so if anyone is interested in the source code then please say so in the comments and I’ll try and finish the job (after a mere 6 months!) and put it up for download.

AS3 Shuffle Grid Class

Soulwire — Wed, 04 Mar 2009 00:50:47 +0000

Drag & Drop the images to shuffle them around…

A friend of mine, Dale Sattler over at No Ponies recently posted a grid sorting class. He said it was based on my old dynamic stacking menu; but that was pure modesty as his script is based on a 2D grid and much more sophisticated.

Anyway – it inspired me to create a grid sorting / shuffling algorithm of my own. It behaves differently to Dales but I think it works pretty well.

The basic logic of the algorithm works by determining how far a dragged item travels along the grid (rows and columns) and then shuffling the surrounding items in the opposite direction by these values, therefore creating space for the dragged item to slot into when released.

It currently only works for grids which are fully populated, but adding more flexibility for incomplete grids will only be a matter of adding a few conditions – functionality which I’ll add when I get a moment.

You can extend the ShuffleGridItem class to add the functionality you need. In the demo I’ve made a simple image class which grabs a photo from Flickr.

Creating a ShuffleGrid is very simple, and can be done like so:

var grid:ShuffleGrid = new ShuffleGrid(4,7,40,40,1);

for (var i : int = 0; i < grid.numCells; i++)
{
	grid.addItem (new ShuffleGridItem());
}

addChild (grid);

The constructor takes the following arguments:

new ShuffleGrid(rows, cols, cellWidth, cellHeight, spacing);

Feel free to download the class and a simple demo and have a play around. I can imagine many uses for it, so hopefully it will come in handy.

Download: Shuffle Grid Class & Demo