isle-evrima-rcon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MENIX (https://github.com/menix1337)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+# isle-evrima-rcon
+
+[![npm version](https://img.shields.io/npm/v/isle-evrima-rcon.svg)](https://www.npmjs.com/package/isle-evrima-rcon)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A high-performance, type-safe RCON client for **The Isle: Evrima** game servers.
+
+Built for production use with automatic reconnection, exponential backoff, and multi-server support.
+
+> **Note:** This library only supports The Isle: Evrima. Legacy does not have RCON support.
+
+## ⚠️ Disclaimer
+
+**Official documentation for Evrima's RCON protocol is extremely limited.** This library has been built through community efforts, reverse-engineering, and trial-and-error testing.
+
+As a result:
+- Some commands may not work as expected or may change with game updates
+- Response formats may vary between server versions
+- Undocumented behavior may occur
+- New commands may be added or existing ones modified without notice
+
+If you encounter issues, please [open an issue](https://github.com/menix1337/isle-evrima-rcon/issues) with details about your server version and the unexpected behavior. Community contributions and discoveries are always welcome!
+
+## Features
+
+- 🚀 **High Performance** — Persistent connections, reusable for thousands of commands
+- 🔄 **Auto-Reconnect** — Automatic reconnection with exponential backoff
+- 🔒 **Type-Safe** — Full TypeScript support with strict type checking
+- 🏢 **Multi-Server** — Manage multiple game servers with named instances
+- ✅ **Validated** — Zod schemas for configuration validation
+- 📦 **Zero Config** — Sensible defaults, works out of the box
+
+## Installation
+
+```bash
+# npm
+npm install isle-evrima-rcon
+
+# bun
+bun add isle-evrima-rcon
+
+# yarn
+yarn add isle-evrima-rcon
+
+# pnpm
+pnpm add isle-evrima-rcon
+```
+
+## Quick Start
+
+### One-Shot Command
+
+Use the `rcon()` helper for single commands — it handles the connection lifecycle automatically:
+
+```typescript
+import { rcon } from 'isle-evrima-rcon';
+
+const result = await rcon({
+  host: { ip: '192.168.1.100', port: 8888, password: 'your-password' },
+  command: { name: 'players' }
+});
+
+console.log(result.data);
+```
+
+### Persistent Connection
+
+For multiple commands, use `EvrimaRCON` to maintain a persistent connection:
+
+```typescript
+import { EvrimaRCON } from 'isle-evrima-rcon';
+
+const client = new EvrimaRCON('192.168.1.100', 8888, 'your-password', {
+  autoReconnect: true,
+  name: 'main-server' // Shows in debug logs
+});
+
+await client.connect();
+
+// Server announcements
+await client.announce('Welcome to the server!');
+
+// Player management
+const players = await client.getPlayers();
+console.log(`Online: ${players.length} players`);
+
+await client.kick({ steamId: '76561197960419839', reason: 'AFK too long' });
+await client.ban({ steamId: '76561197960419839', reason: 'Rule violation' });
+
+// When done
+client.disconnect();
+```
+
+### Multi-Server Management
+
+Each `EvrimaRCON` instance is independent — manage multiple servers simultaneously:
+
+```typescript
+import { EvrimaRCON } from 'isle-evrima-rcon';
+
+// Create separate clients for each server
+const server1 = new EvrimaRCON('192.168.1.100', 8888, 'password1', {
+  autoReconnect: true,
+  name: 'US-West-1'
+});
+
+const server2 = new EvrimaRCON('192.168.1.101', 8888, 'password2', {
+  autoReconnect: true,
+  name: 'EU-Central-1'
+});
+
+// Connect to all servers
+await Promise.all([server1.connect(), server2.connect()]);
+
+// Each server operates independently
+await server1.announce('US West maintenance in 10 minutes');
+await server2.announce('EU Central server rules updated');
+
+// Reconnection is handled per-server automatically
+```
+
+## Configuration
+
+```typescript
+const client = new EvrimaRCON(host, port, password, {
+  // Connection timeout in milliseconds
+  timeout: 10000,           // default: 10000 (10s)
+
+  // Automatically reconnect if connection drops
+  autoReconnect: true,      // default: false
+
+  // Maximum reconnection attempts before giving up
+  maxReconnectAttempts: 5,  // default: 3
+
+  // Base delay between reconnect attempts (uses exponential backoff)
+  // Actual delays: 1s → 2s → 4s → 8s → ... (capped at 30s)
+  reconnectDelay: 1000,     // default: 1000 (1s)
+
+  // Enable debug logging to console
+  debug: true,              // default: false
+
+  // Server name for log identification (useful for multi-server setups)
+  name: 'my-server'         // default: "host:port"
+});
+```
+
+### Connection Resilience
+
+When `autoReconnect` is enabled:
+
+1. **Automatic Recovery** — If the connection drops, the client automatically reconnects
+2. **Exponential Backoff** — Retry delays increase progressively (1s → 2s → 4s → 8s...) to avoid overwhelming the server
+3. **Command Retry** — Commands sent during a disconnect will auto-retry after reconnection
+4. **Max Attempts** — After `maxReconnectAttempts` failures, errors are thrown for handling
+
+## API Reference
+
+> **Note:** Due to limited official documentation, some commands may have undocumented parameters or behaviors. Methods marked with uncertain documentation are based on community research.
+
+### Server Management
+
+| Method | Description |
+|--------|-------------|
+| `announce(message)` | Broadcast message to all players |
+| `directMessage({ steamId, message })` | Send private message to a player |
+| `getServerDetails()` | Get server info (returns `ServerDetails`) |
+| `getPlayables()` | Get list of available playable dinosaurs |
+| `updatePlayables(config)` | Update playable dinosaur configuration |
+| `wipeCorpses()` | Clear all corpses from the map |
+| `save(name?)` | Save the world state |
+| `setPaused(paused)` | Pause/unpause the server |
+| `setMigrations(enabled)` | Toggle dinosaur migrations |
+
+### Player Management
+
+| Method | Description |
+|--------|-------------|
+| `getPlayers()` | Get online players with SteamId, Name, EOSId |
+| `getPlayerData(steamId?)` | Get detailed player data (mutations, prime status) |
+| `ban({ steamId, reason? })` | Ban a player |
+| `kick({ steamId, reason? })` | Kick a player |
+
+### Growth & Network
+
+| Method | Description |
+|--------|-------------|
+| `setGrowthMultiplier(enabled)` | Toggle growth multiplier feature |
+| `setGrowthMultiplierValue(multiplier)` | Set growth multiplier value (e.g., 1.5) |
+| `setNetUpdateDistanceChecks(enabled)` | Toggle network update distance checks |
+
+### Whitelist
+
+| Method | Description |
+|--------|-------------|
+| `setWhitelist(enabled)` | Toggle whitelist on/off |
+| `whitelistAdd(steamId)` | Add player to whitelist |
+| `whitelistRemove(steamId)` | Remove player from whitelist |
+
+### Game Settings
+
+| Method | Description |
+|--------|-------------|
+| `setGlobalChat(enabled)` | Toggle global chat |
+| `setHumans(enabled)` | Toggle human characters |
+
+### AI Controls
+
+| Method | Description |
+|--------|-------------|
+| `setAI(enabled)` | Toggle AI spawning |
+| `disableAIClasses(classes)` | Disable specific AI types |
+| `setAIDensity(0.0-1.0)` | Set AI spawn density |
+| `setAILearning(enabled)` | Toggle AI learning behavior |
+| `getQueueStatus()` | Get server queue status |
+
+### Low-Level Commands
+
+| Method | Description |
+|--------|-------------|
+| `sendCommand(command, params?)` | Execute any RCON command |
+| `batch(commands)` | Execute multiple commands in sequence |
+| `custom(commandString)` | Send custom command (may not be functional) |
+
+### Batch Execution
+
+Execute multiple commands efficiently:
+
+```typescript
+const results = await client.batch([
+  { command: 'announce', params: 'Server restart in 5 minutes' },
+  { command: 'save' },
+  { command: 'announce', params: 'Save complete!' }
+]);
+```
+
+## Error Handling
+
+```typescript
+import { EvrimaRCON, RCONError, RCONErrorCode } from 'isle-evrima-rcon';
+
+try {
+  await client.connect();
+  await client.announce('Hello!');
+} catch (error) {
+  if (error instanceof RCONError) {
+    switch (error.code) {
+      case RCONErrorCode.CONNECTION_FAILED:
+        console.error('Server unreachable:', error.message);
+        break;
+      case RCONErrorCode.AUTH_FAILED:
+        console.error('Invalid RCON password');
+        break;
+      case RCONErrorCode.TIMEOUT:
+        console.error('Connection timed out');
+        break;
+      case RCONErrorCode.NOT_CONNECTED:
+        console.error('Client not connected');
+        break;
+      case RCONErrorCode.INVALID_COMMAND:
+        console.error('Invalid command:', error.message);
+        break;
+    }
+  }
+}
+```
+
+## Validation Utilities
+
+Built-in validators for Steam IDs and configuration:
+
+```typescript
+import { isValidSteamId, validateServerConfig, validateClientOptions } from 'isle-evrima-rcon';
+
+// Validate Steam ID format
+if (isValidSteamId('76561197960419839')) {
+  await client.whitelistAdd('76561197960419839');
+}
+
+// Validate server config (throws on invalid)
+const config = validateServerConfig({
+  ip: '192.168.1.100',
+  port: 8888,
+  password: 'secret'
+});
+
+// Validate client options with defaults applied
+const options = validateClientOptions({
+  timeout: 5000,
+  autoReconnect: true
+});
+```
+
+## TypeScript Support
+
+Full type definitions with strict checking:
+
+```typescript
+import type {
+  Command,
+  CommandResult,
+  PlayerInfo,
+  PlayerData,
+  ServerDetails,
+  ServerConfig,
+  ClientOptions,
+  BanParams,
+  KickParams,
+  DirectMessageParams,
+  ConnectionState,
+  RCONErrorCode
+} from 'isle-evrima-rcon';
+
+// All convenience methods are fully typed
+const players: PlayerInfo[] = await client.getPlayers();
+// Players now include EOS ID: { steamId, name, eosId }
+
+const playerData: PlayerData = await client.getPlayerData();
+// Includes mutations, prime status, character info
+
+const details: ServerDetails = await client.getServerDetails();
+```
+
+## Requirements
+
+- **Bun** >= 1.0.0 or **Node.js** >= 18.0.0
+- **TypeScript** >= 5.0.0 (peer dependency)
+- The Isle: Evrima server with RCON enabled
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.
+
+## Credits
+
+Originally inspired by [smultar-dev/evrima.rcon](https://github.com/smultar-dev/evrima.rcon).  
+Refactored, extended, and maintained by [MENIX](https://github.com/menix1337).
+
+## License
+
+[MIT](LICENSE) © 2026 MENIX

package/package.json

@@ -0,0 +1,91 @@
+{
+	"name": "isle-evrima-rcon",
+	"version": "1.0.0",
+	"description": "High-performance, type-safe TypeScript RCON client for The Isle: Evrima game servers with auto-reconnect and connection pooling",
+	"author": "MENIX <https://github.com/menix1337>",
+	"license": "MIT",
+	"type": "module",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": {
+			"import": "./src/index.ts",
+			"types": "./src/index.ts"
+		},
+		"./client": {
+			"import": "./src/client.ts",
+			"types": "./src/client.ts"
+		},
+		"./commands": {
+			"import": "./src/commands.ts",
+			"types": "./src/commands.ts"
+		},
+		"./protocol": {
+			"import": "./src/protocol.ts",
+			"types": "./src/protocol.ts"
+		},
+		"./types": {
+			"import": "./src/types.ts",
+			"types": "./src/types.ts"
+		},
+		"./validation": {
+			"import": "./src/validation.ts",
+			"types": "./src/validation.ts"
+		}
+	},
+	"files": [
+		"src",
+		"LICENSE",
+		"README.md"
+	],
+	"scripts": {
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"test:coverage": "bun test --coverage",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write .",
+		"prepublishOnly": "bun run typecheck"
+	},
+	"keywords": [
+		"rcon",
+		"the-isle",
+		"the-isle-rcon",
+		"isle",
+		"isle-rcon",
+		"evrima",
+		"evrima-rcon",
+		"the-isle-evrima",
+		"game-server",
+		"game-server-rcon",
+		"dinosaur",
+		"dinosaur-game",
+		"typescript",
+		"bun",
+		"remote-console",
+		"server-admin",
+		"server-management"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/menix1337/isle-evrima-rcon.git"
+	},
+	"homepage": "https://github.com/menix1337/isle-evrima-rcon#readme",
+	"bugs": {
+		"url": "https://github.com/menix1337/isle-evrima-rcon/issues"
+	},
+	"engines": {
+		"bun": ">=1.0.0",
+		"node": ">=18.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.6",
+		"prettier": "^3.8.0"
+	},
+	"peerDependencies": {
+		"typescript": "^5.0.0"
+	},
+	"dependencies": {
+		"zod": "^3.25.76"
+	}
+}