{"id":29391441,"url":"https://github.com/mertushka/haxball.js","last_synced_at":"2026-02-17T02:41:51.506Z","repository":{"id":50652979,"uuid":"387331643","full_name":"mertushka/haxball.js","owner":"mertushka","description":"🎉 A powerful Node.JS library for interacting with the Haxball Headless Host API","archived":false,"fork":false,"pushed_at":"2025-07-09T13:52:55.000Z","size":469,"stargazers_count":37,"open_issues_count":3,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-09T14:23:55.447Z","etag":null,"topics":["api","haxball","haxball-api","haxball-bot","haxball-bot-api","haxball-headless","haxball-headless-host","haxballbot","haxballjs","headless","javascript","nodejs","webrtc","websocket","wrtc"],"latest_commit_sha":null,"homepage":"https://github.com/haxball/haxball-issues/wiki/Headless-Host#api","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mertushka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["mertushka"]}},"created_at":"2021-07-19T03:49:30.000Z","updated_at":"2025-07-09T13:42:14.000Z","dependencies_parsed_at":"2024-06-19T16:40:04.435Z","dependency_job_id":"497f9b6b-ccbe-4c83-8751-131ec0d6d1f7","html_url":"https://github.com/mertushka/haxball.js","commit_stats":{"total_commits":26,"total_committers":4,"mean_commits":6.5,"dds":0.5769230769230769,"last_synced_commit":"1cbfcfa08722c7b15b207a6d7fd0b1c76aa17251"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/mertushka/haxball.js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mertushka%2Fhaxball.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mertushka%2Fhaxball.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mertushka%2Fhaxball.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mertushka%2Fhaxball.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mertushka","download_url":"https://codeload.github.com/mertushka/haxball.js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mertushka%2Fhaxball.js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264555288,"owners_count":23627312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","haxball","haxball-api","haxball-bot","haxball-bot-api","haxball-headless","haxball-headless-host","haxballbot","haxballjs","headless","javascript","nodejs","webrtc","websocket","wrtc"],"created_at":"2025-07-10T09:01:39.332Z","updated_at":"2026-02-17T02:41:51.500Z","avatar_url":"https://github.com/mertushka.png","language":"JavaScript","funding_links":["https://github.com/sponsors/mertushka"],"categories":[],"sub_categories":[],"readme":"[![NPM Version](https://img.shields.io/npm/v/haxball.js.svg?style=flat-square)](https://www.npmjs.com/package/haxball.js) [![NPM Monthly Downloads](https://img.shields.io/npm/dm/haxball.js.svg?style=flat-square)](https://npmjs.org/package/haxball.js)\n\n[![License](https://img.shields.io/github/license/mertushka/haxball.js?style=flat-square)](LICENSE.md) [![Last Commit](https://img.shields.io/github/last-commit/mertushka/haxball.js?style=flat-square)](https://github.com/mertushka/haxball.js/commits/) ![Language Most Used](https://img.shields.io/github/languages/top/mertushka/haxball.js?style=flat-square) [![Implementations](https://img.shields.io/badge/%F0%9F%92%A1-implementations-8C8E93.svg?style=flat-square)](https://github.com/mertushka/haxball.js/issues) ![Repository Size](https://img.shields.io/github/repo-size/mertushka/haxball.js?style=flat-square)\n\n[![Forks](https://img.shields.io/github/forks/mertushka/haxball.js?style=social)](https://github.com/mertushka/haxball.js/network/members) [![Stars](https://img.shields.io/github/stars/mertushka/haxball.js?style=social)](https://github.com/mertushka/haxball.js/stargazers) [![Watches](https://img.shields.io/github/watchers/mertushka/haxball.js?style=social)](https://github.com/mertushka/haxball.js/watchers)\n\n\u003ch1 id=\"title\" align=\"center\"\u003ehaxball.js\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003ehaxball.js is a powerful Node.js module that allows you to easily interact with the Haxball Headless API.\u003c/h4\u003e\n\n### 🔖 Table Of Contents\n\n- 🤔 [How To Use](#how-to-use)\n- 🚀 [Technologies](#technologies)\n- 🌱 [Minimal Requirements](#minimal-requirements)\n- 🎊 [Features](#features)\n- 💡 [How To Contribute](#how-to-contribute)\n- 🔏 [License](#license)\n\n---\n\n\u003ch2 id=\"how-to-use\"\u003e🤔 How To Use\u003c/h2\u003e\n\n#### 💻 Installing\n\n```sh\nnpm install haxball.js\n```\n\n#### CommonJS Module Usage Example\n\n```js\nconst HaxballJS = require('haxball.js').default;\n```\n\n#### ESM Module Usage Example\n\n```js\nimport HaxballJS from 'haxball.js';\n```\n\n#### Module Usage Example\n\n```js\nimport HaxballJS from 'haxball.js';\n\nHaxballJS().then((HBInit) =\u003e {\n\t// Same as in Haxball Headless Host Documentation\n\tconst room = HBInit({\n\t\troomName: 'Haxball.JS',\n\t\tmaxPlayers: 16,\n\t\tpublic: true,\n\t\tnoPlayer: true,\n\t\ttoken: 'YOUR_TOKEN_HERE', // Required\n\t});\n\n\troom.setDefaultStadium('Big');\n\troom.setScoreLimit(5);\n\troom.setTimeLimit(0);\n\n\troom.onRoomLink = function (link) {\n\t\tconsole.log(link);\n\t};\n\n\t// If there are no admins left in the room give admin to one of the remaining players.\n\tfunction updateAdmins() {\n\t\t// Get all players\n\t\tvar players = room.getPlayerList();\n\t\tif (players.length == 0) return; // No players left, do nothing.\n\t\tif (players.find((player) =\u003e player.admin) != null) return; // There's an admin left so do nothing.\n\t\troom.setPlayerAdmin(players[0].id, true); // Give admin to the first non admin player in the list\n\t}\n\n\troom.onPlayerJoin = function (player) {\n\t\tupdateAdmins();\n\t};\n\n\troom.onPlayerLeave = function (player) {\n\t\tupdateAdmins();\n\t};\n});\n```\n\n#### (Optional) Custom WebRTC Library\n\nHaxball.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.\n\nExample:\n\n```js\nconst HaxballJS = require('haxball.js');\nconst WebRTC = require('webrtc');\n\nHaxballJS({ webrtc: WebRTC }).then((HBInit) =\u003e {...});\n```\n\n#### (Optional) Proxy\n\nHaxball has a limit of 2 rooms per IP. Therefore, you can use proxy with adding `proxy: \"http://\u003cYOUR_PROXY_IP\u003e\"` in your HaxballJS config.\n\nExample:\n\n```js\nHaxballJS({ proxy: \"http://1.1.1.1:80\", }).then((HBInit) =\u003e {...});\n\n```\n\n#### 💻 Bun\n\nIt's highly experimental and risky to use it in a production environment, but `haxball.js` is compatible with [Bun.JS](https://bun.sh/).\n\n```bash\nbun install haxball.js\nbun pm trust node-datachannel\nbun index.ts\n```\n\n---\n\n\u003ch2 id=\"technologies\"\u003e🚀 Technologies\u003c/h2\u003e\n\n- node-datachannel - WebRTC implementation for Node.JS\n- ws - Websocket Connection\n- json5 - JSON Helper Module\n- @peculiar/webcrypto - WebCrypto implementation for Node.JS\n- pako - ZLIB port for Node.JS\n- xhr2 - W3C XMLHttpRequest implementation for Node.JS\n- https-proxy-agent - Websocket Proxy Support\n- @types/haxball-headless-browser - Type definitions\n\n[Back To The Top](#title)\n\n---\n\n\u003ch2 id=\"minimal-requirements\"\u003e🌱 Minimal Requirements\u003c/h2\u003e\n\n- NPM\n- NodeJS Version \u003e=18\n\n[Back To The Top](#title)\n\n---\n\n\u003ch2 id=\"features\"\u003e🎊 Features\u003c/h2\u003e\n\n- [x] Performant\n- [x] Strongly Typed\n\n[Back To The Top](#title)\n\n---\n\n\u003ch2 id=\"how-to-contribute\"\u003e💡 How To Contribute\u003c/h2\u003e\n\nPlease check [CONTRIBUTING.md](/CONTRIBUTING.md)\n\n\u003cp align=\"center\"\u003e\n\u003ci\u003eContributions, issues and features requests are welcome!\u003c/i\u003e\u003cbr /\u003e\n\u003ci\u003e📮 Submit PRs to help solve issues or add features\u003c/i\u003e\u003cbr /\u003e\n\u003ci\u003e🐛 Find and report issues\u003c/i\u003e\u003cbr /\u003e\n\u003ci\u003e🌟 Star the project\u003c/i\u003e\u003cbr /\u003e\n\u003c/p\u003e\n\n[Back To The Top](#title)\n\n---\n\n\u003ch2 id=\"license\"\u003e🔏 License\u003c/h2\u003e\n\nCopyright © This project is licensed by [MIT License](https://api.github.com/licenses/mit).\n\n[Back To The Top](#title)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmertushka%2Fhaxball.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmertushka%2Fhaxball.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmertushka%2Fhaxball.js/lists"}