Adventure map engine

In a lot of games the player’s progress through the game is visually represented with an adventure map. The player has an overview of the levels which are finished and the levels which are still to come. Classic examples of games where an adventure map is used are Super Mario and Commander Keen.

keen

mario

The adventure map concept is still used in modern games, an example is Fruit Mania.

fruit

The new DevKit AdventureMap class provides a generic solution for adventure maps. This class wraps the views and model used in the adventure map.

Nodes and Paths

Most of the older adventure maps only support straight angles. The DevKit map allows you to place the node on an arbitrary position within the tile.

There are three different options to connect the nodes: lines, dots and dashes.

From each node you can enable up to four paths: bottom, right, right bottom and right top.

paths

Tags

Each node of the map can be assigned tags. It’s possible to define view constructors for tags. This makes the map very flexible. If a tag is added to a node and there’s a view constructor available for that tag then an instance of the view is immediately created and the view shows up on the node. When the tag is removed the view will immediately disappear.

The map also provides methods of retrieving lists of nodes by the tag name, with this option zones can be created and the node properties of a specific zone can be easily changed.

tag

Doodads

The adventure map engine allows you to add images or animations to the map, these are displayed on the top layer. These images only serve as a decoration. An example is this wonderful long legged blue bunny in our demo app:

doodad

Interacting with the map from code

The map emits two events, ‘ClickNode’, ‘ClickTag’. With these events extra UI elements can be triggered, like showing a dialog with information about a selected player or level.

Map editor

The first version of the map had a simple JSON data structure containing all properties of the map, to change the map you could edit this data structure. While adding more features to the map it became clear pretty soon that this was not a good method for making larger maps.

editor

To design maps there’s a -very simple- map editor class included in the adventure map library.

demo

We’ve already seen some awesome games which were built with our DevKit and included an adventure map. We hope that this new component will save you some time when you want the build your own game with one.

For more information:
Live demo
Library source
Example game

Automating the Illustrator Art Pipeline

Art pipelines can all too often be one of the biggest headaches in game development. During the course of a project, game artists will be creating wireframes, art concepts, screen mockups, style guides, and final assets; not to mention any placeholders or revisions along the way.

The following is a workflow we have designed to streamline the way artists create these, leveraging scripts to automate some of the busywork and repetitive tasks. We’re going to be working exclusively within Adobe Illustrator as we construct a project in a way that allows us to cut many of the more time-consuming corners.

In this article, I’m going to assume the reader has some basic knowledge of creating graphics in Illustrator; hopefully by the end you’ll have a few more tricks in your bag!

Artboards

Firstly, let’s discuss Artboards. Artboards are like pages in a sketchbook; you can add, remove, and re-order them via the Artboard window. (Or by selecting Object>Artboards>Rearrange…)

Illustrator allows you to export your Artboards in bulk as images. What this allows us to do is treat each Artboard as a game screen, and export all of our project’s wireframes or mockups at once. (Check the “Use Artboards” box in the File>Export… dialog.)

This feature may seem more useful after we cover Symbols:

Symbols

Illustrator allows you to convert any art into a Symbol. (Select the items you want to make into a Symbol and click the “New Symbol” button in the Symbols window.) Once created, the Symbol is available in the Symbols window; you can drag instances of it onto the canvas. The main advantage here is that any change to the Symbol’s contents apply to all instances of the Symbol.

What this allows us to do is construct our document in a way that gives us powerful revision control. For example: The UI in any given project is probably going to re-use elements across multiple screens, like a standard type of button. By making that button a Symbol, and designing the wireframes/mockups with instances of that Symbol, I’d be able to edit the Symbol and see the changes cascade through all the places where that Symbol is used. Combine this with the ability to bulk export the Artboards, and we can re-export all the screens with the change we just made. You can probably see how much time this is going to save when it comes to a project with many screens and many instances of the same asset.

A mockup and the Symbol library used to create it. Note that some of the Symbols are built from other Symbols, allowing edits to cascade through multiple assets.

]1 A mockup and the Symbol library used to create it. Note that some of the Symbols are built from other Symbols, allowing edits to cascade through multiple assets.

9-Slice Scaling on Symbols

Symbols have another important use that we would be remiss to exclude: 9-slice scaling. When creating a Symbol, you can check “Enable Guides for 9-Slice Scaling”. (You may also change this for existing Symbols through the Symbol Options dialog) When editing the Symbol, you’ll be able to arrange 4 guides that control how the graphics are stretched when the Symbol is scaled; instead of scaling normally, the Symbol instance will stretch the middle column and row and preserve the corners. This is great for creating the building blocks to construct other elements from, especially when you consider the way changes will cascade through every instance.

Editing a Symbol's 9-slice scaling guides.

]2 Editing a Symbol’s 9-slice scaling guides.

Stretching a 9-Sliced Symbol

]3 Stretching a 9-Sliced Symbol

Batch Export through Scripts

So far, we’ve discussed how Symbolizing repeatable elements allows us to edit a project’s design on a global level, and how the use of Artboards gives us a quick way to export those changes and distribute them to the team. But the biggest shortcut we’ll discuss here involves the creation of deliverables. Is there a way to export all the assets for a project as easily as we exported the Artboard mockups?

Enter a script I created named “WireCutter.” It contains a small set of tools that automatically cut-up our wireframes and export the constituent assets. Let’s think about our Symbol library; if constructed properly, it should contain Symbol versions of every repeated element. It’s not a stretch to start thinking of our Symbol library as the list of deliverable assets. The WireCutter script allows us to do exactly that, and can export our library items in bulk.

Download the WireCutter script from this GitHub repository.

You can run a script in Illustrator by selecting File>Scripts>Other Script… and navigating to the desired file. Running WireCutter.jsx brings up a menu with Tools and Options. (We’ll discuss what these do below, but you can also hover over any option for a short description)

Starting up the WireCutter script

]4 Starting up the WireCutter script

Let’s select the “Export all Library Symbols” tool and see what happens. You’ll see that after choosing a directory to export to, the script renders everything in the library to disk as a PNG.

Each asset is saved to disk. Note that each asset file gets named and organized into folders based on its Symbol name.

]5 Each asset is saved to disk. Note that each asset file gets named and organized into folders based on its Symbol name.

So there you have it; we now have a way to very quickly and painlessly extract all the assets from our document into a collection of deliverables for the developers to implement. When constructed correctly, we can easily batch render all the wireframes, mockups, and deliverables in only a few clicks.

WireCutter Tools and Options Explained

Tools:

  • Export all Library Symbols – Renders everything in the Symbol library to disk.
  • Export Selected Items – Renders only the currently selected items to disk.

Tool Options:

  • Create sub-directories from underscores – When checked, the script will create folders based on any underscore characters in the asset’s name. (Example: “button_play” exports as “/button/play.png”)
  • Omit items starting with “!” – When checked, the script will not export any asset whose name begins with a “!” character. This allows us a way to flag Symbols that are not meant to be assets on their own.
  • Export with balanced padding – When checked, exported assets will be given extra alpha padding to centre their geometric bounds.

This last tool option bears a bit more explanation. When exporting assets, the WireCutter script will crop the art as tightly as it can. (The item’s “visual bounds”) But items in Illustrator also have “geometric bounds”, these bounds do not include things like stroke thickness and Drop Shadows. This option corrects for assets that become off-centred because of non-geometric elements.

These 2 assets have Drop Shadows that add extra space to the right and bottom, causing the button itself to be off-centre when rendered normally.

]6 These 2 assets have Drop Shadows that add extra space to the right and bottom, causing the button itself to be off-centre when rendered normally.

Resulting asset, nicely centred.

]7 Resulting asset, nicely centred.

I hope the ideas presented here help you cut out some of the wasted effort in your art pipeline. The key point of methodology here is that we are architecting a single Illustrator file that handles every deliverable that an artist will produce in the course of a project. Our wireframes can be exported as placeholder assets, the wireframes evolve into mockups as the constituent Symbols become finalized, and our mockups get chopped apart into final deliverable assets. Now, this is clearly a workflow intended for projects with a single artist, but I believe the concepts here could be useful to teams of any size, provided they share my love of making the computer do the heavy lifting.

Happy arting!

Rome Sweet Rome – An Isometric City Building Game and Framework

The latest addition to the demo projects of the DevKit is “Rome, Sweet Rome” – A city building game. This game is built with our new isometric engine which is completely open source.

rome

In this blog post we will provide an overview of the features of this new isometric engine. The engine is written in a way that the behavour can be modified with settings objects. The root class Isometric wraps instances of the models and views, emits Events and exposes a number of helpful methods.

There are settings for the following functions:

  • Generating maps
  • Handling selecting
  • Drawing on a grid: Items, lines, areas
  • Items moving on the grid
  • Particle systems

The isometric engine comes with a number of demo applications:

All these demos are meant to show separate features which makes it easy to understand how to configure the engine to use them.

Isometric: Z Coordinate in a Flat World

One of the challenges of writing an isometric game is making sure all the on-screen items are properly depth-sorted. The engine provides options to create different layers and z-indices for items and particles.

In “Rome, Sweet Rome” there are characters walking around on roads. The characters walk on a side of the road depending on the direction in which they are walking. The position of a character on a tile is given (x, y) coordinates. The z-index is calculated based on the z-index of the tile on which the characters are located, combined with a z-value derived from the (x, y) position.

The opts object is used to pass data from the model to the view. The zIndex value is a property of opts, x and y are also properties of opts. The range of x and y is 0..1. The difference between the z value from one tile to a horizontal adjacent tile is 100.

In the DynamicModel class tick function the relative z value is calculated based on the position within the tile:

The default value of this._zIndex is 0 however subclasses can assign a different value, which happens in the class of the walking characters.

If the character is walking on a road with an aquaduct above it then the this._zIndex value is given a value, there are two checkes, depending on the direction of the road and the aquaduct:

Map Conditions

Almost all actions whether it’s moving an item, changing the grid, or placing an item are conditional based on the state of the map. The Map class provides a condition validator, which is used in “Rome, Sweet Rome” to check if agents can move from one tile to another, if an item can be placed, if a road or aquduct can be drawn, and if a rectangle can be placed by the map generator.

The following editorSettings uses conditions to validate if a road can be drawn on a selected area:

Generating Tile Maps

The engine contains a MapGenerator class with very basic options for creating maps. It can draw chains of rectangles and distribute items across the maps for you.

landscape

Combining several passes with different properties allows you to create a landscape with rivers, plants, rocks and varying ground tiles.

Drawing

There are several tools for drawing items, areas and lines on the map. The engine is based on a binary representation of the tiles. Functions for joining lines are also provided through this binary approach.

When items are drawn on the map a binary OR operation is used. The index represends the contents of the tile. With an OR operation, it’s easy to add tiles! Here are two examples of adding 3×3 tiles:

00011100000 demoRoad56
00001001000 OR demoRoad144
00011101000 = demoRoad184
00001100000 demoRoad48
01001001000 OR demoRoad146
01001101000 = demoRoad178

Here’s an example adding two 2×2 bit tiles:

0010 demoGround2
0101 OR demoGround5
0111 = demoGround2

Particle System

The isometric engine provides two different ways to display particles: All items can emit particles but there are differences between how particles are initialized.

In dynamic objects a particles array property in the opts object can be set in the tick function. The elements in the array are assigned the relative positions of the particles and their types:

As long as the particles array has items, particles will be emitted each tick. Clearing the array stops the item from emitting particles, which is most efficiently done by assigning the length property:

The icons in the following screenshots are actually particles with a fixed position and a long duration:

particles

Particles can be added by using the addParticles function in the private _gridModel value from static objects.

The tileX and tileY value are to select the tile and the x and y values are for the position within the tile. Clearing particles for a given tile can be done with the clearParticles function:

You can find all the source code of “Rome Sweet Rome” in our GitHub repo and the Isometric engine is a DevKit library.

Announcing: DevKit Native Plugin System, Geolocation Plugin, and Map Library!

We are pleased to present the new native plugin system with version 0.1.22 of the Game Closure DevKit!

At the same time we are releasing Geolocation support through the plugin system, which brings navigator.geolocation to mobile platforms, so games that require it will have the permission and other games will not need to request that permission.

And moreover, we would like to put Godefroy’s Open Street Map library into the spotlight. He put a lot of good work into building an Open Street Map -based map library that works on the Game Closure DevKit:

Map Library

Many people from the HTML5 game dev community have contributed just by downloading the DevKit, trying it out, and sharing their experiences with us. Thank you all for helping!

Plugin System

This new plugin system enables you to develop unique features for your game in native code and JavaScript that will seamlessly interoperate with future DevKit versions. There are a lot of benefits:

  • Plugins allow your game to use a minimum set of permissions, which will prevent users from getting scared off.

  • These plugins can be easily shared privately with your internal development team or shared back to Game Closure to benefit the rest of the HTML5 game development community.

  • Native plugin code has access to the manifest.json file contents so you can configure the plugins through that file.

  • Native code and JavaScript interact through a message passing interface so the boilerplate code you need to write has been kept to a minimum.

Get started writing plugins for yourself and others today by reading the full DevKit Native Plugins guide.

Example Plugin: GeoLocation

Quick Mobile GeoLocation Overview

How to use the GPS unit on mobile devices varies between Android, iOS and browsers.

Browsers all implement an HTML5 standard API: navigator.geolocation.getCurrentPosition().

On Android, a special permission is needed to access the user’s GPS location. Having any more permissions than is strictly necessary to run the game on Android is a bad idea, since extra permissions scare off potential users. Furthermore, it is a good idea to kick users over to the GPS settings on the first usage of the API if they have it turned off, and this must be done manually.

On iOS, in contrast, the GPS permissions are requested in a popup at the first use of the API.

Reconciling these differences so that the user sees one simple “get coordinates” interface that works the same as the HTML5 standard is the goal of the GeoLocation plugin. And the new plugin system offers all of the tools necessary to make it happen.

Using the Plugin

Neglecting how it works for now, to use the GeoLocation plugin you will need to install it, and upgrade to the latest version of basil:

This downloads and installs the Geoloc plugin from GitHub [1]. If you want to get your plugin listed, please discuss it with us.

If you have trouble upgrading the Android or iOS addons, deleting them from the addons directory and running basil install native-android will fix that sort of issue.

Inside your games you can enable the plugin by adding it to your game’s manifest.json file under the “addons” section:

And at the top of the game’s src/Application.js:

This attaches the geolocation.getCurrentPosition() function to the navigator object.

The DevKit Native Plugins guide [2] has even more overview about how the plugins are used.

How does it work?

Plugin Directory Structure

The plugin filesystem consists of several pieces:

  • A JavaScript wrapper for the native functions.
  • A configuration file describes what files and dependencies need to be added to the native project before building.
  • The native source code that interacts with your JavaScript wrapper.

The geoloc plugin has a simple directory structure:

The index.js file is used by the addon system to notify the addon of basil events. And the package.json file is a nodejs configuration file that specifies npm dependencies for the index.js source code.

The android and ios directories contain configuration and code for the supported native targets.

The js directory contains JavaScript files to include in the import path.

./js/

For the Geolocation plugin, the ./js/install.js file is imported by import plugins.geoloc.install;. This file contains the JavaScript wrapper for the native code.

Message Passing with Native Code

To communicate with native code from JavaScript, the NATIVE.plugins.sendEvent function is used to send data to the plugin, and the NATIVE.events.registerHandler function is used to receive data from the plugin.

This message passing interface allows you to simulate a callback system, where the native code is abstracted away into a simple JavaScript functional style of code that returns when it completes. The JavaScript code can maintain an id-indexed map of request callbacks and pass ids to and from the native code to match requests with responses.

Invoking Native Plugin Functions from JavaScript

For example, to send the GeoLocation plugin a request called “onRequest” with a JSON object as a parameter:

This causes the onRequest function in the GeolocPlugin native class to be invoked.

On iOS this function looks like:

And on Android it looks like:

Processing JSON objects in native code

For Android, we recommend using the standard JSON library:

For iOS, the JSON has already been deserialized into NSObjects using JSONKit, which turns an array into an NSArray and an object into an NSDictionary, etc:

Emitting Events to JavaScript

JavaScript plugins listen for data from the native code by using the Events subsystem:

iOS

For iOS this “geoloc” event is generated with:

Note that standard NSObjects can be used in the generated event. Serialization into JSON is done for you.

Take a look at the iOS Plugin documentation [3] for the rest of the iOS plugin information.

Android

And on Android it is generated with:

Similar to the iOS version, serialization to JSON is done on your behalf.

Check out the Android Plugin documentation [4] for a complete description of the plugin system for Android.

Wrap Up and Plug In!

Supporting native enhancements and new native features has been one of the primary requests we have received since our public release. And we listened! With these powerful new tools you can contribute platform-specific features back to the development community or enhance your own product in any way you need without having to maintain your own branch of the DevKit.

Thanks again for your suggestions and feedback. We take your input seriously and decide what to work on next based on what you need. And we look forward to continuing to provide the best HTML5 mobile game development toolkit available!

References

Some reference documentation for the plugin system:

1 Geoloc plugin example

2 DevKit Native Plugins guide

3 iOS Plugin documentation

4 Android Plugin documentation

GC Wins Grand Prize @ TDC 2013 Hack-a-thon

GC @ TDC 2013

Our mission was simple: build a game in 24 hours. Typically, this would mean locking your team in a room for the entirety of the project, and putting aside daily routines like sleeping and bathing in favor of a delirious scramble to produce as much as possible before time runs out. Armed with the Game Closure devkit, however, we had a much more enjoyable game jam experience.

We attended the hack-a-thon at the Tizen Developer Conference as two teams. Jeff Himmelman and I were charged with the task of building a new game on the Game Closure devkit, while Martin Hunt and Tom Fairfield ported our devkit to the Tizen platform. I think it’s fair to say that Jeff and I got the better end of that deal.

Laden with laptop bags and a massive Cintiq art tablet, we arrived late Friday afternoon and immediately got to work. Immediately… after procuring a few glasses of red wine and socializing with other conference-goers. The Hilton’s Hacker Lounge was abuzz with HTML5 companies and enthusiasts; we felt right at home. It was exciting to see other industry pioneers like Ludei and MultiPlay.io presenting their tech and sharing our passion for HTML5! After all, Tizen’s development environment is based on HTML5, so it’s no surprise that we were all drawn to the conference like bears to honey.

Jeff and I set about our craft in the midst of hors d’oeuvres, ping-pong, and arcade games. We decided to build Gummy Jam, a sugary spin on a game called 2Fuse by MojoForest. It’s a fast-paced 60-second puzzler and simple enough to build within the allotted time. Jeff had some candy-themed concepts working in just under an hour. We had a fully functional prototype by midnight, but we didn’t stop there. After the commute home to Mountain View from San Francisco, we reconvened at Jeff’s house, aka “The Himmelmansion”. We watched an episode of Adventure Time for extra inspiration and then got back to work. By 4 AM, we had finished implementing the core of the game, including the art, so we happily set aside 6 hours for sleep, and planned to devote the final 8 hours of the hack-a-thon to polish, effects, and the drive back to SF.

Gummy Jam game screen

By the end of the competition, Martin and Tom had successfully ported the GC devkit to run on Tizen phones and simulators, and demonstrated two of our existing games in action. Gummy Jam performed on a Tizen phone without any trouble, despite the ice-cream-float special effects and excessive carbonation particles! We won the grand prize for “Best New App”, but we couldn’t have done it without the devkit!

Gummy Jam with power-ups active

All-in-all, Jeff and I each only spent about 12 of the 24 hours actually working.

The Game Closure devkit is armed to the teeth with tools to help make UI, animations, and polish quick and easy to implement. At its root, the devkit’s view hierarchy and built-in view classes make laying out UI simple, even whilst supporting multiple aspect ratios. My preferred approach is to normalize and scale-to-fit the widths of full screen views with the device’s width, thus simplifying the change in aspect ratio to a mere change in height. We’re so used to the flexibility of the devkit, we didn’t even think about the Tizen phone’s resolution. This may sound more complicated than it is, here’s some code to clear things up:

576×1024 corresponds to our 9:16 background art asset sizes (1024 is the max texture size on some phones). We also know that our smallest workable area, based on the max aspect ratio of 3:4, will be 576×768. After this code has been executed, we can then initialize full-screen views like this:

Now, to position the background art centered, we do this:

Note that the scale is not repeated since the background’s parent is already scaled. We now have two useful parent views to use. To position things along the edges of any device’s screen, we can rely on this.menuView’s boundaries. To position things relative to our background art, we can use this.menuBackground’s boundaries. The devkit provides a layout system for more complex, dynamic UI. You can also read more about our basic scaling strategies.

To top it all off, our robust animation library and particle engine allowed us to produce high levels of polish in a very short amount of time. My favorite animation in Gummy Jam was the “mistake jiggle”. When you try to match two pieces incorrectly, they both shake back and forth quickly to communicate the mistake to the player. I call this function on the two blocks:

The animate code is pretty simple, you can probably read exactly what’s happening from the code, but here’s a quick explanation just in case. We call animate on the subject view of the animation, in this case, block. The ‘.now’ call starts the animation immediately, and the ‘.then’ calls queue up subsequent animations. The first parameter is an object populated with the properties that we want to animate and their desired end values. First we drop the scale and opacity of the blocks slightly, while also starting their first shake movement, which is actually just rotation, r. The second parameter is the duration of the animation, and the third is an easing function baked into our animation library. The alternating variable shakeSign ensures that the two blocks rotate in opposite directions since they are both animated simultaneously. If you’re wondering about the model.timeMultiplier, we have an ice-cream power-up that slows time, so we can divide by the multiplier to increase the animation duration while the power is active.

I hope this has given you a good glimpse of what it’s like to build games with Game Closure, because for me, using the devkit is a dream come true. Thanks to everyone who hosted and attended TDC 2013! Thanks to Michael Carter, our CEO, for helping us find music and sound effects for the game! Thanks to Wei Deng, GC’s Head of Operations, for organizing this adventure and helping us get access to Tizen hardware! Special thanks to the whole Game Closure family for all of their hard work, especially on the devkit, that made our victory possible!