⚽ EasyHax

EasyHax — A maneira mais fácil e moderna de criar bots e servidores para o Haxball Headless.

Uma camada de abstração sobre haxball.js com eventos simplificados, comandos, auto-load de actions e arquitetura plug-and-play.
Projetado para iniciantes e desenvolvedores que querem prototipar rápido sem perder extensibilidade.

Índice

• ⚽ EasyHax
  • Índice
  • Recursos
  • Instalação
  • Quickstart
  • API
    • new EasyRoom(options)
    • room.start()
    • Eventos (shortcuts)
    • room.command(cmd, handler)
    • room.send(message)
  • Actions (autoload)
  • Comandos
  • Exemplo completo (bot.js)
  • Estrutura recomendada do projeto
    • Exemplo de actions/anunciarGol.js
  • Configurações e Build
  • Troubleshooting
    • onJoin não dispara
    • Action 'x' not found
    • Cannot use import statement outside a module
  • Roadmap
  • Contribuição
  • Licença

Recursos

• Abstração simples dos eventos do Haxball: onJoin, onLeave, onGoal, onChat (e mais).
• room.command() para criar comandos com pouca boilerplate.
• Sistema de actions carregáveis por nome (autoload) e handlers inline (funções).
• Compatível com TypeScript (tipagens .d.ts) e build ESM/CJS via tsup.
• Logger embutido com níveis (debug, info, warn, error).
• Plugin-friendly: arquitetura pensada para extensões.

Instalação

npm install easyhax
# ou
yarn add easyhax

Se estiver trabalhando localmente durante o desenvolvimento, você pode usar npm link para testar o pacote localmente.

Quickstart

Crie bot.js simples:

const { EasyRoom } = require("easyhax");

const room = new EasyRoom({
  roomName: "EasyHax Server",
  maxPlayers: 12,
  token: "SEU_TOKEN_DO_HAXBALL",
  public: false,
  noPlayer: false, // importante: false para receber eventos
});

// Handler inline
room.onJoin((player) => {
  room.send(`👋 Bem-vindo, ${player.name}!`);
});

// Comando personalizado
room.command("!ola", (player, room) => {
  room.send(`Olá, ${player.name}!`);
});

room.start();

Execute:

node bot.js

API

new EasyRoom(options)

Opções (exemplo):

{
  roomName?: string;
  maxPlayers?: number;
  password?: string;
  token?: string;
  public?: boolean;
  noPlayer?: boolean; // padrão: false
  geo?: { code: string; lat: number; lon: number };
  playerName?: string;
  proxy?: string;
  debug?: boolean;
}

room.start()

Inicializa a conexão com o Haxball Headless e registra os handlers internos.

Eventos (shortcuts)

• room.onJoin(handlerOrActionName)
• room.onLeave(handlerOrActionName)
• room.onGoal(handlerOrActionName)
• room.onChat(handler) (quando implementado)

Cada handlerOrActionName pode ser:

• uma função: (player, room) => { ... }
• uma string: "nomeDaAction" — que carrega actions/nomeDaAction.js

room.command(cmd, handler)

Registra um comando. handler é função (player, room, args) ou uma string (mensagem simples).

room.send(message)

Envia uma mensagem para a sala (chat).

Actions (autoload)

Você pode criar ações para reutilizar lógica. Ex.: actions/bemVindo.js:

module.exports = (room, player) => {
  room.send(`👋 Bem-vindo ${player.name}!`);
};

E ativar assim:

room.onJoin("bemVindo");

Internamente a lib procura por actions/<name>.js dentro do pacote ou copiado em dist/actions quando construído.

Dica: se preferir não usar actions por arquivo, registre handlers inline com room.onJoin(fn).

Comandos

Registrar comandos simples:

room.command("!ping", (player, room) => {
  room.send("pong");
});

Ou com resposta fixa (string):

room.command("!site", "https://meusite.com");

O CommandManager permite registrar handlers que recebem (player, room, args).

Exemplo completo (bot.js)

const { EasyRoom } = require("easyhax");

const room = new EasyRoom({
  roomName: "Servidor Exemplo",
  maxPlayers: 12,
  token: process.env.HAX_TOKEN || "",
  public: false,
  noPlayer: false
});

room.onJoin((player) => {
  room.send(`Seja bem-vindo, ${player.name}!`);
});

room.onGoal((team) => {
  const teamName = team === 1 ? "🔴 Vermelho" : "🔵 Azul";
  room.send(`GOOOOL do ${teamName}!`);
});

room.command("!players", (player, room) => {
  // exemplo: listar jogadores
  const names = room.listPlayers ? room.listPlayers() : "não suportado";
  room.send(typeof names === "string" ? names : names.join(", "));
});

room.start();

Estrutura recomendada do projeto

meu-bot/
├─ actions/
│  ├─ bemVindo.js
│  └─ anunciarGol.js
├─ bot.js
├─ package.json

Exemplo de actions/anunciarGol.js

module.exports = (room, team) => {
  const teamName = team === 1 ? "🔴 Vermelho" : "🔵 Azul";
  room.send(`⚽ GOOOOOL do ${teamName}!`);
};

Configurações e Build

Recomendado usar tsup para compilar ESM e CJS:

tsup.config.ts

import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts"],
  dts: true,
  format: ["esm", "cjs"],
  outDir: "dist",
  clean: true,
  onSuccess: "cp -r src/actions dist/actions"
});

package.json (exemplo)

{
  "name": "easyhax",
  "type": "module",
  "main": "dist/index.cjs",
  "module": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "dev": "tsup --watch",
    "build": "tsup",
    "test": "node examples/bot.cjs"
  }
}

Troubleshooting

onJoin não dispara

• Certifique-se noPlayer: false. Se noPlayer for true, o bot será espectador invisível e não receberá eventos normalmente.
• Confirme token válido e que a sala está sendo criada corretamente.

Action 'x' not found

• Verifique se actions/x.js existe e exporta module.exports = (room, ...) => {}.
• No build, confirme que dist/actions foi gerado/copied.

Cannot use import statement outside a module

• Defina "type": "module" no package.json para usar import/ESM.
• Ou use a versão CJS (require) e dist/index.cjs.

Roadmap

• [x] Eventos básicos: join, leave, goal
• [x] Sistema de comandos simples
• [x] Autoload de actions
• [x] Tipagens TypeScript básicas
• [ ] Sistema de plugins externo (plugin marketplace)
• [ ] Painel web de administração
• [ ] Suporte a matches e torneios
• [ ] Documentação online (docs.easyhax.dev)

Contribuição

Contribuições são bem-vindas!
Abra issues, envie PRs, crie actions úteis e compartilhe templates de servidores.

Padrões:

• Use prettier e eslint
• Escreva testes básicos quando possível
• Documente novas features no README

Licença

MIT © EasyHax

Obrigado por usar EasyHax!
Se quiser, eu posso também compor um CHANGELOG.md, CONTRIBUTING.md e templates de issues/PR.