hexr-engine v4.0.2

Hexr Engine

Intro

Sort of a 2D game engine for Three.JS. Feed it data from the Hexr editor and it outputs meshes and sprites and stuff. It has no physics or collision detection subsystem built in.

I need to publish the source for this in order to use it for the Ludum Dare competition, so that's what I'm doing. I don't think this is ready for public consumption.

What is it

Hexr Editor outputs a JSON file which contains:

• textures in base64 format
• sprite data (including animation data)
• map prototype data (map prototypes define the number and type of layers and custom metadata associated with each map)
• object prototypes (it supports three types of objects: points, boxes and sprites)
• map data (which supports tile map layers and object layers)

Hexr-Engine then:

• Turns the tilemap into a single mesh (as much as possible. Only tile using the same tilesets can be merged)
• Generates object for all object instances defined in object layers in the maps
• Generates meshes for all sprites
• Lets you manually generate sprites and instances that aren't in the map
• manages initialising, updating and destroying levels and all the individual objects.

This is all incredibly early.

## Usage

// point level runner at your hexr editor data:
var levelRunner = require('hexr-engine')({ 
    scene : someTHREEScene 
  }, 
  require('./my-hexr-editor-data.json'));

Whilst hexr-engine takes care of a lot of stuff, you'll probably have a lot of stuff you need to do manually so the levelRunner object lets you subscribe to various events.

  levelRunner.on({
    initialised : function (currentLevel, levelMeta){

      // after a level/map has been initialised, this fires. 
      // levelMeta is the custom metadata for this map
      // currentLevel is an object that contains all the 
      // objects and tilemap meshes generated

    },
    updated : function (worldTime, levelMeta){

      // after all the objects have been updated,
      // this gets called.

    },
    destroyed : function (levelMeta){

      // when the level/map is done and everything
      // has been completely destroyed, this fires.

    },
    'new-parallax-mesh' : function (mesh, levelMeta){
      // whenever the system has finished generating a parallax tilemap layer, this gets fired.
      // why the seperation?
      // well, basically because all the other tilemeshes are, as much as possible, merged into
      // a single mesh. This separation means you can do whatever you need to the parallax..
      // i.e, move it around manually or scale etc.

    },
    'new-tilemap-mesh' : function (mesh, levelMeta){
      // whenever the system has finished generating a tilemap layer, this gets fired.
    },
    'new-object' : function (object, levelMeta){
      // whenever the system has finished creating an object... this gets fired.
    },
    'new-tilemap-collision-box' : function (boundingBox, levelMeta){
      // whenever the system finds a collision box for the tile maps, this also gets fired.

      // this would be a good place to add it to your physics system....

      var body = shitPhysics.makeBodyFromHexrTilemapCollisionBox(boundingBox);

    }

  });

You can also set and get user data, handy for persisting various computed values during initialisation which you then want to use later.

levelRunner.setUserData('sky colour', new THREE.Color(levelMeta['sky-color']));
sky.material.color = levelRunner.getUserData('sky colour')

The next big thing are object handlers.

  levelRunner.addHandler('player', {
    initialise : function (player){

      // you probably want to add some sort of physics thing here..
      // and so any further customisation of the basic player object 

    },
    update : function (player, worldTime){

      // every tick this will get called. Do what you need.

    },
    destroy : function (object){
      // any tear down stuff goes here.
    }
  });

Hexr-Engine will warn you if your map contains an object that doesn't have a handler in code. Otherwise it will automatically run these handlers for every instance of an object it finds in the map.

You run a particular map with

  var handle = levelRunner.run(mapId);

This runs all the handlers and generates all the meshes for that particular level. Meshes and sprites are automatically added to the scene, so it's up to you to use the various callbacks that fire to make something different happen. Like, say, move an object's mesh into a different scene or manipulate the colour or opacity or basically something not supported by the engine automatically.

The handle returned by run has several methods:

  handle.stop(); // this.. this hasn't been tested at all yet. It's the next thing on the to-do list.
  handle.update(...); // you MUST call this every tick and pass it whatever you want. These params will be cascaded to all other objects 
                      // with an update method. Typically you'll want some sort of worldTime and if you're using hexr-shit-physics
                      // you'll want to pass the output of shitPhysics.test(), for example. 
  handle.getLevelMeta() // returns the custom metadata about this level
  handle.pause() // untested
  handle.resume() // also untested

Licence

MIT