haxroomie-cli
v2.6.4
Published
Command Line Interface for haxroomie to run and control HaxBall rooms.
Downloads
67
Readme
haxroomie-cli
haxroomie-cli is a tool to run and control HaxBall rooms from a Command Line Interface.
Links
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 atmux
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:
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 [email protected] -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});
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.