Haxball Types

Type definitions for developing custom Haxball Headless (https://www.haxball.com/headless) rooms using TypeScript in a NodeJS project.

This package provides type-safe interfaces and function declarations to help you build Haxball rooms with full TypeScript support. It is especially useful for developers who want to use modern tooling (like TypeScript and bundlers) while maintaining compatibility with the Haxball Headless API.

📦 Install

You can install this package via npm:

npm install haxball-headless-types

🔧 Usage Example

Use the provided types and declare global functions like HBInit to create a room:

import type { HBInitType, PlayerObject } from 'haxball-headless-types';
declare const HBInit: HBInitType;

const room = HBInit({
  roomName: "MyRoom",
  public: false,
  maxPlayers: 8,
  noPlayer: false,
  playerName: "host",
  token: "token_here"
});

room.onPlayerChat = (player: PlayerObject, message: string) => {
  room.sendChat(`${player.name} has written ${message}`);
  return true;
};

🛠️ Build Setup

To bundle your room script into a single .js file compatible with Haxball Headless, we recommend using Webpack .

Install dependencies:

npm install --save-dev webpack webpack-cli ts-loader

Webpack config (webpack.config.js):

const path = require('path');

module.exports = {
  entry: './src/index.ts',
  output: {
    filename: 'room.js',
    path: path.resolve(__dirname, 'dist'),
    libraryTarget: 'umd',
  },
  resolve: {
    extensions: ['.ts', '.js'],
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  externals: {},
  mode: 'production'
};

Add a build script in your package.json:

"scripts": {
  "build": "webpack"
}

Then run:

npm run build

Your bundled script will be available at dist/room.js, ready to be injected into Haxball Headless.