bonktools 2.0.1 → 2.3.0

package/README.md

@@ -1,551 +1,262 @@
-# 🎮 BonkTools v2.0
+# BonkBot.js
 
-[![npm version](https://img.shields.io/npm/v/bonktools.svg)](https://www.npmjs.com/package/bonktools)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+BonkBot is a JavaScript library for creating bots for the web game [Bonk.io](https://bonk.io). It provides an easy way to create custom bots that can automate various actions within the game. With BonkBot, you can interact with the game's websocket protocol easily, chat with other players, and perform actions such as joining and leaving rooms.
 
-> Advanced Bonk.io bot library with physics simulation and game state management
+### V4 Alpha, report any issues/bugs in the issues tab
 
-BonkTools is a powerful TypeScript library for creating automated bots for Bonk.io. Unlike other libraries, BonkTools includes a **Box2D physics simulator** that allows you to detect game events like player deaths, round endings, and collisions in real-time.
+### Newer NodeJS versions may encounter issues, node 18 and 16 are confirmed working
 
-## ✨ Features
+## Installation
 
-- 🔌 **WebSocket Connection Management** - Stable connection with automatic reconnection
-- ⚡ **Box2D Physics Simulation** - Replicate game physics locally to detect events
-- 🎯 **Game State Tracking** - Full awareness of game state (rounds, scores, players)
-- 🎭 **Event-Driven Architecture** - React to any game event with TypeScript events
-- 🛠️ **Room Management** - Create, join, and manage rooms programmatically
-- 👥 **Player Management** - Track all players, their states, and positions
-- 🎪 **Host Controls** - Start/stop games, kick players, change settings
-- 📝 **TypeScript Native** - Full type safety and IntelliSense support
-- 🧪 **Tested & Reliable** - Built on proven Bonkbot foundation
-
-## 📦 Installation
+To install BonkBot, you will need [Node.js](https://nodejs.org/en/download/) installed on your system. Then, run the following command in your terminal:
 
 ```bash
-npm install bonktools
+npm install bonkbot
 ```
 
-## 🚀 Quick Start
-
-### Simple Bot Example
-
-```typescript
-import { createBot } from 'bonktools';
-
-// Create bot
-const bot = createBot({
-  account: {
-    username: 'MyBot',
-    guest: true
-  },
-  logLevel: 'info'
-});
+## Features
 
-// Initialize and connect
-await bot.init();
-await bot.connect();
+-   Connect to existing rooms or create new ones
+-   Automatically determine the optimal server using the game's API
+-   Send and receive chat messages
+-   Track players joining and leaving
+-   Manage teams and game settings
+-   Handle game events
+-   Comprehensive error handling
+-   Detailed logging
 
-// Join a room
-await bot.joinRoomByUrl('https://bonk.io/123456');
+# Support
 
-// Send a message
-await bot.chat('Hello from BonkTools! 🎮');
-
-// Listen for events
-bot.on('chatMessage', (player, message) => {
-  console.log(`${player.username}: ${message}`);
-});
-```
+[Discord Server](https://discord.gg/USJQjwD7AY)
 
-### Host Bot Example
+## Basic Usage
 
-```typescript
-import { createBot } from 'bonktools';
+```javascript
+const { createBot, LOG_LEVELS } = require('bonkbot');
 
+// Create a bot instance
 const bot = createBot({
-  account: {
-    username: 'HostBot',
-    guest: true
-  }
-});
-
-await bot.init();
-await bot.connect();
-
-// Create a room
-const room = await bot.createRoom({
-  roomName: 'My Tournament Room',
-  maxPlayers: 4,
-  mode: 'classic'
-});
-
-console.log('Room created:', room.shareLink);
-
-// Detect when round ends (using physics simulation!)
-bot.on('roundEnd', ({ winner, scores }) => {
-  console.log(`Winner: ${winner.username}`);
-  console.log('Scores:', scores);
-  
-  // Auto-restart in 3 seconds
-  setTimeout(() => bot.startGame(), 3000);
-});
-
-// Detect player deaths
-bot.on('playerDeath', (player, position) => {
-  console.log(`${player.username} died at (${position.x}, ${position.y})`);
-});
-
-// Start when all ready
-bot.on('allPlayersReady', () => {
-  bot.startGame();
-});
-```
-
-## 📚 API Reference
-
-### Core Methods
-
-#### `init(): Promise<BonkTools>`
-Initialize the bot (get auth token, server info)
-
-#### `connect(): Promise<BonkTools>`
-Connect to Bonk.io server
-
-#### `disconnect(): void`
-Disconnect from server
-
-### Room Management
-
-#### `createRoom(options: RoomOptions): Promise<RoomInfo>`
-Create a new room
-
-```typescript
-const room = await bot.createRoom({
-  roomName: 'My Room',
-  maxPlayers: 4,
-  password: 'secret',
-  mode: 'classic',
-  hidden: false
-});
-```
-
-#### `joinRoom(address: string, password?: string): Promise<void>`
-Join room by address code
-
-```typescript
-await bot.joinRoom('123456', 'password');
-```
-
-#### `joinRoomByUrl(url: string): Promise<void>`
-Join room by full URL
-
-```typescript
-await bot.joinRoomByUrl('https://bonk.io/123456');
-```
-
-#### `leaveRoom(): Promise<void>`
-Leave current room
-
-### Game Control
-
-#### `startGame(): Promise<void>`
-Start the game (host only)
-
-#### `stopGame(): Promise<void>`
-Stop/abort current game (host only)
-
-#### `setRounds(rounds: number): Promise<void>`
-Set number of rounds to win (1-999)
-
-```typescript
-await bot.setRounds(5);
-```
-
-#### `setReady(ready: boolean): Promise<void>`
-Set bot ready status
-
-```typescript
-await bot.setReady(true);
-```
-
-### Player Management
-
-#### `getPlayer(id: number): PlayerData | null`
-Get player by ID
-
-#### `getPlayerByUsername(username: string, guest?: boolean): PlayerData | null`
-Get player by username
-
-#### `getAllPlayers(): PlayerData[]`
-Get all players in room
-
-#### `getHost(): PlayerData | null`
-Get current host player
-
-#### `isHost(): boolean`
-Check if bot is host
-
-#### `kickPlayer(playerId: number): Promise<void>`
-Kick a player (host only)
-
-#### `giveHost(playerId: number): Promise<void>`
-Transfer host to another player (host only)
-
-#### `joinTeam(team: number): Promise<void>`
-Join a team (0=spectate, 1=FFA, 2-6=teams)
-
-#### `lockTeams(locked: boolean): Promise<void>`
-Lock/unlock teams (host only)
-
-### Chat
-
-#### `chat(message: string): Promise<void>`
-Send a chat message (max 200 chars)
-
-```typescript
-await bot.chat('Hello everyone! 👋');
-```
-
-### Utility
-
-#### `getShareLink(): string | null`
-Get room share link
-
-#### `getRoomInfo(): RoomInfo`
-Get current room information
-
-#### `getMyId(): number`
-Get bot's player ID
-
-#### `isReady(): boolean`
-Check if bot is initialized
-
-#### `isConnected(): boolean`
-Check if bot is connected
-
-#### `getGameState(): any`
-Get current game state (if physics is running)
-
-## 🎭 Events
-
-BonkTools uses TypeScript's EventEmitter for type-safe events:
-
-### Connection Events
-
-```typescript
-bot.on('ready', () => {
-  console.log('Bot initialized');
+	account: {
+		username: 'BotName',
+		guest: true, // Use guest account
+	},
+	logLevel: LOG_LEVELS.WARN, // Set log level (DEBUG, INFO, WARN, ERROR, NONE)
 });
 
-bot.on('connect', () => {
-  console.log('Connected to server');
+// Initialize and handle events
+bot.events.on('ready', async () => {
+	await bot.connect();
 });
 
-bot.on('disconnect', (reason) => {
-  console.log('Disconnected:', reason);
-});
+// Handle chat messages
+bot.events.on('CHAT_MESSAGE', (message) => {
+	console.log(`${message.player.username}: ${message.message}`);
 
-bot.on('error', (error) => {
-  console.error('Error:', error);
+	// Respond to !ping command
+	if (message.message === '!ping') {
+		bot.chat('Pong!');
+	}
 });
-```
 
-### Room Events
-
-```typescript
-bot.on('roomCreated', (room) => {
-  console.log('Room created:', room.shareLink);
+bot.events.on('PACKET', (packet) => {
+	bot.autoHandlePacket(packet);
 });
 
-bot.on('roomJoined', ({ game, room, players }) => {
-  console.log('Joined room:', room.name);
-});
+bot.init();
 ```
 
-### Player Events
+## Authentication Examples
 
-```typescript
-bot.on('playerJoin', (player) => {
-  console.log(`${player.username} joined`);
-});
+### Automatic Server Detection
 
-bot.on('playerLeave', (player) => {
-  console.log(`${player.username} left`);
-});
+By default, BonkBot will automatically determine the optimal server to connect to by querying the game's API. This ensures your bot connects to the most appropriate server based on the current game infrastructure.
 
-bot.on('playerReady', (player, ready) => {
-  console.log(`${player.username} is ${ready ? 'ready' : 'not ready'}`);
-});
-
-bot.on('allPlayersReady', () => {
-  console.log('All players ready!');
-});
-
-bot.on('playerTeamChange', (player, team) => {
-  console.log(`${player.username} joined team ${team}`);
-});
+If you want to override this behavior and connect to a specific server, you can provide the `server` option when creating the bot:
 
-bot.on('playerKick', (player) => {
-  console.log(`${player.username} was kicked`);
+```javascript
+const bot = createBot({
+	// ... other options
+	server: 'b2ny1', // Force connection to a specific server
 });
 ```
 
-### Game Events
-
-```typescript
-bot.on('gameStart', () => {
-  console.log('Game started!');
-});
+### Guest Account
 
-bot.on('gameEnd', (result) => {
-  console.log('Game ended!');
-  console.log('Champion:', result.champion?.username);
-});
-
-bot.on('roundStart', (roundNumber) => {
-  console.log(`Round ${roundNumber} started`);
-});
-
-bot.on('roundEnd', (result) => {
-  console.log('Round ended!');
-  console.log('Winner:', result.winner?.username);
-  console.log('Scores:', result.scores);
-  console.log('Duration:', result.duration);
-});
-
-bot.on('countdown', (seconds) => {
-  console.log(`Starting in ${seconds}...`);
+```javascript
+const bot = createBot({
+	account: {
+		username: 'BotName',
+		guest: true,
+	},
+	logLevel: LOG_LEVELS.WARN,
 });
 ```
 
-### Physics Events (⚡ New!)
+### User Account
 
-These events are powered by the Box2D physics simulator:
-
-```typescript
-bot.on('playerDeath', (player, position) => {
-  console.log(`${player.username} died at (${position.x}, ${position.y})`);
-});
-
-bot.on('collision', (event) => {
-  console.log('Collision detected:', event.type);
-  console.log('Player:', event.playerId);
-  console.log('Position:', event.position);
-});
-
-bot.on('playerOutOfBounds', (player) => {
-  console.log(`${player.username} went out of bounds`);
+```javascript
+const bot = createBot({
+	account: {
+		username: 'YourUsername',
+		password: 'YourPassword',
+		guest: false,
+	},
+	logLevel: LOG_LEVELS.WARN,
 });
 ```
 
-### Chat Events
+## Connection Flow and Examples
 
-```typescript
-bot.on('chatMessage', (player, message) => {
-  console.log(`${player.username}: ${message}`);
-  
-  // Respond to commands
-  if (message === '!help') {
-    bot.chat('Available commands: !help, !placar');
-  }
-});
-```
+The connection flow typically follows this sequence:
 
-### Host Events
+1. Bot initialization (`bot.init()`)
+2. Ready event fires when login completes
+3. Connect to game server (`bot.connect()`)
+4. Find or create room
+5. Join room or create room
+6. Handle game events
 
-```typescript
-bot.on('hostTransfer', (oldHost, newHost) => {
-  console.log(`Host transferred from ${oldHost.username} to ${newHost.username}`);
-});
+### Joining a Room by Name
 
-bot.on('teamLockToggle', (locked) => {
-  console.log(`Teams ${locked ? 'locked' : 'unlocked'}`);
-});
+```javascript
+bot.events.on('ready', async () => {
+	try {
+		// Find room by name
+		const roomInfo = await bot.getAddressFromRoomName('roomName');
+		console.log(`Found room: ${roomInfo.roomname}`);
 
-bot.on('roundsChange', (rounds) => {
-  console.log(`Rounds changed to ${rounds}`);
-});
+		// Set address and connect
+		bot.setAddress(roomInfo);
+		await bot.connect();
 
-bot.on('gamemodeChange', (mode, engine) => {
-  console.log(`Mode changed to ${mode} (${engine})`);
+		// Join with optional password
+		await bot.joinRoom({
+			password: 'optional-password',
+		});
+	} catch (error) {
+		console.error('Failed to join room:', error);
+	}
 });
 ```
 
-### Map Events
+### Joining a Room by Link
 
-```typescript
-bot.on('mapSwitch', (map) => {
-  console.log('Map changed:', map.m.n); // map name
-});
+```javascript
+bot.events.on('ready', async () => {
+	try {
+		// Get room info from share link
+		const roomInfo = await bot.getAddressFromUrl('https://bonk.io/123abc');
+		console.log(`Found room: ${roomInfo.roomname}`);
 
-bot.on('mapSuggest', ({ title, author, player }) => {
-  console.log(`${player.username} suggested map: ${title} by ${author}`);
+		// Connect to room
+		bot.setAddress(roomInfo);
+		await bot.connect();
+		await bot.joinRoom();
+	} catch (error) {
+		console.error('Failed to join room:', error);
+	}
 });
 ```
 
-## 🎯 Advanced Usage
+### Creating a Room
 
-### Tournament Bot
+```javascript
+bot.events.on('ready', async () => {
+	try {
+		// Connect to server first
+		await bot.connect();
 
-```typescript
-import { createBot } from 'bonktools';
-
-const bot = createBot({ /* ... */ });
-await bot.init();
-await bot.connect();
-
-const room = await bot.createRoom({
-  roomName: '🏆 Tournament - Round 1',
-  maxPlayers: 8,
-  mode: 'arrows'
+		// Then create room
+		bot.createRoom({
+			roomname: 'BonkBot Room',
+			maxplayers: 10,
+			roompassword: '',
+			hidden: true,
+		});
+	} catch (error) {
+		console.error('Failed to create room:', error);
+	}
 });
 
-const scores = new Map<string, number>();
-let matchCount = 0;
-const maxMatches = 10;
-
-bot.on('roundEnd', ({ winner }) => {
-  if (winner) {
-    scores.set(winner.username, (scores.get(winner.username) || 0) + 1);
-  }
-  
-  matchCount++;
-  
-  if (matchCount >= maxMatches) {
-    // Tournament ended
-    const champion = Array.from(scores.entries())
-      .sort((a, b) => b[1] - a[1])[0];
-    
-    bot.chat(`🏆 Tournament Champion: ${champion[0]}!`);
-    
-    // Show leaderboard
-    const leaderboard = Array.from(scores.entries())
-      .sort((a, b) => b[1] - a[1])
-      .map(([name, score], i) => `${i+1}. ${name}: ${score}`)
-      .join(' | ');
-    
-    bot.chat(`📊 Final: ${leaderboard}`);
-  } else {
-    // Next match
-    setTimeout(() => bot.startGame(), 5000);
-  }
+// Get share link when room is created
+bot.events.on('ROOM_SHARE_LINK', (data) => {
+	console.log(`Room created! URL: ${data.url}`);
 });
 ```
 
-### Custom Command System
-
-```typescript
-const commands = {
-  '!help': () => bot.chat('Commands: !help, !score, !stats'),
-  
-  '!score': () => {
-    const players = bot.getAllPlayers();
-    const scoreText = players
-      .map(p => `${p.username}: ${p.balance}`)
-      .join(' | ');
-    bot.chat(`📊 ${scoreText}`);
-  },
-  
-  '!stats': () => {
-    const players = bot.getAllPlayers();
-    bot.chat(`👥 Players: ${players.length}`);
-    bot.chat(`🎮 Round: ${currentRound}/${maxRounds}`);
-  }
-};
-
-bot.on('chatMessage', (player, message) => {
-  const command = commands[message.toLowerCase()];
-  if (command) {
-    command();
-  }
-});
+## Available Events
+
+| Event              | Description                 | Returns                   |
+| ------------------ | --------------------------- | ------------------------- |
+| `ready`            | Bot is ready to connect     | -                         |
+| `connect`          | Connected to server         | -                         |
+| `PACKET`           | Any packet received         | `{type, ...data}`         |
+| `JOIN`             | Joined a room               | `{game, room, players}`   |
+| `PLAYER_JOIN`      | Player joined room          | `{player, id}`            |
+| `PLAYER_LEAVE`     | Player left room            | `{player, id}`            |
+| `CHAT_MESSAGE`     | Chat message received       | `{player, message}`       |
+| `TEAM_CHANGE`      | Player changed team         | `{player, team}`          |
+| `HOST_TRANSFER`    | Host was transferred        | `{oldHost, newHost}`      |
+| `READY_CHANGE`     | Player ready status changed | `{player, ready}`         |
+| `GAME_START`       | Game started                | -                         |
+| `GAME_END`         | Game ended                  | -                         |
+| `COUNTDOWN`        | Game countdown              | `{countdown}`             |
+| `MAP_SWITCH`       | Map was switched            | `{map}`                   |
+| `MAP_SUGGEST`      | Map was suggested           | `{title, author, player}` |
+| `CHANGE_ROUNDS`    | Round count changed         | `{rounds}`                |
+| `GAMEMODE_CHANGE`  | Game mode changed           | `{mode, engine}`          |
+| `ROOM_SHARE_LINK`  | Room link created           | `{url}`                   |
+| `PLAYER_KICK`      | Player was kicked           | `player`                  |
+| `PLAYER_TABBED`    | Player tabbed in/out        | `{player, tabbed}`        |
+| `PLAYER_INPUT`     | Player input received       | `{player, movement}`      |
+| `TEAMLOCK_TOGGLE`  | Teams locked/unlocked       | `{teamsLocked}`           |
+| `ROOM_NAME_UPDATE` | Room name changed           | `{name}`                  |
+| `ROOM_ADDRESS`     | Room address updated        | `{address}`               |
+| `BALANCE_SET`      | Player balance changed      | `{player, balance}`       |
+| `disconnect`       | Disconnected from server    | -                         |
+
+## Common Methods
+
+```javascript
+// Chat message
+bot.chat('Hello world');
+
+// Get all players
+const players = bot.getAllPlayers();
+
+// Get host
+const host = bot.getHost();
+
+// Get room share link
+const shareLink = bot.getShareLink();
+
+// Set player ready status
+bot.ready(true);
+
+// Join a team (0-5)
+bot.joinTeam(2); // 0=spectator, 1=FFA, 2=red, 3=blue...
+
+// Give host to player
+bot.giveHost(playerId);
+
+// Kick a player
+bot.kickPlayer(playerId);
+
+// Leave the room
+bot.leaveGame();
 ```
 
-## 🔧 Configuration
-
-### BonkToolsOptions
-
-```typescript
-interface BonkToolsOptions {
-  account: {
-    username: string;
-    password?: string;  // For non-guest accounts
-    guest?: boolean;    // Default: true
-  };
-  server?: string;      // Default: auto-detect best server
-  avatar?: Avatar;      // Custom avatar
-  logLevel?: LogLevel;  // 'debug' | 'info' | 'warn' | 'error' | 'none'
-  protocolVersion?: number; // Default: 49
-  peerID?: string;      // Custom peer ID (auto-generated if not provided)
-}
-```
-
-### RoomOptions
-
-```typescript
-interface RoomOptions {
-  roomName?: string;
-  maxPlayers?: number;  // 1-8
-  password?: string;
-  hidden?: boolean;
-  quick?: boolean;
-  mode?: 'classic' | 'arrows' | 'grapple' | 'death arrows' | 'simple' | 'vtol';
-  minLevel?: number;    // 0-999
-  maxLevel?: number;    // 0-999
-}
-```
-
-## 🏗️ Architecture
-
-BonkTools is built on a modular architecture:
-
-```
-BonkTools (Main API)
-├── BonkConnection (WebSocket layer)
-│   ├── PacketParser
-│   └── PacketBuilder
-├── PhysicsWorld (Box2D simulation)
-│   ├── GameState
-│   ├── CollisionDetector
-│   └── InputProcessor
-├── GameLoop (60 FPS game loop)
-├── RoomManager
-└── PlayerManager
-```
-
-The key innovation is the **PhysicsWorld** module, which:
-1. Receives player inputs from the server
-2. Simulates the game physics using Box2D
-3. Detects collisions, deaths, and round endings
-4. Emits events for your bot to react to
-
-This allows BonkTools to have awareness of the game state that's impossible with just WebSocket packets alone.
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.
-
-## 📝 License
-
-MIT © OBL
-
-## 🙏 Acknowledgments
-
-- Built on [Bonkbot](https://github.com/PixelMelt/BonkBot) by PixelMelt
-- Physics powered by [Box2D](https://box2d.org/)
-- Inspired by the Brazilian Bonk.io community
+## Examples
 
-## 📞 Support
+Check out the `examples` directory for more examples:
 
-- GitHub Issues: [github.com/brenoluizdev/bonktools/issues](https://github.com/brenoluizdev/bonktools/issues)
-- Discord: [Join our Discord](https://discord.gg/dBVmaySqEk)
+-   `simple-bot.js`: A basic bot that connects to a room and responds to chat commands
+-   `host-bot.js`: A bot that creates and hosts a room
 
----
+## Contributing
 
-Made with ❤️ for the Bonk.io community
+Contributions are always welcome! If you find a bug or have a feature request, please open an issue on the project's GitHub page.
 
+## License
 
-[![npm version](https://img.shields.io/npm/v/bonktools.svg?color=blue)](https://www.npmjs.com/package/bonktools)
-[![license](https://img.shields.io/github/license/brenoluizdev/bonktools.svg)](https://github.com/brenoluizdev/bonktools/blob/main/LICENSE)
-[![GitHub Repo stars](https://img.shields.io/github/stars/brenoluizdev/bonktools?style=social)](https://github.com/brenoluizdev/bonktools)
+BonkBot is open-source software licensed under the [GPL-3.0 License](https://www.gnu.org/licenses/gpl-3.0.en.html).