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
• 🚀 Technologies
• 🌱 Minimal Requirements
• 🎊 Features
• 💡 How To Contribute
• 🔏 License

---

🤔 How To Use

💻 Installing

npm install haxball.js

CommonJS Module Usage Example

const HaxballJS = require('haxball.js').default;

ESM Module Usage Example

import HaxballJS from 'haxball.js';

Module Usage Example

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 @webrtc-node/webrtc 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:

import HaxballJS from 'haxball.js';
import {
	RTCPeerConnection,
	RTCIceCandidate,
	RTCSessionDescription,
} from './custom-webrtc.js';

HaxballJS({
	webrtc: {
		RTCPeerConnection,
		RTCIceCandidate,
		RTCSessionDescription,
	},
}).then((HBInit) => {...});

(Optional) Proxy

Haxball has a limit of 2 rooms per IP. Therefore, you can use proxy with adding proxy: "http://<YOUR_PROXY_IP>" in your HaxballJS config.

Example:

HaxballJS({ proxy: "http://1.1.1.1:80", }).then((HBInit) => {...});

---

🚀 Technologies

• @webrtc-node/webrtc - WebRTC implementation for Node.JS
• ws - Websocket Connection
• json5 - JSON Helper Module
• Node.js Web Crypto API - WebCrypto implementation
• Node.js Zlib API - native compression support
• xhr2 - W3C XMLHttpRequest implementation for Node.JS
• https-proxy-agent - Websocket Proxy Support

Back To The Top

---

🌱 Minimal Requirements

• npm
• Node.js Version >=22.18

Back To The Top

---

🎊 Features

• Performant
• Strongly Typed

Back To The Top

---

💡 How To Contribute

Please check 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

---

🔏 License

Copyright © This project is licensed by MIT License.

Back To The Top