specprotocol 1.0.0

package/docs/api/auth.md

@@ -0,0 +1,210 @@
+# 🔐 Authentication (Kimlik Doğrulama)
+
+SpecProtocol iki kimlik doğrulama modu destekler.
+
+## Offline Mod
+
+Cracked (lisanssız) sunucular için. UUID, kullanıcı adından üretilir.
+
+```typescript
+const bot = await createBot({
+  host: 'localhost',
+  username: 'Bot',
+  auth: 'offline',
+});
+```
+
+### offlineUUID Fonksiyonu
+
+```typescript
+import { offlineUUID, createOfflineProfile } from 'specprotocol';
+
+// UUID üret (deterministik — aynı isim = aynı UUID)
+const uuid = offlineUUID('Steve');
+// → "abccda02-8f11-3f9b-9e0f-d5336ec6b535"
+
+// Tam profil
+const profile = createOfflineProfile('Steve');
+// → { username: 'Steve', uuid: '...' }
+```
+
+## Microsoft Girişi
+
+Online (lisanslı) sunucular için. Device Code Flow kullanır.
+
+```typescript
+const bot = await createBot({
+  host: 'online-server.com',
+  username: 'Steve',  // Gerçek Minecraft adınız ile değiştirilecek
+  auth: 'microsoft',
+});
+```
+
+### Giriş Akışı
+
+1. Bot terminalde bir kod ve URL gösterir
+2. Tarayıcınızda `https://microsoft.com/link` adresini açarsınız
+3. Gösterilen kodu girersiniz
+4. Microsoft hesabınızla giriş yaparsınız
+5. Bot otomatik olarak bağlanır
+
+```
+════════════════════════════════════════
+Open this URL: https://microsoft.com/link
+Enter code: ABCD-1234
+════════════════════════════════════════
+```
+
+### Kimlik Doğrulama Zinciri
+
+```
+Microsoft OAuth2 (Device Code)
+    ↓
+Xbox Live Token
+    ↓
+XSTS Token
+    ↓
+Minecraft Access Token
+    ↓
+Minecraft Profile (UUID + username)
+    ↓
+Session Server Join
+```
+
+### Gelişmiş Kullanım
+
+```typescript
+import { authenticateMicrosoft, joinServer } from 'specprotocol';
+
+// Manuel authentication
+const result = await authenticateMicrosoft((code, uri) => {
+  console.log(`Kod: ${code}, URL: ${uri}`);
+});
+
+console.log(result.username);     // Minecraft kullanıcı adı
+console.log(result.uuid);         // Minecraft UUID
+console.log(result.accessToken);  // Minecraft access token
+
+// Session server'a katılma
+await joinServer(accessToken, uuid, serverHash);
+```
+
+---
+
+# 📐 Vec3 — 3D Vektör
+
+Koordinat ve uzaysal hesaplamalar için kullanılır.
+
+```typescript
+import { Vec3 } from 'specprotocol';
+```
+
+## Oluşturma
+
+```typescript
+const v = new Vec3(10, 64, 20);
+const zero = Vec3.zero();           // (0, 0, 0)
+const fromArr = Vec3.from([1, 2, 3]);
+```
+
+## Properties
+
+```typescript
+v.x  // number
+v.y  // number
+v.z  // number
+```
+
+## Aritmetik
+
+```typescript
+const a = new Vec3(1, 2, 3);
+const b = new Vec3(4, 5, 6);
+
+a.add(b)         // Vec3(5, 7, 9)
+a.subtract(b)    // Vec3(-3, -3, -3)
+a.scale(2)       // Vec3(2, 4, 6)
+a.dot(b)         // number (skaler çarpım)
+a.cross(b)       // Vec3 (vektörel çarpım)
+```
+
+## Uzaklık & Büyüklük
+
+```typescript
+a.length()        // Vektör uzunluğu
+a.distanceTo(b)   // İki nokta arası mesafe
+a.normalize()     // Birim vektör (uzunluk = 1)
+```
+
+## Dönüşümler
+
+```typescript
+a.floor()          // Aşağı yuvarla (blok koordinatı)
+a.clone()          // Kopyala
+a.toArray()        // [x, y, z]
+a.toString()       // "Vec3(1, 2, 3)"
+a.equals(b)        // Eşitlik kontrolü
+```
+
+---
+
+# 📝 BufferReader & BufferWriter
+
+Paket verisi okuma/yazma için kullanılır.
+
+```typescript
+import { BufferReader, BufferWriter } from 'specprotocol';
+```
+
+## BufferWriter
+
+```typescript
+const writer = new BufferWriter();
+writer.writeVarInt(42);
+writer.writeString('hello');
+writer.writeBool(true);
+writer.writeFloat(3.14);
+writer.writeDouble(2.718);
+writer.writeLong(123456n);
+writer.writeByte(-1);
+writer.writeUByte(255);
+writer.writeShort(1000);
+writer.writeUShort(65535);
+writer.writeInt(100000);
+writer.writeUUID('550e8400-...');
+writer.writeBytes(Buffer.from([0x01, 0x02]));
+
+const buffer = writer.toBuffer();
+```
+
+## BufferReader
+
+```typescript
+const reader = new BufferReader(buffer);
+const a = reader.readVarInt();     // number
+const b = reader.readString();     // string
+const c = reader.readBool();       // boolean
+const d = reader.readFloat();      // number
+const e = reader.readDouble();     // number
+const f = reader.readLong();       // bigint
+const g = reader.readByte();       // number (-128..127)
+const h = reader.readUByte();      // number (0..255)
+const i = reader.readShort();      // number
+const j = reader.readUShort();     // number
+const k = reader.readInt();        // number
+const l = reader.readUUID();       // string
+const m = reader.readByteArray();  // Buffer
+
+reader.offset    // Mevcut okuma pozisyonu
+reader.remaining // Kalan byte sayısı
+```
+
+## Standalone Fonksiyonlar
+
+```typescript
+import { readVarInt, writeVarInt, varIntSize } from 'specprotocol';
+
+const buf = writeVarInt(300);
+const { value, bytesRead } = readVarInt(buf);
+const size = varIntSize(300); // 2 byte
+```

package/docs/api/bot.md

@@ -0,0 +1,137 @@
+# 🤖 Bot API Referansı
+
+`Bot` sınıfı, tüm alt sistemleri koordine eden ana orkestratör sınıftır.
+
+## Oluşturma
+
+```typescript
+import { createBot, Bot, type BotOptions } from 'specprotocol';
+
+// Factory function (önerilen)
+const bot = await createBot(options);
+
+// Manual oluşturma
+const bot = new Bot(options);
+await bot.connect();
+```
+
+## BotOptions
+
+| Parametre | Tip | Varsayılan | Açıklama |
+|-----------|-----|------------|----------|
+| `host` | `string` | **zorunlu** | Sunucu adresi |
+| `port` | `number` | `25565` | Sunucu portu |
+| `username` | `string` | **zorunlu** | Bot kullanıcı adı |
+| `auth` | `'offline' \| 'microsoft'` | `'offline'` | Kimlik doğrulama modu |
+| `version` | `number` | `769` | Protokol versiyonu |
+| `viewDistance` | `number` | `10` | Görüş mesafesi |
+| `logLevel` | `LogLevel` | `INFO` | Log seviyesi |
+| `plugins` | `Plugin[]` | `[]` | Yüklenecek eklentiler |
+
+## Properties (Salt Okunur)
+
+```typescript
+bot.username     // string — Bot kullanıcı adı
+bot.uuid         // string — Bot UUID'si
+bot.entityId     // number — Bot'un entity ID'si
+bot.health       // number — Can (0-20)
+bot.food         // number — Açlık (0-20)
+bot.saturation   // number — Tokluk değeri
+bot.gameMode     // number — 0=survival, 1=creative, 2=adventure, 3=spectator
+bot.isAlive      // boolean — Hayatta mı?
+bot.position     // Vec3 — Mevcut pozisyon
+```
+
+## Alt Sistemler
+
+```typescript
+bot.world        // World — Dünya yöneticisi (bloklar, chunk'lar)
+bot.entities     // EntityManager — Varlık takibi
+bot.plugins      // PluginManager — Eklenti yönetimi
+bot.entity       // Entity — Bot'un kendi entity'si
+```
+
+## Metodlar
+
+### `chat(message: string): void`
+Chat mesajı gönderir.
+
+```typescript
+bot.chat('Merhaba!');
+bot.chat('/gamemode creative'); // Komut da gönderebilirsiniz
+```
+
+### `attack(entity: Entity): void`
+Bir varlığa saldırır.
+
+```typescript
+const nearest = bot.entities.getNearestTo(bot.position);
+if (nearest) {
+  bot.attack(nearest);
+}
+```
+
+### `setPosition(x, y, z, onGround?): void`
+Bot'un pozisyonunu günceller ve sunucuya bildirir.
+
+```typescript
+bot.setPosition(100, 64, 200);
+bot.setPosition(100, 64, 200, false); // havada
+```
+
+### `setPositionAndRotation(x, y, z, yaw, pitch, onGround?): void`
+Pozisyon ve yönü birlikte günceller.
+
+```typescript
+bot.setPositionAndRotation(100, 64, 200, 90, 0);
+```
+
+### `lookAt(target: Vec3): void`
+Belirtilen koordinata bakar.
+
+```typescript
+import { Vec3 } from 'specprotocol';
+bot.lookAt(new Vec3(100, 65, 200));
+```
+
+### `dig(x, y, z, face?): void`
+Bir bloğu kırmaya başlar. Creative modda anında kırar.
+
+```typescript
+bot.dig(10, 64, 20);       // Üst yüzden
+bot.dig(10, 64, 20, 0);    // Alt yüzden (face: 0=bottom, 1=top, 2-5=sides)
+```
+
+### `setHeldItem(slot: number): void`
+Hotbar slotunu seçer (0-8).
+
+```typescript
+bot.setHeldItem(0); // İlk slot
+bot.setHeldItem(4); // 5. slot
+```
+
+### `disconnect(): void`
+Sunucudan bağlantıyı keser.
+
+```typescript
+bot.disconnect();
+```
+
+### `sendPacket(packetId, data): void`
+Sunucuya ham paket gönderir (gelişmiş kullanım).
+
+```typescript
+import { BufferWriter } from 'specprotocol';
+const writer = new BufferWriter();
+writer.writeString('hello');
+bot.sendPacket(0x06, writer.toBuffer());
+```
+
+### `onPacket(packetId, handler): void`
+Belirli bir paket ID'si için dinleyici ekler (plugin'ler için).
+
+```typescript
+bot.onPacket(0x27, (data) => {
+  console.log('Keep-alive paketi alındı');
+});
+```

package/docs/api/events.md

@@ -0,0 +1,166 @@
+# 📡 Event (Olay) Sistemi
+
+SpecProtocol, tip-güvenli bir event sistemi kullanır. Tüm eventler tam tip desteğiyle gelir.
+
+## Bot Events
+
+### `spawn`
+Bot dünyada doğduğunda tetiklenir.
+
+```typescript
+bot.on('spawn', () => {
+  console.log('Dünyaya girdim!');
+});
+```
+
+### `chat`
+Chat mesajı alındığında tetiklenir.
+
+```typescript
+bot.on('chat', (message: string, isOverlay: boolean) => {
+  // message: Mesaj metni (JSON bileşenlerinden çıkarılmış)
+  // isOverlay: true ise actionbar mesajı, false ise normal chat
+  if (!isOverlay) {
+    console.log(`Chat: ${message}`);
+  }
+});
+```
+
+### `health`
+Sağlık değiştiğinde tetiklenir.
+
+```typescript
+bot.on('health', (health: number, food: number, saturation: number) => {
+  // health: Can (0-20, float)
+  // food: Açlık seviyesi (0-20)
+  // saturation: Tokluk değeri (0-20)
+  console.log(`❤️ ${health}/20 | 🍖 ${food}/20`);
+});
+```
+
+### `death`
+Bot öldüğünde tetiklenir (health ≤ 0).
+
+```typescript
+bot.on('death', () => {
+  console.log('Öldüm!');
+});
+```
+
+### `position`
+Sunucu tarafından pozisyon güncellendiğinde tetiklenir (teleport, spawn).
+
+```typescript
+bot.on('position', (position: Vec3) => {
+  console.log(`Yeni konum: ${position}`);
+});
+```
+
+### `kicked`
+Sunucudan atıldığında tetiklenir.
+
+```typescript
+bot.on('kicked', (reason: string) => {
+  console.log(`Atıldım: ${reason}`);
+});
+```
+
+### `entitySpawn`
+Yakında yeni bir varlık doğduğunda tetiklenir.
+
+```typescript
+bot.on('entitySpawn', (entity: Entity) => {
+  console.log(`Yeni entity: ${entity.id} (tip: ${entity.type})`);
+});
+```
+
+### `entityRemove`
+Bir varlık kaldırıldığında tetiklenir.
+
+```typescript
+bot.on('entityRemove', (entityId: number) => {
+  console.log(`Entity ${entityId} kaldırıldı`);
+});
+```
+
+### `blockUpdate`
+Bir blok değiştiğinde tetiklenir.
+
+```typescript
+bot.on('blockUpdate', (x: number, y: number, z: number, stateId: number) => {
+  console.log(`Blok değişti: (${x}, ${y}, ${z}) → ${stateId}`);
+});
+```
+
+### `rawPacket`
+Her ham paket alındığında tetiklenir (gelişmiş kullanım).
+
+```typescript
+bot.on('rawPacket', (packet: RawPacket) => {
+  console.log(`Paket 0x${packet.id.toString(16)}: ${packet.data.length} bytes`);
+});
+```
+
+### `error`
+Bağlantı hatası oluştuğunda tetiklenir.
+
+```typescript
+bot.on('error', (error: Error) => {
+  console.error('Hata:', error.message);
+});
+```
+
+### `connect`
+Sunucuya TCP bağlantısı kurulduğunda tetiklenir.
+
+```typescript
+bot.on('connect', () => {
+  console.log('TCP bağlantısı kuruldu');
+});
+```
+
+### `end`
+Bağlantı kesildiğinde tetiklenir.
+
+```typescript
+bot.on('end', () => {
+  console.log('Bağlantı kapandı');
+  process.exit(0);
+});
+```
+
+## TypedEventEmitter
+
+SpecProtocol kendi tip-güvenli event emitter'ını kullanır:
+
+```typescript
+import { TypedEventEmitter } from 'specprotocol';
+
+interface MyEvents {
+  'ready': () => void;
+  'data': (value: number, label: string) => void;
+}
+
+class MyClass extends TypedEventEmitter<MyEvents> {
+  start() {
+    this.emit('ready');
+    this.emit('data', 42, 'answer');
+  }
+}
+
+const obj = new MyClass();
+obj.on('data', (value, label) => {
+  // value: number (otomatik çıkarım)
+  // label: string (otomatik çıkarım)
+});
+```
+
+### Metodlar
+
+| Metod | Açıklama |
+|-------|----------|
+| `on(event, listener)` | Dinleyici ekler |
+| `once(event, listener)` | Tek seferlik dinleyici |
+| `off(event, listener)` | Dinleyici kaldırır |
+| `emit(event, ...args)` | Olay tetikler |
+| `removeAllListeners(event?)` | Tüm dinleyicileri kaldırır |

package/docs/api/plugins.md

@@ -0,0 +1,207 @@
+# 🧩 Plugin Sistemi
+
+SpecProtocol, modüler bir eklenti sistemi sunar. Kendi pluginlerinizi yazarak bot'un işlevselliğini genişletebilirsiniz.
+
+## Dahili Pluginler
+
+### ChatPlugin
+Chat mesajı gönderme ve alma.
+
+```typescript
+// Otomatik yüklenir, doğrudan bot üzerinden kullanabilirsiniz:
+bot.chat('Merhaba!');
+```
+
+### CombatPlugin
+Saldırı ve item kullanma.
+
+```typescript
+// Otomatik yüklenir:
+bot.attack(entity);
+```
+
+## Plugin Interface
+
+```typescript
+import { type Plugin, type BotAPI } from 'specprotocol';
+
+interface Plugin {
+  /** Benzersiz eklenti adı */
+  name: string;
+
+  /** Bot bağlandığında başlatılır */
+  initialize(bot: BotAPI): void;
+
+  /** Eklenti kaldırıldığında çalışır (opsiyonel) */
+  destroy?(): void;
+}
+```
+
+## Kendi Plugininizi Yazma
+
+### Basit Örnek: Geri Sayım Plugin
+
+```typescript
+import { type Plugin, type BotAPI } from 'specprotocol';
+
+class CountdownPlugin implements Plugin {
+  name = 'countdown';
+  private bot!: BotAPI;
+
+  initialize(bot: BotAPI): void {
+    this.bot = bot;
+
+    bot.on('chat', (message: string) => {
+      if (message.includes('!countdown')) {
+        this.startCountdown(5);
+      }
+    });
+  }
+
+  private startCountdown(seconds: number): void {
+    let remaining = seconds;
+    const interval = setInterval(() => {
+      this.bot.chat(`⏰ ${remaining}...`);
+      remaining--;
+      if (remaining < 0) {
+        clearInterval(interval);
+        this.bot.chat('💥 BOOM!');
+      }
+    }, 1000);
+  }
+}
+
+// Kullanım:
+const bot = await createBot({
+  host: 'localhost',
+  username: 'Bot',
+  plugins: [new CountdownPlugin()],
+});
+```
+
+### Gelişmiş Örnek: Pozisyon Kayıt Plugin
+
+```typescript
+import { type Plugin, type BotAPI } from 'specprotocol';
+import { Vec3 } from 'specprotocol';
+
+class WaypointPlugin implements Plugin {
+  name = 'waypoints';
+  private bot!: BotAPI;
+  private waypoints = new Map<string, Vec3>();
+
+  initialize(bot: BotAPI): void {
+    this.bot = bot;
+
+    bot.on('chat', (message: string) => {
+      const parts = message.split(' ');
+
+      if (parts[1] === '!save') {
+        const name = parts[2];
+        if (name) {
+          const pos = bot.position;
+          this.waypoints.set(name, pos.clone());
+          bot.chat(`📍 "${name}" kaydedildi: ${pos}`);
+        }
+      }
+
+      if (parts[1] === '!list') {
+        if (this.waypoints.size === 0) {
+          bot.chat('Kayıtlı waypoint yok');
+          return;
+        }
+        for (const [name, pos] of this.waypoints) {
+          bot.chat(`📍 ${name}: ${pos}`);
+        }
+      }
+
+      if (parts[1] === '!goto') {
+        const name = parts[2];
+        const pos = this.waypoints.get(name ?? '');
+        if (pos) {
+          bot.chat(`🚶 "${name}" konumuna gidiyorum...`);
+          bot.setPosition(pos.x, pos.y, pos.z);
+        }
+      }
+    });
+  }
+
+  destroy(): void {
+    this.waypoints.clear();
+  }
+}
+```
+
+### Paket Dinleyicili Plugin
+
+```typescript
+import { type Plugin, type BotAPI, PlayClientboundPackets, BufferReader } from 'specprotocol';
+
+class BlockSpyPlugin implements Plugin {
+  name = 'block-spy';
+
+  initialize(bot: BotAPI): void {
+    // Ham paket dinle
+    bot.onPacket(PlayClientboundPackets.BLOCK_UPDATE, (data: Buffer) => {
+      const reader = new BufferReader(data);
+      const posValue = reader.readLong();
+      const blockId = reader.readVarInt();
+      console.log(`Blok değişti! ID: ${blockId}`);
+    });
+  }
+}
+```
+
+## PluginManager API
+
+```typescript
+// Plugin ekle
+bot.plugins.register(new MyPlugin());
+
+// Plugin kaldır
+bot.plugins.unregister('plugin-adi');
+
+// Plugin var mı?
+bot.plugins.has('plugin-adi'); // boolean
+
+// Plugin al
+const plugin = bot.plugins.get<MyPlugin>('plugin-adi');
+
+// Tüm plugin adları
+const names = bot.plugins.getAll(); // string[]
+
+// Tüm pluginleri kaldır
+bot.plugins.destroyAll();
+```
+
+## BotAPI Interface
+
+Plugin'lerin gördüğü bot arayüzü:
+
+```typescript
+interface BotAPI {
+  // Bilgiler
+  readonly username: string;
+  readonly uuid: string;
+  readonly entityId: number;
+  readonly health: number;
+  readonly food: number;
+  readonly position: Vec3;
+  readonly entity: Entity;
+  readonly world: World;
+  readonly entities: EntityManager;
+
+  // Aksiyonlar
+  sendPacket(packetId: number, data: Buffer): void;
+  onPacket(packetId: number, handler: (data: Buffer) => void): void;
+  chat(message: string): void;
+  attack(entity: Entity): void;
+  lookAt(target: Vec3): void;
+  disconnect(): void;
+
+  // Eventler
+  on(event: string, listener: (...args: any[]) => void): any;
+  once(event: string, listener: (...args: any[]) => void): any;
+  emit(event: string, ...args: any[]): boolean;
+}
+```