Vorple

Note: This readme describes how to develop the Vorple library itself. If you're interested in developing games using Vorple, see the documentation at vorple-if.com instead.

Setting up the development environment

These instructions assume a Unix environment (Linux or macOS). Setting up the environment on a Windows machine should follow similar steps.

The entire Vorple system is comprised of several parts:

• A Glulx engine Quixe that runs the Inform game files
• A custom web interpreter Haven that handles displaying the game output and getting input from the player
• The Vorple JavaScript library itself (this repository) that supports the non-standard features which allow the Inform game files to communicate with the browser environment
• Inform 6 and Inform 7 extensions that allow game authors to use Vorple from within Inform

The project includes webpack-dev-server that re-runs the build step automatically whenever Vorple or Haven sources change and creates a local server that lets you run the development version directly on the computer.

To set up the development environment:

1. Install Node.js
2. Install the rest of the packages with npm install. npm should come with the Node.js installation.
3. Run npm install to install packages

Now you can do npm start to start the development server at http://localhost:9000. The server restarts automatically when changes are made to source files.

The development server exposes files from the library directory. For example, if you place zork.ulx in this directory you can play it from the address http://localhost:9000/?story=zork.ulx when the server is running.

You can also substitute npm with Yarn (recommended).

Building release versions

The npm run build script compiles the Vorple and Haven source code and copies everything into a dist directory. It also creates the files in the lib directory that are needed in the npm distribution package.

Test suite

Tests for the JavaScript library are in the tests/specs directory. The test runner stack is WebDriver + Selenium + Mocha + Chai.

To run the tests:

1. npm install packages if you haven't already. This will download and install required test software.
2. npm start:test to start the development server (keep it running while the tests run)
3. In another window run npm test to start the tests

You should now see a bunch of browser windows pop up, load Vorple, and close soon after. The terminal where you ran npm test should show whether the tests pass or fail.

npm test runs the tests using Firefox, npm test:chrome uses Chrome, npm test:safari uses Safari and npm test:all runs tests once with all browsers. To run tests in Safari, you need to enable WebDriver support as per these instructions.

The test drivers must match the version of Chrome that's installed on the machine that runs the tests. If the test runner complains about incompatible browsers, run npm install chromedriver wdio-chromedriver-service to update the drivers.

There are two separate story files for the Inform 6 and Inform 7 libraries. The Inform 7 tests file is used by default. The environment variable INFORM_VERSION defines which file to use, e.g. INFORM_VERSION=6 npm test:chrome tests the Inform 6 story file using Chrome.

Hint: running the entire test set might take some time, so if you're working on only one feature you can temporarily skip other tests by changing './tests/specs/**/*.js' near the start of the wdio.conf.js file to point to a specific test file.

The tests in this repository test the individual JavaScript library methods. There are many more tests in the Inform 7 repository for the extensions.