Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Resource packager for Javascript games
JavaScript
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
test
.gitignore
LICENSE
README.md
package.json

README.md

Swallow

What it is

  • A directory scanner which packages files into a single JSON file
  • A small part of your build chain

What it is not

  • A complete end-to-end framework
  • A client-side loader
  • An elephant

Why?

  • You have a large number of assets (textures, sounds, models, shaders) which are needed for the game to run
  • You want to know when they're all loaded so the game can start
  • Doing 500 HTTP requests on start-up seems a bit excessive
  • You don't want to load most things on demand, but working out what you need is a bit of a bother
  • You want to package all of those assets into single deployable files as JSON and load them out the other side without changing too much code
  • You want to be able to create a package which can be played offline

How

Given a directory of assets, and an appropriate structure within:

  - assets
    - models
      - craft.json
      - tree.json
    - textures
      - craft.jpg
      - grass.jpg
      - snow.jpg
      - sky.jpg
      - smoke.jpg
    - sound
      - explosion.wav
      - engine.wav
    - shaders
      - super.fragment
      - super.shader
      - particles.fragment
      - particles.shader
    - etc

And some code like so:

var swallow = require('swallow');

swallow.build({
  in: './assets',
  out: './assets.json'
});

A file (assets.json) will be generated containing all the data in the specified directory.

This can be downloaded and consumed in one go like thus:

$.getJSON('/assets.json', function(data) {
  var audioData = data['assets/sound/explosion.wav'];
  var audio = new Audio();
  audio.src = "data:image/png;base64," + audioData;
  // etc
});

You'll more likely want to enumerate the package when it is down and pre-load the assets, there is code on the way to do that as it needs extracting from the project that this library was pulled from in the first place.

Adding extensions

There are some convenience methods supplied to help with this process, the following will suffice for most scenarios:

var swallow = require('swallow'),
    handlers = swallow.handlers;

swallow.build({
    in: './in/assets',
    out: './out/assets.json',
    extraHandlers: [
      handlers.byExtension('.shader', handlers.text),
      handlers.byExtension('.model', handlers.json),
      handlers.byExtension('.crazy', handlers.binary)
    ]
});

In the above example, we use the built in handlers, which match by file extension and can deal with the obvious content types.

A handler is just an object with two methods,

valid: function(filename, callback) {
  callback(true);
}

Given a filename, the callback should be invoked with either 'true' or 'false' depending on whether the handler is valid for the file passed in.

handle: function(filename, callback) {
  callback(err, data);
}

Given a filename, callback should be involved with something that is serializable into JSON, or an error if one occurs.

TODO

  • Dependencies between assets
  • per-level/world-area/ asset file generation (taking into account the dependencies)

Client code

I'll release some client code as another Github repo once I've extracted it from my game

  • For loading assets (already written, needs extracting from one project into another project
  • Transparent client code for loading assets from either file or server if not in fileT
Something went wrong with that request. Please try again.