haxroomie

Haxroomie is an API and CLI to run headless HaxBall rooms without GUI.

With haxroomie you can

run rooms without desktop environment
run multiple rooms with ease
use a modular plugin system
monitor and control rooms from command line
use the API to create an interface to run rooms

Installing

Prerequisites:

Node.js version 10.15.1 or newer
npm (usually comes with Node.js)

Installing using the -g flag (or with sudo) wont work unless your user has pemissions for the global npm installation directory. Do not install as a root user!

Follow this guide to configure your npm properly!

To install run:

npm install haxroomie -g

To install the API for your own project:

npm install haxroomie

If you do not have Chrome installed in your system, then install the dependencies for it listed in the troubleshooting section.

Troubleshooting

If you get an error like "Failed to launch Chrome", it is possible that you are missing some libraries that Chrome depend on.

To install dependencies in Debian based Linux you can use the following command:

sudo apt install gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget

For dependencies in other systems see puppeteers troubleshooting page.

For support join the discord.

Updating

Please see the CHANGELOG before updating to watch out for any breaking updates!

To update to latest release run the install command again:

npm install haxroomie -g

To update to a specific release:

npm install morko/haxroomie#[release_number] -g

e.g. npm install haxroomie@1.0.7 -g

CLI usage

By default haxroomie uses the config from ~/.haxroomie/config.js.

If the config does not exist, then one will be created using this example configuration.

Here you can find more examples.

See config section for more information about the config file.

To start run:

haxroomie

If you wish to load the config from elsewhere you can give haxroomie the -c argument.

e.g.

haxroomie -c [path/to/config.js]

Every room requires a token from https://www.haxball.com/headlesstoken.

You will be prompted for the tokens when opening a room. Or you can give it in the config (token property).

Once haxroomie CLI is running you can type help for available commands.

Config

Haxroomies config is used to tell haxroomie how many rooms you are planning to run and with what kind of options. Each room config accepts same options than the regular HBInit function with some additional ones.

See the documentation for all the possible options and their explanations.

You can find examples of configs in examples directory.

To enable a repository in config:

use repositories option

To load plugins from the repository:

use pluginConfig option

Here is a simple example of a config that starts one private room.

let config = {
  // ID for the room (has to be unique):
  'room1': {

    // Options for room1:
    autoStart: true,
    roomName: 'haxroomie',
    playerName: 'host',
    maxPlayers: 12,
    public: false,
    pluginConfig: {
      'sav/roles': {
        roles: {
          admin: 'adminpass',
          host: 'hostpass',
        }
      }
    }
  }
};
module.exports = config;

Scripts and plugins

You can run your script with the configs roomScript option.

Running a script this way will disable the default plugins that haxroomie loads (except few essential ones).

Running plugins instead of a room script

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

See the saviolas guide for writing plugins.

Developing plugins with haxroomie

You can load your repository from the file system.

Add this to the repository array in haxroomie config:

{
  type: 'local',
  path: '/path/to/local/repo',
  subpath: 'src' // optional (src is default)
  suffix: '.js' // optional (.js is default)
}

Publishing your plugins

To publish the plugins you can create your own HHM plugin repository.

Using own HHM config

Haxroomie supports custom Haxball Headless Manager (HHM) configs. However there should rarely be a reason to do this.

(see HHM config requirements).

HHM config requirements

HHM.config.room object must have a token property like this:

HHM.config.room = {
  token: hrConfig.token
}

The postInit plugin should set the window.hroomie.hhmStarted property to true on the onRoomLink event like this:

HHM.config.postInit = HBInit => {
  let room = HBInit();

  room.onRoomLink = () => {
    window.hroomie.hhmStarted = true;
  }
}

Differences to vanilla HHM config

Haxroomie injects a hrConfig object to the HHM config. The object contains all the properties sent to the function that is used to start the room. See the API documentation for openRoom for a list of these properties.

See the default configuration file for a complete example.

See HHM docs for more information about the configuration file.

Thioby/haxroomie