Starter Basics

Draw Text

This starter project demonstrates how to setup a simple HamonEngine implementation in HTML & JS, requiring only a canvas element in the HTML and overriding the hamonengine.core.engine class.

See Storyboard Starter Demo for creating a starter project using the Storyboard.

HTML Source

The following HTML creates the 1st canvas (screen) for the engine to use as the primaryScreen.

NOTES:

• A screen in the HamonEngine is a special wrapper class around a HTML canvas that provides additional functionality to simplify its usage.
• The HamonEngine will automatically detect all canvases (screens) on your page by default and the first canvas (screen) to be detected without a name will be known as the primaryScreen in the engine.
• Any canvas (screen) that does not have a name attribute will be assigned the name 'canvas(index)', where the index is the order of the canvases detected.
• Automatic canvas (screen) detection can be disabled by setting the engine option detectCanvas to false and providing a collection of HTMLElement canvases to the property canvasCollection.

JS Source

The following JS snippet demonstrates how to draw text to the PrimaryScreen. Note that the text is drawn at the center of the viewport.

constructor(options={}) {
    super(options);
}
renderBasics(screen, elapsedTimeInMilliseconds) {
    //Always begin painting before drawing anything to clear the previous etching on the canvas, as well as set the viewport and fill color. 
    screen.beginPainting();

    //-----------------------
    //Add drawing logic here.
    //-----------------------

    //Draw Hello World at the center of the screen (viewport).
    const x = screen.viewPort.center.x;
    const y = screen.viewPort.center.y;
    screen.drawText(`Hello World`, x, y, { font: '48px serif', color: 'yellow', textOffset: 'center', verticalTextOffset: 'center' });

    //End painting to clean up and restore the canvas to a state before transformations were applied.
    screen.endPainting();
}
onFrame(elapsedTimeInMilliseconds) {
    //Render the text to the primaryScreen, the canvas without a name.
    this.renderBasics(this.primaryScreen, elapsedTimeInMilliseconds);
    ...
}
                            

Handling Events

HTML Source

The following HTML creates a second named canvas (screen) to demonstrate the output of event handling.

NOTES:

• Providing a name to the canvas (screen) gives you more control of what canvas to use. In most cases, only one canvas will be used on a page.
• In order for a canvas (screen) to respond to events, the data attribute allowEventBindings must be set to true.
• By default, keyboard events can only be captured if the canvas has focus. If the option allowDocumentEventBinding is set to true then the HamonEngine will capture ALL document events regardless of the element in focus. Be cautious using this option, as all events will be funneled through the onKeyEvent event, for example, arrow keys will no longer scroll the page up and down.

JS Source

The following JS snippet demonstrates how to handle events on the 'event-handling' screen.

constructor(options={}) {
    super(options);
}
renderHandleEvents(screen, elapsedTimeInMilliseconds) {
    //Always begin painting before drawing anything to clear the previous etching on the canvas, as well as set the viewport and fill color. 
    screen.beginPainting();

    //-----------------------
    //Add drawing logic here.
    //-----------------------

    //Draw _keyEventMessage & _mouseEventMessage at the center of the screen (viewport).
    const x = screen.viewPort.center.x;
    const y = screen.viewPort.center.y;
    screen.drawText(this._keyEventMessage, x, y, { font: '24px serif', color: 'red', textOffset: 'center', verticalTextOffset: 'center' });
    screen.drawText(this._mouseEventMessage, x, y + 32, { font: '24px serif', color: 'red', textOffset: 'center', verticalTextOffset: 'center' });

    //End painting to clean up and restore the canvas to a state before transformations were applied.
    screen.endPainting();
}
onFrame(elapsedTimeInMilliseconds) {
    ...
    //Render the event binding actions to the screen with the name 'event-handling'.
    this.renderHandleEvents(this.getScreen('event-handling'), elapsedTimeInMilliseconds);
}
onKeyEvent(type, keyCode, e, caller) {
    //Allow engine to run it's base logic, which is just logging.
    //This logic can be omitted.
    super.onKeyEvent(type, keyCode, e, caller);

    //Only respond to key events for our 'event-handling' screen.
    if (caller === this.getScreen('event-handling')) {
        //Add key code event handling logic here.
        this._keyEventMessage = `keyCode: '${keyCode}'   keyType: '${type}'`;
    }
}
onMouseEvent(type, v, e, caller) {
    //Allow engine to run it's base logic, which is just logging.
    //This logic can be omitted.
    super.onMouseEvent(type, v, e, caller);

    //Only respond to mouse events for our 'event-handling' screen.
    if (caller === this.getScreen('event-handling')) {
        //Add mouse event handling logic here.
        this._mouseEventMessage = `mousePosition: '(X: ${v.x}, Y: ${v.y})' mouseType: '${type}'`;
    }
}
                            

Starting the Engine.

Starting the engine simply requires the snippet of code below. The class starter is derived from hamonengine.core.engine.

The engine should call the load method first to load all resources, bindings, or perform any other pre-starting logic. Since the load method will return a promise, the logic can await before caling the start method.

(async function() {
    (await new starter().load()).start();
})();