https://github.com/mertushka/haxball.js
🎉 A powerful Node.JS library for interacting with the Haxball Headless Host API
https://github.com/mertushka/haxball.js
api haxball haxball-api haxball-bot haxball-bot-api haxball-headless haxball-headless-host haxballbot haxballjs headless javascript nodejs webrtc websocket wrtc
Last synced: 4 months ago
JSON representation
🎉 A powerful Node.JS library for interacting with the Haxball Headless Host API
- Host: GitHub
- URL: https://github.com/mertushka/haxball.js
- Owner: mertushka
- License: mit
- Created: 2021-07-19T03:49:30.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-07-09T13:52:55.000Z (12 months ago)
- Last Synced: 2025-07-09T14:23:55.447Z (12 months ago)
- Topics: api, haxball, haxball-api, haxball-bot, haxball-bot-api, haxball-headless, haxball-headless-host, haxballbot, haxballjs, headless, javascript, nodejs, webrtc, websocket, wrtc
- Language: JavaScript
- Homepage: https://github.com/haxball/haxball-issues/wiki/Headless-Host#api
- Size: 458 KB
- Stars: 37
- Watchers: 4
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/haxball.js) [](https://npmjs.org/package/haxball.js)
[](LICENSE.md) [](https://github.com/mertushka/haxball.js/commits/)  [](https://github.com/mertushka/haxball.js/issues) 
[](https://github.com/mertushka/haxball.js/network/members) [](https://github.com/mertushka/haxball.js/stargazers) [](https://github.com/mertushka/haxball.js/watchers)
haxball.js
haxball.js is a powerful Node.js module that allows you to easily interact with the Haxball Headless API.
### 🔖 Table Of Contents
- 🤔 [How To Use](#how-to-use)
- 🚀 [Technologies](#technologies)
- 🌱 [Minimal Requirements](#minimal-requirements)
- 🎊 [Features](#features)
- 💡 [How To Contribute](#how-to-contribute)
- 🔏 [License](#license)
---
🤔 How To Use
#### 💻 Installing
```sh
npm install haxball.js
```
#### CommonJS Module Usage Example
```js
const HaxballJS = require('haxball.js').default;
```
#### ESM Module Usage Example
```js
import HaxballJS from 'haxball.js';
```
#### Module Usage Example
```js
import HaxballJS from 'haxball.js';
HaxballJS().then((HBInit) => {
// Same as in Haxball Headless Host Documentation
const room = HBInit({
roomName: 'Haxball.JS',
maxPlayers: 16,
public: true,
noPlayer: true,
token: 'YOUR_TOKEN_HERE', // Required
});
room.setDefaultStadium('Big');
room.setScoreLimit(5);
room.setTimeLimit(0);
room.onRoomLink = function (link) {
console.log(link);
};
// If there are no admins left in the room give admin to one of the remaining players.
function updateAdmins() {
// Get all players
var players = room.getPlayerList();
if (players.length == 0) return; // No players left, do nothing.
if (players.find((player) => player.admin) != null) return; // There's an admin left so do nothing.
room.setPlayerAdmin(players[0].id, true); // Give admin to the first non admin player in the list
}
room.onPlayerJoin = function (player) {
updateAdmins();
};
room.onPlayerLeave = function (player) {
updateAdmins();
};
});
```
#### (Optional) Custom WebRTC Library
Haxball.JS uses `node-datachannel` as the default WebRTC library. However, you can use a custom WebRTC implementation by specifying it in the HaxballJS config using the `webrtc` option.
Example:
```js
const HaxballJS = require('haxball.js');
const WebRTC = require('webrtc');
HaxballJS({ webrtc: WebRTC }).then((HBInit) => {...});
```
#### (Optional) Proxy
Haxball has a limit of 2 rooms per IP. Therefore, you can use proxy with adding `proxy: "http://"` in your HaxballJS config.
Example:
```js
HaxballJS({ proxy: "http://1.1.1.1:80", }).then((HBInit) => {...});
```
#### 💻 Bun
It's highly experimental and risky to use it in a production environment, but `haxball.js` is compatible with [Bun.JS](https://bun.sh/).
```bash
bun install haxball.js
bun pm trust node-datachannel
bun index.ts
```
---
🚀 Technologies
- node-datachannel - WebRTC implementation for Node.JS
- ws - Websocket Connection
- json5 - JSON Helper Module
- @peculiar/webcrypto - WebCrypto implementation for Node.JS
- pako - ZLIB port for Node.JS
- xhr2 - W3C XMLHttpRequest implementation for Node.JS
- https-proxy-agent - Websocket Proxy Support
- @types/haxball-headless-browser - Type definitions
[Back To The Top](#title)
---
🌱 Minimal Requirements
- NPM
- NodeJS Version >=18
[Back To The Top](#title)
---
🎊 Features
- [x] Performant
- [x] Strongly Typed
[Back To The Top](#title)
---
💡 How To Contribute
Please check [CONTRIBUTING.md](/CONTRIBUTING.md)
Contributions, issues and features requests are welcome!
📮 Submit PRs to help solve issues or add features
🐛 Find and report issues
🌟 Star the project
[Back To The Top](#title)
---
🔏 License
Copyright © This project is licensed by [MIT License](https://api.github.com/licenses/mit).
[Back To The Top](#title)