specprotocol 1.0.0

package/docs/guides/custom-plugins.md

@@ -0,0 +1,211 @@
+# 🧩 Kendi Plugin'inizi Yazın
+
+Bu rehber, sıfırdan gelişmiş bir plugin oluşturmayı adım adım gösterir.
+
+## Plugin Yaşam Döngüsü
+
+```
+register() → initialize(bot) → [bot çalışırken] → destroy()
+```
+
+## Temel Şablon
+
+```typescript
+import { type Plugin, type BotAPI } from 'specprotocol';
+
+export class MyPlugin implements Plugin {
+  name = 'my-plugin'; // Benzersiz olmalı
+
+  private bot!: BotAPI;
+
+  initialize(bot: BotAPI): void {
+    this.bot = bot;
+    // Event listener'ları buraya ekleyin
+    // Timer'ları buraya başlatın
+  }
+
+  destroy(): void {
+    // Temizlik: timer'ları durdurun, kaynakları serbest bırakın
+  }
+}
+```
+
+## Örnek 1: Auto-Respawn Plugin
+
+Öldüğünde otomatik yeniden doğar:
+
+```typescript
+import { type Plugin, type BotAPI, BufferWriter, PlayServerboundPackets } from 'specprotocol';
+
+export class AutoRespawnPlugin implements Plugin {
+  name = 'auto-respawn';
+  private bot!: BotAPI;
+
+  initialize(bot: BotAPI): void {
+    this.bot = bot;
+
+    bot.on('death', () => {
+      console.log('💀 Öldüm, yeniden doğuyorum...');
+
+      // 1 saniye bekle sonra respawn
+      setTimeout(() => {
+        // Client Status paketi: 0 = Perform Respawn
+        const writer = new BufferWriter();
+        writer.writeVarInt(0);
+        bot.sendPacket(0x09, writer.toBuffer());
+      }, 1000);
+    });
+  }
+}
+```
+
+## Örnek 2: AFK Prevention Plugin
+
+Düzenli olarak hareket ederek AFK kick'i önler:
+
+```typescript
+import { type Plugin, type BotAPI } from 'specprotocol';
+
+export class AntiAFKPlugin implements Plugin {
+  name = 'anti-afk';
+  private bot!: BotAPI;
+  private interval?: ReturnType<typeof setInterval>;
+
+  initialize(bot: BotAPI): void {
+    this.bot = bot;
+
+    bot.on('spawn', () => {
+      this.interval = setInterval(() => {
+        // Küçük bir hareket yap
+        const pos = bot.position;
+        bot.setPosition(
+          pos.x + (Math.random() - 0.5) * 0.1,
+          pos.y,
+          pos.z + (Math.random() - 0.5) * 0.1
+        );
+      }, 30000); // 30 saniyede bir
+    });
+  }
+
+  destroy(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+    }
+  }
+}
+```
+
+## Örnek 3: Chat Logger Plugin
+
+Chat mesajlarını dosyaya kaydeder:
+
+```typescript
+import { type Plugin, type BotAPI } from 'specprotocol';
+import * as fs from 'fs';
+
+export class ChatLoggerPlugin implements Plugin {
+  name = 'chat-logger';
+  private stream?: fs.WriteStream;
+
+  initialize(bot: BotAPI): void {
+    this.stream = fs.createWriteStream('chat.log', { flags: 'a' });
+
+    bot.on('chat', (message: string, isOverlay: boolean) => {
+      if (isOverlay) return;
+      const timestamp = new Date().toISOString();
+      this.stream?.write(`[${timestamp}] ${message}\n`);
+    });
+  }
+
+  destroy(): void {
+    this.stream?.end();
+  }
+}
+```
+
+## Örnek 4: Guard Bot Plugin
+
+Belirli bir alanı korur ve yaklaşan varlıklara saldırır:
+
+```typescript
+import { type Plugin, type BotAPI, type Entity, Vec3 } from 'specprotocol';
+
+export class GuardPlugin implements Plugin {
+  name = 'guard';
+  private bot!: BotAPI;
+  private guardCenter!: Vec3;
+  private guardRadius: number;
+  private interval?: ReturnType<typeof setInterval>;
+
+  constructor(radius: number = 10) {
+    this.guardRadius = radius;
+  }
+
+  initialize(bot: BotAPI): void {
+    this.bot = bot;
+
+    bot.on('spawn', () => {
+      this.guardCenter = bot.position.clone();
+      this.startGuarding();
+    });
+  }
+
+  private startGuarding(): void {
+    this.interval = setInterval(() => {
+      const nearest = this.bot.entities.getNearestTo(
+        this.guardCenter,
+        (entity: Entity) => {
+          if (entity.id === this.bot.entityId) return false;
+          return entity.position.distanceTo(this.guardCenter) <= this.guardRadius;
+        }
+      );
+
+      if (nearest && nearest.position.distanceTo(this.bot.position) <= 3) {
+        this.bot.lookAt(nearest.position);
+        this.bot.attack(nearest);
+      }
+    }, 500);
+  }
+
+  destroy(): void {
+    if (this.interval) clearInterval(this.interval);
+  }
+}
+
+// Kullanım:
+// const bot = await createBot({ ..., plugins: [new GuardPlugin(15)] });
+```
+
+## Plugin'leri Kullanma
+
+```typescript
+import { createBot } from 'specprotocol';
+import { AutoRespawnPlugin } from './plugins/auto-respawn';
+import { AntiAFKPlugin } from './plugins/anti-afk';
+import { ChatLoggerPlugin } from './plugins/chat-logger';
+
+const bot = await createBot({
+  host: 'localhost',
+  username: 'Bot',
+  plugins: [
+    new AutoRespawnPlugin(),
+    new AntiAFKPlugin(),
+    new ChatLoggerPlugin(),
+  ],
+});
+```
+
+## Runtime'da Plugin Yönetimi
+
+```typescript
+// Çalışırken plugin ekle
+bot.plugins.register(new MyPlugin());
+
+// Plugin kaldır
+bot.plugins.unregister('my-plugin');
+
+// Plugin var mı kontrol
+if (bot.plugins.has('auto-respawn')) {
+  console.log('Auto-respawn aktif');
+}
+```

package/docs/guides/raw-packets.md

@@ -0,0 +1,80 @@
+# 📦 Raw Packet Erişimi
+
+SpecProtocol, protokol paketlerine doğrudan erişim sağlar.
+
+## Tüm Paketleri Dinleme
+
+```typescript
+bot.on('rawPacket', (packet) => {
+  console.log(`ID: 0x${packet.id.toString(16)} | ${packet.data.length} bytes`);
+});
+```
+
+## Belirli Paketleri Dinleme
+
+```typescript
+import { PlayClientboundPackets, BufferReader } from 'specprotocol';
+
+// Keep Alive paketlerini dinle
+bot.onPacket(PlayClientboundPackets.KEEP_ALIVE, (data) => {
+  const reader = new BufferReader(data);
+  const keepAliveId = reader.readLong();
+  console.log(`Keep Alive: ${keepAliveId}`);
+});
+```
+
+## Ham Paket Gönderme
+
+```typescript
+import { BufferWriter, PlayServerboundPackets } from 'specprotocol';
+
+// Özel paket oluştur ve gönder
+const writer = new BufferWriter();
+writer.writeVarInt(1);        // Entity ID
+writer.writeVarInt(1);        // Type: Attack
+writer.writeBool(false);      // Sneaking
+
+bot.sendPacket(PlayServerboundPackets.INTERACT, writer.toBuffer());
+```
+
+## Hex Dump ile Debug
+
+```typescript
+bot.on('rawPacket', (packet) => {
+  const hex = packet.data.subarray(0, 32).toString('hex');
+  console.log(`[0x${packet.id.toString(16).padStart(2, '0')}] ${packet.data.length}b | ${hex}`);
+});
+```
+
+## Bilinmeyen Paketleri Analiz Etme
+
+```typescript
+bot.on('rawPacket', (packet) => {
+  // Tanınmayan paketleri logla
+  const knownIds = new Set([0x01, 0x09, 0x1D, 0x27, 0x28, 0x2C, 0x3A, 0x42, 0x5B, 0x73]);
+  if (!knownIds.has(packet.id)) {
+    console.log(`Bilinmeyen paket: 0x${packet.id.toString(16)} (${packet.data.length} bytes)`);
+  }
+});
+```
+
+## Paket Istatistikleri
+
+```typescript
+const stats = new Map<number, { count: number; bytes: number }>();
+
+bot.on('rawPacket', (packet) => {
+  const existing = stats.get(packet.id) ?? { count: 0, bytes: 0 };
+  existing.count++;
+  existing.bytes += packet.data.length;
+  stats.set(packet.id, existing);
+});
+
+// Her 10 saniyede istatistikleri yazdır
+setInterval(() => {
+  console.log('\n--- Paket İstatistikleri ---');
+  for (const [id, stat] of [...stats.entries()].sort((a, b) => b[1].count - a[1].count)) {
+    console.log(`0x${id.toString(16).padStart(2, '0')}: ${stat.count} paket, ${stat.bytes} bytes`);
+  }
+}, 10000);
+```

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "specprotocol",
+  "version": "1.0.0",
+  "description": "A Minecraft bot framework built from scratch in TypeScript — Mineflayer alternative with full protocol support for Java Edition 1.21.4",
+  "main": "dist/index.js",
+  "bin": {
+    "specprotocol": "./bin/specprotocol.js"
+  },
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build",
+    "example:basic": "npx tsx examples/basic-bot.ts",
+    "example:guard": "npx tsx examples/guard-bot.ts"
+  },
+  "keywords": [
+    "minecraft",
+    "bot",
+    "mineflayer",
+    "typescript",
+    "protocol",
+    "minecraft-bot",
+    "java-edition",
+    "game-bot",
+    "automation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "eslint": "^10.0.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ]
+}