haxroomie-cli

haxroomie-cli is a tool to run and control HaxBall rooms from a Command Line Interface.

Links

• Config file documentation
• Changelog
• Discord server for haxroomie

Quick Start

Installation script is tested only on Ubuntu but it should work on Debian based distributions. Use at your own risk!

The installation script

• creates an user for running haxroomie-cli (default: haxroomie)
• installs Node.js (with nvm)
• installs dependencies for chromium browser and
• installs tmux to keep haxroomie-cli running when not connected to the server
• creates a startup script that automatically switches to the haxroomie user and starts/resumes haxroomie-cli in a tmux session.

Run the installation script as root user. Using sudo will probably not work.

bash <(curl -s https://raw.githubusercontent.com/morko/haxroomie/master/scripts/install-haxroomie-cli-debian.sh)

Start haxroomie.

haxroomie

Once you have your rooms running you can use the min command "minimize" haxroomie and haxroomie will keep running on background.

Read CLI usage for usage instructions and how to add more rooms.

Manual Install

If you do not wish to use the installation script you can only install the haxroomie-cli package from npm.

Prerequisites:

• Node.js version 16 or newer
• npm (Node Package Manager that usually comes with Node.js)

It is not recommended to install/run haxroomie with root user!

Use nvm (Node Virtual Manager) to install Node.js or see this guide to configure your npm properly!

Install wont work if your user does not have permissions for the global npm installation directory.

To install haxroomie-cli run:

npm install haxroomie-cli -g

You need to install some dependencies for the headless browser to work. See puppeteer troubleshooting page and install the dependencies for your system.

To start the interactive CLI run:

haxroomie-cli

Updating

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

To update to latest release:

npm install haxroomie-cli -g

To change to a specific release:

npm install haxroomie-cli#[release_number] -g

e.g. npm install haxroomie-cli@1.0.7 -g

CLI usage

By default haxroomie uses the config file from ~/.haxroomie/config.js (~ meaning your users home directory). The config file is where you configure how many and what kind of rooms you want to run.

See the config section for more information about the config file.

When starting haxroomie-cli config file will be created (if it does not exist) using this example configuration. Here you can find more examples.

To start the interactive interface run:

haxroomie

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

To list all possible arguments for the executable:

haxroomie --help

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).

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 HaxBall Headless Host HBInit function with some additional ones.

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

You can find examples of configs in examples directory.

To load a plugin 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 two private rooms.

let config = {
  // ID for the room (has to be unique):
  room1: {
    // Options for room1:
    autoStart: true,
    roomName: 'first room',
    playerName: 'host',
    maxPlayers: 12,
    public: false,
    noPlayer: true,
    pluginConfig: {
      'sav/roles': {
        roles: {
          admin: 'adminpass',
          host: 'hostpass',
        },
      },
    },
  },
  // ID for the room (has to be unique):
  room2: {
    // Options for room2:
    autoStart: true,
    roomName: 'another room...',
    playerName: 'host',
    maxPlayers: 12,
    public: false,
    noPlayer: true,
    pluginConfig: {
      'sav/roles': {
        roles: {
          admin: 'adminpass',
          host: 'hostpass',
        },
      },
    },
  },
};
module.exports = config;

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.

Repositories can be loaded with repositories and plugins with pluginConfig option for RoomController.open().

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 object).

Developing plugins with haxroomie-cli

You can load your repository from the file system.

Add this to the repository array in the config file:

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

You might also want to enable more extensive logging and/or make haxroomie start the browser in windowed mode with window option in the command line.

Publishing your plugins

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