dale.io

Rustris Postmortem: Making Tetris with ggez

Sat, 08 Jul 2017 00:00:00 -0400

You know what game I love? Tetris. An easy game to play but difficult to master that’s been released on every platform under the sun. The game has had a strong following for over 30 years and it’s still going strong. For my next Rust-based game project, I decided to make my own version of Tetris with basic gameplay features, a menu screen and game ending states. After a month of working on it sporadically, I managed to get the project into a state I’m okay with releasing into the wild (The source code is available on GitHub or GitLab). Here are some of my thoughts on challenges faced & choices made during development.

Goals

The main goal of this project was to learn how to create Tetris in Rust. It was not to learn how to make a game engine in Rust. If I had wanted to do that, I would have started with something like SDL2 and worked off of that.

Making Good Games Easily

After spending some time earlier playing around with the Lua-based love2d game framework, picking a Rust framework influenced by love2d seems like the obvious path to take. ggez fits the bill here, providing easy ways to draw to the screen, play audio, access the filesystem, render text, handling input and deal with timing. It doesn’t aim to provide every feature one can want in a game engine such as entity-component systems or math functions; this functionality can be provided by already-existing crates. Instead, the focus is on being easy to get up and running, and to be productive quickly without having to think about lower level operations. Just like the name of the framework says!

Personally, I found ggez quite pleasant and easy to work with. Much of ggez revolves around the EventHandler trait. This trait contains required callbacks that must be implemented (update(), draw()) as well as a bunch of optional input-related callbacks. From there, a developer has free reign to do whatever they please.

As an example, this is what my GameEndState struct looks like:

pub struct GameEndState {
    request_replay: bool,
    request_menu: bool,
    request_quit: bool,
    options: Vec<Option>,
    current_selection: usize,

    game_end_text: graphics::Text,
    final_score_text: graphics::Text,
    final_line_text: graphics::Text,
    final_level_text: graphics::Text,
}

The input system in Rustris is state-based instead of event-based so for smaller states such as the game over screen, I store a bool for each potential input response from a user¹. In the state’s update() method, I check whether any of these switches have flipped and act accordingly. Options were abstracted into an Option struct, so I store a vector of those as well as the currently selected option. Finally, when the GameEndState is created, so are any graphics::Text objects that are required to display some information on screen. These are stored in the state and drawn to the buffer every frame.

The simplicity of ggez’s API allowed me to just focus on making the game. Each state contained what it needed to do its job and that’s it. Whenever I found myself repeating code across states, I’d lift that code into a module containing code shared between states. For example, my Option struct which is used across multiple states (MenuState, GameEndState), is in shared module. It feels very simple and clean as well as easy to extend later on.

Bumps in the Road

Once work on the main ‘play field’ state was finished and plans for the menu state began, I had noticed a couple of limitations:

I had created a Transition enum listing potential transitions between states within a state manager. I wanted to have both update() and draw() return said Transition² so a state’s update() method can request state changes but the ggez EventHandler trait is hardcoded to return an empty tuple.
What if I wanted to create an Assets object that held all my assets that lived at the top-level of my object hierarchy? This way, a reference to that object can be passed to any active states that may need access to an image, or a sound.
If Transition was defined in my code, how would EventHandler even know about it? This is when I first jumped into the ggez event module source code in attempts to make the return type generic. This ended a rabbit hole filled with Boxes and eventually, failure.

Thankfully, ggez is written in a clean and modular way - no spaghetti here. I was able to simply make my own copy of the event module and make my needed changes. I think ideally, there would be a way to define return types from EventHandlerfrom the framework user’s end but for now, this will do. The problem of passing Assets seems like a harder one to solve. I don’t believe Rust currently has the option to call functions with a variable number of arguments or optional arguments. For now, editing the event module will work as a solution.

Other stuff

Another issue I had actually has to do with one of ggez’s dependencies. rodio, created by master crate creator tomaka. Currently, it doesn’t have a way to stop any audio that is being played. There is a PR ready to be merged into implement this, and then ggez simply needs to offer a high-level interface to stop audio³. This isn’t a huge deal, but it will be nice to have this functionality when it is finally implemented.

The design for both the Assets struct and Transitions enum were shamelessly inspired by the Rust-based Amethyst game engine, another excellent project. It has tons of great ideas and I’m excited to start playing around with it in the future on larger projects.

I implemented a state manager inspired by the “Pushdown Automata” discussed in the “State” chapter of the excellent Game Programming Patterns. I believe that Amethyst also uses a similar pattern which makes sense if my Transition enum, used to transition between game states, was inspired by Amethyst’s Trans enum. With a state stack, all one needs to do to add a ‘pause state’ or ‘inventory’ screen’ is to push that state on the stack when needed and pop it off when done.

I’m not an artist nor a musician, so I had to rely on open source and freely licensed assets. All the audio and sound effects were found online and some of the assets I made, such as the black hole graphic on the menu and the background of the play field. It’s not the best looking or sounding game in the world but for what was an educational non-commercial product, I think it did the job.

Final Thoughts

Tetris is a fun game to write in Rust. I don’t think that my code is some kind of incredible work of art, a standard that other code should be judged against (if anything, it’s probably the opposite) but I had lots of fun and I learned quite a bit about making games, making games in Rust and Rust itself. That was my goal, so mission accomplished! You can check out the source code on GitHub or GitLab. I don’t have access to a Windows or Mac right now so I unfortunately cannot produce any binaries to distribute this at the moment.

ggez is a great framework to use for small 2D games. I was able to talk with Icefox, one of the library authors, at the Game Development in Rust meetup in Toronto on July 7th 2017. He’s a nice & smart guy and after watching him talk about the future of ggez during his presentation of the framework, I have 100% confidence that it will continue to grow into a ~~fine young lad~~ great framework to use to make good games easily.

For states with more input such as my PlayState, I threw all the potential state bool into its own struct - makes the code easier to read, in my opinion. ↩
Wrapped in ggez’s custom Result type, GameResult. ↩
Yes. Just “simply” implement it. You know, easy! ↩

Automated Publishing Pipeline with Org Mode

Sun, 12 Mar 2017 00:00:00 -0500

I have some files written in Org that I want to publish & upload to a web server every week at a set time. Why? I’d like to be able to view my notes from anywhere, and others may stumble upon them and find them useful. However, I don’t want to have to remember to publish & upload everytime I make change to these files, and I want this to occur with as little user interaction as possible.

To accomplish this, I’m going to make use of Emacs Batch Mode. Batch Mode will run Emacs in a non-interactive fashion; you feed it a file or an Elisp function to run, Emacs does its work and then exits without displaying a window. ox-twbs is an Emacs package I’ll be using to export my Org files to Bootstrap-themed HTML.

The project I want to set up will be a couple of files that will act as a log of the things I have accomplished each week, goals for the next week and any associated notes or links I’d like to record. I’m going to create a directory for this project at ~/org/log and create a couple of files: index.org will just contain a link to our second file, 2017.org. 2017.org will contain a descending-order list of the weeks of the year with associated notes using the following structure:

* Week 11 (March 13 2017)
** Recap
** Next Week
* Week 10 (March 6 2017)
** Recap
** Next Week

By default, Org mode will create a full table of contents for the page, complete with the headlines being numbered. I’d like to avoid this: I only want to see up to the second level headlines in the table of contents and nothing below. Additionally, I don’t want the headlines to be numbered.

Thankfully, I can easily specify all of these settings in one place by defining a project in Org mode. By defining a project, we can easily generate HTML for our project with one command: (org-publish-project "PROJECT_NAME"). A variable called org-publish-project-alist is used to define any number of Org projects one may have.

The first thing I want to do is create a new Elisp file that will be used to import needed packages, define any required variables, and run the necessary function to build the site. Since I use Spacemacs (which has a fairly high amount of modules to load), the only modules I want to load are the bare minimum required to get Org running so Emacs can do its business. Inside ~/.emacs.d/, I create a new file called org-export.el with the following contents:

(package-initialize)
(require 'org)
(require 'ox)
(require 'ox-publish)

(setq user-full-name "Dale Karp")
(setq user-mail-address "dale@dale.io")

(setq org-publish-project-alist
      '(("my_log"
        :base-directory "~/org/log/"
        :publishing-directory "~/projects/site/log"
        :publishing-function org-twbs-publish-to-html
        :section-numbers nil
        :table-of-contents 2)))


(org-mode)
(org-publish-project "my_log")

First, I import some packages and set some variable such as who the author will be (me!). Next, the Org project gets defined within org-publish-project-alist.

I define a single project called “my_log” with some options. Some of these are self-explanatory: :base-directory tells Org where to look for the files - any .org file in this folder will be processed. Since I’ll be publishing this to a subsection of my website, I’ve set the :publishing-directory to the right location. Because I’m using ox-twbs to generate our HTML, I need to tell Org to use it when publishing instead of the built-in HTML exporter. Finally, I let Org know that I don’t want any sections to have numbers, and that I only want our table of contents to have links for level 2 headlines and above.

Now that our publishing pipeline is ready, I need to set up the ‘automation’ part. I host my site on GitHub Pages, so all I need to do to build my site is to create a new Git commit in my site repository after publishing, and pushing that commit to GitHub. To do all of this, I’ll write a Shell script! Because I’ll be a systemd timer to run this script at a set interval once a week, I need to set up a few things like retrieving SSH keys for the session so I can push to GitHub without being prompted for a pssword.

#!/bin/sh

# load ssh keys from keychain for this session
eval $(keychain --eval --quiet --noask id_rsa)

# call & run our exporter elisp script
emacs --batch -l ~/.emacs.d/orgexport.el

# change directory to our repo
cd ~/projects/site

# commit latest changes
git commit -am "Log for: $(date)"

# push commit to get built on gh pages
git push

With the script written, the last thing to do is to use a scheduler to run it every week. I’m using systemd’s timers to do this, but cron should work as well. I created two files in ~./config/systemd/user with the following contents:

# mylog-org-export.service
[Unit]
Description=Exports Org project "My_Log" and pushes Git to GH Pages

[Service]
ExecStart=/home/dale/.bin/org_upload.sh

# mylog-org-export.timer
[Unit]
Description=Run mylog-org-export.service every Monday at midnight.

[Timer]
OnCalendar=weekly
Persistent=true
Unit=mylog-org-export.service

[Install]
WantedBy=timers.target

Now I can test to make sure our timer works and once verified, enable it:

systemctl --user start mylog-org-export.service
systemctl --user enable mylog-org-export.timer

Verify that the timer is active with systemctl --user list-timers, and we’re good to go!

At this point, I have an automated Org publishing pipeline that will convert our Org files to HTML once a week and then push the new data to GitHub pages to built. This approach can be customized fairly easily to publish anything from project documentation to a personal blog. If you have any suggestions on how to improve this or have any alternative methods, please let me know!

A Rusty Venture: Writing a text adventure in Rust

Mon, 07 Nov 2016 00:00:00 -0500

After a couple of months of playing around with Rust, I’ve finished a project! It’s a simple text adventure game in the vein of class text adventure Zork called Adventure!. The feature set isn’t as wide as Zork; there is no combat and movement & world interaction is pretty simple. I was never really into text adventures myself, but I though that it would make an interesting & fun first project with Rust.

Design

I wanted to write a game containing of a few rooms, with a few things to do in each room. The feature set wouldn’t go past picking up objects, adding them to an inventory, and using inventory objects with static objects in the world. I didn’t want to involve combat on NPCs as I didn’t want to work on this project for the long-term; it’s a toy project for learning a bit about how Rust works.

Changing Rooms

My first design involved having Room structs that would contain a member connection: Connection. This Connection struct would itself have 4 members: north, south, east and west. The value of these members was to be an Option<Box<Room>>. The main Game object that ran the whole show would have a current_room reference that points to whatever instance of Room the user was in.

Unfortunately, this design gave me trouble with the borrow checker. I got many cannot moved out of borrowed context errors thrown at me. At the time, I didn’t really fully understand how the borrow checker works - and honestly, I’m pretty sure I still don’t understand fully. I decided to take a simpler approach: I’d store current_room as an integer representing an index in the vector of rooms. In Rust, the index of a vector is the type usize, a pointer-sized (therefore system-dependent) unsigned int. At first, I stored current_room as an i32 but this led to lots of as usize casting all over the place. Connection objects would be Option<usize> and changing rooms would be as simple as replacing current_room with another usize value.

The downside of this approach is having to know each Room’s index in the vector ahead of time. I kept track of the room number while designing the game ‘map’ so it wasn’t a big deal in my particular situation. I thought being able to ‘point’ to other Room directly with a reference would be simpler, but that would bring its own problems with it. For example, this would bring about circular references (eg: Room 1 is connected to Room B, but if we create Room 1 first, how do we define this relationship when creating the Room object? My solution: You wouldn’t, you’d connect the rooms afterwards).

Flags & Actions

My next set of problems came with dealing with state change in the game. I ended up declaring a HashMap<&'static str, bool> in a struct Flags at the top-level of the game that gets passed around to the different functions. Originally, each Room was going to have its own set of flags but I didn’t want have to reach across rooms to check the state of something - especially if an action in one room can have consequenes elsewhere.

Dealing with the actions took the longest to figure out. I had an important questions I needed to answer at this point: How can I define each Item or Room to have different behaviour depending on the state of global flags? To solve this, I used closures. For instance, here is how an Item is defined:

struct Item {
    name: String,
    is_grabbable: bool,
    on_grab: Box<Fn(&mut Flags)>,
    on_use: Box<Fn(&mut Flags, String, usize) -> bool>,
}

Both on_grab and on_use accept closures. Because our state is stored in a global object, each room doesn’t really need to worry about what’s going on in other rooms - they only need to know the state of the world through the Flag objects they receive. This allows me to use closures to define certain behaviour.

I’m not exactly sure if this method is idiomatic Rust. I’ve been writing primarily JavaScript for my day job for the past few years so I’m still in that state of mind where functions are first class citizens that I should be taking advtange of. I wasn’t really sure how else to define individual behaviour for separate instances of the same type.¹

For instance, this is an example of how an Item is defined:

Item {
    name: "shovel".to_string(),
    is_grabbable: true,
    on_grab: Box::new(|flags: &mut Flags| {
        println!("The shovel looks as if it has never been used before; the layer of dust that falls off as you pick it up shows that it has been sitting on that table for a long time. You slip the shovel in your pocket.");
        flags.update_key("pickedUpShovel", true);
    }),
    on_use: Box::new(|flags: &mut Flags, object_name: String, current_room: usize| -> bool {
        // this sucks; checking if we are in the room before perfoming action
        if current_room == 1 && object_name == "glass door" {
            if flags.get_key("smashedDoor") == Some(&false) {
                println!("It takes a few swings before a couple of cracks appear in the glass. Wondering why such strong glass is needed for a greenhouse door, you continue to swing away until a loud crash and gust of fresh air announces the success of your swinging endeavours.");
                flags.update_key("smashedDoor", true);
                false
            }
            else {
                println!("You seem to have already done a number on that poor door - maybe you should leave it alone?");
                false
            }
        }
        else {
            println!("You aren't sure how to use the shovel with the {}", object_name);
            false
        }
    }),
}

… and that’s just one item! Imagine a whole Room, with it’s own behaviour and items! (Or see for yourself and check out the source file with the levels defined).

Another issue is that this method leads to cases where certain objects that don’t use a specific callback have empty closures, which makes rustc complain about unused variables. This isn’t a huge deal, but it can clutter up compiler messages which is slightly annoying.

Originally, I planned on serializing each room into data files instead of hard coding them into Rust source code. This way, anyone can write their own text adventure without knowing a line of Rust! As soon as I decided to use closures, however, that task seemed like it would be much more difficult. How do you serialize behaviour? The only method I can think of is via a scripting language, and that was way out of scope for this project.

Other random notes

It would be nice if there was a way to initialize a HashMap by passing a series of key/values to its new() function or via a literal. I’m using a macro I found on StackOverflow to do the job right now but it would be neat if this was built into the standard library.

Conclusion: I like it.

In the process of writing this post, I’ve had to question a few of my design choices and actually learned new stuff (the idea of changing the type of current_room from i32 to usize happened due to this post)!

The likelihood of me continuing to work on this project is low. Howevever, if I were to make an ‘Adventure! 2.0’, I’d make the following changes:

Spice things up with Termion. I came across this great blog post by the author of the termion crate, ticki. Maybe making some item names show up in Zelda’s “Important Noun” red, or having more of a persistant GUI on screen such as the inventory.
Take advantage of more core Rust/Cargo tools, like rustdoc.
Tests! Testing is important. I worked on this project for a few hours a week over the span of a month so it wasn’t something at the top of my mind.
Figure out cross-compilation so I can build executables for Windows & MacOS from my Linux desktop

I had fun working on Adventure. If you’d like to check it out, here is the GitHub repo. I’d like to figure out cross-compilation soon to get some binaries up on on the GitHub page. My next project will involve gasp graphics! Until then…

As I write this, a few ideas come to mind (although I’m not sure if they actually work). Perhaps creating a trait that all Rooms/Items implement, and write a macro that creates a new struct with said trait with the individual behaviour defined within? Just a thought. ↩

A Boilerplate for WebGL Projects

Thu, 10 Dec 2015 12:00:00 -0500

2015/12/12: Added source map support

Between Grunt, Gulp, Webpack and Broccoli, it seems like a new build tool/asset pipeline/module bundler/etc arrives in the land of JavaScript every few months. While learning WebGL, I started to look into ways to make starting a new project and development a bit easier. I’ve been using Webpack for work-related purposes over the past few months and I’ve really grown to like its easy-to-read config files, async code splitting abilities and wide plugin ecosystem. “Since it helped make my React-based development smooth as butter,” I thought to myself, “perhaps using Webpack would help to make WebGL development go just as smoothly.”

This post follows the steps and rationale used to build a Webpack-based boilerplate for WebGL. If you just want to look at the code, you can grab the source here.

Getting Started

For this build system, all you need to start with is Node.js + npm. We will use Webpack as our module loader/build tool combo. Another invaluable tool in our arsenal will be Babel library for allowing use of ES6+ features. This guide assumes you have basic familiarity with JavaScript and using npm to install modules.

We will start off by installing Webpack globally. I like doing this so I can just use webpack on the command line from anywhere:

$ npm install -g webpack

Webpack is a tool used to bundle files into modules. It has a vast variety of plugins created by both the Webpack team and community to allow modules to be created using both JavaScript and non-JavaScript files. You can even use it in conjunction with tools like Grunt or Gulp! We will be making use of Webpack to transpile our ES6 code to something modern browsers can read with Babel, a plugin that allow us to write our GLSL shader code like you would for a desktop application, and finally bundle all our code into a single (or multiple) JavaScript files.

Let’s create a new directory called webgl_project:

$ mkdir webgl_project
$ cd webgl_project

We will be saving a list of libraries and tools we need to package.json so let’s create one first:

$ npm init -y

Using the -y flag uses default values; we will edit these shortly. Personally, I’d rather edit these fields in a text editor rather than input them into a prompt.

Next, we will install our dependencies required for development, including:

webpack: The webpack documentation recommends saving webpack as a local dev. dependency
webpack-dev-server: Used to watch files & recompile on changes, servers files
babel-core: Compiler used to make our ES6 code usable in modern browsers
babel-preset-es2015: Since version 6, Babel comes with no settings out of the box. This is a preset to compile ES6.
babel-loader: Webpack plugin to transpile JavaScript files before creating modules out of them
html-webpack-plugin: A plugin used to auto-generate a HTML file with all webpack modules included.
webpack-glsl-loader: Webpack plugins to load our shaders from files into strings

Let’s install these modules all at once:

$ npm install webpack webpack-dev-server babel-core babel-reset-es2015 babel-loader html-webpack-plugin webpack-glsl-loader --save-dev

At this point, I usually like to open package.json and start making some edits. This is what I end up with:

{
  "name": "webgl-webpack-boilerplate",
  "version": "1.0.0",
  "private": true,
  "description": "a boilerplate webpack project for getting started with WebGL.",
  "scripts": {},
  "author": "Dale Karp <dale@dale.io> (http://dale.io)",
  "license": "CC-BY-4.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/obsoke/webgl-webpack-boilerplate"
  },
  "devDependencies": {
    "babel-core": "^6.1.19",
    "babel-loader": "^6.1.0",
    "babel-preset-es2015": "^6.1.18",
    "html-webpack-plugin": "^1.7.0",
    "webpack": "^1.12.4",
    "webpack-dev-server": "^1.12.1",
    "webpack-glsl-loader": "^1.0.1"
  }
}

We’ll come back to this file to add some commands to use to the scripts key. For now, let’s hop back to the terminal.

Project Structure

I wanted the file structure for an intial project to be simple:

.
├── package.json # lists dependencies for easy re-install
├── src
│   ├── index.html # html to use as template for generated output html
│   ├── js
│   │   └── main.js # entry point for our application
│   └── shaders
│       └── ... # glsl files go here
└── node_modules/ # folder containing our dependencies

This structure can be created with mkdir & touch commands.

Now that we have a clear idea of what files are going to be a part of the project, let’s get a Git repository going and set up a .gitignore file:

$ git init
$ touch .gitignore

Open up .gitignore up and enter the following:

node_modules
dist

Since the contents of these two folders are generated, we shouldn’t commit them to version control.

With that out the way, let us continue by setting up Webpack.

Webpack Configuration

Webpack can be configured a few different ways: with its own configuration files, via the command line with flags, or as a module in Gulp/Grunt. We’ll be using the config file route. Create a file in the root of your project directory called webpack.config.js. Input the following:

var path = require('path');
var HtmlWebpackPlugin = require('html-webpack-plugin');

var ROOT_PATH = path.resolve(__dirname);
var ENTRY_PATH = path.resolve(ROOT_PATH, 'src/js/main.js');
var SRC_PATH = path.resolve(ROOT_PATH, 'src');
var JS_PATH = path.resolve(ROOT_PATH, 'src/js');
var TEMPLATE_PATH = path.resolve(ROOT_PATH, 'src/index.html');
var SHADER_PATH = path.resolve(ROOT_PATH, 'src/shaders');
var BUILD_PATH = path.resolve(ROOT_PATH, 'dist');

var debug = process.env.NODE_ENV !== 'production';

module.exports = {
    entry: ENTRY_PATH,
    plugins: [
        new HtmlWebpackPlugin({
            title: 'WebGL Project Boilerplate',
            template: TEMPLATE_PATH,
            inject: 'body'
        })
    ],
    output: {
        path: BUILD_PATH,
        filename: 'bundle.js'
    },
    resolve: {
        root: [JS_PATH, SRC_PATH]
    },
    module: {
        loaders: [
            {
                test: /\.js$/,
                include: JS_PATH,
                exclude: /(node_modules|bower_components)/,
                loader: 'babel',
                query: {
                    cacheDirectory: true,
                    presets: ['es2015']
                }
            },
            {
                test: /\.glsl$/,
                include: SHADER_PATH,
                loader: 'webpack-glsl'
            }
        ]
    },
    debug: debug,
    devtool: debug ? 'eval-source-map' : 'source-map'
};

Let’s take a look at what’s going on here:

File header

Firstly, we import some modules such as path and our html-webpack-plugin. We also define some constants containing the absolute paths to the folders we wil keep various types of files in, along with the entry and output paths.

We also check for the presence of the environmental variable NODE_ENV to determine whether to build production or development bundles.

`entry`

The JavaScript entry point of our application.

`plugins`

The html-webpack-plugin generates HTML files that already have appropriate script and link tags to bundled JS and CSS bundles. We’ll make use of that plugin with a few options. title is the value of the title tag. template is a path to the HTML file we want to base our index.html off of. Finally, inject allows us to control where our script tags are being created. Valid values are body and head. We will set up our HTML template after configuring Webpack.

`output`

Here we define where we want Webpack to place the modules it creates.

`resolve`

resolve’s root key lets you tell Webpack which folders to search in when importing one file into another. For example, imagine the following file structure:

.
├── js
│   ├── Component
│   │   └── Dude.js
│   ├── main.js
│   └── Utility
│       └── VectorUtils.js
└── shaders

The contents of js/utility/VectorUtils.js look something like this:

export function getDotProduct(v1, v2) {
    // gets & returns dot product
}

Without setting the resolve.root property in our Webpack settings, the way to include VectorUtils.js in Dude.js would look something like this:

import { getDotProduct } from '../VectorUtils.js';

export default class Dude extends Person {
    // use getDotProduct somewhere in here
}

After setting resolve.root to include our src/js path, we can treat that as a root directory that Webpack will search through to find other modules. This lets us write import paths like this:

import { getDotProduct } from 'Utility/VectorUtils.js';

export default class Dude extends Person {
    // use getDotProduct somewhere in here
}

Since we’ve also added src as a root path, we’ll be able to include shaders just by writing something like this:

import boxShader from 'Shaders/boxShader_v.glsl';

This makes importing files easy, no matter what directory you happen to be working in.

`module`

The loader key on module tells Webpack which files to load into modules, and how to load them. We’ve defined two loaders: one for JavaScript files, and one for our GLSL shaders. test is a regular expression that will bundle the files that match it; obviously for a JavaScript loader, we want Webpack to find modules ending with .js. We don’t want Webpack to do anything with our dependencies unless we explicitly import one, so we tell Webpack to exclude them. The loader key is the name of the Webpack plugin used to process JS files. Since we want to be able to write using ES6 syntax, Babel will handle that responsibility. Because Babel 6 comes with no options out of the box, we need to tell it to use the es2015 presets package we installed earlier. Enabling directory caching will give us faster compile times so of course we enable that.

Our last loader is for our shader files, ending with .glsl. Here, we simply tell Webpack to use the webpack-glsl loader.

`debug`

Some loaders will perform optimizations when building bundles depending on whether the debug key is set to true or false.

`devtool`

At the moment, this tells Webpack which style of source maps to use. source-map is recommended for production use only, so we’ll use eval-source-map which is faster and produces cache-able source maps.

With that, our configuration of Webpack is complete. Not too bad, eh?

Let’s re-open package.json and add some commands to scripts that will make interacting with webpack a bit easier:

{
    // ...
    "scripts": {
        "build": "NODE_ENV=production webpack --progress --colors",
        "watch": "webpack --progress --colors --watch",
        "dev-server": "webpack-dev-server --progress --colors --inline --hot"
    },
    // ...
}

Webpack will check for webpack.config.js and use it if found. I’m using flags to show build progress and to give the output a bit more colour. Any key added to the scripts object can be used by running npm run <keyname>. This gives us three easily accessible commands:

NODE_ENV=production npm run build: Builds our project into /dist/. Uses a flag to tell Webpack we want loaders to build production-mode modules.
npm run watch: Builds our project and watches files for changes, re-builds on change.
npm run dev-server: Builds our project and watches files for changes, also serves files from a web server. The --inline --hot flags enable Hot Module replacement, which will update your page without any user input. You can read more about HMR in webpack-dev-server’s documentation.

Now we have one thing left to do, and that is to create our index.html in /dist. This is what the contents look like:

<!doctype html>
<html lang="en">
    <head>
        <meta http-equiv="Content-type" content="text/html; charset=utf-8"/>
        <title>{%= o.htmlWebpackPlugin.options.title %}</title>
    </head>
    <body>
        <canvas id="canvas"></canvas>
    </body>
</html>

That weird value used in the title tag allows Webpack to change the page’s title depending on the value of the title key passed to html-webpack-plugin. As you can see, no script tags are needed - Webpack will handle that for us.

And with that, the boilerplate is complete. “But Dale,” you exclaim, “I don’t see the point of this. You made a simple Webpack config, so what?”

Motivations

My main motivations behind this came from my own experiences trying to learn WebGL. I’ve noticed that many WebGL tutorials will demonstrate shader usage in WebGL in one of two ways:

Write a JavaScript string containing the shader code.
Have a script element of type x-ver-shader and grab the element’s content from JavaScript.

Personally, I don’t like either of these solutions. The first one is just ugly, unreadable and difficult to maintain yet most of the WebGL resources I see introduce shaders using this method. The second is slightly better, but I prefer to keep shaders in their own files, where I can use an editor with syntax highlighting to make readability a bit easier.

I completely understand why tutorial writers do this. WebGL is complex, and wrapping your head around everything needed to render a simple triangle in shader-based GL can be a lot to take in at once. Once you get your head around those concepts, though, then what? What’s the best way to deal with shaders moving forward as a project scales? I’m not claiming this boilerplate is anywhere close to the best, but for me it works. Hopefully it does for you too (and if it doesn’t, please open an issue/PR on the GitHub repo and let me know).

Mini-example: Hello Triangle

Let’s go through a short example of how one would potentially use this boilerplate to easily load GLSL shaders. Imagine we have two shaders in our src/shaders directory, called box_vert.glsl and box_frag.glsl containing our vertex and fragment shader, respectively. No need for <script> tags or multi-line strings! Just import it when you need it, where you need it.

// import our shaders and store them variables
import boxVertShaderSource from 'shaders/box_vert.glsl';
import boxFragShaderSource from 'shaders/box_frag.glsl';

const canvas = document.getElementById('canvas');
const gl = canvas.getContext('experimental-webgl');

// ...

// time to create our shader program with a handy function!
// it expects the gl context and strings containing shaders.
let program = createProgramFromGLSL(gl, boxVertShaderSource, boxFragShaderSource);

That’s all!

I hope you found this useful in some way. If you have any suggestions on how to improve the boilerplate, please open an issue on the GitHub repo.

dale.io v4

Sun, 31 May 2015 21:30:00 -0400

I recently decided that my personal site needed a tune up. No longer happy with the current design, I decided to throw it away completely and to start from scratch. Here are a few things I thought about during the process of re-writing the website.

Choosing a backend

Right off the bat, I knew that I wanted to continue using a static site generator for my homepage. Tools like WordPress and Ghost are interesting but for my use case I found both to be overkill. After taking a look at some of the most popular static site generators¹ around and playing around with them, I had a better idea of the current tool landscape at the time.

There are a bunch of static site generators these days written in a variety of languages. I took a look at a few JavaScript-based ones, such as Hexo and Metalsmith - both on opposite sides of the feature list spectrum. Metalsmith is completely barebones to the point where all functionality is added via plugins. This is a pretty neat idea but I was looking for something that was more balanced between features and do-it-yourself mentality. When I was initially researching static site generators, Metalsmith had a lot of issues with plugin version rot as well. The idea of everything being a plugin is pretty neat - as long as these individual plugins are maintained! On the other end of the feature spectrum, Hexo reminds me a lot of Jekyll but written in JavaScript and more of an emphasis on blogs. This wasn’t enough to pull me away from Jekyll, a tool I already knew.

On the Ruby end, I took a look at Middleman and Jekyll. Middleman is a great competitor for Jekyll with some neat features. It allows for incremental building of your site, a feature that Jekyll will be lacking until its v3 release. I have not had much of an issue with build times with Jekyll but I can see how a huge site with thousands of pages would not scale well without incremental builds. Middleman also offers more in the way of a default template and such. However, in the end I stuck with Jekyll. Recent additions to Jekyll such as collections make building non-blog and hybrid websites with Jekyll much easier.

Choosing a colour palette

I am not a designer - I think the previous designs of my site show as much. As much as I wish I did, I just don’t have the eye for colour. Working with designers in the past always blew my mind as to how easy it came to them. I know I could take the time to learn colour theory (and perhaps I will someday) but at the time I was more focused on redesigning my site quickly, not leisurely learning something new. This made the simple task of choosing a colour palette a long and tedious process. There are a few tools available to help one come up with a colour palette, such as Paletton or Adobe Color CC, formerly Kuler. After fiddling for them for a few days on and off and having no success, I decided just to choose a colour I liked: blue. Once I had a colour chosen for the header, I was able to build the rest of the site off of that.

While I’m pleased with how the header turned out, I still feel as if the rest of the site can possibly use a splash of colour here or there just to make things a bit more appealing. I couldn’t really see any place to fit these accent colours in a way that felt natural. This will probably be something that will to be iterated on over time.

The Holy Grail that is Flexbox

Flexbox is the best thing to happen to CSS. I’ll scream it from the mountain tops if needed because it’s true. As long as the only browsers your site needs to support are IE11+ or an evergreen browser, you can (mostly²) say goodbye to hacky CSS rules to position elements on a web page.

The great thing about Flexbox is that it’s flexible (yet another surprise!) and will adjust its size across different screen sizes if the developer desires it. For example, the page header makes use of flexbox to make sure it looks great on both large and small screens. All I need to do to get my header to scale the way I wish is use the following CSS rules on the wrapper for my header block:

.nav-wrapper {
    display: flex;
    justify-content: center;
    align-items: center;
}

This sets the wrapper rendering box style to flexbox and centers all the elements along both axis. When the screen width is below a certain size, we can use the following rules to change the direction of the main axis from a row to a reversed column so each header element has room to breath and appears in the proper order:

@media screen only and (max-width: 600px) {
    .nav-wrapper {
        flex-direction: column-reverse;
        align-items: stretch;
    }
}

I’m using a few more rules to align individual items, but that is the basics of it. Flexbox has enabled me to re-arrange the entire site with just a few CSS rules and I think that is awesome. I’m using it for any part of my page that requires even a tiny bit of element positioning and it’s been very easy to both learn and use. Offloading a lot of the grunt work to the browser while providing a fewer set of CSS rules was definitely a smart move, and I’m excited to see what further revisions to the spec bring.

Consistency between old and new

In the redesign, I decided to make better use of header tags to denote subheading rather than bolded text. Unfortunately, a few of my older blog posts made liberal use of the old and bold way. I took this opportunity to flex my bash and regex muscles and see if I can come up with an elegant way to fix this in one swing.

My first step was to construct a regular expression that would find all the old headers. The old headers took the form of bold text which, in Markdown, meant the text was surrounded by two asterisks on each end. The header would be the only string of text on the line. With this information, I came up with the following regular expression and used it to find all headers in my _posts folder:

git grep '^\*\*.*\*\*$'

This regular expression looks for any length of characters in between two literal asterisks that bookend the entire line. After testing that the regex worked, I used a combination of the find and sed commands to do a massive search and replace with the following command:

find _posts -type f -exec sed -i '' 's/^\*\*\(.*\)\*\*$/\#\#\# \1/g' {} \;

The above command looks for files in the _post directory, and for each file runs a sed command asking it to edit files in-place without a backup³. The regular expression now creates a group around the header text so we can use it in the replace with the proper symbol denoting an h3 tag: three literal pound characters. Now all blog posts with headers will conform to the new style.

Design & organization choices

Aside from choosing site colours, I spent the most time thinking about how I wanted to layout my website. My previous v3 design was bland and didn’t make the best use of available space. I spent a lot of time looking at other Jekyll blogs for some inspiration but I found many of them to be overly busy or overly minimalistic. I would draw layout after layout on paper until I came to the one you see now. Moving the persistent navigation block from the side to the top allows me to take advantage of all the below space: this comes in handy when scaling the site to work on multiple resolutions.

Since the beginning of 2015, I’ve been writing reviews on the games I have finished for fun. After deciding to add these reviews to the site. As of the launch of the redesign, only one of the eight reviews I have written are published but I’ll be editing the others and getting them online shortly. Right now, they are a separate entity from the other blog posts and I’m not sure if this was the best idea. This home page is a place for me to talk about what I love doing. For the past few years, this has solely been about programming. I’d like to expand that to writing about other subjects but dividing posts up into ‘blogs’ and ‘reviews’ may limit myself in the future. I could (and probably will) just treat everything as a blog and use tags or categories to group the related info. Design choices like this are what I spent the most time on during this redesign. Implementing the ideas I come up with are no problem but deciding whether I’m making the right choice on certain decisions is an area where working on a team definitely benefits.

There are a bunch of other small but useful additions I’ve made. If you haven’t noticed, I tend to go off on tangent mid-paragraph. Making use of footnotes allows me to do this without breaking up the flow of content, and the Kramdown markdown renderer used by Jekykll makes usage of footnotes very easy. Some posts can have a header image, such as this one. If you’re reading this on a small device, you may not see it - I’m currently thinking of a good way to display the header image without making all of the above-the-fold content on a mobile device nothing but headers. Most of the small additions are there to make writing content easier for me and for said content to display correctly, no matter the screen scale.

In the end

I’m pretty happy with the layout I ended up with. I find easier on the eyes than previous designs. Standing here with the project finished, I already have a list of things I’m no longer happy with and will work on for the next iteration. Personal projects like home page redesigns give me an opportunity to experiment and play but if I don’t limit myself and consider the project ‘finished’, I’ll never release it. Do you have any suggestions about the design? Love it? Hate it? Let me know in the comments!

According to StaticGen which ranks generators based off of GitHub stars and forks. ↩
While much better than the old way of doing things, Flexbox itself is not perfect. Check out Flexbugs for more info. ↩
Not recommended. ↩

Jump Around

Fri, 27 Feb 2015 18:30:00 -0500

A few months ago, I wrote a blog post about my experience playing around with the Phaser game engine. I ended up making a short 2D platformer game called Jump Around. I’ve uploaded the source onto GitHub for those who are interested in taking a peek. It was a great experience in which I learnt quite a bit, so without further ado…

Initial Design & Scope

My initial goals for the project were pretty simple:

Make a short 2D platformer game.
Each level would fit on the screen; no camera work needed.
Don’t focus too much on making the ‘cleanest’ code possible on this project. This is more getting a feel for game development again.

I wanted to keep things pretty simple, as this project was meant to not only evaluate Phaser for future projects but also getting my feet wet with some simple game design. It seems almost like a rite of passage nowadays for game developers to make a 2D platformer, so I decided to go for that. Jump Around is inspired by platformers such as Super Meat Boy, where the emphasis is on pixel-perfect platforming as quickly as possible. The smaller levels in Super Meat Boy that would fit within the initial camera frame were always pretty interesting to me. The small characters moving quickly around an environment in which danger is visible everywhere made for a strange mix of emotions. Upon entering a level, I’d both feel terror at the level that I was to get through, and excitement at the challenge ahead.

I originally scoped for around 6 levels, but I cut it down to 3 as I came to a realization: good level design is hard work! Once the game mechanics were implemented, the majority of my time was spent on figuring out how to be clever with level design. This wasn’t my goal for the project so I decided to cut the level count in half so I could move on to another project sooner. Aside from that, I feel like I did a good job with my initial design and didn’t end up with much feature creep. The only feature I ended up missing was using “Jump Around” by House of Pain as the obvious background music choice. I planned on distributing the source code for this and I’m pretty sure I would not have the rights to distribute that song. This is an issue I also had to look into regarding art I used (gasp, could this be… a segue?!).

Art is hard

Although I have tried many times, I just can’t draw very well. This can be a problem when you are a lone programmer working on a video game. Thankfully, there are tons of free art resources online. One of these is the great website Open Game Art. I ended up purchasing a donation-ware art pack from an incredibly talented & generous artist named Kenney. I’ve seen him post on /r/gamedev before, offering free art packs under liberal license terms for people like me who aren’t so artistically inclined. While this was a decent solution to not being able to produce art myself, in retrospect I think I should have kept it simple and gone with a more abstract art style.

As said before, I eventually wanted to release the source of Jump Around. However, I wasn’t too sure about the license to redistribute the assets. Thankfully, Kenney includes a LICENSE.TXT in his zip of art which helpfully states that the assets are released under the liberal CC0 license. As long as I attribute him, I should be okay to redistribute the art I used and modified for my purposes.

Most of the audio I use is also from Kenney’s donation pack, but the incredibly ~~cheezy~~ awesome end of level noise that plays was a clip I found off of freesound.org. This is another great resource for developers just looking for simple or placeholder sounds under a variety of licenses. Thankfully, this asset is also CC0 so the game can be fully redistributed with all assets intact.

Resolution is confusing

Another issue I ran into was answering the question “What resolution am I targeting with this game?” I was making this game for web browsers running on a desktop. I probably should have consulted the great Valve Hardware Survey to get a sense of what kind of resolutions people were playing at. While 1920x1080 is the most popular resolution, it only had 33.48% of user share as of this blog post. In second place was 1366x768 with 26.80%. I ended up hardcoding my game’s resolution at a very strange and non-standard 1050x714. I did this because that was the size of my level in tiles (50x24 tiles, as each tile was 21x21). In retrospect, this was a dumb idea. While I haven’t exactly alienated either of the two largest resolution groups (according to Valve), it doesn’t scale up or down at all. I probably should have spent more time on making sure the scaling worked; at one point in development, I found myself even looking at options to use the fullscreen API. In the end, I decided to push that learning exercise to my next project.

Another consideration was “Could this game work on a mobile device?” Due to the decisions I made based on the art and not bothering to scale anything, it wouldn’t be a great experience. However, mechanically, it could work. I ended up adding a toggle to cause the player to continuously jump, and I noticed the game was actually kind of fun when I left it on. It felt more like “Pogo Around” than “Jump Around” but it was still fun. I could have left that setting on for the mobile version and had the user touch either side of the screen to simulate the left/right cursor movements. Using two fingers instead of one could make the player run… or… pogo-run… rather than pogo-walk. In the future, I may revisit this project and try to add that in, but for now it was out of scope of what I wanted to accomplish.

If you’re interested in trying this ‘pogo’ mode for yourself, just hit the F key while playing the game. It adds another layer of challenge… think of it as hard mode!

Architecture & Tools

At first, I wasn’t really sure how to structure this project. I’ve done game development before but never in JavaScript. I found a very useful blog post called Building your Phaser Projects with Browserify that was helpful in getting the file structure of a game in place.

Since the majority of my game objects were simple, I was able to make to do with simple objects that didn’t follow any particular programming pattern. Some variables, such as current level and overall game time, were kept in the game object, while each state kind of dealt with it’s own area. After the assets are preloaded, the menu state is spun up and waits for user input. After that, the level state is entered. The level state checks what level it should be loading via the game object and starts to create the needed platforms and tiles.

The levels themselves were created using the fantastic Tiled map editor. One neat feature of Tiled that I liked was creating Objects on the map that can store any properties you wish. I ended up doing this to store quite a bit of data in the level itself, such as player spawn position, level key position, and starting positions of moving platforms, as well as their speed, distance and initial direction. This allows me to use a single state for each level with little to no code change needed to properly load each level. I feel like I do cheat a bit by passing the player object through each level state to retain some data like how many times the player has died, but it seemed like the simplest solution so I went with it.

Phaser is a pretty nice framework but I ran into some issues. Currently only a single tile layer from Tiled can be marked as a collision layer. When Phaser moved from version 1 to 2, it lost some of it’s advanced camera capabilities such as the ability to zoom; I believe the current camera can only pan by default. Neither of these are dealbreakers, but they would be nice to have features. I still think Phaser is one of the best JS engines you can use right now. It has a decent sized community and there are always people on the IRC channel willing to help (such as myself!) I’ve read that Phaser 3 may be getting a ES6 makeover which makes me very excited for the future of the engine.

However…

Conclusions

I had a blast making Jump Around, and I’m glad I finished the project. I learnt quite a bit about a variety of topics. I now have a huge amount of respect for great level designers, as I spent quite a bit of time thinking of how to make each level progressively more interesting. I’m not sure if I’ve succeeded but I tried to do something new in each level. I also learnt a bit about 2D animation to animate the player, audio codecs & conversion to get the sound effects working, and some basic game design as a result of the project.

One area that I didn’t get to focus on as much as I would have liked was the game programming itself. I think this is because I used an engine which did a lot of it for me. Because of this, my next project will most likely not use an engine at all. I don’t want to do everything myself (not yet at least) so I’ll probably use a helper library to handle things like asset loading, input reading and window creation (if targeting desktops rather than the web). I plan on reading some of the excellent Game Programming Patterns book to get a better feel on how game architecture works and how things fit together.

So that’s Jump Around! Feel free to try the game out and check out the source if you’re interested.

Giffy: A Postmortem

Wed, 31 Dec 2014 12:05:00 -0500

I’ve recently finished up a small side project that I started quite a while ago called Giffy. It wasn’t a particularly large or complex project but the motivation to continue working on it diminished shortly after starting. Now that the project is done, I wanted to write a post discussing some of the challenges I faced and thoughts I had.

On Side Projects

Working on a side project is a great way for any developer to learn about a new technology, further develop an existing skill or just get some creative juices flowing. However, I’ve found it much easier to start a project than to actually finish one. There can be many reasons why finishing a side project can be hard. For Giffy, those reasons were feature creep, scope and changing personal thoughts on images on the web. While side projects can be a great place to experiment, too much experimenting led to a feature list that was much too long. This can be mentally draining when done close to the beginning of a project. I wouldn’t recommend it. I’ve learned a lot about looking at a feature and breaking it down into smaller features. Working in smaller chunks makes it easier for me to focus on the current objective and to experience the thrill of seeing a feature come to life more frequently.

What is Giffy?

Giffy is simply an image hosting service for gifs. You can tag gifs that has been uploaded, and find similarly tagged gifs. If you don’t have any gifs to upload, you can create one in the browser using your webcam. Once you’ve created your gif, you have the option to upload it directly to Giffy.

Some features, such as adding & deleting tags, require an account. One of the features I ended up cutting was a permissions system that would let the admin define roles and associated permitted & forbidden actions (eg: upload a gif, delete a tag). Bits and pieces of the permissions system exist in the code, but it was never finished.

There were a bunch of social-networky features I cut from the feature list. I had to step back and remember what my goals were for this project:

Learn more about Angular
Learn how to upload images directly to an Amazon S3 bucket from the browser via CORS
Learn how to create a gif from a webcam using WebRTC and upload that gif directly to S3

Here on the other side of the project, I feel that I’ve completed these goals. Learning not only how to cut unnecessary fat from the feature list, but also how to divide my main tasks into smaller, more manageable sub tasks was important to keep me going towards the finish line. Focusing on the important features to cut can be hard in a project that exists solely for learning and experimenting, but for some people it may be necessary if that project is ever going to see the light of day.

The Backend

There is not a whole lot of magic happening on the backend. All it is really doing is serving HTTP requests and fetching data from the database. I’m using the Bookshelf ORM to handle all things database, backed by Postgres. It’s a pretty nice ORM that makes mapping models to database tables incredibly easy. While I found that it lacked some basic features such as limiting the amount of rows returned, it’s possible to use the underlying Knex.js library to perform raw SQL queries. Other libraries I use are bcrypt for password salting, shortid to generate a unique file name for gifs and Amazon’s AWS library for Node.js

In terms of design, I make heavy use of promises instead of callbacks in my API code. Promises are very easy to use and, in my opinion, make ones code much more readable (goodbye, callback hell).

One design choice I regret is choosing session-based authentication over token-based. The way I originally designed the application was a standalone API that would be able to handle requests by clients on any kind of device. I ended up with more of a Rails-type monolithic app so cookie-based sessions were pretty easy to implement. From my limited understanding, cookie-based authentication doesn’t work very well on mobile devices. A much simpler solution would be to include a token that identifies the user with each request. Ah well, lesson learned for my next side project!

Angular

It really bothers me that I need to use a plugin for a framework just to do something as simple as nested views. I feel like a framework that focuses on building single-page apps like Angular should have this built in. Perhaps I’m being nit-picky but it’s a design choice I find baffling. Also, the way Angular differentiates services, factories and providers is a little strange and seems arbitrary.

Aside from those points, using Angular has been mostly painless and made developing the web app portion of Giffy easy. I don’t think I was pushing the limits of the framework or anything. Most of the challenges I faced came with getting sessions to work between Angular and Express, or routing static assets; nothing specific to Angular compared to other single-page app frameworks.

In the end, I was mostly pleased with Angular, and would consider it in future projects.

EDIT (2015-01-17): After some consideration, I’m not too sure if I would actually use Angular for another personal project. I’m not a huge fan of how Angular 2 is looking.

Direct to S3 Upload

One feature I really wanted in Giffy was the ability to upload a file directly to an Amazon S3 bucket directly from the browser. I wanted the API behind Giffy to solely handle requests and to fetch the appropriate data from the database. I found an article on Heroku’s dev centre on the subject, which makes use of Amazon’s AWS library for Node.js. The library is used to create the proper signature for the upload request, which contains information like where in the bucket to put the file, expected file size, and authentication to the bucket. Once the image is successfully uploaded, a call to the API is made to register the newly uploaded gif in the Giffy database.

The Heroku article also included a link to a client-side S3 uploading script. I quickly ran into some limits with the script though, such as not getting as much metadata as I would have liked about the file with the upload completion callback, or not supporting the ability to upload a binary image blob to S3. I ended up forking the repo and made the necessary adjustments, which you can find here.

While this solution is novel, I kind of regret designing it this way. This has to due with how I now feel about gifs in general. Gifs can cause unnecessary repaints in some browsers, which can greatly affect performance. For Giffy, where I could potentially have a page full of gifs, I was worried that performance on some older desktop and laptops or mobile devices would suffer.

There have been some interesting ways of solving this problem. For instance, Twitter converts gifs to mp4 and shows users the video file instead. I thought this was a pretty neat solution. Not only will a mp4 file be much smaller than the average gif, but the user also gets control over the playback of the image. This is most likely the solution I would have chosen for Giffy as well. However, since Giffy uploads the image directly to S3, it wasn’t feasible for this iteration of the project. If I decide to return to the project, it would be the first thing I would change.

Create gif from webcam

The final feature I wanted to implement was the ability to use one’s own webcam to create a gif. When I was working as a contractor for Mozilla Webmaker last year, this was an idea the frontend team played around with for the Webmaker Profiles feature. I thought it was fun and decided to implement it into Giffy.

My implementation is pretty simple. The creation of gifs is done by capturing frames via button click. I found a gif encoder written in JavaScript that I use to create the gifs. When one clicks the `Capture` button, the current frame displayed in the video tag is copied pixel by pixel to a canvas. The image data stored in the canvas is used by gif.js to create one frame of the gif. gif.js uses web workers to create the gif in the background, leaving the interface responsive.

For one crazy second, I actually considered writing my own gif encoder in JavaScript. It would have been an interesting project, but way out of the scope for Giffy. Other things I would have liked to add would have been some tacky Instagramish filters and the ability to record a gif for N seconds, rather than having to add each frame manually.

Final Thoughts

Some other features that were cut from the list were allowing users to add gifs to a favourites list, unit tests, and allowing user comments. The ability to search by tag was another feature I cut. In retrospect, none of these features would be particularly difficult to implement at this point but you have to draw the line somewhere on some personal projects or they will never end. There are other potential projects that I am currently more interested in spending my time on.

I learned quite a bit from working on Giffy. Aside from the numerous technical and design lessons I learned, the lessons about scope and feature creep are what really hit me: breaking big features up into smaller ones and setting attainable milestones that end with some feature that can be demonstrated in at least a small fashion. Working on Giffy one huge feature at a time made it feel like a chore, but now that it’s finally over, the satisfaction of putting the ‘Complete’ label on a project makes it all feel worth it. Kinda weird how that happens.

Feel free to check out the source code on my GitHub repo. A demo of Giffy is also available. I’ll be writing a cron script to clean out the database & S3 bucket every few days. Please don’t abuse the demo site! Feel free to fork, open pull requests, or leave feedback!

Playtime with Phaser

Fri, 21 Nov 2014 07:30:00 -0500

For the past few days, I’ve been playing around with Phaser, a game engine written in JavaScript. I decided that I’d like to experiment with game development for the next month. It has been a career path I’ve considered on and off throughout my life, but I need to put the idea to the test: do I actually want to make games, or do I just find the thought of doing it appealing? Let’s find out!

Struggle of Inaction

A lot of new game developers (including myself) seem to fall into a trap. Do you want to make a game, or do you want to learn how to program games through engines? My problem was that I was obsessed with the idea that I had to start out learning how it all worked from the lowest level. “If I use an engine,” I would think to myself, “and it limited my grand ambitious game, whatever would I do?!” I would then attempt to learn OpenGL, get frustrated trying to tie everything together into something that resembles a game and give up.

The fear of using an engine without fully understanding how games work was a huge concern, although I don’t know why. I don’t understand how my car works but that doesn’t stop me from using it. I think I was partially making excuses to justify the Not Invented Here Syndrome I was experiencing. If I really want to make games, an engine is probably the best place to start. When I run into issues due to gaps in my knowledge, I’ll just fill those gaps in as I need to.

Select your Engines

With a renewed sense of resolve, I now had to choose a language and engine to work in. I decided that my first project would be a simple platforming-style game so heavy engines like Unreal or CryEngine seemed a bit over-the-top. Unity is another very popular engine with indie and hobbyist developers, and has the ability to export your game to a variety of platforms. In the end, I felt forced into using their GUI app to get stuff done. I’m just not a big fan of using mice!

It had been a few years since I last looked at JavaScript game engines. Back then, audio on the web wasn’t well-supported. The Web Audio API is now here but still doesn’t have full browser support (looking at you, IE). Regardless, I feel like JavaScript speed increases, audio API improvements and the growth of the JS game development community has made this a good time to try out writing a game in JavaScript.

There are quite a few mature JS game engines around, such as MelonJS, ImpactJS, and Phaser. I ended up choosing Phaser for a few reasons:

The Website looked good (Hey, what can I say, this actually matters to me)
Excellent examples site and documentation. These two were fairly important in my final decision. The examples site contains many (you guessed it) examples of different ways to implement everything from animation via spritesheets, using the camera, music and more. I’m a learn-by-example kind of person, so this was perfect for me. The documentation is pretty great, and the source code itself is well commented and easy to understand.
Price & license. ImpactJS costs $99USD for a license. While you receive the source code with your download, you can’t contribute upstream from what I understand. Both MelonJS and Phaser are open source under the MIT license. I’d prefer to use an open source engine if I could, as I’d like to contribute any bug fixes I may come across with the engine itself.
Built-in support for levels created with Tiled, a tile-based map editor. This wasn’t a huge deal but it is nice to have.

Both Phaser and MelonJS seemed equally capable. I found more questions asked on StackOverflow on Phaser (287 vs MelonJS’s 47 as of this post). While questions on StackOverflow isn’t the greatest metric to judge an engine on, I just wanted to make a quick choice and this shallow justification did the job.

Initial thoughts & issues

Now that I had my engine chosen, it was time to get started. This is where I encountered my first roadblock: I had no art. I needed some tilesets and character sprites to start off with. Luckily, there are plenty of freely licensed artwork packs available for those of us who are not artistically inclined. One such pack, Platformer Art Complete is a huge pack of tiles, items, character sprites and more made by an awesome dude named Kenney.

After creating a small simple level with a few platforms, I loaded it into the engine and noticed that some platform tiles were not the ones I selected to use in Tiled. The initial spritesheet included in the pack that I was using had some excess art on the right margin. Spritesheets work by providing the size of each frame in the sheet, and the amount of rows and columns of frames. So if Tile N is on row 3, column 3 of the sheet, and each frame is 50 pixels square, then by grabbing the subsection of the image at x 100, y 100 should get us the desired frame. However, while Tiled was smart enough to remove the excess tiles from the spritesheet, there is no way Phaser could possibly know that; it just knows how big each frame is and the amount of frames per row and column. I found a version of Kenney’s platformer base pack that was made to work with Tiled. After using this, my problems went away. When I attempt to create my own art, I’ll be able to specify how the spritesheet is layed out. Until then, be mindful of your art!

After ensuring the level was being rendering correctly, I added a simple character with basic move left/right controls. So far, so good. I decided to test out the camera functions by creating a level larger than the canvas/game viewport of 1280x720. For some reason, this caused my player sprite to get caught on some invisible walls. I did some research and found this thread with some else describing a similar issue. Luckily enough, a Phaser developer chimmed in stating that he found the cause and that it had been fixed in the dev branch. Thankfully, using the dev version of Phaser seemed to fix it.

So far, I’m pretty happy with Phaser. Just getting things happening on a screen and reacting to input is pretty awesome. Hopefully I’ll have something to show off in my next post!

Back to Blogging, Back to Game Dev

Fri, 27 Sep 2013 10:58:00 -0400

It’s been a few months since I’ve last written a post here on the blog. I’ve been working with Mozilla on the Webmaker project since school ended. Not only have I been having lots of fun doing a ton of front-end work but I’ve also been learning from the brilliant people on my team. Working at Mozilla has been and continues to be an awesome experience but that’s not what this blog post is about.

Once again, I’ve gotten the game development itch. When I think back on the past few years, I realize that the itch never went away but school took a priority. Additionally, my RSI was so bad that I couldn’t really afford to use my hands for anything but programming assignments. Since then, my hands have significantly improved. I’m now able to work full work weeks and also do programming and gaming on the side. As things have been going so well, it seems like a good time to scratch the game development itch.

As usual, I spent quite a bit of time agonizing over what language and technologies to dedicate my efforts towards. In the last year, I’ve worked a lot with C++ (with WebVTT in Firefox) and JavaScript (with Webmaker). I have had prior game development experience in C++ (SFML) and C# (XNA). I also understand that Unity is a popular choice for those who want to start designing a game right away. After careful thought, I realized that designing a game right away is the exact opposite of what I want to do. Perhaps I’m being stubborn, but the desire to learn how games actually work is far greater than the desire to started working on a game right away. I’m also interested in the demoscene, which creates audio/visual demos of… well, anything. Just do a YouTube search for ‘demoscene’ to see what I am talking about.

Actually, while writing that last paragraph, I believe I thought of why I want to learn how games (and graphics) work. There is a lot of room to be creative through programming. The cool graphics or games one can create with code is proof of that. Right now, I have all these cool ideas in my head for potential demos and games. The problem is I have very little technical knowledge on how to get those ideas onto the screen. So it’s time to remedy that! The languages and technologies I’ve decided to go with are GLFW to create the window creation, OpenGL for graphics and… that is it for now. I’ll be working on a 2D tetris clone, and I’ll be blogging about it as I go. I figure that is a good project to start with. My first goal will be to draw a box on the screen. Once I learn exactly how to do that, I’ll be back with another post!

WebVTT: The Middle

Fri, 19 Apr 2013 11:30:00 -0400

It’s been a while since my last post about WebVTT. A lot has been going on since that last post in the beginning of March. The OSD team gave two presentations about WebVTT to Mozilla Toronto: one during a class visit to MoTo and another during MoTo’s Open Web Open Mic event to some of the Toronto open source community. Both events were a lot of fun! I was surprised by how excited some people seemed to get when they saw WebVTT. When you work on a project, it can be hard to take a step back and see the impact your project has on others, especially when you can get so invested in said project. Good job team!

I haven’t been able to spend as much time on WebVTT as I would have liked over the past month. After the push to get things working for the first Mozilla Toronto demo, I had an avalanche of final assignments fall onto me. Now that they are finally behind me, I’ve been able to get back into the swing of things.

Review Issues

While I’ve been busy with school, rillian has been working on the patch. Thanks a lot, rillian! There have been several iterations of the patch since. As always, you can see the latest updates on the Bugzilla bug. It’s been reviewed quite extensively by bz and Ms2ger who brought up a few issues.

One of the issues had to do with nested templates. We were using nsTArrays like this: nsTArray<nsRefPtr<TextTrackCue>>, which reads as ‘an array of nsRefPtr which refer to TextTrackCue objects.’ Apparently, the >> at the very end was being interpreted as the >> operator on some older compilers. So we just added some whitespace to pad out the characters: nsTArray< nsRefPtr<TextTrackCue> >. Easy fix!

In the review, it was suggested that we convert nsAString out parameters in class getters to DOMString, a relatively new class in the Mozilla codebase. I went ahead and did this, but it was not an easy fix. In fact, it was pretty messy, and involved extracting a StringBuffer from an nsAString object and using that to set the value of the DOMString out parameter.

The code used to set getters went from this:

void GetKind(nsAString& aKind) const
{
  aKind = mKind;
}

to this:

void GetKind(DOMString& aKind) const
{
  aKind.SetStringBuffer( nsStringBuffer::FromString(mKind), mKind.Length() );
}

Yikes. That’s what I call messy. To be fair, this is the only way to set the value of a DOMString from an nsString, the type used internally to store strings.

It didn’t get accepted. In retrospect, it would have been easier to just adjust the internal members of the TextTrack* objects to use a DOMString rather than a nsString. Once I clarify with others that this is the best way to go about with this fix, I’ll probably end up doing just that.

The first fix ended up making its way into the patch on Bugzilla. The pull request on GitHub is still open due to the DOMString issue. If you’re interested in following that particular issue, you can check it out here.

Exceptions

Something I’ve wanted to start adding to the WebVTT DOM implementation for a while now is exception handling. Firefox’s C++ code doesn’t use exceptions; I’m talking about JavaScript exceptions. For instance, if one tries to use the removeCue(cue) method on a TextTrackList JavaScript object which doesn’t contain cue, a NotFoundError exception should be thrown.

In order to do this, we first need to edit the WebIDL file which defines the DOM interface. We must add a [Throws] declaration in front of every method which throws an exception. For example, in TextTrack.webidl:

[Throws]
void addCue(TextTrackCue cue);
[Throws]
void removeCue(TextTrackCue cue);

By using some crazy wizardry, this creates the necessary DOM bindings to use exceptions. More specifically, it passes an ErrorResult& as the last argument to our method. We can use this object to throw exceptions.

Let’s take a look at TextTrack::RemoveCue and how we can throw an exception if the cue passed as an argument is not already in the internal TextTrackList.

In our header file:

void RemoveCue(TextTrackCue& aCue,
               ErrorResult& aRv);

In the implementation file:

TextTrack::RemoveCue(TextTrackCue& aCue,
                     ErrorResult& aRv)
{
  // If the given cue is not currently listed in the
  // method's TextTrack object's text track's text
  // track list of cues, then throw a NotFoundError
  // exception and abort these steps.
  if( DoesContainCue(aCue) == false ) {
    aRv.Throw(NS_ERROR_DOM_NOT_FOUND_ERR);
    return;
  }
  // Remove cue from the method's TextTrack object's text track's text track
  // list of cues.
  mCueList->RemoveCue(aCue);
}

The generated bindings make it very easy to throw an exception. Now that an ErrorResult& is being passed to our method, we simply call Throw on the object and pass the error. One could search on MXR for the particular error macro/constant they need; luckily, bz told me which to use in #content.

Initially, I was a bit confused when trying to implement exceptions. While looking through MXR to see examples of how other classes implemented exceptions, I’d often see ErrorResult initialized as a local variable within a method. Apparently, this is only used for methods that catch exceptions. Methods that throw exceptions do it through an ErrorResult& argument passed in by the generated binding methods. Oh, you Mozilla engineers. You guys/gals are magic.

That particular pull request is still open at the time of writing. You can check out that pull request here.

“1.0”

I’m really not sure if this release can be considered a 1.0 release. The code still hasn’t landed in Firefox (although it seems close). There are still things to do! Some of those things include: maintaining and using TextTracks.activeCueList, finish implementing exceptions on the rest of the TextTrack* classes, and fix all of the issues raised in the reviews done by bz and Ms2ger. Concurrently, I believe we are at the point where we can start using the MochiTests written by Marcuus and Jordan to bring other issues to light.

A big issue is the ever-shifting nature of the WebVTT spec. It seems like every week, the spec changes - and not always for the better. For instance, there are now a list of rules associated with every TextTrack that defines how the text tracks should be rendered. Also, TextTrackCue is an abstract class from which we should be creating a new object: WebVTTCue. Not all these changes make sense to me (Rules for updating cues? Why?) but I guess that is a part of the age-old rift between spec writers and implementers.

Between the spec being in flux and the other items still on my to do list, there is still quite a bit to be done before I’d be comfortable slapping the ol’ 1.0 tag on. Now that school is officially complete forever, I should have much more time to spend on WebVTT.

The Middle

Speaking of school being officially done forever, this is my last official ‘for school’ post on my blog. This isn’t the end though, not by a longshot. I’ll be continuing my work on WebVTT as a volunteer. I’m excited to see what happens with the project in the coming few months!

Thanks to Humph for teaching the OSD classes to begin with. If you are a student at Seneca in CPA or BSD, do yourself a favour and take these classes. The OSD classes are the best professional options offered at Seneca, in my opinion. I’d also like to thank my OSD teammates for a crazy 8 months. We’re still alive! Success!