haxroomie-core

API made with Node.js for running and controlling HaxBall rooms.

The most important interfaces the API offers are:

• createHaxroomie
  • creates instances of Haxroomie
• Haxroomie
  • container for the room instances (controls the headless browser)
• RoomController
  • controls the HaxBall room (owns a tab in the headless browser)

Installation

To install haxroomie-core for your project its preferred to install it locally with

npm install haxroomie-core

Scripts and plugins

Haxroomie uses Haxball Headless Manager (HHM) that allows you to modularize your room script. Instead of one massive JavaScript file you can implement the functionality in smaller modules called plugins.

If you just need to run your own vanilla room script, you can use the roomScript option.

You might want to disable other plugins from pluginConfig to prevent them from interfering with yours.

Using plugins

The plugins live inside repositories like hhm-sala-plugins. The repositories can be loaded with repositories property and plugins with pluginConfig.

If you want to write your own plugins, see saviolas guide for writing plugins.

Downloading files / haxball recordings

You can download files from your plugins/room scripts with the global function haxroomie.download().

const obj = {hello: 'world'};
const blob = new Blob([JSON.stringify(obj, null, 2)], {type : 'application/json'});
haxroomie.download({ fileName: 'example.txt', file: blob});

See more info about blobs.

The recs can be downloaded with the haxroomie.downloadRec() function.

const bestGameEver = stopRecording();
haxroomie.downloadRec({ fileName: 'best-game-ever.hbr2', rec: bestGameEver });

By default the files will be downloaded to ~/.haxroomie/downloads (can be changed with downloadDirectory argument for Haxroomie constructor).

Development logging/debugging

See this to enable more extensive logging.

To make haxroomie start the browser in windowed mode, use headless: true in Haxroomie constructor.

Examples

Opening One Room

Requires the token to be set as an environment variable named HAXBALL_TOKEN.

const { createHaxroomie } = require('haxroomie-core');

async function bootstrap() {
  try {
    let haxroomie = await createHaxroomie();
    let room = await haxroomie.addRoom('example');

    let roomInfo = await room.openRoom({
      roomName: 'haxroomie',
      playerName: 'host',
      maxPlayers: 10,
      public: false,
      token: process.env.HAXBALL_TOKEN
    });

    console.log(`Room started. Here is the link: ${roomInfo.roomLink}`);

  } catch (err) {
    console.error(err);
    process.exit(1);
  }
}

bootstrap();

Getting Repository Info Before Opening Room

Initialize the room with RoomController.init before using RoomController.repositories.

Initializing loads the Haxball Headless Manager (HHM) library. It is required to use the repositories property.

const { createHaxroomie } = require('haxroomie-core');

async function getRepoInfoExample() {
  try {
    let haxroomie = await createHaxroomie();
    let room = await haxroomie.addRoom('example');
    await room.init();

    repoInfo = await room.repositories.getRepositoryInformation({
      type: 'github',
      repository: 'morko/hhm-sala-plugins'
    });

    console.log(repoInfo);

  } catch (err) {
    console.error(err);
    process.exit(1);
  }
}

getRepoInfoExample();