ZIM - Code and Learn Coding with ZIM for JavaScript and HTML Canvas with CreateJS


The ZIM Docs and many ZIM examples use the zim namespace - for instance:

var circle = new zim.Circle();

This is no longer required so you can just use:

var circle = new Circle();

Another example is zim.rand(20) can now be just rand(20). See the news post.
You can chain almost all ZIM methods. For example:

var circle = new Circle()

Note the semi-colon is at the end. Putting these on multiple lines allows you to comment out individual commands for testing. Do NOT chain the CreateJS on() method for events and do NOT chain properties. ZIM provides a number of equivalent chainable methods like:

pos(), mov(), sca(), alp(), rot(), reg(), ske()

New methods have been added and old ones adjusted too chain such as

cur(), sha(), cache() and setMask()

Do NOT use scale() as it conflicts with CreateJS 1.0 but rather use sca(). See the Bubbling video.

In general, to confirm that a ZIM method returns the object, check at the bottom of the docs for that method under the RETURNS section. If it says returns obj for chaining, then you are good to chain!
Configuration Objects are object literals { } that hold properties that match the parameter names for classes and functions. The ZIM DUO technique allows us to pass in parameters individually or as a single parameter that is a configuration object. For example:

// traditional parameters in order:
var rect = new Rectangle(100, 100, frame.red, null, null, 20);

// or as a configuration object:
var rect = new Rectangle({width:100, height:100, color:frame.red, corner:20})

Configuration Objects can be clearer and can be considerably shorter. Also, the order of the properties in the configuration object does not matter. On the other hand, if you are using only the first couple parameters, they could take longer to type.

RECOMMENDATION: switch between the two depending on the situation. If you need a parameter that is many parameters along, then a configuration object will be better. If you are using a few parameters in order, then traditional paremeters are fine.

See the Parameter sections of the ZIM Docs to see if a class or function accepts ZIM DUO. You can also make your own classes and functions work with configuration objects by using zob.
ZIM loop() is an easier format than a traditional for(var i=0; i<10; i++){} loop. Here is the format - which matches the familiar event call:

loop(10, function(i) {
  zog(i); // 0-9

There are lots of extra features too. Here are ways to loop through arrays, objects and containers. In the container example we loop through backwards which is important when removing children:

var letters = ["A", "B", "C"];
loop(letters, function(letter) {
  zog(letter); // "A", "B", "C"

var person = {age:20, job:"farmer", greeting:"yo"};
loop(person, function(property, value) {
  zog(property, value); // age 10, job farmer, greetings yo

var monsters = new Container(); // then fill with monster Bitmaps, etc.
loop(monsters, function(monster) {
  if (monster.growl) monster.removeFrom(monsters);
}, true); // true loops backwards

See ZIM Docs for more details including start and end values, continuing or breaking from a loop, more parameters, etc.
ZIM Frame() can scale to a window keeping proportions or fit full window with no scaling. See the Frame page for the templates. Frame can also fit in an existing HTML tag and act just like an image - except an interactive image! You can use multiple frames on the same page.

Frame can be used to load assets:

frame.loadAssets(["pic.png", "sound.mp3"]);
frame.on("complete", function() {

There are more options (such as techniques for multiple loadings) and events when loading - see the ZIM Docs. Frame also has a color and outerColor property to set the backing colors and there are a number of ZIM colors stored on Frame such as:

frame.green, frame.orange, frame.blue, frame.pink, frame.brown, frame.yellow, frame.purple, frame.red

As well as shades such as:

frame.dark, frame.darker, frame.light, frame.lighter, frame.grey, frame.tin, frame.silver, frame.white, frame.black, frame.faint, frame.clear, etc.

We tend to use these in ZIM examples but any HTML/CSS string color will do such as:

"red", "#CC0000", "#333", "rgba(0,0,0,.2)", etc.
ZIM is over 200K in size and growing but you can easily use Distill to create a minified file of only the ZIM code that you are using. In your scripts, before you call ZIM Frame, add the following:

DISTILL = true;

This starts a recording of function numbers. When your code is done (i.e. in a click event function) add the following:


At this point, a coded list of all the functions that have been used are displayed in the console (F12). Copy this list and go to the Distill page where you can paste them into the form and submit to receive the distilled minified code - and non-minified code for your reference. You can then paste this code in a remote JavaScript file and call it from your page instead of the full ZIM cdn link:

<script src="remote.js"></script>

Or load the code in between script tags. Here are some Examples and the Docs.
It is beneficial to keep up with changes. The ZIM News section has two main links - the Bubbling videos (started March 2017) and Blog (started March 2016) both of which highlight new features. Bubbling shows features that were added or changed since the end of the ZIM Bits series of 64 code tutorials and after the ZIM Capture video tutorials both found in the ZIM Learn section. A look through the Bubbling videos titles is a quick way to summarize changes (this list as of Oct 2017):

Transform | Noise & Generative Art | Canvas Accessibility | Optional Namespace | ZAP Code Sharing | Multitouch Gesture | Badges Tutorial | New Site for ZIM VEE | Code Zero | SoundWave Frequencies | Documentation Changes and Overview | Lessons | StageGL | Blobs & Beziers! | Ticker | Particle Emitter | Changes in ZIM 5 | ZIM VEE and ZIK | Animate Calls | TextArea | Image Loader | Window Resize | Physics Workshop | Asteroids Workshop | ANIMATE Constant | FPS Meter | Leader Board | GamePad Support | Motion Controller | Accelerator! | Dynamo! | Sprite Updates! | Animation Series | Chaining | Bubbling Series

Specific and complete changes in the ZIM code can be found in the Updates page which goes hand in hand with the updates of the Docs. These show the version numbers of ZIM in major.feature.fix format: Here is a snip of an Updates example where an IMPROVEMENT and a BREAK have been noted:

ZIM 6.3.2
Added split property to Parallax object to center the input value IMPROVEMENT
BREAK Adjusted Parallax parameter order to layers, damp, auto, stage

You may consider updating old code for improvements and if you do update, note that any breaks may require adjustment to old code - usually in the order of parameters.
When you are coding, sometimes things do not show up. Here are some reasons why that might happen: This last tip is the ZEN FIVE MINUTE rule of debugging. If you have been trying to fix something for more than five minutes - no matter what - confirm that you are viewing the file that you are updating.
Often we need to test if objects are hitting. This almost NEVER happens when the code first loads. Usually it happens in a function in one of three places:
  1. Ticker.add(function(){});
  2. object.on("pressmove", function(){});
  3. object.on("pressup", function(){});
The first will check all the time and is good when the various targets are moving on their own. The second is good for when moving an object with a mouse or a finger and the others objects are not moving. The last is good for checking only when you drop on object - for instance, throwing an object in a garbage can. Here is an example of the third:

var ball = new Circle(20).center(stage).drag();
var can = new Rectangle(100,200).addTo(stage).pos(100,100);
ball.on("pressup", function() {
  if (can.hitTestCircle(ball)) {

WARNING: we could use ball.hitTestRect(can) but the ball is smaller and it could fit inside the bounds of the can. The hitTestRect() checks to see if the shape of the object the method is placed on is hitting points around the bounding box rectangle. By default, it checks points at the corners of the bounds and one point in the middle of the bounds. Even if we increase the points around the edge of the bounds (with the second parameter), the small circle could be dropped inside the can and not even touch the edges or the exact middle. So the general rule when using hitTestRect() and hitTestCircle(), is put the method on the BIGGER object and test against the points on the Circle or Rectangle of the smaller object with the smaller object in the round brackets - hence, can.hitTestCircle(ball);

OPTIONS: there are other types of hitTests but for the most part, hitTestRect() and hitTestCircle() will be the most popular unless you have two rectangular shapes and then use hitTestBounds() or two circles and then use hitTestCircles(). These last two are very fast as they use equations. The fastest way to test if the mouse (or any object) is over a cell in a grid is with hitTestGrid() - see Docs. This also uses a mathematical calculation rather than comparing color/point based intersection which is used by a mouseover event. See the ZIM Bit or the ZIM Capture on hitTests.
Browsers have a console (F12) that can be used by developers to see what is happening in their code. The console is not seen by the end user - although, if they know how, they can view it. There are also debuggers but these are often not needed. We can zog() helpful messages to the console as we code. zog() is just short for JavaScript's console.log().

If you are just starting to code, it is a good idea to test often. Every time you make a function, the first thing you do should be to zog("functionName"); inside the function to make sure the function is running. Here are a few examples of where we might use functions:

function test() {
  zog("test"); // will show test in the console when function runs
// this function above will not run until it is called:

object.on("click", function() {
  zog("clicked"); // runs when object is clicked

  call:function() {
    zog("animation done"); // runs when animation finishes

Ticker.add(function() {
  zog("ticking"); // runs at the frame rate - very fast!

interval(1000, function() {
  zog("interval"); // runs every second

timeout(500, function() {
  zog("timeout"); // runs once after half a second

loop(10, function(i) {
  zog(i); // shows 0-9 as we loop

In all of these, we would want to make sure the function is running before we start coding inside the function. If we do not, we sometimes will think that our code inside is broken - when really, it is just that the function is not running.
ZIM is built on CreateJS at http://createjs.com and so all CreateJS documentation applies to ZIM.

ZIM Containers extend CreateJS Containers and many of the ZIM Display objects extend ZIM Containers. This means, the ZIM objects get all the CreateJS methods, properties and events like on(), setBounds(), x, y, rotation, alpha, mousedown, mouseover, mouseout, pressmove, pressup, etc.

If we have a CreateJS display object such as a Container or Shape that comes from Adobe Animate, etc. then we can give this object all the ZIM display methods by using the zimify(CreateJSObject) global function. This adds drag(), animate(), all the ZIM hitTests, center(), centerReg(), pos(), mov(), etc. to the CreateJS object.

It should be noted too that ZIM objects have a width, height, widthOnly and heightOnly properties. These scale the object to give the desired width and height. They leave the bounds as originally set:

var rect = new Rectangle(100,100).center(stage);
rect.width = 200; // scales the rect by 2 in both the x and y
zog(rect.width); // 200
zog(rect.getBounds().width); // 100
zog(rect.scaleX, rect.scaleY); // 2, 2

When you are creating a Container or a Shape you have the choice of setting the width and height as parameters as you make the object. You can optionally set the boundsX and boundsY and the width and height. You can also let the container make its own bounds based on its contents by leaving the container parameters as null. And of course, you can get and set the bounds at anytime using getBounds() and setBounds(). Setting the bounds to null will have the container automatically calculate its bounds. For ZIM center() and centerReg() and various hitTest methods it is often helpful or necessary to have the bounds set.
We are here and love to help. There is no question too small and no question too big. Here is an invite to the ZIM Slack Team. It just takes a moment to sign up to Slack and it is all online. Many companies are using Slack for internal communication. Slack is being used as forums for software support, educational communications, etc. Here are the ZIM Slack channels - it helps to post in the relevant channels but you will find us all very friendly - so no worries:
  • Examples - view and show projects
  • General - posts that don't fit in other channels
  • Releases - ZIM announces each release here
  • Questions - ask how to do something
  • Random - chit-chat - maybe not about ZIM
  • Requests - what would you like to see in ZIM