The HTML Document Object Model and its accompanying CSS box model lend themselves to responsive 2D-casual game board layouts. The highly-tuned HTML render flows of our browsers are more battery safe than canvas or WebGL alternatives, while also providing opportunities for graphics acceleration and performance. With boxart-boiler games, the idea is to build DOM-first. If you want to drop down into lower level drawing APIs, you can always temporarily rasterize and enhance an element outside of boxart.
Moreover, HTML gives us a way to represent whatever information we mean to convey visually, no matter how complex, in a way that assistive technologies can tap into. This is how we can make truly open Open Web Games.
Contributing, Bug Reports, and More Information
BoxArt is being developed in the open, so you can see and get involved in our planning process at waffle.io/boxart/boxart-boiler. To file a bug report, open an issue on the BoxArt-Boiler Github repository and it will be automatically added to our Waffle board.
Getting Started with Boxart
To start working with this repo and build your own responsive, accessible game we recommend you either download the code for the latest release from the releases page, or fork this repo and use git to clone your fork.
Once the code is on your machine open a terminal in its directory and run
npm install; this will install all our dependencies and you’ll be able to run the project’s grunt tasks. To see the site hosted locally run
grunt and visit http://localhost:8080 in your browser of choice.
For your own games, we recommend starting with the
master branch and build from there. But if you want a working example of how BoxArt can be used, these branches contain demo games that you can download and run to see how different types of game logic and animation can be implemented:
- simple-demo: A demo matching game demonstrating BoxArt’s batched custom animation support
- box2d-demo: A demo showing how BoxArt can be used in conjunction with Box2D
- 2048-demo: A BoxArt implementation of the addictive sliding number game
In order to use or contribute to this repo you’ll need the following things installed on your system:
The following tasks are provided by this boilerplate for use during development.
grunt task (aliased to
npm start) runs
webpack-dev-server; a task which hosts your site on a local http server and watches your code for changes. When changes are detected webpack will automatically cut a new build and the code (where possible) will be automatically swapped into the browser, meaning you don’t have to refresh the page to see updates. If the code cannot be hotswapped the page will be refreshed so the latest changes are visible. The
webpack-dev-server task is configured in the
grunt-webpack.js file in the tasks directory, and is setup to read the
webpack.config.js file to configure webpack’s behavior.
grunt lint or
npm run lint
This repo uses eslint to enforce code quality and a consistent style across the project. Running
grunt lint (aliased to
npm run lint) will notify you of any possible JS errors or style variations. This task is configured with numerous
.eslintrc files that are scattered throughout the repo. Note that none of those files actually define linting rules, instead they reference predefined rule sets which live in the eslint directory.
.editorconfig file is also provided to help reduce frustrating style
errors that could bog down this linting task. If your text editor or IDE
supports it, install an editor config plugin.
grunt test or
grunt test task (aliased to
npm test) first lints the code, then runs our tests using the karma test runner. This task runs the test suite once, then exits; this mirrors what happens in our continuous integration environment.
To skip linting and run only the tests themselves, use the command
grunt karma:ci instead.
grunt test-dev or
npm run test-dev
grunt test-dev task (aliased to
npm run test-dev) first lints the code, then starts the tests in a watcher that will re-run tests when code changes are detected. This task is designed to be run in the background while coding, to help catch errors as they occur.
grunt build or
npm run build
grunt build task (aliased to
npm run build) uses Webpack to bundle our code for release for a dev environment. Before building the code this task runs both the
karma:ci tasks, to ensure code quality. The
webpack.config.build.js file is used to configure webpack’s behavior during this task.
Built files are output into the
The BoxArt-Boiler source contains a number of useful inline comments embedded within the code, but this repository also includes user documentation for all available BoxArt & BoxArt-Boiler features. This documentation is contained within the docs-src directory, and can be rendered and viewed using the commands below.
grunt docs or
npm run docs
grunt docs command (aliased to
npm run docs) will compile the live inline code example files, then use Jekyll to build the documentation site from the docs-src directory into the
docs/ folder. Once built, a web server will be available on http://localhost:4000/ : the documentation site can be viewed at this address, and the HTML documentation will automatically be re-generated if any of the source markdown files change. (Note however that this server does not include live reload, so you will need to manually refresh your browser window to see those changes.)
Developing Inline Examples
npm run docs-dev
Code for the live inline (iframed) examples within the documentation is contained within the
examples/ folder in the repository root. Running
npm run docs-dev will start the Jekyll site as with
grunt docs, but will start a webpack build in parallel so that any changes to the examples source code will be compiled into the docs-src folder, and then picked up by the Jekyll watcher and rendered into the live docs site. This one command has the same effect as running
grunt jekyll and
grunt build-examples-dev in two separate terminals.
Tech Stack and Tool Chain
This project makes liberal use of the following technologies:
Cross-Browser Testing generously provided by