Erik Onarheim

2024 The Best Worst Year

Sat, 08 Mar 2025 00:00:00 +0000

My Darling Daughter

2024 started with paternity leave, and spending lots of time with my daughter and family. It was a wonderful time. There was more laughter than tears.

Technically my daughter Maeve was born in 2023, but she's really become her own person this year. Such a wonderful human. So full of smiles and giggles, they bring me life. She's hands down been the best thing that's happened to me.

Family in Norway

The whole family in America got to travel to Norway for 2 weeks, we met with all our extended family on my father's side and reconnected with folks I haven't seen in years. I learned a lot of transactional Norwegian.

We landed in Bergen and spent a week there! Our family surprised us at the airport with a big van to bring us to our lodging, I was so happy I almost cried after the long travel day. We really appreciate Sigbjorn driving us around. They brought us groceries and my great aunt even baked us a chocolate cake ❤️🎂

My cousin Margrette (though we call her aunt) loved our daughter Maeve, she was such a huge help while we were there.

We stayed nearby historic Bryggen (think colorful historic buildings on the water), which has a lot of fun food and shopping. We ate some traditional fair at Bryggeloftet

One of the most memorable was our visit to the village of Onarheim on the island of Tysnesøya to see the family farm and have a big reunion.

We took the scenic train ride across Norway to Oslo, which was absolutely wonderful! You should definitely take this train ride if you visit.

NDC Oslo 2024

While in Norway, I presented at the prestigious NDC Oslo! I gave my spicy talk about serverless tech "You Don't Want Serverless"

Serverless is a lose-lose. Don't use it. There's been a lot of over-hype around it and I'm here to tell you not to buy in.

I'll talk about the various shortcomings, mitigations, and solutions!

Cloud provider business incentive misalignment
Very poor developer experience
Cold starts and performance problems
Concurrency myths
Cheap cost myths
Finally when you should use serverless, spoiler alert there are very few use cases that make sense

At the end of this you'll know when and where to use serverless, and when to use "boring" technology to solve your problems.

NDC Oslo 2025

I'll be back in Norway in 2025 about how to make JavaScript Blazingly fast! lessons from a game engine.

Is your app slow? Don't blame JavaScript! It might be a problem between the chair and the keyboard...

I've spent over a decade building a game engine for the web called excalibur.js, I've learned a ton of tricks and techniques to make JavaScript run BLAZINGLY fast. These learnings are broadly applicable to more than just games, they've been very useful in my day to day work building massive web applications for EdTech.

You'll learn how to:

Demystify the browser performance tools in Chrome & Firefox
Optimize slow functions
Identify and prevent memory leaks
Cache expensive computations
Prevent regressions
And when to use WebWorkers, WASM, WebGPU, and TypedArrays

You'll walk away with practical JavaScript optimization techniques you can apply RIGHT NOW!

Death

In August my father passed away suddenly. It's been pretty hard. He was a great man, and a wonderful father. Great listener, full of laughter, and always quick with a joke.

He loved our daughter, and I'm glad she was able to meet him. Also he fed her a chocolate donut 🍩 when babysitting instead of the baby food I left him. They were two peas in a pod, that girly sure does love chocolate, always room for dessert.

I'm glad we were able to take him to Norway, he has wanted to visit again for years. The last time he was there he was 12 years old with his mother and father.

Navigating the world without him has been challenging for the entire family. So many things remind me of him, he brought a lot of smiles to all of us.

2D Con

Excalibur did its first convention at 2D Con in August in Bloomington Minnesota! And we won a gameplay award at the show!?

We presented 3 of our high fidelity sample games

Sweepstacks

Sweep across the screen to clear blocks! It's a match-3 like where you can also match diagonals.

This game was originally created for Ludum Dare 31 where it placed in the top 100. Coming soon to app stores near you!

Click on the image to play! (Warning addictive)

Sum Monsters

Play the mathimagical game where you arrange monsters to complete the dungeon’s sum-mons. May Trix the Witch is doing all she can to bring the dungeon to order!

It's like sudoku, except you're trying to sum the rows and columns to the desired number to clear the stage

Click on the image to play! (Warning addictive)

Jelly Jumper

High fidelity sample of a platforming game with jump physics inspired by Super Mario World!

This was created with painstaking effort by our new maintainer Matt Jennings.

Click on the image to play!

Distance Running

Not my best running year, I've definitely slowed down from my successful sub-4 hour marathon at Grandma's in 2023. My plan for this year is to keep it simple, work on the fundamentals and base build then race again in 2026. My new goal is to run sub 3:30, and eventually I'd like to qualify for the Boston marathon.

IGDATC (International Game Developers Association Twin Cities)

Pronounced "igg-daa-TC" by the locals 😁

I've recently become very active in the IGDATC, volunteering, speaking, and attending events.

I've made a lot of new very talented friends that have been wonderful, and they are willing to listen my nonsense about games in JavaScript/TypeScript. I'm especially fond of our late night Applebee's/Mac's game dev discussions.

Presented about building Excalibur.js, the Friendly Open Source Game Engine

Excalibur

Excalibur has had a BIG year!

We've added 2 new official maintainers with commit access, Justin Young and Matt Jennings!
We did our first con! (2D Con!)
Started a Discord
Saw Huge community growth
Tons of cool stuff being built
Tons of new features
New plugins: Tiled Rewrite, LDtk, Spritefusion, Path Finding, JSFXR, and more!
Large number of new contributors
Check out my other posts about excalibur

Caliburn Games

Started a business to publish and make games in Excalibur.js

We're currently offering custom development projects, game dev consulting, and professional support!

Check us out if you're interested! Caliburn Games

Our plan for 2025 is to release 2 commercial games on various platforms AND offer Nintendo Switch Console publishing!!!

C Programming

One of my goals this year was to re-learn C. I definitely did classes in university but I don't really think I understood it that well.

One reason C appeals to me is that it's the original lingua franca of computers, if it can run in C it can run anywhere. Similarly JavaScript has become the new lingua franca, running everywhere with Electron, Capacitor.js, Tauri, etc. I'm attracted to the simplicity and portability of C.

One of the coolest things is that the Lua interpreter "lua.c" is a single iso C file meaning its super easy to include ANYWHERE because of the portability of C. Heck Balatro was written in Lua with Love2D! Really speaks to the power of C.

I picked up the book "Effective C" and can recommend . I've pre-ordered Modern C, 3rd Edition C23

I spent this year's Advent of Code learning modern C 23 and clang, you can observe my probably poorly written C here

Neovim & RSI

Another bummer is I've managed to develop a RSI (repetitive stress injury) this year in my hands! It really sucks! It's quite painful to pick things up wrong, or to lean incorrectly on my fingers.

I'm learning Neovim to hopefully help this, and it's definitely taken me a solid 2 months to get fast in it. I'm pretty fast now-a-days, this blog post was written in neovim!

I'm looking into ergonomic keyboards. I think concave key wells are probably my best bet. I've yet to purchase one, so if y'all have some affordable recommendations send them my way.

Optimism, Dreams, and Schemes

Despite the disappointing and terrible events in 2024, I remain optimistic about the future. Even though life will be very different, and probably really hard for the next few years, we have good friends and family to get us through. I want to have a world my daughter can grow up in where she'll have the most opportunity possible.
I'm excited about my business
Planning on shipping a commercial game this year using Excalibur.js to Nintendo Switch! It's going to be something chill and cozy that everyone can enjoy.
We have a conference coming up at VGM Con in April 2025!

Cheers,

Erik

Animating with Coroutines

Thu, 02 Jun 2022 00:00:00 +0000

Using an concept known as coroutines you can produce some really nice looking imperative animation code! I was inspired by two great YouTube videos recently to try a new approach to building animations in games.

// Look at this nice imperative animation code 😎
coroutine(function* animation() {
    // scale the entity 2x over 1000 ms duration
    yield* scaleTo(entity, 2, 1000);
    // delay animation 1000 ms duration
    yield* delay(1000);
    // move the entity to (200, 100) 500 ms duration
    yield* moveTo(entity, {x: 200, y: 100}, 500);
    // rotate the entity to 4 PI  over 1000 ms duration
    yield* rotateTo(entity, 4 * Math.PI, 1000);
});

TLDR show me the code

What is a coroutine anyway?

The word "coroutine" definitely sounds fancy! Coroutines are a type of suspendable execution. They are a useful way of simulating concurrent tasks or sequences over time without blocking the main thread. They are made possible by a new(ish) feature in JavaScript called generators!

Why are they called "coroutines"? Well it's because they cooperatively share execution. In our example below the coroutine passes control into the generator, and it yield's control back up to the coroutine.

In our example, we are working with animation's over time, so each yield can be thought of as a single frame that takes an "elapsed" amount of time.

function coroutine(generatorFunction: () => Generator<any, void, number>) {
    const generator = generatorFunction(); // instantiate the coroutine
    generator.next(); // execute until the first yield to start the generator
    return (elapsed: number) => {
        return generator.next(elapsed);
    }
}

coroutine(function* myAnimation() {
    let elapsed: number;
    // each yield represents a frame
    elapsed = yield; // frame 1
    elapsed = yield; // frame 2
    elapsed = yield; // frame 3
    // ...
});

Implementing Animations with `requestAnimationFrame`

We need something to drive updating each frame for our animations, we can use a classic game update approach with requestAnimationFrame.

let lastTime = performance.now();
let running = true;
const mainloop = (time: number) => {
    try {
        if (!running) return;
        requestAnimationFrame(mainloop);
        const now = time;
        const elapsed = now - lastTime;

        // update coroutines
        for (let animation of animations) {
            animation(elapsed);
        }

        // draw stuff
        clear(ctx);
        draw(ctx, elapsed)
        lastTime = now;
    } catch(e) {
        running = false;
        throw e;
    }
}
mainloop(performance.now());
animations.push(coroutine(function* myAnimation(){ ... }))

Now we can use our fancy coroutines to make some fancy animations!

MoveTo Generator with Linear Interpolation

We can build some animation primitives. One of the first things you might want to do is move things around, something like moveTo which will animate an entity to a set of coordinates over a duration.

First things first we'll need to define a "Linearly Interpolate" function, or as they say in the biz "lerp". Traditionally easing functions like lerp specify a numeric start and end value, and a time between 0 and 1.

This means that when time is 0, we return the start, and when time is 1 we return the end, else we mix them. Looking at our example below that math checks out. You can think of this as a weighted average between the start and end over time 😎

const lerp = (start: number, end: number, time: number) => {
    return start * (1-time) + end * time;
}

Another useful helper is clamp, which is useful for keep a value between an upper and lower bound. And it is important that our time passed to lerp stays in between 0 and 1.

const clamp = (val: number, min: number, max: number) => {
    return Math.min(max, Math.max(val, min));
}

Now we have those utilities explained, let's start with the basic structure of our animation generator:

function* moveTo(entity: Entity, destination: {x: number, y: number}, durationMs: number){
    let totalTime = 0;
    while (true) {
        let elapsed = yield;
        totalTime += elapsed;
        // TODO implement the rest
    }
}

The first thing you might notice above is the apparent infinite loop! Believe it or not this is totally okay in a generator, the yield will pause execution and "yield" it back up to our main loop for the next animation.
The second thing you might notice is let elapsed = yield; this is sort of wild, but the yield acts like a two way return! Things can be passed down into the generator and they fall out left hand side, but also things can be passed back out of the generator if on the right, for example yield 42; will "return" 42 up to the caller. This in/out duality in generators makes them ideal for coroutines.

Next we can use JavaScript scope to capture the entities original x/y position. Notice that it is above the yield.

function* moveTo(entity: Entity, destination: {x: number, y: number}, durationMs: number) {
    let totalTime = 0;
    // Capture the original position
    const { x: originalX, y: originalY } = entity;
    while(true) {
        let elapsed = yield;
        totalTime += elapsed;
        // TODO implement the rest
    }
}

Then Convert our current totalTime to something between 0 and 1 for our lerp.

const currentTime = clamp(totalTime / durationMs, 0, 1);

Then the meat of our moveTo is calculating the lerp and setting the properties on the entity we are animating!

const currentX = lerp(originalX, destination.x, currentTime);
const currentY = lerp(originalY, destination.y, currentTime);
entity.x = currentX;
entity.y = currentY;
if (totalTime >= durationMs) {
    console.log('moveTo complete', currentX, currentY);
    return;
}

Finally, putting the whole thing together it looks like this

function* moveTo(entity: Entity, destination: {x: number, y: number}, durationMs: number) {
    let totalTime = 0;
    const { x: originalX, y: originalY} = entity;
    while(true) {
        let elapsed = yield;
        totalTime += elapsed;
        const currentTime = clamp(totalTime / durationMs, 0, 1);
        const currentX = lerp(originalX, destination.x, currentTime);
        const currentY = lerp(originalY, destination.y, currentTime);
        entity.x = currentX;
        entity.y = currentY;
        if (totalTime >= durationMs) {
            console.log('moveTo complete', currentX, currentY);
            return;
        }
        
    }
}

Here is an example of our moveTo animations in action, each animation runs in sequence on after the other!

The yeild* is a new piece of syntax but it basically means that if the thing to the right is a generator, dig into and run that generator! Cool right?

coroutine(function* boxAnimation() {
    yield* moveTo(entity, {x: 50, y: 550}, 1000);
    yield* moveTo(entity, {x: 750, y: 550}, 1000);
    yield* moveTo(entity, {x: 750, y: 50}, 1000);
    yield* moveTo(entity, {x: 50, y: 50}, 1000);
});

Concurrency with Coroutines

There are more cool tricks we can play, like simulating concurrent animations with coroutines!

Let's say in addition to moveTo I also create a rotateTo and a scaleTo animation, AND I want to do all three at once! Well now that we have generators helping us out we can drive multiple generators at the same time.

In this example we grab a list of our animations, and drive them until they are all done:

function* parallel(...animations: Generator[]) {
    while (true) {
        let elapsed = yield;
        let results: IteratorResult<any, any>[] = [];
        // Drive each animation 1 frame
        for (let anim of animations) {
            results.push(anim.next(elapsed));
        }
        // Wait to all the child animations are done
        if (results.every(f => f.done)){
            return;
        }
    }
}

See how it reads in usage:

coroutine(function* boxAnimation() {
    // animations run in parallel
    yield* parallel(
        moveTo(entity, {x: 400, y: 400}, 1000),
        rotateTo(entity, 2 * Math.PI, 1000),
        scaleTo(entity, 2, 1000),
    )
});

Wrapping Sequences with Coroutines

Sometimes it's useful to specify different groups of animations that you want to run.

This collects up the animations and runs each of them!

function sequence(...animations: Generator[]) {
    return function* generatorSequence() {
        for(let generator of animations) {
            yield* generator;
        }
    }();
}

Now we can run 2 separate sequential animations AT THE SAME TIME! 🤯

coroutine(function* manyBoxesAnimation() {
    yield* parallel(
        sequence(
            moveTo(yellowEntity, {x: 50, y: 550}, 1000),
            moveTo(yellowEntity, {x: 750, y: 550}, 1000),
            moveTo(yellowEntity, {x: 750, y: 50}, 1000),
            moveTo(yellowEntity, {x: 50, y: 50}, 1000),
        ),
        sequence(
            moveTo(greenEntity, {x: 750, y: 50}, 1000),
            moveTo(greenEntity, {x: 750, y: 550}, 1000),
            moveTo(greenEntity, {x: 50, y: 550}, 1000),
            moveTo(greenEntity, {x: 50, y: 50}, 1000),
        )
    )
})

I hope this helps you aspiring game devs out there who are trying to build some animations!

Check out the code and play around

-Erik

Handling Height in Isometric Tile Maps

Wed, 02 Feb 2022 00:00:00 +0000

Some of my favorite games are isometric styled. I played a lot of "Super Mario RPG" and "Final Fantasy Tactics" in my day and I've always wanted to build isometric games 😎

With that desire in mind, I've been working on Tiled map editor support for Excalibur. Simulating and drawing tiles at a certain height can be tricky with z-indexing. In this post I'll talk about drawing isometric maps and some of the techniques I used to produce a height illusion in an isometric map with a moving character.

TLDR show me the code

Isometric Math

There is a great post by Clint Bellanger that goes into detail about the derivation of the math. I highly recommend reading his post for a nuanced understanding of the math.

Here is the basics though: given a 2D grid of tiles, we need to draw it effectively rotated by 45 degrees to produce the isometric 2.5 illusion. A common approach to drawing this in pixel art this is 2 pixels over and 1 down.

Okay let's say our tile data structure looks like below, each tile has its x/y coordinate, a screen position, and a image to show, and the IsometricMap contains a list of Tiles.

export class Tile {
    public x: number;
    public y: number;
    public screenX: number;
    public screenY: number;
    public image: HTMLImageElement;
    constructor(public map: IsometricMap) { }
}

export class IsometricMap {
    public tiles: Tile[] = [];
    constructor(
        public widthInTiles: number,
        public heightInTiles: number,
        public tileWidthPx: number,
        public tileHeightPx: number) {}
}

Calculating Screen Position

Here is my verbal reasoning for the isometric formula, again I recommend reading Clint's post for more nuance.

For each positive step in x tile coordinate, the final drawing is shifted down screen y and right in screen x by half a tile
For each positive step in y tile coordinate, the final drawing is shifted down screen y and left in screen x by half a tile

If we combine all the x changes and y changes we get:

export class IsometricMap {
    ...

    /**
     * Returns the top left corner of the tile in screen coordinates
     */
    public tileCoordinateToScreen(tileX: number, tileY: number): [number, number] {
        const halfTileWidth = this.tileWidthPx / 2;
        const halfTileHeight = this.tileHeightPx / 2;
        // each screen x is dependent on tile.x to the right & tile.y to the left
        const screenX = (tileX - tileY) * halfTileWidth;
        // each screen y is dependent on tile.x down & tile.y down
        const screenY = (tileX + tileY) * halfTileHeight;
        return [screenX, screenY];
    }
}

Selecting Tile width and height based on assets

The tile height should be the height of the base parallelogram not the height of the tile image asset necessarily.

For example if your tile is "flat", the height of the parallelogram and the image are the same.

With other art assets the logical height can be different, in this case roughly half the height of the asset. This height will depend on your art assets.

Drawing isometric tiles

Drawing isometric maps can be slightly different from your traditional 2D maps, specifically it is often convenient to draw isometric tiles from the bottom left instead of the top right in the traditional 2D case. (The Tiled editor does this)

One reason to draw from the bottom, is this preserves the mental model of placing a 3D object down on the grid

To accomplish this we need to offset our screen coordinates, by the full height of our tile image.

export class Tile {
    public x: number;
    public y: number;
    public screenX: number;
    public screenY: number;
    public image: HTMLImageElement;
    constructor(public map: IsometricMap) { }

    public draw(gfx: CanvasRenderingContext2D) {
        if (!this.image) return;
        const halfTileWidth = this.image.width / 2;
        gfx.save();
        // shift left origin to corner of map, not the left corner of the first sprite
        gfx.translate(-halfTileWidth, 0);
        gfx.translate(this.screenX, this.screenY);
        // shift the image up to draw from the bottom (minus tile height)
        gfx.drawImage(this.image, 0, -(this.image.height - this.map.tileHeightPx));

        gfx.restore();
    }
}

Multiple isometric tiles at different "elevation"

This is were things can get tricky, because as a player or objects move in your environment the order in which each tile or object needs be drawn must change to preserve the illusion.

Conceptually, as objects move "closer" to the screen they need to be drawn last (the classic painter technique of painting close things last).

Z-index is a useful way to think about closeness to the screen that developers might be familiar with. Given a high z-index, this means an object is close to the screen, and low z-index further away.

Solution: Sort entity draw by z-index

One way to make the illusion work is to sort our objects by a z-index that we calculate every frame from a synthetic "elevation".

First add z and elevation to your entity implementation.

export interface Entity {
    z: number; // distance to the screen
    elevation: number; // "height" of the layer in the illusion
}

export class Tile implements Entity {
    ...
    // add z and elevation to implementation
}

export class Player implements Entity {
    ...
    // add z and elevation to implementation
}

Set your entities to the desired elevation for your simulation.

// Set the elevation of the ground tiles
const ground = new IsometricMap(...);
ground.tiles.forEach(t => t.elevation = 0);

// Set the elevation of the box tiles
const boxes = new IsometricMap(...);
boxes.tiles.forEach(t => t.elevation = 1);

// Set the elevation of the player, the player will be at the
// same elevation as the boxes
const player = new Player(....);
player.elevation = 1;

Process through all the entities' elevation and calculate the correct z-index given their position on screen at any given time, then sort before drawing them all. This lets object move about and retain the proper draw order based on z-index.

The trick is to pick the maximum possible y-coordinate for your game screen, this allows you to bucket each elevation into its own range of z-indexes. For example the grass tiles will never be drawn in front of the box tiles because they are at a different elevation.

// Some canvas details omitted for brevity
// See full code: https://github.com/eonarheim/isometric-layers

const entities = [...ground.tiles, ...boxes.tiles, player];

const processElevation = (entity: Entity) => {
    const maxZIndexPerElevation = 600;

    const newZ = maxZIndexPerElevation * entity.elevation + entity.screenY;

    entity.z = newZ;
}

const clearScreen = (gfx: CanvasRenderingContext2D) => {
    gfx.fillStyle = '#176BAA';
    gfx.fillRect(0, 0, canvas.width, canvas.height);
}

const mainloop = () => {
    requestAnimationFrame(mainloop);
    clearScreen(gfx);

    // Given the elevation and y coord calculate the correct z-index
    entities.forEach(e => processElevation(e));

    // Sort entities in place
    entities.sort((a, b) => {
        return a.z - b.z;
    });

    // Draw our entities
    gfx.save();
    gfx.translate(400, 100);
    for (const entity of entities) {
        entity.draw(gfx);
    }

    gfx.restore();

}
mainloop();

Voila! 🎉

In this example all the green grass tiles have elevation = 0 and the black cube and boxes have elevation = 1. Notice how the black cube is properly in front of the box tile to the left, but behind the box tile to the right.

Check out the code and play around

Hope this helps you isometric game enthusiasts out there!

-Erik

Excalibur v0.25.2 Released!

Sat, 22 Jan 2022 00:00:00 +0000

After the winter break, the team has put out a new release of Excalibur@v0.25.2 with a lot of improvements to the core engine and plugins! Check the roadmap for our current plans.

Check out the new version on npm!

> npm install excalibur@0.25.2

"Winter holiday, when developers work on their side projects" - Anonymous Coworker

Dev Tools

> npm install @excaliburjs/dev-tools

We've built a brand new tool to help debug Excalibur games! Check it out!. This tool lets you see information about the the Excalibur engine, scenes, actors, clocks, and more!

Debugging why things aren't working has historically been pretty difficult. This plugin will greatly assist in the game development cycle. Nearly everything is available and configurable.

It's pretty low effort to install into your game:

import { DevTool } from '@excaliburjs/dev-tools';

const game = new ex.Engine({...});
const devtool = new DevTool(game);

Tiled Updates

> npm install @excaliburjs/plugin-tiled

The Tiled plugin now implicitly adds a z-index to each layer (which can be overridden) which means things will look as you expect in Excalibur as they do in the Tiled editor.

Set the starting layer z (defaults to -1) and get gaming!

const map = new TiledMapResource('path/to/map.tmx', { firstLayerZIndex: -2 });

Renderer Performance Improvements

The performance gains were achieved through some core renderer refactors and identifying places where expensive calculations could be cached!

This is huge, we stay above 30fps in the 4000 actor benchmark, and we have dramatic improvement in average fps in both cases!

This benchmark was performed on my Surface Book 2 with the power plugged in, in Chrome.

Processor: Intel(R) Core(TM) i7-8650U CPU @ 1.90GHz, 2112 Mhz, 4 Core(s), 8 Logical Processor(s)
Physical Memory: (RAM) 16.0 GB
Graphics: NVIDIA GeForce GTX 1060

A number of improvements were made to Excalibur in the graphics systems to get to this performance. The big factors to this improvement were:

Avoiding recalculation of graphics transforms and other expensive operations when they can be cached
Refactoring the renderer to be simpler and to use index buffers to share geometry vertices.
Rendering batches at the actual maximum for the batch renderer
Avoid recreating Matrix types, they are somewhat expensive to create then garbage collect

Post Processing

The postprocessor improvements allow custom WebGL shaders, this can produce some cool effects! (Minimally modified from this ShaderToy)

To produce the above effect Excalibur has a new built in ScreenShader type for doing quick shaders meant for the whole screen.

class CrtPostProcessor implements ex.PostProcessor {
  private _shader: ex.ScreenShader;
  initialize(gl: WebGLRenderingContext): void {
    const crtEffectSource = document.getElementById("modified-crt-shader-source").innerText;
    this._shader = new ex.ScreenShader(crtEffectSource);
  }

  getLayout(): ex.VertexLayout {
    return this._shader.getLayout();
  }

  getShader(): ex.Shader {
    return this._shader.getShader();
  }
}

game.graphicsContext.addPostProcessor(new CrtPostProcessor());

Renderer Improvements

Renderer Design

When v0.25.0 was released, it was a "monolithic" renderer design, meaning everything Excalibur could possibly draw was built into a single renderer and shader program. This became fairly onerous fairly quickly. And as the old adage goes "you don't know how to build something until you've built it twice"

With v0.25.2 each type of drawing is split internally into separate renderer plugins, while this does come with some overhead when switching shader programs, the simplicity, maintainability, and extensibility benefits are a boon.

Image Filtering

Excalibur now allows you the ability to control the WebGL image filtering mode both implicitly and explicitly. Really this means Excalibur will try to pick a smart default, but allows overrides

Explicitly when loading ex.ImageSource:

const myImage = new ex.ImageSource('path/to/image', false, ex.ImageFiltering.Pixel);

ex.ImageFiltering.Blended - Blended is useful when you have high resolution artwork and would like it blended and smoothed
ex.ImageFiltering.Pixel - Pixel is useful for pixel art when you do not want smoothing aka antialiasing applied to your graphics.

Implicitly if the ex.EngineOption antialiasing property is set:

antialiasing: true, then the blend mode defaults to ex.ImageFiltering.Blended
antialiasing: false, then the blend mode defaults to ex.ImageFiltering.Pixel

Custom Renderer Plugins

Excalibur knows how to draw many types graphics to the screen by default comes with those pre-installed into the ExcaliburGraphicsContext. However, you may have a unique requirement to provide custom WebGL commands into Excalibur, this can be done with a custom renderer plugin.

A custom renderer can be registered with Excalibur and draw in any draw routine! Read more in the docs

const game = new ex.Engine({...});

export class MyCustomRenderer extends ex.RendererPlugin {
    public readonly type = 'myrenderer';
    ...
}

game.start().then(() => {
    // register
    game.graphicsContext.register(new MyCustomRenderer());
});

// call from a graphics callback or event
const actor = new ex.Actor({...});
actor.graphics.onPostDraw = (graphicsContext) => {
    graphicsContext.draw<MyCustomRenderer>('myrenderer', ...);
}

Community

We've had a lot of community engagement this iteration, especially through the issues and github discussions. Lots of good issues, and lots of cool things in the show and tell

Big thanks to everyone: @ivasilov @luttje @tsanyqudsi @lampewebdev @joshuadoan @berkayyildiz @simon-jaeger @YJDoc2 @JumpLink

The Future

We are progressing at full speed toward the v1 vision, there is still a lot to do but the end is in sight. Here are a few things that I'm personally really excited for:

Event system redo
Particle system refactor
Final deprecation of old drawing api
New TileMap enhancements for hexagonal and isometric maps

This was a point release, but despite that a lot of exciting things were added! Looking forward to v0.26.0!

-Erik

Fixing WebGL Tile Map Seams

Wed, 15 Dec 2021 00:00:00 +0000

There is a common issue with tile based maps having visible seams where they shouldn't.

In this post I want to explain why they were happening to me, and to document the solutions I found that you can mix and match in your code! 😎

TLDR Show me the code and demo

The Problem

The core problem that causes seams is floating point numbers. Floating point numbers in computers do not have infinite resolution, there are "gaps" in the possible numbers that can be represented by a computer. In fact, the gaps in representable numbers get worse the further from zero you go!

This issue is super unintuitive. If you start from pure mathematics, this shouldn't be possible, but because of limited floating point precision and error accumulation seams in the geometry can happen.

Factors in the webgl that influence the issue:

Lower pixel density screens (standard definition) seem to be easier to reproduce this problem
The screen size and window.devicePixelRatio (ratio between logical CSS pixels to physical screen pixels) seem to affect the appearance of these artifacts.
Large amounts (tm) of floating point manipulations of the geometry before rendering introduces and propagates floating point errors.
- Geometry manipulation
- Camera positioning
- Canvas scaling
Texture sampling can sometimes bleed at UV's near 1.0 into adjacent pixels in your source image that you did not intend 😱 (#thanks-float-point)

Some Specifics

WebGL 1.0 is based on the OpenGL ES 2.0 spec which indicates that if the center of the fragment is not in the polygon screen pixel projection it doesn't color it in. So when the screen pixel center (0.5, 0.5) falls directly on a geometry boundary between two quads, but neither is far enough into a screen pixel for webgl to color the pixel. Mathematically this seems like it shouldn't be possible, but because of limited floating point precision there are holes in the numbers (at least with the method that Excalibur uses to build tiles).

This explanation fits with the flickering moire pattern to the left that can be seen when moving across the screen. You can see the background peaking through sometimes when the rasterizer doesn't fill in the pixel.

Solution 1 - Shared Tile Edge (best for tile maps)

If you know ahead of time that you are tiling, you can re-use the right edge of the previous tile so that there are no floating point gaps. There can be no gaps because you are using the exact same edge and not recomputing it.

Recomputing edges is where we can get into floating point trouble. Note is that this identity for the ith tile does not hold true for all floating point numbers given rounding/error, even though mathematically that is true.

i * width + width / 2 == (i + 1) * width - width / 2

Avoid recomputing edges.

So here is an example where we precompute all the x-edges and y-edges and use them to build our tile geometry

export function generateTiles(
                    tileRows: number,
                    tileColumns: number,
                    tileWidthPixels: number,
                    tileHeightPixels: number): Tile[] {

    const tiles: Tile[] = [];
    const tileXs: number[] = [];
    const tileYs: number[] = [];
    // Precompute all the x's & y's for the tile geometry
    // this keeps us from getting into trouble with floating point math 
    for (let x = 0; x < (tileColumns + 1); x++) {
        tileXs[x] = x * tileWidthPixels;
    }
    for (let y = 0; y < (tileRows + 1); y++) {
        tileYs[y] = y * tileHeightPixels;
    }

    // Create tile geometry that share the same edges
    for (let x = 0; x < tileColumns; x++) {
        for (let y = 0; y < tileRows; y++) {
            const tile = new Tile({
                left: tileXs[x],
                right: tileXs[x + 1],
                top: tileYs[y],
                bottom: tileYs[y + 1]
            });
            tiles.push(tile);
        }
    }
    return tiles;
}

Shared Edge Solution in action

You can see the gap in far right appear and disappear

Solution 2 - Bodge the UV coordinates near 1.0

If you are resizing images on the fly to make them power-of-two dimensions or have a texture atlas with multiple sprites packed into one image, the texture sampling can bleed into the new transparent pixels. A slightly hacky work around is to back off of the UV by a small bodge factor, 0.01 but seems to work without losing actual image pixels.


 for (let i = 0; i < num; i += (size * 4)) {
        data[i + vertex + 0] = 0;
        data[i + vertex + 1] = 0;
        vertex += size;

        data[i + vertex + 0] = 0;
        data[i + vertex + 1] = (tileHeightPixels - 0.01)/ tilePOTHeight;
        vertex += size;

        data[i + vertex + 0] = (tileWidthPixels  - 0.01) / tilePOTWidth;
        data[i + vertex + 1] = 0;
        vertex += size;

        data[i + vertex + 0] = (tileWidthPixels - 0.01) / tilePOTWidth;
        data[i + vertex + 1] = (tileHeightPixels - 0.01) / tilePOTHeight;
        vertex = 0;
    }

Quick note on other texture related issues

WebGL will sample and blend pixels from other parts of a texture atlas sometimes (and is desirable for a lot of images). WebGL is trying to be helpful and picking pixels to blend next to produce high quality images.

Some additional texture consideration:

You can change your sampling mode to gl.NEAREST (this might not work out depending on your art style). I believe to do this in Unity this is SpriteAtlas with texture packing, and filter mode set Point, you'll need to build/start the project.

Be sure to clamp to the edge of the texture (not useful for bleed in the atlas)

gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);

Add transparent padding between sprites in your texture atlas to hack around the sampler
You can extrude the edge pixel out 1 pixel to hack around the sampler, this might be a ton of effort to update all your tiles, there are some tools that exist to do this for you.
- Tile Extruder

UV Bodge In action

Notice the horizontal gap in the center of the tiles.

Solution 3 - Avoid Unnecessary Floating Point Manipulation

3.1 Unnecessary geometry scaling for HiDPI

Kronos has a good article on handling hidpi in webgl

But one important thing to keep in mind is to have your orthographic matrix mapped to your "logical" resolution (or clip space if you prefer). And keep your gl.viewport() set to the size of the hidpi scaled canvas.

If you think about it makes sense because that gl viewport is the size of the drawing surface in real machine pixels.

// logical resolution
const resolution = {
  width: 800, // "CSS" logical pixels
  height: 600 // "CSS" logical pixels
}

// hidpi scaling
function applyHiDPIScaling() {
    if (window.devicePixelRatio > 1.0) {
        canvas.width = resolution.width * window.devicePixelRatio;
        canvas.height = resolution.height * window.devicePixelRatio;

        canvas.style.width =  resolution.width + 'px';
        canvas.style.height = resolution.height + 'px';
    }
    console.log('pixel ratio', window.devicePixelRatio);
}
applyHiDPIScaling();

const shader = /*...*/
// setup orthographic 2D projection for our shaders
// Notice the orthographic is the logical resolution, not the scaled
const ortho = Matrix.ortho(0, resolution.width, resolution.height, 0, 400, -400);
shader.addUniformMatrix('u_matrix', ortho.data);

// draw frame
function draw() {
    // Clear the context with the newly set color.
    gl.clearColor(114 / 255, 213 / 255, 224 / 255, 1.0);
    gl.clear(gl.COLOR_BUFFER_BIT);

    // Use the physical scaled resolution as the viewport
    gl.viewport(0, 0, canvas.width, canvas.height);

    // Do all the drawing
    // ...
}

This eliminates the need to artificially scale your geometry (which can introduce floating point error), consider the following (which you should NOT USE)

// DO NOT USE THIS SNIPPET
applyHiDPIScaling();
const shader = /*...*/

// If we used the scaled width/height it forces use to "zoom-in" later on the geometry
const ortho = Matrix.ortho(0, canvas.width, canvas.height, 0, 400, -400);
shader.addUniformMatrix('u_matrix', ortho.data);
transform.current = Matrix.identity();

// This is applied to all geometry!! so can introduce floating point errors
transform.scale(window.devicePixelRatio, window.devicePixelRatio);
// DO NOT USE THIS SNIPPET

3.2 - Keep geometry in local coordinates for as long as possible

Do as little transformation as possible to the geometry in your pipeline. Each floating point operation is an opportunity for error to compound or propagate. If you can help it, keep geometry in local coordinates until the very last moment where you must render.

3.3 - Pixel snap

Rounding to the nearest pixel, or truncating the fraction portion can fix some issues.

However, depending on where you do your rounding or truncate the geometry might fall ahead or behind where it should in screen space. You might need to look at the "Nudge" solution to remedy this.

See this example were truncating makes it worse

3.4 - Position your camera in ideal locations

If you implement your camera by transforming the entire context, it may be a good idea to keep the camera at whole pixel values to avoid floating point issues from propagating.

Solution 0.5: "Nudge" pixels to screen (Useful for Ad-Hoc Drawing Systems)

I don't recommend this solution unless you have no other choice, or you have limited control of your drawing.

That said, this technique doesn't know if you plan to draw tiles, but if you happened to draw a tiles it will work 😎

This type of solution is covered in the beginning of OLC code zone stream #28

To fix the seam in the geometry we want to nudge the game geometry of each draw so that it will bias the left and right edge of each image to a screen pixel without a gap.

Basic algorithm:

Map vertices to screen space
Nudge it to the nearest screen pixel up or down
Map vertices back to world space and use those

Our scheme to nudge pixels will be to take all our (red) right edges and add a 0.5 pixel bodge then find the ceiling, and we take all our (blue) left edges and add a 0.5 pixel bodge then find the floor.

While this works pretty well, this does have a drawback of overlapping the geometry by 1 pixel on the left or right in the majority case when the edges don't straddle the mid-pixel.

But maybe 1 pixel overlap is better than having a perceptible gap? You decide. It is a more noticeable effect if your assets are small, or your are zoomed out, because the 1 screen pixel will become a larger portion of the asset on screen.

Quick note

You might be thinking why not use ceiling for both edges (or floor) all the time to avoid overlapping by 1 pixel, well the same mid-pixel problem we were trying to solve before is now shifted to the pixel boundaries and we still have a gap.

Nudge code

It's important to multiply whatever your screen space dimensions are by the window.devicePixelRatio to account for hidpi displays. Remember that it's important to factor in the ratio between physical screen pixels and logical "css" pixels to do this mapping properly.

For HTML games

// Game resolution in "logical" pixels
// <canvas width="800" height="600" >
const resolution = {
  width: 800,
  height: 600
};

// Screen space in actual screen pixels 
// <canvas style="width:800px;height:600px">
// "logical" * devicePixelRatio = physical pixels
const screen = {
  width: this.viewport.width * window.devicePixelRatio,
  height: this.viewport.height * window.devicePixelRatio 
};

Map the coordinate from world "game" resolution to screen space.


function toScreenSpace(coord, resolution, screen) {
  // Map coordinate to screen space
  let screenSpacePos = vec(
    (coord.x / resolution.width) * screen.width,
    (coord.y / resolution.height) * screen.height);

  return screenSpacePos;
}

Make the inverse to map back to world space

function toWorldSpace(coord: Vector, resolution: Dimension, screen: Dimension) {
    // Map coordinate to world space
    let worldSpacePos = vec(
        (coord.x / screen.width) * resolution.width,
        (coord.y / screen.height) * resolution.height);

    return worldSpacePos;
}

Putting this all together, we apply our half pixel algorithm in both the floor and ceil

/**
 * Pushes a world space coordinate towards the nearest screen pixel (floor)
 */
export function nudgeToScreenPixelFloor(transform: Matrix, coord: Vector, resolution: Dimension): Vector {
    coord = transform.getAffineInverse().multv(coord);
    const screen = {
        width: resolution.width * window.devicePixelRatio,
        height: resolution.height * window.devicePixelRatio
    };

    let screenSpacePos = toScreenSpace(coord, resolution, screen);

    // Adjust by half a pixel "bodge" factor
    const screenSpacePosBodge = screenSpacePos.add(vec(0.5, 0.5));

    // Find the nearest screen pixel
    const nearestScreenPixelFloor = vec(
        Math.floor(screenSpacePosBodge.x),
        Math.floor(screenSpacePosBodge.y));
    
    // Convert back to game resolution
    const worldSpace = toWorldSpace(nearestScreenPixelFloor, resolution, screen);

    // Transform back to world coordinate
    return transform.multv(worldSpace);
}

/**
 * Pushes a world space coordinate towards the nearest screen pixel (ceiling)
 */
export function nudgeToScreenPixelCeil(transform: Matrix, coord: Vector, resolution: Dimension): Vector { 
  // Same as above but with Math.ceil()
}

Putting it all together, we apply our floor nudge to the left edge, and the ceiling nudge ot the right


export function drawTile(tile: Tile) {
    // Quad update
    let topLeft = vec(tile.left, tile.top);
    let bottomRight = vec(tile.right, tile.bottom);

    topLeft = nudgeToScreenPixelFloor(transform.current, topLeft, resolution);
    bottomRight = nudgeToScreenPixelCeil(transform.current, bottomRight, resolution);

    // (0, 0) - 0
    const vertices = def.buffer.bufferData;
    vertices[vertIndex++] = topLeft.x;
    vertices[vertIndex++] = topLeft.y;

    // (0, 1) - 1
    vertices[vertIndex++] = topLeft.x;
    vertices[vertIndex++] = bottomRight.y;


    // (1, 0) - 2
    vertices[vertIndex++] = bottomRight.x;
    vertices[vertIndex++] = topLeft.y;

    // (1, 1) - 3
    vertices[vertIndex++] = bottomRight.x;
    vertices[vertIndex++] = bottomRight.y;
}

"Nudge" solution in action

Notice the semi-obvious overlap that could be undesirable in your game.

Wrapping up

Check out the code and demo

There are a lot of quirks when doing tile based drawing, the majority of them boil down to floating point math or texture settings.

You may need to apply one or many solutions in this post, or remove some problematic code from your game.

Hope this helps any future explorers!

-Erik

Excalibur v0.25.0 Released!

Sun, 03 Oct 2021 00:00:00 +0000

After a year of work a lot of great additions and improvements have made it into Excalibur, and we are making good progress towards our v1.0 release! Check the roadmap for our current plans. It's hard to believe how different things are now since the first commit of Excalibur (back when it was called GameTS)!

Excalibur started as a tech demo in a presentation to show how powerful TypeScript can be. The engine has come so far since then, it's really amazing!

We are really excited to share this release with you! This release contains over 30 bug fixes and 50 new features! It's been a labor of love over the last year by many people, and we have some big features to share.

Check out the official release!

> npm install excalibur@0.25.0

Performance

There is a combination of features (mentioned below) that resulted in big performance gains. Across the board, there's been a dramatic increase in what Excalibur can do in v0.25.0 vs v0.24.5.

I want to highlight the graphics performance specifically:

There is much better performance across the board with a higher baseline fps in v0.25.0 for the same number of actors. You'll notice that FPS improves over time as more actors are offscreen in v0.25.0 compared to v0.24.5.

This benchmark was performed on my Surface Book 2 with the power plugged in, in Chrome.

Processor: Intel(R) Core(TM) i7-8650U CPU @ 1.90GHz, 2112 Mhz, 4 Core(s), 8 Logical Processor(s)
Physical Memory: (RAM) 16.0 GB
Graphics: NVIDIA GeForce GTX 1060

Plugin Strategy Going Forward

We are adopting a similar versioning strategy to Angular, during pre-1.0. All plugins compatible with the core library will share the same prefix through the minor version. - Example: If core is excalibur@0.25.0 then the plugins that support this version are @excaliburjs/plugin-tiled@0.25.x.

DisplayMode Updates

Excalibur DisplayModes have been refactored and renamed to clarify their utility.

FillContainer - Fill the game viewport to take up as much of the immediate parent as possible
FillScreen - Fill the game viewport to take up as much of the screen as possible
FitContainer - Fit the game maintaining aspect ratio into the immediate parent
FitScreen - Fit the game maintaining aspect ration into the screen
Fixed - Specify a static size for the game width/height

Refactor to Entity Component System (ECS) Based Architecture

The core plumbing of Excalibur has been refactored to use an ECS style architecture. With this change developers using Excalibur do not need to know or care about the this underlying change to ECS if they don't want too.

What does this mean? Roughly speaking ECS architecture breaks down like this:

Components - Contain data needed for various systems
Systems implement the "behavior" by looping over entities that match a list of components. For example the graphics system processes all entities with a TransformComponent and a GraphicsComponent
Entities are a holders of components

Actor, Scene, and Engine remain the friendly interface to build games, just implemented differently under-the-hood. The reason for the change was to break down growing and complex logic that had accumulated in the Actor and Scene implementnation into Components and Systems for maintainability. This change increases the flexibility of Excalibur to add new novel behavior directly into the core loop with custom components ones if desired.

Excalibur does not have the purest implementation of an ECS by design, the built in components are more than just data. The built in components do provide behavior, convenience features, and helpers to maintain our core mission of keeping Excalibur easy to use. The Excalibur core team goal with ECS is flexibility and maintainability, not performance. (read more)

A quick example of using the new ECS features

class SearchComponent extends ex.Component<'search'> {
    public readonly type = 'search'
    constructor(public target: ex.Vector) {
        super();
    }
}

class SearchSystem extends ex.System<ex.TransformComponent | SearchComponent> {
    // Types need to be listed as a const literal
    public readonly types = ['ex.transform', 'search'] as const;

    // Lower numbers mean higher priority
    // 99 is low priority
    public priority = 99;

    // Run this system in the "update" phase
    public systemType = ex.SystemType.Update

    private _searchSpeed = 10 // pixels/sec

    public update(entities: ex.Entity[], delta: number) {
        for (let entity of entities) {
            const target = entity.get(SearchComponent)!.target;
            // ex.TransformComponent is a built in type
            const transform = entity.get(ex.TransformComponent) as ex.TransformComponent;

            const direction = target.sub(transform.pos);
            const motion = direction.normalize().scale(this._searchSpeed);

            // Moves these entities towards the target at 10 pixels per second
            transform.pos = transform.pos.add(motion.scale(delta / 1000))
        }
    }
}

// Actors come with batteries included built in features
const actor = new ex.Actor({
    pos: ex.vec(100, 100),
    width: 30,
    height: 30,
    color: ex.Color.Red
});
actor.addComponent(new SearchComponent(ex.vec(400, 400)));

// Create a scene with your new system
const scene = new ex.Scene();
scene.world.add(new SearchSystem());
scene.add(actor);

Collision System Improvements

The collision system has been significantly overhauled to improve the quality of the simulation and the stability of collisions. The core simulation loop "solver" has been redone to use an iterative impulse constraint solver, which provides a robust method of computing resolution that has improved performance and stability.

Collision intersection logic has now also been refactored to report multiple contact points at once. Multiple contacts improves the stability of stacks of colliders over single contact collisions (which can result in oscillations of boxes back and forth).

Colliding bodies can now optionally go to sleep. This relieves some of the pressure on the collision solver and improves the stability of the simulation by not moving these objects if they don't need to move. Colliders can be started asleep before a player in a game might interact with them

New CompositeColliders now make it possible to combine Excalibur Collider primitives (PolygonCollider, CircleCollider, and EdgeCollider) to make any arbitrary collision geometry. These new composite colliders power the new TileMap cell collisions and also power the new ex.Shape.Capsule(width, height) collider.

Capsule collider is a useful geometry tool for making games with ramps or slightly jagged floors you want a character to glide over without getting stuck. This collider also helps with any "ghost collisions" that you might run into under certain conditions in your game.

CollisionGroups allow more granular control over what collides above and beyond collision type. Collsion groups allow you to create named groups of colliders like "player", "npc", or "enemy". With these groups, you can specify that players and enemies collide, player and npcs don't collide, and that npcs and enemies don't collide without needing to implement that logic in a collision event handler.

// Create a group for each distinct category of "collidable" in your game
const playerGroup = ex.CollisionGroupManager.create('player');
const npcGroup = ex.CollisionGroupManager.create('npcGroup');
const floorGroup = ex.CollisionGroupManager.create('floorGroup');
const enemyGroup = ex.CollisionGroupManager.create('enemyGroup');

// Define your rules
const playersCanCollideWith = ex.CollisionGroup.collidesWith([
  playersGroup, // collide with other players
  floorGroup, // collide with the floor
  enemyGroup // collide with enemies
]);

const player = new ex.Actor({
  collisionGroup: playersCanCollideWith
});

New Graphics System

The new Excalibur graphics system has been rebuilt from the ground up with speed in mind. It is now built on a WebGL foundation with a built-in batch renderer. This means that Excalibur will batch up draw commands and submit the minimum amount of draw calls to the machine when the screen is updated. This dramatically improves the draw performance and also the number of things wec can display on screen (as noted in the benchmarks earlier).

For drawing hooks the ExcaliburGraphicsContext is replacing the browser CanvasRenderingContext2D. If you still need to do some custom drawing using the CanvasRenderingContext2D the new Canvas graphic can help you out.

const canvas = new ex.Canvas({
  cache: true, // If true draw once until flagged dirty again, otherwise draw every time
  draw: (ctx: CanvasRenderingContext2D) => {
    ctx.fillStyle = 'red';
    ctx.fillRect(0, 0, 200, 200);
  }
});

actor.graphics.use(canvas);

TileMap and Tiled updates

Tiled is easily one of the best tools out there for building and designing levels for your game. It has certainly been a valuable tool in our toolbox. We have doubled down on our efforts to provide a first class Tiled integration with Excalibur via the excaliburjs/plugin-tiled. This work also involved a few improvements to the TileMap to improve it's graphics API and collision performance.

Check out the Tiled Excalibur Plugin!

Full support for the Tiled object model
Full support for all Tiled file types
Excalibur built ins
Not yet supported
- Tiled Group Layers
- Custom Tile colliders
- Isometric/Hexagonal maps
- Parallax

Documentation

A lot of time was spent reviewing and improving our documentation. Part of this work was ensuring that the snippets don't go stale over time by building them in GitHub Actions.

Please check out the new and shiny doc site with new code examples excaliburjs.com!

Testing

The Excalibur core repo now has WallabyJS enabled to improve the VS Code test development and debugging experience. Wallaby is a paid tool; because of that Excalibur will always also support the Karma based testing framework for official tests.

A useful update to excalibur-jasmine allows async matchers, which greatly simplifies checking image diffs in Jasmine unit tests.

it('should match images', async () => {
  let engine = new ex.Engine({width: 100, height: 100});
  await expectAsync(engine.canvas).toEqualImage('images/expectedcanvas.png', .99);
});

A brand new integration test utility has been created called @excaliburjs/testing, which provides a quick way to drive Excalibur games with Puppeteer and do image-based snapshot testing.

// excalibur testing

test('An integration test', async (page) => {
    // Check for the excalibur loaded page
    await expectLoaded();

    // Compare game to expected an expected image
    await expectPage('Can check a page', './images/actual-page.png').toBe('./images/expected-page.png');

    // Use puppeteer page object to interact
    await page.evaluate(() => {
        var actor = ((window as any).actor);
        actor.pos.x = 400;
        actor.pos.y = 400;
    });

    // Compare game to a new expected image
    await expectPage('Can move an actor and check', './images/actual-page-2.png').toBe('./images/expected-page-2.png');
});

Templates

There are a lot of different ways to build web apps; we've created repo templates for some of the popular ones:

Samples

Community

We've had tons of community contributions since the last release. Heartfelt thanks to everyone in the discussions, issues and PRs!

Contributors:

@jedeen
@kamranayub
@alanag13
@DaVince
@DrSensor
@djcsdy
@catrielmuller
@AndrewCraswell
@miqh
@rledford
@SirPedr
@helloausrine
@dpayne5
@herobank110
@didii
@Charkui
@muirch
@rumansaleem
@mogoh
@kala2
@MrBartusek
@josh-greenlaw
@LokiMidgard
@romaintailhurat
@EduardoHidalgo
@jaredegan

Breaking Changes

There are some breaking changes in v0.25.0 from v0.24.5; see thechangelog and release notes for more specifics, but they generally fall into these categories. See the migration guide for guidance

New APIs replacements
- Graphics API
- Actor drawing functions moved to graphics component
API renames for clarity
Bug fixed necessitated change
Extracted behavior to a plugin
- Perlin noise is now offered as a plugin and is no longer included in the core library @excaliburjs/plugin-perlin
Big Plugin changes
- The Tiled plugin is now published under @excaliburjs/plugin-tiled and will start with version v0.25.0

Next on the horizon looking towards "v1"

Pointer events plumbing refactor; the current system is hard to follow and debug/enhance
Particle system refactor
Graphics enhancements to support advanced postprocessing/shaders
ExcaliburGraphicsContext enhancements to grant more flexibility
Event system redo
Better Scene management and granular asset loading
Expand and enhance TileMap
Progressive WebAssembly enhancements in the physics simulation
Potential New plugins on the horizon
- Browser Debugger Utility
- Aseprite
- Pyxel Edit
AI patterns and plugins like A* search
API finalization

I want to thank everyone who helped make this version of Excalibur possible. A lot of effort went into it and I'm really proud of what we achieved.

-Erik

Bookmarklets - Automating Websites

Mon, 06 Sep 2021 00:00:00 +0000

Every so often I find myself on a website (like YouTube) where I wish it had X or Y feature. Bookmarklets are powerfull little tools you can use to create automation against websites you use.

TLDR show me the code

Bookmarklets

Bookmarklets are a piece of custom JavaScript run from the bookmark's UI in your browser on the current page. They are a bookmark that points to javascript instead of a URL. Think lo-fi proto browser plugin 🤷‍♂️

⚠ WARNING ⚠ Make sure you understand whatever is in a bookmarklet, this code is running AS YOU against websites that you may be logged into (like a bank, social media, etc). A nefarious bookmarklet author could do bad things to you.

Things that can be done with a bookmarklet

Poke authenticated api endpoints
Drive UI like clicking
Manipulate the DOM
Malware...😱

See the MDN article for more details

Structure of the bookmarklet

Prefixed with javascript: with some code to execute for example: javascript:(function(){alert('hello world');})()
Must not contain newlines

Example "hello world" bookmarklet

javascript:(function(){alert('hello world');})()

YouTube playlist managment (at the time of writing this)

One feature I wish YouTube had was to remove videos automatically that are at a certain percentage watched. Currently the "Remove Watched" removes any video with any amount of watch time 😢 this is no good for me because sometimes I watch a few seconds. I want to remove videos at 80 or maybe 90 percent watched.

Websites change over time, and anything you write to automate them will decay, the code in this blog post is based on a reddit post that doesn't work anymore, but I've updated it for August 2021 version of YouTube (also the source is on github)

/* Unprocessed script for removing videos */
var removeVids = function () { 
    /* Ask user for number of videos to remove */
    var n = parseInt(prompt('Number of videos to remove?', 1));
    /* What is the "watched percent" */
    var watchedPercent = parseInt(prompt('Percent to consider watched', 100));

    /* Find the videos that match that percentage based on the width of the progress element */
    var vids = Array.from(document.querySelectorAll('ytd-playlist-video-renderer'));
    var vidsThatMatch = vids.filter(v => {
        return v.querySelectorAll('#progress').length && parseInt(v.querySelector('#progress').style.width) >= watchedPercent;
    });

    /* Janky loop based on timing since we are driving UI we need to give it time to respond*/
    if (vidsThatMatch.length < n) { n = vidsThatMatch.length };

    var i = 0;
    var interval = setInterval(function () {
         if (n > 0) {
             /* open the video context menu */
            vidsThatMatch[i].querySelector('yt-icon-button.ytd-menu-renderer').click();
            var title = vidsThatMatch[i].querySelector('#video-title');
            console.log('Removed:', title.innerText, title.href);

            /* Need to search the whole document pop up lives in another container in the DOM */
            setTimeout(() => {
                /* Some xpath to find the remove from playlist dialog in the DOM */
                var removeResults = document.evaluate("//span[contains(., 'Remove from')]", document, null, XPathResult.ANY_TYPE, null);
                var removeText = removeResults.iterateNext();
                removeText.click();
                n--;
                i++;
            });
        } else {
            console.log('No vids to remove');
            clearInterval(interval);
        }
    }, 500);
}; 
removeVids();

Building Bookmarklets with Webpack

Depending on how complicated your bookmarklet becomes, manually crafting the javascript:... might become too onerous. It is possible to use a bundler like webpack to help out, this also suggests the possiblility of really rich bookmarklet experiences!

Transforming the source to match the bookmarklet isn't too bad, based on this SO post I've crafted a webpack configuration.

I tweaked the webpack plugin in the original post to be compatible with webpack v5

// Modified for webpack v5: See https://stackoverflow.com/a/46920791/839595
class AssetToBookmarkletPlugin {
    pluginName = 'AssetToBookmarkletPlugin';
    apply(compiler) {
        compiler.hooks.thisCompilation.tap(this.pluginName, (compilation) => {
            compilation.hooks.processAssets.tap({
                name: this.pluginName,
                stage: webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL
            }, (assets) => {
                // Emit a new .bookmarklet
                for (const assetName in assets) {
                    const asset = assets[assetName];
                    const content = 'javascript:' + encodeURIComponent('(function(){' + asset.source() + '})()');
                    compilation.emitAsset(assetName + '.bookmarklet', new webpack.sources.RawSource(content))
                }
            });
        });
    };
}

Tada! 🎉

Here is the source code for the bookmarklet.

(Remember to verify any bookmarklets you decide to trust) Click and drag this link into your bookmarks bar to Remove Videos By Percent

Hope this helps anyone wanting to do some bookmarklet automation! -Erik

Understanding Collision Constraint Solvers

Sun, 21 Mar 2021 00:00:00 +0000

Constraints are a useful way to build relatively cheap, stable, and efficient physics systems. Lots of cool stuff can be unlocked with this approach 😎

In this post I want to help people understand constraints too!

I'll admit I had a hard time wrapping my brain 🧠 around using constraints to resolve collisions. I watched this amazing talk by Erin Catto at GDC 2014 and wanted to replicate and understand the technique.

What I want to do is reason out why these constraints might be the way they are by intuition and perhaps helpful ways to think about constraints.

The actual derivation is better served by Erin's talk, I recommend you check it out. I've probably watched it 10 times 😉

TLDR show me the code

What is a "Constraint"

Think of a constraint like a statement you want to be true and the "solver" attempts to make it true. Examples of constraints in a physics system might be: "I don't want these two objects to overlap", "I want these two objects to be attached to another", or "I want these two objects to bounce off each other"

A constraint solver, takes all the contraints in your system and finds a solution that satisfies them all.

In theory a set of constraints can be thought of as a group of related equations that can be solved. A stack of colliding objects is a good example of related contraints where the solution is their correct positions and velocities without any overlap.

Awesome! I think I get it. How do I turn those into code?

Solving with Sequential Impulse

In this setup we are going to attempt to "solve" these constraints by applying a series of "impulses" to each object in contact. Once enough impulses are applied over time, a stable configuration of all the objects under constraints should fall out the other side.

I have a goofy metaphor for this. Picture shaking a box of puzzle pieces that have magic magnets which are attracted to the right position. Shake until it's solved. 🤷‍♂️

Okay, what is an impulse? Well an impulse is defined as force added up over a time period. A super quick derivation from Newtonian physics from the familiar 2nd law:

force = mass * acceleration

Acceleration is another way of saying change in velocity in a given time step so re-written:

force = mass * deltaVelocity/deltaTime

Multiply by deltaTime

force * deltaTime = mass * deltaVelocity

Force over a time is the definition of impulse, so we can solve for our velocity. We will call our time period is the same for each frame so you can think of it as 1 unit of time 😎

impulse = mass * deltaVelocity

deltaVelocity = impulse * (1/mass) - Linear Impulse

The angular version of this has a similar formulation, but I'll cut to the chase.

deltaAngularVelocity = impulse x (1/momentOfInertia) - Angular Impulse

/**
 * Apply an impulse at a point
 * @param point 
 * @param impulse 
 * @returns 
 */
applyImpulse(point: Vector, impulse: Vector) {
    if (this.static) {
        return;
    }

    // Important for the torque term, the distance from the center
    // Changes the rotational amount applied 
    const distanceFromCenter = point.sub(this.xf.pos);

    this.m.vel = this.m.vel.add(impulse.scale(this.inverseMass));
    this.m.angularVelocity += this.inverseInertia * distanceFromCenter.cross(impulse);
}

Check out (additional reading on impulses)

Building Constraints - Overlap

Let's start with "not allowing objects to overlap." We know the exact amount that two circles overlap with each other. We'll say that a negative separation means overlap.

let combinedRadius = circleA.radius + circleB.radius
let distance = circleA.pos.distance(circleB.pos);
if (distance < combinedRadius) {
  let separation = combindedRadius - distance;
  // making it negative to signify "overlap"
  // only a convention for the math
  return -separation;
}

To avoid overlap we want to trend separation === 0 over time.

To do this, we can apply a steering factor every iteration to push separation towards 0. In the biz 😎, this steering factor is called Baumgarte stabilization, the idea of which is to feed the current "error", scaled by a chosen constant, back into the solver.

Erin Catto suggests not feeding the position correction term into the actual velocities because it introduces more artificial kinetic energy into the system, this differs from other solver implementations that do correct position overlap with velocity based impulses. Erin calls this positional approach a "pseudo-impulse".

// DO THIS FOR X Iterations per frame, in practice only a couple are necessary
for (let contact of contacts) {
  for (let point of contact.points) {
    const separation = contact.getSeparation();

    // Magic number by 0.2 seems to be a good amount
    const steeringConstant = 0.2
    // Limit the amount of correction at once for stability
    const maxCorrection = -5;
    // Be tolerant of 1 pixel of overlap
    const slop = 1;

    // Clamp to avoid over-correction
    // Remember that we are shooting for 0 overlap in the end
    const steeringForce = clamp(steeringConstant * (separation + slop), maxCorrection, 0);
    const impulse = contact.normal.scale(-steeringForce / point.normalMass);

    // NOTE! Update positions of bodyA & bodyB directly by "pseudo-impulse", we still use the same impulse formula from above
    if (!bodyA.static) {
        bodyA.xf.pos = bodyA.xf.pos.add(impulse.negate().scale(bodyA.inverseMass));
        bodyA.xf.rotation -= point.aToContact.cross(impulse) * bodyA.inverseInertia;
    }

    if (!bodyB.static) {
        bodyB.xf.pos = bodyB.xf.pos.add(impulse.scale(bodyB.inverseMass));
        bodyB.xf.rotation += point.bToContact.cross(impulse) * bodyB.inverseInertia;
    }
  }
}

In theory we could adjust both body's by the exact overlap (steeringConstant === 1.0), which we do know, but this introduces overlap in other shapes and the simulation ends up looking pretty terrible with shapes bouncing back and forth into each other.

Example of steeringConstant === 1.0 ☹

Build Constraints - Velocity Collision Response

To prevent overlap in the direction of collision, we want the relative velocity of the two shapes to be 0 along the normal. So relativeVelocity.dot(normal) === 0

In this code we calculate the velocity in the normal direction and apply the impulse in the opposite direction to cancel it out. Voila! Constraint met!

Hand-waving some of the Newtonian math, impulses works out like so for us. (More reading on impulses)

effectiveMass * deltaVelocity = impulse

Given this formula, if we can solve for an impulse that will yeild a deltaVelocity hat will bring velocity to 0 along the normal we are all set! See below:

// DO THIS FOR X Iterations per frame, in practice 6ish
for (let contact of contacts) {
  for (let point of contact.points) {
    // Need to recalc relative velocity because the previous step could have changed vel
    const relativeVelocity = point.getRelativeVelocity();

    const effectiveMass = bodyA.inverseMass + bodyB.inverseMass + 
                          bodyA.inverseInertia * aToContactNormal * aToContactNormal +
                          bodyB.inverseInertia * bToContactNormal * bToContactNormal;

    // Compute impulse in normal direction
    const normalVelocity = relativeVelocity.dot(contact.normal);
    let impulseDelta = -normalVelocity / effectiveMass;

    let impulseVector = contact.normal.scale(impulseDelta);
    
    // By convention the normal points away from A, so negate
    contact.bodyA.applyImpulse(point.point, impulseVector.negate());
    contact.bodyB.applyImpulse(point.point, impulse);
  }
}

This is only part of the picture the above only, what about objects bouncing off of each other? Borrowing from the wiki page for impulse based reactions the formula for this is:

-(1 + restitution) * relativeVelocity.dot(normal) / effectiveMass

Restitution is the ratio the body velocities after collision, one way to think about this is perhaps the "bounciness" of the system. Values of restitution should be between 0 and 1.

So lets adjust the code from above to add that "bounce"

// DO THIS FOR X Iterations per frame, in practice 6ish
for (let contact of contacts) {
  for (let point of contact.points) {
    // Need to recalc relative velocity because the previous step could have changed vel
    const relativeVelocity = point.getRelativeVelocity();

    const effectiveMass = bodyA.inverseMass + bodyB.inverseMass + 
                          bodyA.inverseInertia * aToContactNormal * aToContactNormal +
                          bodyB.inverseInertia * bToContactNormal * bToContactNormal;

    const restitution = bodyA.restitution * bodyB.restitution;

    // Compute impulse in normal direction
    const normalVelocity = relativeVelocity.dot(contact.normal);
    let impulseDelta = (-(1 + restitution) * normalVelocity) / effectiveMass;

    let impulseVector = contact.normal.scale(impulseDelta);
    
    // By convention the normal points away from A, so negate
    contact.bodyA.applyImpulse(point.point, impulseVector.negate());
    contact.bodyB.applyImpulse(point.point, impulse);
  }
}

Now the resulting velocity after is the opposite in the normal direction scaled according to the restitution term! Voila we have bouncing! ✨

Build Constraints - Friction

For friction, the process is similar to the constraint in the normal direction. We want to trend velocity in the tangent direction relativeVelocity.dot(tangent) === 0

Notice that the effective mass in the tangent direction is different than the normal direction.

for (let contact of contacts) {
  for (let point of contact.points) {
    const relativeVelocity = point.getRelativeVelocity();

    const effectiveMass = bodyA.inverseMass + bodyB.inverseMass +
                          bodyA.inverseInertia * aToContactTangent * aToContactTangent +
                          bodyB.inverseInertia * bToContactTangent * bToContactTangent;

    const tangentVelocity = -relativeVelocity.dot(contact.tangent);
    let impulseDelta = tangentVelocity / point.tangentMass;

    // Impulse along the TANGENT
    let impulseVector = contact.tangent.scale(impulseDelta);
    
    // By convention the normal points away from A, so negate
    contact.bodyA.applyImpulse(point.point, impulseVector.negate());
    contact.bodyB.applyImpulse(point.point, impulse);
  }
}

Not too bad, and it produces a pretty believable simulation.

Contact Warming for Stability

We can take advantage of previous work in earlier frames to help improve simulation stability (especially for large stacks of objects) by accumating the impulse for contacts that persist across frames. This helps overcome the force of gravity on big stacks by giving objects at the bottom extra impulse to start with.

Notice compression of the stack when warming is off

There is a trick to this, you can't just stash all the the impulses. We need to preserve the constraint that the sum of all impulses is positive (Velocity >= 0) over time or it's possible shapes will end up overlaping on warming.

In these examples we keep track of accumulated impulses in each persistent contact point.


// Clamping based in Erin Catto's GDC 2014 talk
// Accumulated impulse stored in the contact is always positive (V >= 0)
const newImpulse = Math.max(point.normalImpulse + impulseDelta, 0);
// But current impulse deltas can be negative
impulseDelta = newImpulse - point.normalImpulse;
point.normalImpulse = newImpulse;

Friction needs an additional check to keep things proportional to the normal force. Intiutively this makes sense, the harder something is pushing down on a surface, the more it sticks and resists sliding.


// Clamping based in Erin Catto's GDC 2006 talk
// Correct clamping https://github.com/erincatto/box2d-lite/blob/master/docs/GDC2006_Catto_Erin_PhysicsTutorial.pdf
// Accumulated fiction impulse is always between -uMaxFriction < dT < uMaxFriction
// But deltas can vary
const maxFriction = friction * point.normalImpulse;
const newImpulse = clamp(point.tangentImpulse + impulseDelta, -maxFriction, maxFriction);
impulseDelta = newImpulse - point.tangentImpulse;
point.tangentImpulse = newImpulse;

Once we have the impulses, at the beginning of the frame we can apply the accumulated impulses to any body's part of a persistent contact.

for (let contact of contacts) {
  for (let point of contact.points) {
    const normalImpulse = contact.normal.scale(point.normalImpulse);
    // Scaling back the tangent impulse seems to increase stack stability?
    const tangentImpulse = contact.tangent.scale(point.tangentImpulse).scale(.2);
    const impulse = normalImpulse.add(tangentImpulse);
  
    contact.bodyA.applyLinearImpulse(normalImpulse.negate());
    contact.bodyA.applyAngularImpulse(point.point, tangentImpulse.negate());

    contact.bodyB.applyLinearImpulse(normalImpulse);
    contact.bodyB.applyAngularImpulse(point.point, tangentImpulse);
  }
}

Order is important

Order of solving constraints creates precedence, constraints solved later in the frame take precedence. In general, your position constraints (like overlap) will probably take the most precedence in your simulation.

Lowest precedence

Warm Contacts
Friction
Collsion Response (Velocity)
No Overlap (Position)

Highest precedence

Summary

Constraint based collision resolution feels very similar in principle to other steering approaches, like flocking AI's, or enemy/npm AI. Steering is a powerful technique to create interesting emergent behavior with simple rules.

Things to explore next with constraints might be joints, motors, etc using constraints!

Read the code, and see the demo!

Resources & Additional Reading

Also check out Allen Chou's physics blog post series, and his great video series on the topic
Erin Catto also has a GDC 2006 slide deck that goes into detail about these different constrants.

Hopefully this helps folks out there implementing or trying to understand their own constraint systems!

-Erik

Don't Test Fonts

Sun, 13 Dec 2020 00:00:00 +0000

Recently for Excalibur I found myself in need of testing text rendering on the canvas, and found myself in a whole world of hurt 🤕. I was unaware of all of the pain around font rendering differences on different platforms.

The Problems

Finding a font shared by all platforms is hard, web safe fonts get you close sometimes
Platforms Windows/Linux/MacOS/Mobile render the exact same font slightly differently
Flash of unstyled text, ensuring a font is available for rendering
Writing tests for text in a font

TLDR the code and the jasmine matcher

Use a specific font

Loading a specific open font is probably your best bet, relying on system fonts existing will not be consistent across platforms. I used the google fonts to find a font with a compatible license for me, in this example I used "Open Sans"

https://fonts.google.com/specimen/Open+Sans

Let's disect the google font link quick.

The first link is this preconnect to the google cdn where the actual font files are stored. preconnect is a hint to the browser to start opening a connection to that domain so that it's ready to accept requests for fonts as soon as possible.

<link rel="preconnect" href="https://fonts.gstatic.com">

The second link is a style sheet that defines the CSS font-face for the font.

<link href="https://fonts.googleapis.com/css2?family=Open+Sans&display=swap" rel="stylesheet">

Popping that link into the browser you get something like below. Notice it's referencing the font CDN to grab the font files we mentioned earlier.

/* latin */
@font-face {
  font-family: 'Open Sans';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url(https://fonts.gstatic.com/s/opensans/v18/mem8YaGs126MiZpBA-UFVZ0b.woff2) format('woff2');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
...

Fix the Flash of Unstyled Text

After loading your fonts, there is a period of time before they are loaded preventing consistent tests.

There is a new browser api FontFaceSet that works most places you'll want to test in.

The FontFaceSet.load() forces a specific font to be loaded and returns a promise when it's done. This needs to be a fairly specific font string to work, including the the size, style, and font you want to load. ProTip^tm you must specify italic or bold explicitly if you want to wait for it to load.

await document.fonts.load('18px Open Sans');
await document.fonts.load('italic 18px Open Sans');
await document.fonts.load('bold 18px Open Sans');

For some reason the load() API doesn't seem to guarantee that the font is also "available". You must also check() that the font has been loaded and is available, but doesn't initiate a load itself.

if (document.fonts.check('18px Open Sans')) {
    ...
}

With all of that here is the final helper to wait for a font, sourced from this SO post

async function waitForFontLoad(font, timeout = 2000, interval = 100) {
  return new Promise((resolve, reject) => {
    // repeatedly poll check
    const poller = setInterval(async () => {
      try {
        await document.fonts.load(font);
      } catch (err) {
        reject(err);
      }
      if (document.fonts.check(font)) {
        clearInterval(poller);
        resolve(true);
      }
    }, interval);
    setTimeout(() => clearInterval(poller), timeout);
  });
}

Putting it together

If you are using text in the dom, one trick is to use a marker CSS class on the document like font-loaded to control display.

async function main() {
    await waitForFontLoad('18px Open Sans');
    await waitForFontLoad('bold 18px Open Sans');
    await waitForFontLoad('italic 18px Open Sans');
    document.body.classList.add('font-loaded');
}
main();

.text {
    display: none;
    font-family: 'Open Sans';
}

.font-loaded .text {
    display: block;
}

.text.italic {
    font-style: italic;
}

.text.bold {
    font-weight: bold;
}

This is great for testing! We can know if the font is present before running our test or drawing text in the canvas!

However, this is not great visually if you inflict this on users 😢.

Brief aside, here are a few options to fix this visual if you want to load fonts like this for people:

Block loading the WHOLE site until fonts are ready (not recommended, it's better to show your users something).

Add placeholder rectangles while things are loading. This can work great if you need to load other data that'll take some time. Or if the text is being loaded from an endpoint.

.text {
    font-family: 'Open Sans';
    
    display: inline-block;
    color: transparent;
    background-color: #ccc;
    border: solid #ccc;
    border-radius: 3px;
}

.font-loaded .text {
    border: none;
    border-radius: none;
    
    background-color: transparent;
    color: black;
}

My favorite, some CSS animations to fade in as things load

@keyframes fadeIn {
    0% { opacity: 0; }
    100% { opacity: 1; }
}

.font-loaded .text {
    display: block;
    animation: fadeIn ease-in-out .2s
}

Writing the tests

If you're in jasmine, they support running async functions in your beforeAll, this means we can wait for things before starting our tests.

I recommend downloading the font files from google fonts and making your own fonts.css for the faces and characters you care about. I used the google sheet https://fonts.googleapis.com/css2?family=Open+Sans&display=swap as a reference. Some CI platforms won't allow fonts to be loaded from an outside link (like AppVeyor).

describe('My Text', () => {

    beforeAll(async () => {
        // Insert font into DOM
        // Fonts are stored in the locally in the project
        // path/to/my/font-normal.woff
        const fontfaces = document.createElement('link');
        fontfaces.href =
            'path/to/my/fonts.css';
        fontfaces.rel = 'stylesheet';
        document.head.appendChild(fontfaces);

        // Wait for all font flavors to be available before starting the tests
        await document.fonts.load('18px Open Sans');
        await document.fonts.load('bold 18px Open Sans');
        await document.fonts.load('italic bold 18px Open Sans');
        await document.fonts.load('italic 18px Open Sans');
    });
});

Supporting different platforms

If you are doing pixel diffing (like me) the same font will not render exactly the same on each platform. So I built a couple helpers that take advantage of navigator.platform. Normally I would NOT recommend using navigator.platform for production code, but with CI I have control of the environment.

async function runOnWindows(asyncCtx) {
  if (navigator.platform === 'Win32' || navigator.platform === 'Win64') {
    await ctx();
    return true;
  }
  return false;
}

async function runOnLinux(asyncCtx) {
  if (navigator.platform.includes('Linux')) {
    await ctx();
    return true;
  }
  return false;
}

I'm using a very basic image matcher built for excalibur we implemented that can compare a canvas pixel by pixel with an expected image.

import { ExcaliburAsyncMatchers } from 'excalibur-jasmine';

...

beforeEach(() => {
   jasmine.addAsyncMatchers(ExcaliburAsyncMatchers);
});

it('should match images', () => {
    const canvasElement = document.createElement('canvas');
    const ctx = canvasElement.getContext('2d');
    ctx.font = 'bold 18px Open Sans';
    ctx.fillText('Some Text');

...
    await runOnWindows(async () => {
        await expectAsync(canvasElement).toEqualImage('src/spec/images/GraphicsTextSpec/text.png');
        });

    await runOnLinux(async () => {
        await expectAsync(canvasElement).toEqualImage('src/spec/images/GraphicsTextSpec/text-linux.png');
    });
})

This outputs results as base64 to the console, not the best but works in all the CI platforms and can be copied to a browser to compare results.

For a more full featured image diffing in your tests I'd look into pixelmatch.

Hopes this helps you text and font peeps!

Here is the code, jasmine matcher, and the excalibur example

-Erik

Using AssemblyScript with Webpack and TypeScript

Wed, 25 Nov 2020 00:00:00 +0000

I've recently been playing around with AssemblyScript for increasing the performance of my game engine Excalibur. It's a great language for WebAssembly, it's a subset of TypeScript (sounds familiar 😂) that compiles to WebAssembly. It was my first choice because I'm very familiar with TypeScript, but there are great resources out there for C++ and Rust to WebAssembly.

For my setup, I want to build my main app in TypeScript, my wasm in AssemblyScript and use a bundler to make it all happen. Turns out this was a bit tricky.

TLDR show me the code 😎

Enter AssemblyScript

Getting AssemblyScript installed and compiling is fast with npm

> npm install --save-dev --save-exact assemblyscript

I built a small wasm adder built in AssemblyScript to demostrate, it should look pretty familiar for peeps used to TypeScript. I'll be writing a more in-depth post on using AssemblyScript, but I recommend reading more. The only piece I will say, is that wasm only understands specialized number types and AssemblyScript has builtins to help with these. In this case below i32 stands for signed 32-bit integer.

// wasm-adder.ts
export function add(a: i32, b: i32): i32 {
    return a + b;
}

You also need to setup a tsconfig.json nearby to pull in those special AssemblyScript types with extends.

//tsconfig.json
{
  "extends": "assemblyscript/std/assembly.json",
  "include": [
    "wasm-adder.ts"
  ]
}

With all this setup it can be built into wasm on the commandline with:

> asc --optimize -b ./wasm/wasm-adder.wasm -t ./wasm/wasm-adder.wat ./wasm/wasm-adder.ts

Which when compiled to the wasm text format .wat looks like this. The final .wasm is a binary file!

 (func $wasm/assemblyscript/wasm-adder/add (param $0 i32) (param $1 i32) (result i32)
  local.get $0
  local.get $1
  i32.add
 )

Webpack Setup

I'm a big fan of Parcel for quick easy dev, but it's WebAssembly support isn't there yet. I tried to make my setup work in parcel but couldn't make it happen. Hopefully in Parcel 2 🤞

The Webpack setup here wasn't too bad. Here I've setup the typescript loading using the popular ts-loader and the excellent wasm-loader from ballercat (who arguably has the best GitHub username ever 😎).

// webpack.config.js
const path = require('path');
module.exports = {
    // The 'first' file to start the import chain
    entry: './main.ts',

    // Local dev setings
    mode: 'development',
    devtool: 'source-map',
    devServer: {
        contentBase: path.join(__dirname, '.'),
        compress: true,
        port: 9000,
    },

    // Output bunddle into the dist folder
    output: {
        library: 'main',
        libraryTarget: 'umd',
        path: path.resolve(__dirname, "dist"),
    },

    resolve: {
        // Add `.ts` and `.tsx` as a resolvable extension (means you can leave the file extension off)
        // I purposley didn't put ".wasm" here to illustrate the file being loaded
        extensions: [".ts", ".tsx", ".js"]
    },
    module: {
        rules: [
            // all files with a `.ts` or `.tsx` extension will be handled by `ts-loader`
            { 
                test: /\.tsx?$/,
                // Tells webpack how to interpret TypeScript files into JavaScript-land
                loader: "ts-loader" 
            },
            {
                test: /\.wasm$/,
                // Tells webpack how to interpret wasm files into JavaScript-land
                loader: "wasm-loader"
            }
        ]
    }
}

AssemblyScript + Webpack

AssemblyScript doesn't have an official Webpack loader, but there are a few out there by others (buyer beware hasn't been updated in a while). However, I'm building my AssemblyScript manually, mostly because I have need to configure a few of the newer compiler options in my eventual use case.

Here I use the AssemblyScript compiler, asc, directly in my npm scripts. The AssemblyScript compiler has a lot of options the ones I have here specificy the -b binary, -t web assembly text file (for debugging), -d the TypeScript declaration file (this will be important for strong typing our wasm module), and finally the --optimize to do optimizations on the final generated assembly.

Below the idea is to build the wasm with the AssemblyScript compiler, then use the webpack wasm-loader to bundle it.

// package.json
"scripts": {
    "build": "npm run build:assembly && webpack",
    "build:assembly": "asc --optimize -b ./wasm/wasm-adder.wasm -t ./wasm/wasm-adder.wat -d ./wasm/types.d.ts ./wasm/assemblyscript/wasm-adder.ts",
    // For development the wasm is only built once
    // The wasm will need to be rebuilt each time there isn't an asc --watch command yet
    "start": "npm run build:assembly && webpack serve"
}

Configuring your AssemblyScript and wasm-loader Types

One cool trick when importing non-TypeScript files is to setup a files.d.ts declaration at the root of your project. The declare module '*.wasm' caters to the wasm-loader's runtime JavaScript interface which provides a builder function with the optional WebAssembly imports. For AssemblyScript, you generally need to provide an importsObject directly with an env containingchunk of WebAssembly memory and an abort function.

// files.d.ts
declare module '*.wasm' {
    // Strongly type the exports with T
    function wasmBuilderFunc<T>(importsObject?: WebAssembly.Imports): Promise<{instance: WebAssembly.Instance & { exports: T }}>;

    export = wasmBuilderFunc;
}

With Webpack and all the types configured, you can import the wasm file directly like so in main.ts!

// main.ts
// wasmBuilder for https://github.com/ballercat/wasm-loader webpack loader
import wasmBuilder from './wasm/wasm-adder.wasm';

wasmBuilder({
    env: {
        memory: new WebAssembly.Memory({ initial: 1}),
        abort: () => {}
    }
}).then(wasm => { ... });

One slightly goofy thing about the AssemblyScript declaration file is that it's the types of the instantiated WebAssembly module instance's exports, not the value directly out of the import which gives us a wasm-loader builder at runtime. So I renamed the AssemblyScript type declartion file to something else types.d.ts to not confuse TypeScript types and import those types separately (note in the package.json build:assembly). This approach was inspired by the way AssemblyScript imports the types using the small assemblyscript file loader if your interested.

// wasmBuilder for https://github.com/ballercat/wasm-loader webpack loader
import wasmBuilder from './wasm/wasm-adder.wasm';

// TypeScript type-only import
import type AdderModule from './wasm/types';

wasmBuilder<typeof AdderModule>(...).then(wasm => {
    const Adder = wasm.instance.exports; // Full type support!
    const results = Adder.add(1, 2);
    document.write('Huzzah! 1 + 2 = ' + results) // Pardon the document.write 😢
});

Yay strong typing on wasm modules using AssemblyScript and Webpack!

Hope this helps my TypeScript and WebAssembly peeps out there!

Cheers! Erik

Android Games with Capacitor and JavaScript

Thu, 29 Oct 2020 00:00:00 +0000

Updated on Feb 21st 2022 to the latest Excalibur, Capacitor.js & Parcel!

In this post we put a web canvas game built in Excalibur into an Android (or iOS) app with Capacitor.js!

In the past I would have used something like Cordova, but this new thing from the folks at Ionic has TypeScript support out of the box for their native APIs and support for using any Cordova plugins you might miss.

TLDR show me the code

Capacitor Setup

The capacitor project setup is pretty straightforward from their docs, it can drop in place in an existing project or create a brand new project from scratch.

I opted for the brand new project:

> npm init @capacitor/app

Then follow their wizard and instructions to configure.

After that step add the platforms you're interested in, in this case Android

> npx cap add android

I recommend reading the capacitor documentation on workflow with a hybrid native app. The gist is this

Run npx cap sync to copy your web project into capacitor
Run npx cap run android to start the project on android (or start in the Android SDK)

Android Setup

Before you try to run the project

Download Android Studio Android Studio
Open it up and check for updates if needed (first time initialization takes some time)
Accept your SDK package licenses, the easiest way I've found to do this is with the SDK command line tools with Powershell on W.
1. Find the SDK Manager
2. In SDK Tools, check Android SDK Command-line Tools
Next we need to accept licenses.
- In powershell, navigate to the Android SDK Location for command line tools C:\Users\<username>\AppData\Local\Android\Sdk\cmdline-tools\latest\bin
- Set your java home temporarily $env:JAVA_HOME = 'C:\Program Files\Android\Android Studio\jre'
- Run .\sdkmanager.bat --licenses and select y for each

Starting the App

Now that we have Android all setup we can start the app with the capacitor command line.

The gist is that it copies the final compiled html/css/js assets from your favorite frontend frameworks and build tools into the native container

> npx cap sync

After that we can open it in Android Studio with the capacitor commandline

> npx cap open android

Building the project and running the first time can take some time, so be patient after hitting the big green play button.

ProTip^TM The Emulator is MEGA slow to start so once you get it on, leave it on. You can redeploy the app to a running emulator with the "re-run" hightlighted below.

If your Android emulator crashes on the first try like mine did with something like The emulator process for AVD Pixel_3a_API_30_x86 was killed, this youtube video was super helpful. For me the problem was disk space, the AVD needs 7GBs of disk space to start so I had to clean out some junk on the laptop 😅

Building Your Canvas Game

The dev cycle is pretty slick, run npm cap copy android to move your built JS living in the www to the right android folder. The default app looks like this after running it in the android emulator.

Setting Up Your JS Build

First let's setup our TypeScript by installing and creating an empty tsconfig.json

> npm install typescript --save-dev --save-exact
> npx tsc --init`

Recently I've been a big fan of parcel(v1) for quick and easy project setup, and it works great with excalibur also webpack is cool too if you need more direct control of your js bundling.

> npm install parcel --save-dev --save-exact

I copied the generated manifest.json, index.html, and css/ folder out of the original generated www/ and put it into game/.

We need to setup our development and final build script in the package.json. The npm "start" script tells parcel to run a dev server and use game/index.html as our entry point to the app and follow the links and build them (notice the magic inline <script type="module" src="./main.ts"></script>) ✨

<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
  <meta charset="UTF-8">
  <title>Game Test</title>
  <meta name="viewport" content="viewport-fit=cover, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
  <meta name="format-detection" content="telephone=no">
  <meta name="msapplication-tap-highlight" content="no">

  <link rel="manifest" href="./manifest.json">
  <link rel="stylesheet" href="./css/style.css">
</head>
<body>
  <script type="module" src="./main.ts"></script>
</body>
</html>

In this setup I'm sending all my built output with --dist-dir into the www directory, which is what capacitor will copy to android. I went ahead and deleted the provided default app in the www directory.

/* package.json */
{
  "name": "my-cool-game",
  "scripts": {
    "start": "parcel game/index.html --dist-dir www",
    "typecheck": "tsc -p . --noEmit",
    "build": "parcel build game/index.html --dist-dir www"
  }
  ...
}

Vanilla Canvas code

To start with I have a really awesome game that shows the fps and a red square. This shows how get started from scratch with the HTML Canvas.

// main.ts
const canvas = document.createElement('canvas') as HTMLCanvasElement;
const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;

canvas.height = window.innerHeight;
canvas.width = window.innerWidth;
document.body.appendChild(canvas);

let lastTime = performance.now();
const mainloop: FrameRequestCallback = (now) => {
    const delta = (now - lastTime)/1000;
    lastTime = now;
    ctx.fillStyle = 'blue';
    ctx.fillRect(0, 0, canvas.width, canvas.height);
    
    ctx.font = '50px sans-serif';
    ctx.fillStyle = 'lime';
    ctx.fillText((1/delta).toFixed(1), 20, 100);

    ctx.fillStyle = 'red';
    ctx.fillRect(canvas.width/2, canvas.height/2, 40, 40);

    requestAnimationFrame(mainloop);
}

mainloop(performance.now());

Using Excalibur🗡

Using the Excalibur engine with capacitor and parcel will be a breeze! Really any web based game engine could be substituted here if you want. Here is the source on github!

> npm install excalibur --save-exact

Update the main.ts with some Excalibur

import { Actor, DisplayMode, Engine, Input, Loader, ImageSource } from "excalibur";

const game = new Engine({
    displayMode: DisplayMode.FillScreen,
    pointerScope: Input.PointerScope.Canvas
});

const sword = new ImageSource('assets/sword.png');
const loader = new Loader([sword]);

game.start(loader).then(() => {
    game.input.pointers.primary.on('move', event => {
        const delta =  event.worldPos.sub(actor.pos);
        actor.vel = delta;
        // Original asset is at a 45 degree angle need to adjust
        actor.rotation = delta.toAngle() + Math.PI/4;
    });

    const actor = new Actor({
        x: game.halfDrawWidth,
        y: game.halfDrawHeight,
        width: 40,
        height: 40
    });
    actor.graphics.use(sword.toSprite());

    game.add(actor);
});

Note, depending on your emulator settings you may need to tweak it's graphics settings and restart Android Studio for it to build and run (This works out of the box fine on real hardware tested in BrowserStack, for some reason the emulator graphics can be confused)

Tada! 🎉

Hope this helps you web game devs out there!

-Erik

JavaScript Object Pools for Value Objects

Sun, 18 Oct 2020 00:00:00 +0000

What do I mean by "value" objects? I mean things that behave like numbers conceptually. For example const result = 1 + 2, adding two numbers doesn't change the value of 1 or 2 they are immutable, but a new value falls out the left hand side into the result. This is a useful property, and sometimes you want JavaScript objects to behave this way. I'll call such objects them "value" objects in this post.

Value Objects

In the example below one and two behave like values and are immutable, result is a new value object, not a reference to one or two that was updated.

class Vector {
    constuctor(
        public x: number,
        public y: number
    ) {}

    add(v: Vector): Vector {
        return new Vector(this.x + v.x, this.y + v.y);
    }
    /// More implementation hidden
}

const one = new Vector(1, 1);
const two = new Vector(2, 2);
const result = one.add(two); 
// one still has the value (1, 1) after the 'add' operation
// two still has the value (2, 2) after the 'add' operation
// result is a new "value" object that has the value (3, 3)

Immutability helps protect against bugs, especially when working with objects that represent mathematical quantities. If the value of one was updated to (3, 3) after the .add(), it might be unexpected (at least to me very confusing to have a "value" object change like this)!

The JavaScript Value Object Problem

So one downside to this type of value object is how quickly these ephemeral value objects can be created and discarded! This can build up in memory quickly and cause garbage collection pauses leading to some jankiness^tm!

This might be unacceptable depending on your app. If you need high throughput and performance, like a game, value object related garbage collection could be a big problem.

One solution is to use an object pool strategy! While this technique is nothing new, it can be useful for these ephemeral value objects that might be used for intermediate calculations, this can cut down on new Vector() allocations by an order of magnitude!

TLDR: Object Pool Source

⚠ Caveats of Object Pools! ⚠

I need to offer an obligatory warning, object pooling is a memory optimization technique. It effectivley works by taking on the role of memory manager instead of the very powerful and well engineered browser. Also don't trust me because I'm writing about it, verify for yourself something will work for your usecase.

1. They are easy to get wrong and cause a memory leak

It's important to have a limit or perhaps a soft limit with logging in an object pool. Using a pool or implementing a pool incorrectly will just cause a memory leak that the browser cannot garbage collect anymore.

Mitigation: Add some stress tests with large numbers of objects over time to make sure pools are working as expected.

2. Hard to track down bugs

Using a reference to a value object that has been returned to the pool can cause bugs. Often the source of the bug is separated from where it manifested. For example if a leaked reference to a value object managed by the pool was reused and values were change it may cause invalid results in calculations.

Mitigation: Track the state of your objects and throw when used in invalid contexts.

Value Object Pool Implementation Details

We can compare the difference in allocations with a quick modification to our Vector type to track the number of constructions. This type of thing is super useful in general if you're looking to increase memory efficency

class Vector {
    public static ALLOCATIONS = 0;
    constuctor(
        public x: number,
        public y: number
    ) {
        Vector.ALLOCATIONS++;
    }

    //...
}

In order for this type of value object to make full use of the pool we need to pollute the type with some pool logic 😱 A less effecient version could be done without doing this. I try to minimize the intrusiveness of this change with a _new(x: number, y: number) helper to abstract the pooling decision. Send me a note if you have any other suggestions on how to accomplish this better!

interface Poolable<Type = any> {
    _pool?: Pool<Type>;
}

// Implements a `Poolable` interface which decorates a `_pool` prop
class Vector implements Poolable<Vector> {
    static _ALLOCATIONS = 0;
    // 
    public _pool?: Pool<Vector> = undefined;

    private _new(x: number, y: number): Vector {
        return this._pool?.get(x, x) ?? new Vector(x, x);
    }

    //...

    add(v: Vector): Vector {
        return this._new(this.x + v.x, this.y + v.y);
    }

    //...
}

With our Vector value object setup to make use of pooling, we can use using(...) to do all of our intermediate calculations, then when the using block is done all of the vectors used are recycled! This means we only need enough unique vectors to perform the calculation, none of the instances get waisted.

const VectorPool = new Pool<Vector>(
    // Builder Function tells the pool how to build an object
    (x, y) => new Vector(x, y),
    // Recycler Function tells the pool how to update an object for re-use
    (v, x, y) => { v.x = x; v.y = y; return v; },
    // Max size on a pool is important to help catch memory leaks
    100
)

// Update 200 things in my game loop
for (let i = 0; i < entities.length; i++) {
    // After the using all Vectors are reclaimed for later use!
    const [pos, vel] = VectorPool.using((p: Pool<Vector>) => {
        // Uses the builder or recycler to retrieve a vector instance
        const position = p.get().copyFrom(entities[i].pos);
        const velocity = p.get().copyFrom(entities[i].vel);
        const acceleration = p.get(0, accel);

        // Perform euler position approximation
        const finalVelocity = velocity.add(acceleration.scale(time));
        const finalPosition = position.add(velocity.scale(time)).add(acceleration.scale(.5 * time * time));

        entities[i].pos.copyFrom(finalPosition);
        entities[i].vel.copyFrom(finalVelocity);
        // Returning these vectors from the pool `using()` signals that these will be unmanaged
        // These vectors are taken out of the pool
        return [finalPosition, finalVelocity]
    });
}

Object Pool Example & Results

The results are really impressive for the slightly contrived example of a game type program below! It becomes pretty clear the amount of objects that can be generated over time in this type of scenario if not pooled.

Here is the source for the object pool if you want to use it for yourself!

Pooled

Non-pooled

More allocations can be squeezed if no pooled value objects are allowed to leave the pool with a using() or done(). Organizing your internal calculation this way can produce some very memory efficent results 😎

Hope this helps the person out there trying to do the same thing!

Cheers,

-Erik

Quickly Open Visual Studio on the Command Line

Tue, 06 Oct 2020 00:00:00 +0000

I'm a huge fan of using the command line for things, and I use the command line to open vs code all the time with code ..

I wanted a way to do the same thing for visual studio, turns out you can! In the example below I use visual studio in a directory. The code works by searching recursivel for the .sln file and passing the solution file path to devenv.exe and you're set.

Just stick this in your powershell profile, which can be opened with vs code with code $PROFILE at the powershell prompt. Now type vs . in the root of your favorite visual studio project.

function vs([string]$start = ".") {
    # Locate a solution file recursivle "*.sln"
    $sln = ((Get-ChildItem -Path $start -Filter *.sln -Recurse) | where { $_.fullname -notmatch 'node_modules' })[0]

    # Open the solution file with the well know visual studio path
    # If you have the community edition replace "Professional" with "Community"
    & "C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\Common7\IDE\devenv.exe" $sln.fullname
}

This approach can be used for more than just visual studio, it could be applied to any program that has it's own project type. Possibilities might be unity, photoshop, aseprite, etc.

Hope this makes your visual studio development a delight! -Erik

Understanding The Canvas Measure Text Metrics

Fri, 02 Oct 2020 00:00:00 +0000

When doing canvas drawing with text you may want to measure how the text is placed. Different fonts and different font sizes result in different pixel rendering, and it can be difficult to work with text pixel positioning in graphics programing.

One problem is that the TextMetrics object that comes out of canvas rendering context measureText() has a lot of information and it's not super clear what it all means.

const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');

ctx.font = 'italic 50px serif';

const metrics = ctx.measureText('Some text, but at what length?');

The `metrics.width` Is A Lie

You probably want to add actualBoundingBoxLeft and actualBoundingBoxRight, this will be a more acurate than just width. The reason is some fonts have glyphs that hang or stretch over their width used for text placement. This is especially true if you want to ensure text renders within certain confines, like UI for a game.

const metrics = ctx.measureText('Some text, but at what length?');
const width = metrics.width; // this can be slightly smaller

Use absolute values to calculate the width, depending on alignment and text these values may be negative.

const metrics = ctx.measureText('Some text, but at what length?');
const width = Math.abs(metrics.actualBoundingBoxLeft) + 
              Math.abs(metrics.actualBoundingBoxRight);

There Is No Height (or Spoon)

The only way to get the height of a piece of text is to measure from the text baseline the ascent or descent. Before this was available the only thing was to guess the pixel height using the font size 😢.

The baseline is the horizontal line that the text rests against in some way. Some characters in a piece of text can be above or below in some amount from this line. The main textBaseline (and the default) is the alphabeticBaseline where text normally sits this is 0 by default. There are 2 other baselines, hangingBaseline and ideographicBaseline.

Calculating the real height of some text is the sum of actualBoundingBoxAscent and actualBoundingBoxDescent. Guessing by the font size doesn't really work.

const height = Math.abs(metrics.actualBoundingBoxAscent) + 
               Math.abs(metrics.actualBoundingBoxDescent);

Drawing Bounds Around Text

Canvas text is drawn from the bottom left, which is different from the rectangle apis that draw from the top left.

One way to remember this is that the position specified in fillText('some text', 20, 20) is on the baseline. The text rests on the same line that the position does.

With this in mind to draw bounds around text we subtract the the actualBoundingBoxAscent from the y coordinate and actualBoundingBoxLeft from the x coordinate.

// [x, y]
const pos = [10, 100];
const bounds = {
  top: pos[1] - metrics.actualBoundingBoxAscent,
  right: pos[0] + metrics.actualBoundingBoxRight,
  bottom: pos[1] + metrics.actualBoundingBoxDescent,
  left: pos[0] - metrics.actualBoundingBoxLeft
};

Cool Things with Bounds

Once you have an accurate bounding box for the text there are a lot of cool things that can be done.

Finding the center of the text is the average of the correct bounds, let's you flip and rotate with ease!

const center = [
  (bounds.left + bounds.right) / 2,
  (bounds.top + bounds.bottom) / 2
];
// Move the transform to center in the middle of the text
ctx.save();
ctx.translate(center[0], center[1]);
// flip in y
ctx.scale(1, -1);
// rotate 45 degrees
ctx.rotate(Math.PI / 4);
ctx.fillText(text, pos[0] - center[0], pos[1] - center[1]);
ctx.restore();

Hope this helps with your canvas text endeavors! -Erik

HttpClient and BOM sadness with JSON serialization

Sun, 13 Aug 2017 00:00:00 +0000

This week I ran across a problem when building a custom extension method to format a PATCH request to an api endpoint. Basically I wanted to create a PatchAsync method that matched the same semantics as PostAsync and GetAsync in HttpClient. I had some more unique JSON serialization requirements working with the IIS Admin rest api like snake_casing and booleans and numbers serialized at string literals like "124" or "true", so I needed to be able to pass my own JSON.NET configuration to the serialization.

Borrowing from this SO post I crafted this extension method:

public static async Task<HttpResponseMessage> PatchAsync<T>(this HttpClient client, string requestUri, T value, MediaTypeFormatter formatter)
{
    var method = new HttpMethod("PATCH");

    HttpRequestMessage request;

    using (var ms = new MemoryStream()) {
        var jsonFormatter = formatter as JsonMediaTypeFormatter;
        
        jsonFormatter?.WriteToStream(typeof(T), value, ms, Encoding.UTF8);

        var content = Encoding.UTF8.GetString(ms.GetBuffer(), 0, (int)ms.Length);
        request = new HttpRequestMessage(method, requestUri)
        {                    
            Content = new StringContent(content, Encoding.UTF8, jsonFormatter?.SupportedMediaTypes.First()?.MediaType)
        };
    }

    HttpResponseMessage response;
    try
    {
        response = await client.SendAsync(request);
    }
    catch (TaskCanceledException e)
    {
        throw e;
    }

    return response;
}

As far as I could tell from human eyeballs everything looked good, but when I ran this code from code it would bomb with "Unsupported Media Type: Invalid JSON". I could craft the same request by hand in fiddler or postman and it would work!

I did notice one odd artifact in the requests, the Content-Length didn't match up between the failing and succeeding requests even with what looked like the same payload...


PATCH https://mycoolserver:55539/api/webserver/logging/JpcOekeNc7uR-m9y8_uE9Q HTTP/1.1
Access-Token: Bearer abcdefghijklmnopqrstuvwxyz
Content-Type: application/json; charset=utf-8
Host: mycoolserver:55539
Content-Length: 76
Expect: 100-continue

{"id":"JpcOekeNc7uR-m9y8_uE9Q","directory":"D:\\inetpub\\logs\\coolsite160"}


HTTP/1.1 200 OK
Cache-Control: public, max-age=0
Transfer-Encoding: chunked
Content-Type: application/vnd.Microsoft.WebServer.Logging.2.0.0+json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 08 Aug 2017 20:08:59 GMT

// Success Response

PATCH https://mycoolserver:55539/api/webserver/logging/JpcOekeNc7uR-m9y8_uE9Q HTTP/1.1
Access-Token: Bearer abcdefghijklmnopqrstuvwxyz
Content-Type: application/json; charset=utf-8
Host: mycoolserver:55539
Content-Length: 79
Expect: 100-continue

{"id":"JpcOekeNc7uR-m9y8_uE9Q","directory":"D:\\inetpub\\logs\\coolsite160"}


HTTP/1.1 415 Unsupported Media Type
Cache-Control: public, max-age=0
Transfer-Encoding: chunked
Content-Type: application/problem+json
Content-Language: en
Server: Microsoft-HTTPAPI/2.0
Accept-Patch: application/json;charset=utf-8
Date: Tue, 08 Aug 2017 20:09:10 GMT

34
{"title":"Invalid JSON request object","status":415}
0

Aaaah HAAAA! There must be some invisible characters my dear Watson!

So I cracked open the trusty HEX editor and lo and behold! A BOM (literally) aka a byte order mark has snuck it's way in between my request headers and JSON payload! This 3-byte mark is included in UTF encoded stuff to help readers decode correctly. Ironically it breaks some deserializers, like the one in the IIS Rest Admin API!

Successful request:

Failed request:

After I discovered this the fix was pretty easy, .NET provides a new UTF8Encoding type that can be passed true or false to its constructor to indicated whether a BOM is wanted.

So the fixed extension method:

public static async Task<HttpResponseMessage> PatchAsync<T>(this HttpClient client, string requestUri, T value, MediaTypeFormatter formatter)
{
    var method = new HttpMethod("PATCH");

    HttpRequestMessage request;

    // No BOM now
    var utf8 = new UTF8Encoding(false);

    using (var ms = new MemoryStream()) {
        var jsonFormatter = formatter as JsonMediaTypeFormatter;
        
        jsonFormatter?.WriteToStream(typeof(T), value, ms, utf8);

        var content = utf8.GetString(ms.GetBuffer(), 0, (int)ms.Length);
        request = new HttpRequestMessage(method, requestUri)
        {                    
            Content = new StringContent(content, utf8, jsonFormatter?.SupportedMediaTypes.First()?.MediaType)
        };
    }

    HttpResponseMessage response;
    try
    {
        response = await client.SendAsync(request);
    }
    catch (TaskCanceledException e)
    {
        throw e;
    }

    return response;
}

Hopefully this helps out any of you JSON payload peeps trying to customize HttpClient. Somebody set us up the 💣!

IIS Administration REST API with PowerShell DSC in Azure

Sat, 17 Jun 2017 00:00:00 +0000

For a long time I have been using the good ol'fashioned DCOM based ServerManager client from Microsoft.Web.Administration.dll to configure IIS web servers. Now there is a nifty new open source administration REST api from Microsoft! OMGWTFBACON! This a great boon to your "DevOps" play because any language that speaks HTTP can be used to manage IIS cluster no matter how large or small! In this post I'll introduce you to PowerShell Desired State Configuration to install this powerful management tool in your environment. Like a boss 😎

What is DSC?

PowerShell DSC is a super powerful desired state configuration tool that comes with your windows server as a part of WMF (it is similar in concept to Puppet or Chef which can also work with windows servers). DSC can be setup in multiple ways: "Pull" or "Push". In my environment we've setup things in a Pull configuration, where enrolled nodes check into the central Pull server every thirty minutes for configuration. Push is an on demand process that pushes config to target nodes with an admin credential. Optionally, you could use azure automation as a pull server in the cloud to manage your on-prem or cloud windows machines.

Constructing the DSC

This is actually pretty easy to setup manually following the steps outlined on the Microsoft github project, but if you have an environment with hundreds or thousands of servers that spin up and down, this isn't super sustainable.

First we need to setup our configuration, all configuration in DSC needs to be in a configuration block.

configuration Install-IIS-Admin-Rest-Api {

    <# Todo awesome config for these righteous web servers #>
}

There are TONS of prebuilt open source DSC resources, along with some experimental resources from Microsoft. Their github has tons of examples. In PowerShell 5, we can source these resources from the internet using Install-Module -Name xPSDesiredStateConfiguration

In order for the rest api to work there are a few requirements:

IIS installed
Windows authentication enabled
URL authorization enabled
Hostable web core enabled
ASP.NET Core hosting bundle
Local in-bound firewall opened on management port 55539 (or whatever port you want)

The windows features are pretty simple, you just need to find the string for the feature you are looking for. The Get-WindowsFeature *web* command will get you far. Notice the DependsOn = "[ResourceType]ResourceName" strings, these are how you can make one resource depend on another. Unfortunately they are "stringly" typed and easy to mistype by mistake so I tend to copy paste these values.

WindowsFeature InstallIIS {
    Name = "Web-Server"
    Ensure = "Present"
}

WindowsFeature EnableWinAuth {
    Name = "Web-Windows-Auth"
    Ensure = "Present"
    DependsOn = "[WindowsFeature]InstallIIS"
}

WindowsFeature EnableURLAuth {
    Name = "Web-Url-Auth"
    Ensure = "Present"
    DependsOn = "[WindowsFeature]InstallIIS"
}

WindowsFeature HostableWebCore {
    Name = "Web-WHC"
    Ensure = "Present"
    DependsOn = "[WindowsFeature]InstallIIS"
}

For installers available online you can download them on the fly with the xRemoteFile resource, one method of sourcing such dependencies is to check them into your git repo using git lfs. Check out my friends post on that.. Otherwise you can source the direct download links like I did for this demo. Note that if you are in a corporate environment you may work behind a proxy which this resource takes into account.

xRemoteFile DownloadDotNetCoreHostingBundle {
    Uri = "https://go.microsoft.com/fwlink/?linkid=844461" #https://docs.microsoft.com/en-us/aspnet/core/publishing/iis
    DestinationPath = "C:\temp\dnhosting.exe"
    MatchSource = $false # Match source false wont re-download if the files change
    #Proxy = "optional, your corporate proxy here"
    #ProxyCredential = "optional, your corporate proxy credential here"
}

The built in Package resource is pretty simple, it does require some hard to find metadata. I find most consistent way to discover the metadata necessary for DSC is to install it once and run Get-WmiObject Win32_product | ft IdentifyingNumber,Name to find it's ID and Product Name. Note that IIS WindowsFeature and the xRemoteFile installer resource dependency before we can install the hosting bundle. Then I cheat by temporarily adding dotnet.exe to the path to avoid a reboot.

# Discover your product name and id with Get-WmiObject Win32_product | ft IdentifyingNumber,Name after installing it once
xPackage InstallDotNetCoreHostingBundle {
    Name = "Microsoft ASP.NET Core Module"
    ProductId = "B1B05FBB-1255-4F5B-9BAF-43B971A92613"
    Arguments = "/quiet /norestart /log C:\temp\dnhosting_install.log"
    Path = "C:\temp\dnhosting.exe"
    DependsOn = @("[WindowsFeature]InstallIIS",
                  "[xRemoteFile]DownloadDotNetCoreHostingBundle")
}

# Cheating and adding the dotnet.exe to the path to avoid reboot
Script PutDotNetOnPath {
    SetScript = {
        $env:Path = $env:Path + "C:\Program Files\dotnet\;"
    }
    TestScript = {
        return $env:Path.Contains("C:\Program Files\dotnet\;")
    }
    GetScript = {
        return @{
            SetScript = $SetScript
            TestScript = $TestScript
            GetScript = $GetSCript
            Result = "Set dotnet path"
        }
    }
}

Finally, lets download the Admin Rest API from Microsoft's GitHub release page and run the script installer. Note that in this case I use the Archive resource to unpzip the downloaded package into a directory for me to call later with a Script resource. For things that don't exist by default or in an external module, you can use Script resources to write vanilla powershell. The script resource has a few parts, the SetScript which does the work if the resource is not in compliance, TestScript which returns $true if in compliance and $false if not, and the GetScript which can be used to return the status of the node with the @{ Result = "status"}.

xRemoteFile DownloadAdminRestApi {
    Uri = "https://github.com/Microsoft/IIS.Administration/releases/download/v1.1.1/IIS.Administration.zip"
    DestinationPath = "C:\temp\IISAdministration.zip"
    MatchSource = $false
}

Archive UnzipAdminRestApi {
    Path = "C:\temp\IISAdministration.zip"
    Destination = "C:\temp\Admin\IISAdministration"
    Ensure = "Present"
    DependsOn = "[xRemoteFile]DownloadAdminRestApi"
}

Script InstallAdminRestApi {
    DependsOn = @("[Archive]UnzipAdminRestApi",
                    "[WindowsFeature]InstallIIS",
                    "[WindowsFeature]EnableURLAuth",
                    "[WindowsFeature]EnableWinAuth"
                    "[xPackage]InstallDotNetCoreHostingBundle",
                    "[Script]PutDotNetOnPath")
    SetScript = {
        # Run the IIS Administration installer
        & C:\temp\Admin\IISAdministration\setup\setup.ps1 Install -Verbose                
    }
    TestScript = {
        $svc = $null
        try {
            $svc = Get-Service "Microsoft IIS Administration" -ErrorAction SilentlyContinue
        } catch {}

        return !!$svc
    }
    GetScript = {
        return @{
            SetScript = $SetScript
            TestScript = $TestScript
            GetScript = $GetScript
            Result = "Install Admin Rest Api"
        }
    }
}

Let's see how it's all put together with the final configuration script! Checkout my gist with the code.

Azure DSC Pull Server

Now let's deploy this to some servers to build our web farm using Azure Automation DSC

If you don't already have an Azure Automation account they are easy to create and by far the easiest way to setup a DSC pull server. But if paying for a pull server isn't your speed checkout the OSS project Tug or try standing up your own.

All you need to do now is install the modules you need in your DSC environment, upload your completed configuration, and compile! In our case we need the xNetworking and the xPSDesiredStateConfiguration modules.

Deploying to Azure VMs

Here I show the UI way to enroll, but if automation is your goal the Azure RM PowerShell SDK has a cmdlet for enrolling VM's automagically Register-AzureRmAutomationDscNode

You can test it manually by running Update-DscConfiguration -Wait -Verbose this is helpful when spotting any potential errors in your DSC. If there is already a configuration running you can stop it with Stop-DscConfiguration -Force and start it on demand with Start-DscConfiguration –UseExisting –Verbose –Wait. In production it may be useful to checkout the event log if you need to debug configuration errors.

Final product

And voila, you can login to the admin api with your admin credentials and generate an API token to do work (don't worry this IP is long gone 😎). You can get a single pane of glass view of your VMs using this REST Api with the Microsoft tool https://manage.iis.net/

Manage your cloud web farm with REST Apis!!!

So cool!

Building Custom Analytics with Azure Functions

Thu, 27 Apr 2017 00:00:00 +0000

Recently we did a game jam for Ludum Dare 38, and we were not satisfied with the level of customization in analytics providers out there, so we decided to build our own with Azure Functions with Azure Table Storage as a semi-unstructured data store. We were up and running quickly and the process was fairly easy.

Setting up the function

For pennies on the dollar, you can setup Azure functions easily on in an azure account (currently forcasted to spend ~20 cents this billing period!). All that's required is an existing Azure account, which can be created here.

Next navigate to the new plus icon in the top left of your screen, search for function, and click the item labeled Function App published by Microsoft. After clickig create you'll have a few options. You'll notice that azure fuctions live inside of the *.azurewebsites.net subdomain, this is because technically they live in the Azure web apps ecosystem.

You'll need to pick a name, location (I recommend a place near-ish where people will be calling the function), hosting plan, and a storage account.

Writing a function

In this example I'm using the Node.js support in Azure functions to write a function. It is pretty easy to test and setup output to Azure table storage. It can even be wired up with source control so that code checked into github or another source code hosting provider is automatically deployed (Under Platform Features -> Deployment Options).

var uuid = require('node-uuid');

module.exports = function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    if (req.body && req.body.started) {

        // Add the required properties for Azure Table Storage
        var payload = {
            // Records in a single partition are fast to retrieve together, since I don't really have many records I used this scheme to force a convenient sorting in Storage Explorer, probably not ideal for a production scenario.
            PartitionKey: (Number.MAX_SAFE_INTEGER - Date.now()).toString(),
            // RowKey is the unique identifier in a partition, using GUIDs to solve this.
            RowKey: uuid.v4()
        }

        // Since table storage is NoSQL-ish you can drop whatever columns you want into it dynamically
        for(var prop in req.body){
            // exclude private _ members
            if(prop[0] !== '_'){
                payload[prop] = JSON.stringify(req.body[prop])
            }
        }

        // These bindings need to be added to the contex and are magically added 
        context.bindings.ludum38data = []
        context.bindings.ludum38data.push(payload);
        
        // Return value to echo back data stored
        context.res = {
            // Store analytics payload in table storage
            
            body: "Stored analytics: " + JSON.stringify(payload, null, 3)
        };
    }
    else {
        context.res = {
            status: 400,
            body: "Please pass a valid analytics body"
        };
    }
    context.done();
};

The one hiccup is that in order to use node modules like node-uuid you need to navigate to your functions scm (Kudu) site, create a package.json file, and run npm install manually. This can be found in the function's Platform features tab labeled Advanced tools (Kudu) or if you go to <nameofyourapp>.scm.azurewebsites.net. Navigate to the directory containing the package.json and run npm install

{
  "name": "ludum38stats",
  "dependencies" : {
      "node-uuid": "~1.4.8"
  }
}

Integrating with Azure Table Storage

Remember that storage account we created when we set up the Azure function? We'll use that to store our semi-unstructured data from analytics.

In the Integrate section of your specific function you can attack different data outputs to your function. In this case we want to persist it to Azure table storge.

Once we select the Azure Table Storage preset in the 'New Output' wizard, it is pretty easy to add things to it.

In your function you'll need to reference the outputTable that you've created in order to store things. Unfortunately it is a little unintuitive but you'll need to create your own array off of the Azure function context to submit your values.

So this would be an example of using the table parameter name above:


var payload = {
    PartitionKey: (Number.MAX_SAFE_INTEGER - Date.now()).toString(),
    RowKey: uuid.v4()
}
...
context.bindings.outputTable = []
context.bindings.outputTable.push(payload);

In order to insert into Azure table storage there are 2 required properites PartitionKey and RowKey. PartitionKey allows you to partition data to enhance data clustering, things with the same PartitionKey can be queried more quickly. RowKey is meant to be the unique itentifier for a row witin a partition. The rest of the properties are up to you, there are some limitations to be aware of, but they are pretty generous.

To test if things are working, Azure has a convenient test window to send fiddler like requests to your function.

Once you've pushed data into Azure Table Storage there is a convenient cross platform client from Microsoft to view the data located at http://storageexplorer.com/

CORS (Cross-Origin Resource Sharing) in Azure Functions

This setting is a pretty well hidden, but if you click on the Platform Features tab inside of the Azure function you'll find CORS under the API heading. Enter your domains to whitelist, IF YOU WANT TO ALLOW ALL you'll need to delete all entries and put a *, this does mean that ANYONE IN THE WORLD can call your function from any web page. Generally speaking this is a bad idea, but for our game analytics for LD38 it doesn't really matter.

With CORs implemented all we needed to do on to build our custom client-side logger was the following. Config.analyticsEndpoint is just the obscured function url that can be accessed in Azure with a click of the Get function URL button.

interface IPosition {
   x: number,
   y: number
}

interface IPayload {
   date: string, // date
   commit: string,
   seed: number, // seeded value
   started: number, // time
   timePlayed: number, // amount of time played
   won: boolean, // won or lost
   enemiesOnScreen: number, 
   foodCollected: string[],
   playerPositions: IPosition[]
   enemyPositions: IPosition[],
}

class Analytics {


   public static publish(payload: IPayload){
      return fetch(Config.analyticsEndpoint, {
         method: 'POST',
         headers: {
            'Content-Type': 'application/json'
         },
         body: JSON.stringify(payload)
      });
   }   
   
}

Putting it all together

Once that was complete we were able to build a heat map for player analytics for our game to see where people go in order to help better design the game.

Check out the cool heat map with our custom data (pun intended) 😎

Building a Sprite Editor for the NES

Sun, 26 Mar 2017 00:00:00 +0000

I did a talk about building nintendo games using the NESASM3 assembler. For this talk I wanted to be able to build my own sprites rather than use existing game rom files. The unfortunate thing was I couldn't find any in-depth documentation online about how sprites worked on the Nintendo, other than they are 8x8 pixels large, take up 16-bytes, and can only define 4 possible colors (1 of which needs to be the background).

This lead me down a path to reverse engineer the byte format of NES sprites using the emulator FCEUX and then build a simple editor that could produce sprite files format for my game. Check it out, the source is up on github!

NES Sprite Format

Originally, I thought that each sequential 2-bit chuck of the 16-bytes allocated per sprite encoded the color 1-4 of the sprite. Since 2-bits can represent all four possible colors (00, 01, 10, and 10), seems pretty reasonable right? Wrong!

Actually the format is much trickier than that, still not 100% sure why Nintendo did things this way, but I can only guess that there is a performance reason behind it.

Sprites are definited by byte n and byte n+8 to control the color of the first row of pixels in the 8x8 sprite. This means that the 1st byte and the 9th byte control the first row of pixels, and the 8th byte and the 16th byte control the last row of pixels for a sprite. The layout in memory to the corresponding 8x8 pixel looks like this:

Think about these two pairs of bytes (byte n and byte n+8) as separate channels, where the second channel's binary digits are weighted by 2 and the resulting color is the sum of channel 1 and channel 2 together. For example look at the sprite in the top left corner and the calculation of its colors.

Reverse engineering the format

Using FCEUX's PPU Viewer and PPU memory viewing feature I was able to reverse engineer the format by poking at bytes individually. It took a while to discover the scheme above, but this is roughly the trial and error process I followed to determine the colors of each pixel.

Each row of the the FCEUX hex editor is 16 bytes wide by default, which makes it convenient for testing out sprite behavior since we already know that 16 bytes are allocated per sprite. Each byte in the editor is represented by 2 hexidecimal digits where are grouped together for easy reading.

First, by setting the first byte to all 1's (hexidecimal FF) the first color in the palette was selected for the first row of the first sprite.

Next, filling out the next 7 bytes with 1's produces a solid 8x8 block. This produces color 1 in the palette.

On the 9th byte, we can change the top left pixel by entering a byte that has these binary digits 10000000 which is 80 in hexidecimal. This produces color 3 in the palette.

To produce color 2 we need to set the corresponding bit in the channel 1 byte to 0.

Reading binary files in JavaScript

Now that we know byte format for each sprite's pixel, we can build a simple web app to help edit and make binary NES sprite files. The app I built isn't the most beautiful app ever, but it got the job done. Hopefully I'll be able to update it in the future and adding common image editing features like flood fill, selections, layers, etc.

To deal with binary data, JavaScript has a useful type called the ArrayBuffer. With this type we can load up bytes directly from a source files using the XHR method and the FileReader method.

/// Upload utilities

function readBlob() {

    var files = document.getElementById('nesfile').files;
    if (!files.length) {
        alert('Please select a file!');
        return;
    }

    var file = files[0];
    var start = 0;
    var stop = file.size - 1;

    var reader = new FileReader();

    // If we use onloadend, we need to check the readyState.
    reader.onloadend = function(evt) {
        
        if (evt.target.readyState == FileReader.DONE) { // DONE == 2
            spriteRomData = new Uint8Array(evt.target.result);
            NEStoCanvas(spriteRomData);
        }
    };

    var blob = file.slice(start, stop + 1);
    reader.readAsArrayBuffer(blob);
}


/// Load up default sprite sheet

var xhr = new XMLHttpRequest();
xhr.open('GET', 'main.chr')
xhr.responseType = 'arraybuffer';

xhr.addEventListener('load', function(evt){
    spriteRomData = new Uint8Array(xhr.response);
    NEStoCanvas(spriteRomData);
});

xhr.send();

In order to see the native NES sprite files, we need to output it to an HTML5 canvas. The idea is to hop through the binary file 16 bytes (1 sprite) at a time and calculate the 8x8 pixels to place on the canvas. The putPixel method handled the mapping for the current palette from color b, 1, 2, 3 to the appropriate RGB.

function NEStoCanvas(byteArray){
    var xpos = 0;
    var ypos = 0;
    // every sprite is 16 bytes
    // 1 byte is 8 pixels 
    // byte n and byte n+8 control the color of that pixel
    //  (0,0) background
    //  (1,0) color 1
    //  (0,1) color 2
    //  (1,1) color 3
    for(var b = 0; b < byteArray.length; b+=16){
        ypos = Math.floor(b/height) * 8
        // draw sprite
        for(var i = 0; i < 8; i++){
            for(var j = 7; j >= 0; j--){
                var mask = 0x1;

                var channel1 = byteArray[b + i];

                var channel2 = byteArray[b + i + 8];

                var color = ((channel1 >>> j) & mask) + (((channel2 >>> j) & mask) << 1)

                putPixel(xpos + (7 - j), ypos + i, palette, mapping[color], imageData);
            }            
        }        
        xpos = (xpos + 8) % width;
    }
    
    paintCanvas();
}

The paintCanvas method is pretty simple, it uses the putImageData api to write color bytes directly to the canvas context.

// On-screen canvas set to be scaled
var canvas = document.getElementById('editor');
var ctx = canvas.getContext('2d');
ctx.imageSmoothingEnabled = false;

var scale = 10;
var width = 128;
var height = 256;

canvas.width = width * scale;
canvas.height = height * scale;

// Off-screen sprite canvas
var spriteCanvas = document.createElement('canvas');
spriteCanvas.width = width;
spriteCanvas.height = height;
var spriteCtx = spriteCanvas.getContext('2d');
spriteCtx.imageSmoothingEnabled = false;

// On-screen image data
var imageData = ctx.getImageData(0, 0, spriteCanvas.width, spriteCanvas.height);
var data = imageData.data;

function paintCanvas(){
    spriteCtx.putImageData(imageData, 0, 0);
    ctx.drawImage(spriteCanvas, 0, 0, width * scale, height * scale);
    if(showGridLines){
        drawSpriteBorderGridLines();
    }
}

Outputing the proper format

Outputting to the binary format was a little trickier. Since I know the correct bit tuples to output in the channel 1 and channel 2 bytes, I decided to do a first pass to convert RGB values of the canvas element to the appropriate tuple (00, 01, 10, 11) using rgbColorTopaletteTuple for writing back to a binary NES file. The second pass does a pretty complicated loop to fill in a new byteArray with the appropriate values.


function canvasToNES(imageData){
    // 16 byte wide sprite with 512 sprites
    var byteArray = new Uint8Array(512 * 16);

    // tuple buffer
    var tupleBuffer = new Array(imageData.width * imageData.height);


    for(var y = 0; y < imageData.height; y++){
        for(var x = 0; x < imageData.width; x++){        
            // extract which color it is from imageData
            var color = getPixel(x, y, imageData);

            // find the pallet color
            var palletTuple = rgbColorTopaletteTuple(color, palette);

            // write it to the tupleBuffer
            tupleBuffer[x + imageData.width * y] = palletTuple
        }
    }
    
    
    // tuple buffer has imageData.width * imageData.heigh pixels, so divide that by 16 for sprites
    var xtotal = 0;
    var ytotal = 0;
    for(var i = 0; i < byteArray.length; i+=8) {
        ytotal = Math.floor(i/height) * 8
        
        
        for(var y = ytotal; y < (ytotal + 8); y++){
            // do each row channel
            var byteChannel1 = 0x00;
            var byteChannel2 = 0x00;

            // complete row calculation
            for(var x = xtotal; x < (xtotal + 8); x++){
                var tup = tupleBuffer[x + y * imageData.width];
                byteChannel1 = (byteChannel1 << 1 | tup[0]);
                byteChannel2 = (byteChannel2 << 1 | tup[1]);
            }
            // write calc'd row channels to appropriate byte locations
            byteArray[i] = byteChannel1;
            byteArray[i+8] = byteChannel2
            i++;
        }

        xtotal = (xtotal + 8) % width;
    }

    return byteArray;
}

The binary content can be downloaded with the neat little trick by dynamically creating an anchor tag and manufacturing a click event to trigger a download (which seems a little spooky 👻, feels like a way to engineer a drive-by-download type attack 😨).

/// Download utilities

function download(filename, byteArray, type) {
    // convert to a blob
    var blob = new Blob([byteArray], {type: type});
    if(type == 'octect/stream'){
        var url = window.URL.createObjectURL(blob);
    } else {
        var url = byteArray;
    }

    var pom = document.createElement('a');
    pom.setAttribute('href', url);
    pom.setAttribute('download', filename);

    if (document.createEvent) {
        var event = document.createEvent('MouseEvents');
        event.initEvent('click', true, true);
        pom.dispatchEvent(event);
    }
    else {
        pom.click();
    }
}

Putting it together

Once the binary file is downloaded, it can be included in NESASM3 with the .incbin directive. Check out the full source of my NES game here. I'll have a post coming soon about more in-depth NES programming until then please watch my talk.


;;;;;;;;;;;;;;  
; Load in external sprite or audio data
  
  .bank 2
  .org $0000
  .incbin "art.chr"   ;includes 8KB graphics file

And voila! We have our own sprites for our brand new Nintendo game.

Repairing an old broken NES

Sun, 26 Feb 2017 00:00:00 +0000

I recently acquired an original Nintendo Entertainment System for an upcoming talk where I show how to develop real NES games in 6502. There was only one problem, the NES was not working and flashing the infamous "Red Blink of Death." In this post I'll walk through the steps I used to restore and repair my NES.

Spelunking inside the NES

First I wanted to see what was wrong, so I opened up the NES for visual inspection to check for any obvious problems. The original NES is surprisingly easy to take apart with a standard Philips head screwdriver (compared to later Nintendo devices with bizarre screws that no one has the wrench for). There are only 6 screws to undo and the top of the Nintendo will come right off.

I wonder if they'll still help me... 😉

Looking inside you'll see the RF shielding which is fairly easy to remove, it's just held on with a couple screws.

I just went through all the other parts and unscrewed everything. Once I did that, you can pull the loader mechanism off fairly easy. The loader mount has the only special long screws in the NES, the rest are interchangeable, remember where they go.

The top side of the PCB board looks pretty good, there is some slight visible corrosion on some of the PPU and CPU pins. For the most part the traces look okay on this side, no burns, no dead capacitors, etc.

The bottom of the PCB (which faces towards to top of the console when it's mounted) is a different story. It looks like there was some sort of liquid spilled into the console, possibly soda, or juice. It looks like it also caused some corrosion as well.

After this discovery, I spent around an hour our so with isopropyl alcohol ~90% (don't worry it's perfectly safe for electronics) and some Q-tips cleaning up the sticky residue on the bottom of the PCB. I went through a lot of Q-tips to get this clean. One downside of this is that the Q-tips began to leave cotton fuzz everywhere that I needed to pull off later, I don't think cotton on the PCB is good for the NES 😉

While I was at it I also cleaned up the PCB 72-pin connector contact as well

TA-DA! A much cleaner PCB, you'll want to let this dry for a bit. (Photo was taken the next day, marked improvement from before)

But after all that cleaning, things still didn't work 😭

Enter the 72-pin connector

Another common thing that can wear out over time is the 72-pin connector that connects the game cartridge to the NES PCB, so I decided to see if I couldn't clean/repair that. There are a lot of people that have had success fixing the "Red Blink of Death" buy cleaning the contacts of corrosion either by rubbing the pins with a cleaner like isopropyl alcohol, or by using the boiling method. However, I didn't have a cooking pot I wanted to sacrifice to mad science, so I went with the pin bending method instead. (I prefer my food not taste like 35 year old electronics! Ack!)

I cleaned the connections as best I could with rubbing alcohol but that had no effect. There is some definite corrosion on the pins highlighted that doesn't show up in the photo. It is difficult to clean this small space, and if I had a science pot I'd be boiling it for 30 minutes.

Let the bending of the pins commence! I used a safety pin and an overhead desk lamp to bend the pins up slightly, this will have the side effect of making the cartridge harder to insert into the mechanism but hopefully that means better contact.

Here you can see the first 6 pins bent upwards, I proceeded to bend the rest of the pins and remounted everything in the NES.

At this point I had assembled and disassembled the NES like 6 times, so I just put things together without screws to see if things worked... and booyah!

Wrapping it up

After all this work, the NES still has about a 50% success rate of booting the cartridge. This is much better than the 0% success rate before I started. You can make it load better doing the "wiggle trick." While the cart is loaded in the NES, wiggle the top of it and repeatedly hit reset until the game boots. I suspect even with the bent pins on the 72-pin connector the corrosion is significant enough to prevent good contact. (If there isn't good contact to the lock-out chip the NES will do the "red blink of death" thinking it's a non-licensed Nintendo cart).

Since I don't want to try boiling electronics in my cookware, I purchased a replacement 72-pin connector on Amazon for $10 which I thought was reasonable. Hopefully, this will increase the success rate to 100% of the time it works 100% of the time 😎 I'll post an update to this as soon as I receive the part.

Update

After installing the replacement connector everything works 100% of the time! The replacement connector grabs more tightly, so it does take a little effort to push carts into the NES. If anyone tries the boiling method let me know!

-Erik

Migrating to Wyam in GH Pages from WordPress

Fri, 17 Feb 2017 00:00:00 +0000

Recently I needed to update my blog WordPress version (yet again), along with patch my server, update my HTTPS certificate, and pay my hosting bill. The amount of admin-istrivia around maintaining your own server and application platform is more than I want to do for a blog going forward. This got me thinking there must be a better way to do this. My friends, @kamranayub in particular, have been pushing me to do more blogging and to move to static site generation. So here goes!

(BTW, this setup is saving me $400 per year on hosting costs!)

Intro Wyam

This leads me to the Wyam static site generator. It is a great little static site generator built in C#/.NET (full framework). If you come from a Markdown/Razor background you'll really find this stuff familiar and easy to use. Wyam is super configurable, fully customizable, and compatible with GitHub pages. Let's dig into it!

Installing Wyam

Installing Wyam is pretty easy, navigate here and follow one of the many ways to install. I used the Windows installer, unfortunately it does not automatically add itself to the path. Fortunately, it is easy to do with the following command once installed:

%LocalAppData%\Wyam\Wyam.Windows add-path

In a new command window you can confirm wyam is in your path:

wyam --help

Building your blog in Wyam

Check out the blog recipe on wyam's site, but honestly it is as easy as running:

mkdir blog
cd blog
wyam new -r Blog

wyam new -r Blog will generate the blog scaffolding in the current directory.

To build your static html files into the output/ directory, run wyam -r Blog -t CleanBlog. This will build the Blog recipe with the CleanBlog theme. You may also just encode these parameters in your config.wyam created at the root then you only need to run wyam in the directory with the config file.

#recipe Blog
#n Wyam.Markdown
#t CleanBlog
Settings[BlogKeys.Title] = "Erik Onarheim";

Top level files in your input directory will show up in your nav bar, notice that they can be a mix of cshtml or markdown! So really some pages that need some more power can use Razor, others just Markdown.

Building a new blog post is as simple as dropping a new markdown file in your input/posts directory and adding the appropriate metadata to the file.


Title: Migrating to Wyam in GH Pages from WordPress
Published: 2/17/2017
Tags: 
 - Static Site
 - Wyam
 - Markdown
 - Razor
 - WordPress
 - GitHub Pages
disqus_identifier: https://erikonarheim.com/posts/using-wyam-blog/
---
Recently I needed to update my blog WordPress version (yet again)...

The default theme is pretty slick, but if you ever want to tweak it, it is as easy as dropping a new file with the same name as the theme. Below I've added a custom _Layout.cshtml, _Footer.cshtml, and more that I copied from Wyam's CleanBlog github and tweaked with my own google analytics and favicon. You'll also notice that you can mix and match Markdown with you Razor cshtml!

Customizing Wyam with Disqus

Wyam comes with a bunch of built-in document metadata which can be used to give the post a title, tags, published date. Custom metadata is also supported as well! Notice the disqus_identifier metadata which I use to add comments into my posts. This particular tag is picked up by my custom _PostFooter.cshtml here, note the @Model.String("disqus_identifier") the rest comes from disqus's embedding documentation.


<div id="disqus_thread"></div>

<script type="text/javascript">
    var disqus_shortname = 'erik-onarheim';
    var disqus_identifier = '@(Model.String("disqus_identifier") ?? Model.FilePath(Keys.RelativeFilePath).FileNameWithoutExtension.FullPath)';
    var disqus_title = '@Model.String(BlogKeys.Title)';
    var disqus_url = '@Context.GetLink(Model, true)';

    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
    
    (function () {
        var s = document.createElement('script'); s.async = true;
        s.type = 'text/javascript';
        s.src = '//' + disqus_shortname + '.disqus.com/count.js';
        (document.getElementsByTagName('HEAD')[0] || document.getElementsByTagName('BODY')[0]).appendChild(s);
    }());
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>

It's pretty much that easy to make changes to the default template to make your own customizations!

Testing Wyam locally with IIS (or just use the easy way)

When I started working on this I tried a number of different of local servers to test this, TLDR: just use wyam preview in the root directory of our blog (above the input folder).

If you want to know the hard way and see how to use IIS in a non-standard directory to run Wyam read on, otherwise skip to the next section :)

I keep a projects directory on my machine where I do most of my development on various projects. Unfortunately IIS does not have the permission to read into directories outside of C:\inetpub\wwwroot by default which is a good default for servers. But if you want to test outside of your web root in your development space it is a problem. To fix this you'll need to set some file ACLs so that IIS can read your files. Give IIS_IUSRS and Users on the local machine Execute, List, and Read.

Next you'll need to solve the problem of the extension-less /posts/name-of-my-post file names that need to be served as if they contained an index.html when they don't.

Versus

In order to fix this Wyam has some azure documentation referencing the rewrite module in azure. IIS does not come with this pre-installed so you'll need to install the module located at the bottom of the page.

Once that is complete you can drop in a web.config in your input directory with the rewrite rule referenced in the Wyam docs and voila!

<?xml version="1.0"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="html">
          <match url="(.*)" />
          <conditions>
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="{R:1}.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Now you can run wyam -w in your root blog directory and it will rebuilt the output when any input changes! The best part is this will be served by IIS that you've just stood up.

Preserve you WordPress old links

If your blog has some good SEO juice, or maybe you just don't want to break older links, you'll want to preserve old links or at least redirect to your new ones. Here is how it is done

Wyam handles these via the Meta-refresh tag on specific pages using the RedirectFrom meta data like so

Title: "Game Development – A Year in Review 2014"
Published: 1/9/2015
Tags:
- News
- Game Dev
- Excalibur
RedirectFrom: blog/game-development-a-year-in-review-2014/index.html

Setting up automatic deployment with AppVeyor and GitHub Pages

AppVeyor is a super powerful CI/CD tool for Windows with free plans for open source. It's pretty much TravisCI for Windows. It's super easy to tie it to your GitHub account and add your repository for building.

Find your GH pages repo and turn it on.

I suggest only building on official pushes and not PR's because it is possible for anyone to craft a malicious PR to output secrets from appveyor. Also I recommend only building when .appvyor.yml files are present to prevent gratuituous error emails in your inbox before repo is ready for prime time.

Wyam has a really nice appveyor.yml file example to follow. One caveat is that GitHub pages for user pages must be built from the master branch.

In order to accomodate this I had to tweak the provied yaml file a little. AppVeyer will only build on my source

branches:
  only:
    - source
    
install:
  - git submodule update --init --recursive
  - mkdir ..\Wyam
  - mkdir ..\output
  # Fetch the latest version of Wyam 
  - "curl -s https://raw.githubusercontent.com/Wyamio/Wyam/master/RELEASE -o ..\\Wyam\\wyamversion.txt"
  - set /P WYAMVERSION=< ..\Wyam\wyamversion.txt
  - echo %WYAMVERSION%
  # Get and unzip the latest version of Wyam
  - ps: Start-FileDownload "https://github.com/Wyamio/Wyam/releases/download/$env:WYAMVERSION/Wyam-$env:WYAMVERSION.zip" -FileName "..\Wyam\Wyam.zip"
  - 7z x ..\Wyam\Wyam.zip -o..\Wyam -r

build_script:
  - ..\Wyam\wyam --output ..\output

on_success:
  # Switch branches to gh-pages, clean the folder, copy everything in from the Wyam output, and commit/push
  # See http://www.appveyor.com/docs/how-to/git-push for more info
  - git config --global credential.helper store
  # EDIT your Git email and name
  - git config --global user.email $env:op_build_user_email
  - git config --global user.name AppVeyor
  - ps: Add-Content "$env:USERPROFILE\.git-credentials" "https://$($env:access_token):x-oauth-basic@github.com`n"
  - git checkout master
  - git rm -rf .
  - xcopy ..\output . /E
  # EDIT the origin of your repository - have to reset it here because AppVeyor pulls from SSH, but GitHub won't accept SSH pushes
  - git remote set-url origin https://github.com/eonarheim/eonarheim.github.io.git
  - git add -A
  - git commit -a -m "Commit from AppVeyor"
  - git push

Also you'll notice my env:access_token this is setup in AppVeyor's encrypted environment variables.

This can be generated by logging into GitHub, and generating a "Personal Access Token", with repo scope.

Now AppVeyor builds commits to my origin source branch automagically! And Voila!

Finished product!

Using CloudFlare CDN for HTTPS and Custom Domains

CloudFlare is super useful (and free) for setting up HTTPS for your GitHub pages, and for the free tier account it is very full featured. If you aren't too squeamish about surrendering your NS (name server) records, it is pretty simple.

Sign up for a free account on cloudflare
CloudFlare can scan the DNS records in your site and let you know if there will be any problems migrating.

Update your name server records to point to CloudFlare's names servers so the can serve up DNS on your behalf. In my case, I use a service called DNSimple.com but you may use GoDaddy or NameCheap as your registrar.

Setup your free SSL certificate by switching the SSL drop down to "full", this can take some time so keep that in mind. The CloudFlare site says up to 24 hours (but from experience it seems to finish in about an hour or so).

Once everything has been provisioned and propagated you'll notice that CloudFlare is serving your domain off of a SAN certificate.

We are done! The new Wyam blog platform is now ready for new posts and is on a more sustainable and secure set of technologies. Hopefully you find this useful, let me know what you think.

-Erik

Game Development – A Year in Review 2014

Fri, 09 Jan 2015 00:00:00 +0000

This year I have really been exploring my passion for game development, and I feel like I’ve learned some useful things that I would like to share. Full disclaimer: this is mostly all unsubstantiated opinions.

I attempted to do the "One Game a Month" challenge (which I recommend to anyone into games or wanting to improve their game making ability). It’s great because it forces you to build a product every month, and even if you don’t succeed you still get great practice. There are always more ideas than there is time, and this is a great way to explore many ideas in a short amount of time. It also prevents you into falling into the trap of the magnum opus idea, where you believe your idea to be more awesome than it actually is. It is so easy to wind up being more concerned about protecting your magnum opus from others than actually finding out if it’s good at all.

I participated in a number of game jams this year including Ludum Dare 29 (Jam), Public Domain Jam, and Ludum Dare 31 (Jam). I think the three biggest lessons I’ve learned from jamming have been how to manage scope, how to brainstorm properly, and prototyping.

Kraken Unchained for Ludum Dare 29

Sleepy Hollow for the Public Domain Jam

Sweep Stacks for Ludum Dare 31

Managing scope, especially when you are really excited about an idea, is hard. It’s easy to want to build the biggest, coolest, and most awesome thing around, but in a game jam you have limited time, resources, and people forcing you to face reality. I think Rami Ismail of Vlambeer fame said it best, "Your scope is too damn big!". As a team working on our LD 29 game, kraken unchained, we definitely learn that we sucked at managing scope. Over the course of this year we have relearned this lesson time and time again. Lately, we have begun to use the phrase minimum viable game to get at the root of a game idea, basically what is the simplest possible version of this game that is still interesting. In Ludum Dare 31, which yielded sweep stacks, we originally had a fantasy theme where the blocks were a marching army heading towards a castle wall, and you controlled a wizard zapping orcs, goblins, and spiders as they approached. Obviously, this really didn’t make the game any more fun than it is right now and we wound up cutting the idea all together since colored blocks were just as fun.

For each of the jams, our group brainstorming process has evolved fairly organically and I feel like the results have been awesome. Basically, our method is throw out and fully explore every idea that everyone puts out until there are no more ideas and everyone agrees on one. This process generally takes approximately 4 hours of intense discussion, and a willingness to not get stuck on a particular idea just because you like it (caveat this process may not scale past a few people). There are so many ideas, and if you stop at the first "good" one, you will miss out on all of those other ideas that might actually be better. In the case of Ludum 31, there were a couple of ideas that I really wanted to do before we got to the ideas that spawned Sweep Stacks. I’d argue that because we continued to brainstorm we arrived at the best game possible, and it turned out to be really fun.

During our last jam, we used a physical prototype for the game that would eventually become Sweep Stacks, and I cannot stress how well it worked for us. Our prototype was basically a checker board and some colored poker chips, then we took turns playing, suggesting new ideas and mechanics, and acting as the "game engine".

Using prototypes is a great way to cheaply test new ideas and mechanics to make sure they are fun, don’t break the game, or have any problems. In our case we spotted one of the biggest problems, which we named the "shaft of doom", basically it is possible to play in such a way that stacks of unclearable blocks rise to the top where the game will end abruptly. This was a huge problem...

Before writing a single line of code, we were able to observe potential problems and come up with solutions, and our solution was the basic “sweep” mechanic that will either let you clear blocks of a single color or the mega "sweep" which clears the entire board at once. Boom! Problems solved before code was written all with a couple of poker chips.

After all of these experiences, I’ve learned so much and gained a lot of respect for the game development community. It is not an easy thing to build a game, let alone offer it up to the masses for criticism. The masses can be very cruel. And in general, I’ve been really impressed with the indie game development community, everyone I have meet and spoken or interacted with has been so supportive and cool. We all are here because of our passions, and that is just so cool. I wish every online community was like this one.

Do I feel like a "real" game developer after this year? yes. Did I just change my twitter bio to reflect that? yup 🙂

Cheers! Erik

Conway’s Game of Life in JavaScript

Tue, 10 Jun 2014 00:00:00 +0000

After stumbling onto a code kata video about Conway’s “Game of Life” I wanted to learn more about it.

TL;DR – Here is the code on github, and here is a running example, click to seed the board and any key to start the simulation.

Once I got to googling I noticed a neat little easter egg in the sides of the page:

Bam! I was inspired to implement the simulation for myself.

The “Game of Life” is a simulation of cellular automatons that demonstrates that complex patterns can emerge from simple rules. Evolution of the simulation is determined by the initial state of the simulation and progresses forward.

The rules that drive the simulation are as follows:

Any live cell with fewer than two live neighbors dies, as if caused by under-population. Any live cell with two or three live neighbors lives on to the next generation. Any live cell with more than three live neighbors dies, as if by overcrowding. Any dead cell with exactly three live neighbors becomes a live cell, as if by reproduction. From Wikipedia

There is a compact notation that is used to describe these rules to the simulation, fore example “B3/S23”. The way to read this is a cell is spontaneously born if it has exactly 3 neighboring cells, “stays lives on if it has 2 or 3 living neighboring cells. In all other cases, the cell dies. There are many people who tweak the rules to bring about interesting variations in the standard game.

So how would you do this in JavaScript?

The first thing to accomplish is to represent a “Cell”.

var Cell = function(x,y, _cells){
        var me = this;

        me.isAlive = false;
        me.x = x;
        me.y = y;
        me.distance = function(cell){
                return Math.abs(cell.x - me.x) + Math.abs(cell.y - me.y);
        };

        me.neighbors = null;        

        me.countNeighbors = function(){
                return me.neighbors.filter(function(cell){
                        return cell.isAlive;
                }).length;
        };

        return me;
};

Cells have an pair of coordinates, an “isAlive” flag, and they also know about their neighbors. Having a reference to their neighbors makes it very simple to interrogate cells and find out whether or not they will survive to the next generation of the simulation.

Once we have the cells figured out, we need some way to arrange and keep track of them. I did this by creating a simple grid structure.

var Grid = function(width, height){
        var me = this;
        var _cells = new Array(width*height);

        var _living = [];

        // instantiate cells
        for(var i = 0; i < width; i++){
                for(var j = 0; j < height; j++){
                        (function(){
                                _cells[i+j*width] = new Cell(i, j, _cells);
                        })();// Self executing function necessary to capture i and j values
                             // For-loops in JavaScript DO NOT create scope which is a bummer                       
                }
        }
        // Continued below...

Here I’m applying a trick to pack a 2D grid into a 1D array. You may also notice the self executing function inside the for-loop, this is to create scope and capture the values of i and j.

Next, we need to assign neighbor references to all the cell, in this example I’m really brute forcing this. There is definitely a more elegant way to do this, but for the purposes of the example I feel this is okay.

       // assign neighbors
        _cells.forEach(function(cell){
                cell.neighbors = _cells.filter(function(cell2){
                        var dx = Math.abs(cell2.x - cell.x);
                        var dy = Math.abs(cell2.y - cell.y);
                        return (dx === 1 && dy === 1 ) || (dx === 1 && dy === 0) || (dx === 0 && dy === 1);
                });
        });

       // Continued below..

The next piece is the implementation of the rules of the simulation. First the cells that die are calculated then the cells that live on and reproduce. This step is made easier by the ability to ask cells about their neighbors directly, no need for complicated array math with “.countNeighbors()”.

        me.updateLiving = function(){

                var deadOvercrowded = _cells.filter(function(cell){
                        return cell.isAlive && (cell.countNeighbors() > 3);
                });

                var deadUnderpop = _cells.filter(function(cell){
                        return cell.isAlive && (cell.countNeighbors() < 2);
                })

                var reproduction = _cells.filter(function(cell){
                        return !cell.isAlive && cell.countNeighbors() === 3;
                });

                var livesOn = _cells.filter(function(cell){
                        return cell.isAlive && (cell.countNeighbors() === 2 || cell.countNeighbors() === 3);
                });

                deadOvercrowded.concat(deadUnderpop).forEach(function(cell){
                        cell.isAlive = false;
                });

                reproduction.forEach(function(cell){
                        cell.isAlive = true;
                });
                livesOn.forEach(function(cell){
                        cell.isAlive = true;
                });

        };

        //Helpers
        me.filter = function(fcn){
                return _cells.filter(fcn);
        };

        me.getCell = function(x,y){
                return _cells[x+y*width];
        };

        return me;
};

Now with the simulation “engine” and data structures out of the way, we can work on the drawing aspect. With the HTML5 canvas we can accomplish some pretty cool stuff. Here is the basic boiler plate we need before we can get started.

var App = function(targetElementId, squaresX, squaresY){
        var me = this;
        // Grab the canvas and drawing context
        me.canvas = document.getElementById(targetElementId);
        me.ctx = me.canvas.getContext("2d");

        // Grab the start button
        me.button = document.getElementById("start");

        // Initialize page styles
        var body = document.getElementsByTagName('body')[0];
        body.style.margin = '0px';
        body.style.overflow = "hidden";

        // Set height and width to window inner height to make the app 'fullscreen'
        var viewWidth = me.canvas.width = window.innerWidth;
        var viewHeight = me.canvas.height = window.innerHeight;

        squaresX = squaresX || 20;
        squaresY = squaresY || 20;

        // Calculate the height and width of each cell
        var _squareWidth = me.canvas.width/squaresX;
        var _squareHeight = _squareWidth;

        // Initialize our Grid data structure from above
        var grid = new Grid(squaresX, squaresY);

        // Continued below

The user is going to want to setup the initial state of the simulation to they can play around, so we are going to setup event handlers for starting and stopping the simulation as well as handlers for clicking. To start and stop we will response with any keypress to make things simple, and mouse click and drag with lay down intial state.

        // Handle Click events
        var _mouseDown = false;
        var handleClick = function(event){
                var x = event.pageX - me.canvas.offsetLeft;
                var y = event.pageY - me.canvas.offsetTop;

                var i = Math.floor(x/_squareWidth);
                var j = Math.floor(y/_squareHeight);

                grid.getCell(i, j).isAlive = true;
                return;
        };

        var _startSim = false;

        window.onkeydown = function(ev){
                _startSim = !_startSim;
        };

        window.onresize = function(ev){
                viewWidth = me.canvas.width = window.innerWidth;//viewWidth || 600;
                  viewHeight = me.canvas.height = window.innerHeight;//viewHeight || 600;
        };

        me.canvas.addEventListener('mousedown', function(event){
                _mouseDown = true;
                handleClick(event);
                me.canvas.addEventListener('mousemove', handleClick);
        });

        me.canvas.addEventListener('mouseup', function(event){
                _mouseDown = false;
                me.canvas.removeEventListener('mousemove', handleClick);
        });
        // Continued below...

Now for the fun part, drawing and updating

        // Here is our start responsible for kicking off our mainloop 
        me.start = function(){
                setInterval(function(){
                        me.update();
                        me.draw();
                }, 60); // Mainloop set to refresh every ~60 milliseconds

        };

        // Update is responsible for updating all state in the app
        me.update = function(){
                if(_startSim){
                        grid.updateLiving();        
                }
        };

        // Draw is responsible for drawing the entire app
        me.draw = function(){
                // Erase previous draw by filling the entire canvas with white
                me.ctx.fillStyle = 'white';
                me.ctx.fillRect(0,0,me.canvas.width,me.canvas.height);

                // Draw living squares first
                grid.filter(function(cell){
                        return cell.isAlive;
                }).forEach(function(cell){
                        me.ctx.fillStyle = 'black';
                        me.ctx.fillRect(cell.x * _squareWidth, cell.y * _squareHeight, _squareWidth, _squareHeight);
                });

                // Draw grid

                // First draw vertical lines
                me.ctx.fillStyle = 'gray';
                for(var x = 0; x <= viewWidth; x+=_squareWidth){
                        me.ctx.beginPath();
                        me.ctx.moveTo(x, 0);
                        me.ctx.lineTo(x, viewHeight);
                        me.ctx.stroke();
                };

                // Second draw horizontal lines
                for(var y = 0; y <= viewHeight; y+= _squareHeight){
                        me.ctx.beginPath();
                        me.ctx.moveTo(0, y);
                        me.ctx.lineTo(viewWidth, y);
                        me.ctx.stroke();        
                };
        };

        return me;
};

To kick off the whole thing, all you need to do is the following

var app = new App("game", 100, 50);
app.start();

Check out the code on github, and here is a running example on the web.

Happy games!

Cheers, Erik

Erik Onarheim

2024 The Best Worst Year

My Darling Daughter

Family in Norway

NDC Oslo 2024

NDC Oslo 2025

Death

2D Con

Sweepstacks

Sum Monsters

Jelly Jumper

Distance Running

IGDATC (International Game Developers Association Twin Cities)

Excalibur

Caliburn Games

C Programming

Neovim & RSI

Optimism, Dreams, and Schemes

Animating with Coroutines

What is a coroutine anyway?

Implementing Animations with requestAnimationFrame

MoveTo Generator with Linear Interpolation

Concurrency with Coroutines

Wrapping Sequences with Coroutines

Handling Height in Isometric Tile Maps

Isometric Math

Calculating Screen Position

Selecting Tile width and height based on assets

Drawing isometric tiles

Multiple isometric tiles at different "elevation"

Solution: Sort entity draw by z-index

Excalibur v0.25.2 Released!

Dev Tools

Tiled Updates

Renderer Performance Improvements

Post Processing

Renderer Improvements

Renderer Design

Image Filtering

Custom Renderer Plugins

Community

The Future

Fixing WebGL Tile Map Seams

The Problem

Some Specifics

Solution 1 - Shared Tile Edge (best for tile maps)

Shared Edge Solution in action

Solution 2 - Bodge the UV coordinates near 1.0

Quick note on other texture related issues

UV Bodge In action

Solution 3 - Avoid Unnecessary Floating Point Manipulation

3.1 Unnecessary geometry scaling for HiDPI

3.2 - Keep geometry in local coordinates for as long as possible

3.3 - Pixel snap

3.4 - Position your camera in ideal locations

Solution 0.5: "Nudge" pixels to screen (Useful for Ad-Hoc Drawing Systems)

Quick note

Nudge code

"Nudge" solution in action

Wrapping up

Excalibur v0.25.0 Released!

Performance

Plugin Strategy Going Forward

DisplayMode Updates

Refactor to Entity Component System (ECS) Based Architecture

Collision System Improvements

New Graphics System

TileMap and Tiled updates

Documentation

Testing

Templates

Samples

Community

Breaking Changes

Next on the horizon looking towards "v1"

Bookmarklets - Automating Websites

Bookmarklets

Structure of the bookmarklet

YouTube playlist managment (at the time of writing this)

Building Bookmarklets with Webpack

Implementing Animations with `requestAnimationFrame`

The `metrics.width` Is A Lie