Getting Started

by @collinhover

Welcome to Impact++! Our goal in this tutorial is to get you up and running as fast as possible, without wasting your time whether you're new to ImpactJS or a long time user. Let's break this down into a step-by-step:

1. The HTML file

We'll assume you're starting simple, so make sure you have an index.html file in your game's root directory. In this file, you'll need the basic HTML code for any page (head, title, css, body), as well as two additional pieces: the canvas and the core javascript files for ImpactJS and your game.

/* HTML */
Canvas element with id="canvas"

/* Scripts */

/* CSS (optional) */
html,body {
    background-color: #111111;
    color: #fff;
    font-family: helvetica, arial, sans-serif;
    margin: 0;
    padding: 0;
    font-size: 12pt;
#canvas {
    position: absolute;
    left: 0;
    right: 0;
    top: 0;
    bottom: 0;
    margin: auto;

2. The main.js file and the main module

Open your main.js file, and setup the basics of a module (this assumes your main.js is blank):

ig.module('game.main').requires('plusplus.core.plusplus').defines(function () {});

The above is calling ig.module to create a new module in the "game" folder with a name of "main", then telling that module to require another module in the "plusplus/core" folder with a name of "plusplus", and finally defining a function to be executed when all requirements are loaded.

3. Create a custom game class

Inside the defined function for our main module we'll add the code to make a custom game class:

ig.module('game.main').requires('plusplus.core.plusplus').defines(function () {
     var myGameClass = ig.GameExtended.extend({ /* game settings go here */ });

This creates a new game class for your game and assigns it to the myGameClass variable. ig.GameExtended is a layer Impact++ adds on top of ImpactJS's ig.Game, and it will coordinate all of your main game logic such as updates and rendering. Remember, you can always get a reference to the currently running game using (note the lowercase).

4. Starting a blank game

ig.module('game.main').requires('plusplus.core.plusplus').defines(function () {
    var myGameClass = ig.GameExtended.extend({ /* game settings go here */ });
    ig.main( '#canvas', myGameClass, 60, 320, 240, 1, ig.LoaderExtended );

The new line above tells ImpactJS to start a new game that will draw into the HTML element with an id of "canvas", using myGameClass to control the game, to run at 60 fps, to have a size of 320 x 240 and a scale of 1, and to use the Impact++ customizable loader. Remember, Impact++ can scale dynamically based on the screen size and can be resolution independent (see step 8 on config).

5. Structure

Before you can add anything to your game, you'll need media such as images, sprite sheets, and sound files. ImpactJS has a strong opinion on the organization of your project, and Impact++ has been built with the same opinions in mind. Your game directory should look something like this:

            (your game entities)
            (your game levels)
        (ImpactJS engine files)
        (Impact++ files)
        (ImpactJS and Impact++ editor files)
    (images, sprite sheets, sounds)

6. Loading a level

Making levels with Impact++ is no different than with ImpactJS, so go ahead and make a level using the Weltmeister editor, called "test". While you're working with the editor, don't forget to copy the lib/weltmeister/ from your Impact++ download into your project's lib/weltmeister directory. Now, let's add your test level to the game:

.defines(function () {
    var myGameClass = ig.GameExtended.extend({
        init: function () {
    ig.main( '#canvas', myGameClass, 60, 320, 240, 1, ig.LoaderExtended );

7. Creating a player character

We'll need a player character so we can explore our test level. In the game's entities folder, located at lib/game/entities/, create a new file called player.js. To create the most basic of player characters, place the following code into the new file:

ig.module( 'game.entities.player' )
.defines(function () {
    ig.EntityPlayer = = ig.Player.extend({
        animSheet: new ig.AnimationSheet( "media/player.png", 32, 32),
        animInit: "idleX",
        animSettings: {
            idleX: { sequence: [0], frameTime: 0.1 }

The idea here is to create a new entity, ig.EntityPlayer, that extends Impact++'s player abstract which has all sorts of built in functionality. Next, open up / refresh the level editor, Weltmeister, and add the player entity to your test level's entities layer. Once your restart your game, Impact++ will hook the player entity automatically and you should be able to move, jump, and climb all around the level. You can add animations to an entity the ImpactJS way, or you can add them through the animSettings object by following the format of the "idle" animation example above. If you need a test player sprite sheet, check out the Run N' Jump or SUPERCOLLIDER example media folders.

Remember, Impact++ expects animations in a "name" + "direction" format, and entities that extend the ig.Character abstract, such as the player abstract above, expect specific animation names for various action. For example, when moving the player entity will automatically try to play "moveX" and "moveY" if we can flip/mirror on the x-axis and y-axis, otherwise it will try to play "moveLeft" or "moveRight" and "moveUp" or "moveDown", if we cannot flip on the x-axis and y-axis. The full list of automatic animation can be found in the docs for ig.Character

8. The configuration files

One last optional thing we can do is fiddle with settings. In the lib/plusplus/core folder, you'll find a config.js file, and in the lib/plusplus/ folder, you'll find a config-user.js file. The config file has a huge list of settings for almost every option in Impact++, and any of those settings can be overwritten by the user config file. For example, let's have Impact++ to do some heavy lifting for us when it comes to resizing the screen. Place the following into your config-user.js file, inside the module definition:

    // make the game fullscreen!
    // dynamic scaling based on dimensions in view (resolution independence)

10. Learn More!

Player Manager
Player Abstract
Character Abstract
Config file