Manual

Introduction

Isogenic Engine is a client and server-side JavaScript system that provides a scene-graph with built-in multiplayer functionality. Simulations running on the server-side can be automatically streamed to all connected clients, or sectioned off into distinct rooms in which only those clients that are participating receive updates.

The engine fully supports both 2d and isometric rendering and can run either with or without multiplayer functionality. A build system is also included to automatically scan your final game code, detect the sections of the Isogenic API that you have used and minify your game and Isogenic into the smallest possible package ready for deployment.

Installation

Single or Multiplayer?

If you intend to use the Isogenic Engine's multiplayer stream system you will need to have a server with Node.js setup. If you are not developing a multiplayer game you can skip this step.

Open a command prompt, change to the ige/server folder e.g. cd /ige/server and then execute:

npm install

All of the engine's dependencies will then be installed under the /ige/server/node_modules folder.

Getting Started

Folder Structure

First, unzip (or clone the git repo) to a folder that is best for you. Once you are done and you want to start to develop your first game, the folder structure you should aim for will look something like this:

+ Root Development Folder
+-- ige (Where you unzipped or cloned the engine to)
+-- Your game folder (where you do all your game development)

If you follow this structure, you will be able to pull new versions of the engine in (or unzip them on top of) the existing “ige” folder without affecting your game code. You can also add your game folder to a public GitHub repo without including the private engine code accidentally (remember, publishing the engine’s code to the internet in its raw un-obfuscated form is against the terms and conditions of your license).

Updating the Engine

If you have cloned the repo via git (or the GitHub app) you can update the repo at any time by opening a terminal window, changing directory to the “ige” folder and typing:

git pull

Running the Examples

Client-Side Examples

Please Note

Many browsers such as Google Chrome expect you to run web pages from an HTTP server such as Apache, NGINX or via a package such as WAMPServer (also uses Apache).

If you do not you are likely to run into errors such as “Uncaught Error: SecurityError: DOM Exception 18″. Lots of users have found this error confusing and assume the engine is not working… PLEASE RUN FROM A LOCAL WEB SERVER!

As a web developer, making web-based games and simulations, you should already have a local web server running.

Load the Startup Example
Browse to the ./ige/tests/1.1.0-startup folder
Double-click index.html

You should now see something like this:

The game code for the example is located in the client.js file.

Server & Network-Based Examples

Please Note

Before you try to use the server-side, please ensure that you have Node.js and have run the engine installation.

Load the Network Stream Example
cd /ige
node ./server/ige -g ./examples/24.1-network-stream

That will execute the IGE server and run the example in the 24.1-network-stream folder. Then you should open your browser and load the index.html file for the associated example from your webserver.

Isogenic Node.js Server

Isogenic Engine will not serve static game files from the Node.js server, it only serves to handle incomming socket connections for multiplayer / streaming functionality.

You must serve your game files from a separate HTTP server such as apache.

If you’re wondering why that is, using Node.js to serve HTTP requests while also serving game server requests can cause the game server process to block when reading static files from storage. While this can be mitigated by running separate child processes it is pointless to write and maintain an HTTP server when so many existing projects already do the job.

The IGE server is not meant to be a full HTTP server replacement and there are already many well-maintained applications that are excellent at providing multi-threaded HTTP services such as NGINX and Apache.

Quick Reference

Setup a Basic Scene

At a minimum to get some graphics on the screen you need to have both a viewport and a scene defined and added to the engine.

The engine has a quick built-in way to add a scene and viewport for you:

ige.addGraph('IgeBaseScene');

That call will add a viewport with the id "vp1" and a scene with the id "baseScene" to your engine scene graph. The viewport is set to fill the screen to that your scene will be rendered across the entire canvas.

Creating an Entity

Entities are the building blocks of your game / simulation. They can be transformed (translated, rotated and scaled) and can have textures assigned to them (images). Creating an entity is very simple:

var entity = new IgeEntity();

Mounting an Entity

Once you have an entity, you can mount it to your scene, or another entity. If you mount one entity to another one, transforming the parent entity will also transform the child. This allows you to build up complex scenes from single entities stacked or "mounted" to one another. To mount an entity to something, use the mount() method. Let's go ahead and mount our entity to the baseScene:

var baseScene = ige.$('baseScene');
entity.mount(baseScene);

In the code above we used the selector method to get the baseScene object by it's id, then we mounted the entity to the baseScene by calling the entity's mount() method and passing the baseScene object to it.

Loading a Texture

Even though we have mounted our entity, the engine has nothing to render because the entity has not been assigned a texture (image) to render. Let's load a new texture:

var tex = new IgeTexture('https://www.isogenicengine.com/assets/logo2.png');

Keep in mind that loading textures is an asynchronous process. You can listen to the load event or check the tex._loaded flag is true to find out if a texture has been loaded or not. The engine also has a global "texturesLoaded" event that allows you to listen for when all game textures have finished loading. You can use it like this:

// Listen for the texturesLoaded event from the engine
ige.on('texturesLoaded', function () {
    // All textures have loaded, start your game logic etc
});

// Load all our textures up front here, when they are loaded
// the listener above will be called
var tex = new IgeTexture('https://www.isogenicengine.com/assets/logo2.png');

Applying a Texture

Now we have a texture loaded, let's assign it to our entity so that the engine will render it:

entity
    .texture(tex)
    .dimensionsFromTexture();

The first call to texture() passes the texture the entity should render and the second to dimensionsFromTexture() tells the entity to size itself to the texture's dimensions (the image width and height).

© Copyright 2013 Irrelon Software Limited. All Rights Reserved. UK Registered Company Number: 07522767
Isogenic (ī´sōjen´ik): Adj originating from a common source; possessing the same genetic composition.
Strange Things Happen at the One Two Point