Building Games for the Web

In Getting Started, we covered the basics of writing a game that can run from the command line. Here we’ll explain how to use the Gamefic SDK to make games you can run in a web browser.


The SDK’s web tools require Node.js and NPM.

Generating the Web Scaffold

After creating a game project, run rake web:generate to add the necessary components. The following commands will create a new project and prepare it for the web:

$ gamefic init mygame
$ cd mygame
$ bundle install
$ rake web:generate
$ npm install

Quick Tip: If you have a game that already works on the command line, you should be able to make it into a web game simply by running rake web:generate && npm install && rake web:run.

The Web Components

The above commands add several files and directories to the project. Most of them should look familiar to JavaScript developers. The breadth of components can be daunting, but rest assured that you can safely ignore most of them (at least for now).

  • package.json: The primary configuration for your web application. You should’t need to change anything in here yet, but you can customize metadata fields like name, description, and author if you’d like.
  • webpack.config.js: The rules for building the web app. You can leave this alone for now too. Elsewhere we’ll cover some of the things you can do with Webpack to add more features to your game, such as graphics and sound.
  • node_modules: The package dependencies required to test and build the application. You should never need to change anything in here yourself. It gets managed automatically via npm commands, e.g., npm install.
  • web: The directory with all of your web assets. When you want to change the look and feel of your game’s interface, you’ll do most of the work in here.

We’ll cover the web components in more detail later. For now we can jump right into your new game.

Testing the Game in a Browser

Run rake web:run to start a local web server. Open your browser and go to http://localhost:4342.

Hello world web

The initial game is the same one you get with rake ruby:run, except you can play it in a browser instead of a terminal.

Make some changes to your game in main.rb and reload the page. You should see the changes immediately.

Technical Details

The Gamefic SDK uses several Node-based tools for web apps.

  • React: A JavaScript library for building user interfaces. Everything on the game’s web page is built using React components.
  • gamefic-driver: The interface between React and the game code. At its core, its only responsibilities are to receive input from the player and provide JSON data representing the current game state. For most Gamefic projects, it Just Works(tm).
  • react-gamefic: A collection of React components that quickly bootstraps adventure games and allows for easy customization.
  • Webpack: A JavaScript module bundler. This tool is responsible for turning your game into an app that you can share and publish.
  • opal-webpack-bundler: A Webpack extension that compiles Ruby to JavaScript using Opal.

The runtime dependencies are limited to gamefic-driver and a small set of React packages.

Opal Limitations

The SDK uses Opal to compile your Ruby code into JavaScript. Opal introduces a few differences that need consideration to ensure that the compiled code works correctly.

  • Symbols are strings
    Opal does not differentiate between symbols and strings at runtime.
    :word == 'word' # => true
  • Strings are immutable
    Since JavaScript strings are immutable, Opal follows suit when it compiles Ruby to JavaScript. String methods that modify the string in place result in an error.
    string = 'my string'
    string.concat '...'     # Error
    string = string + '...' # OK
    string.upcase!          # Error
    string = string.upcase  # OK
  • Most I/O functions are disabled
    Ruby functionality is limited to features that do not violate browser security restrictions. As a result, the compiled code cannot access the filesystem or open network connections.
  • Prefer require or require_relative to autoload
    Although autoload is supported in Opal, I’ve run into situations where the file never gets loaded, and I couldn’t determine why. Using require or require_relative is generally more reliable.

Changing the Design

The page layout can be customized through standard HTML and CSS. You can start experimenting right away by making changes to web/public/index.html and web/src/style.css.

The Base Layout

The react-gamefic library provides several options for a base page layout. The default is ebook, a clean and responsive design suitable for text adventures.

The base layout is declared by an import call in web/src/index.js:

import 'react-gamefic/styles/ebook';

Other available options are react-gamefic/styles/normal and react-gamefic/styles/terminal. If you want to start your layout from scratch, you can also remove the import altogether.

Refer to react-gamefic for more information.

Building the Web App

Run rake web:build to compile the game into a standalone web app. All the files you need will be created in the builds/web/production directory. You can play it by opening the index.html file in a browser. No web server is necessary.

Distributing the Game

If you want to share your game, all you have to do is provide the files in the web/builds/production directory. Two quick solutions are uploading them to a website or sending them in a zip file.

Many game marketplaces like make it easy for developers to publish web-based games.

Since the app is built purely on web technology, you can also integrate it into other web-based development frameworks, such as Electron, PhoneGap, and Cordova.

Next: The standard library