specprotocol 1.0.0

package/docs/api/protocol.md

@@ -0,0 +1,129 @@
+# 🔌 Protokol Katmanı
+
+SpecProtocol, Minecraft Java Edition protokolünü sıfırdan implemente eder.
+
+## Bağlantı Akışı
+
+```
+[TCP Connect] → [Handshake] → [Login] → [Compression] → [Configuration] → [Play]
+```
+
+## Connection Sınıfı
+
+TCP bağlantısını yönetir: paket framing, compression, encryption.
+
+```typescript
+import { Connection } from 'specprotocol';
+
+const conn = new Connection({
+  host: 'localhost',
+  port: 25565,
+});
+
+await conn.connect();
+conn.on('packet', (packet) => { /* ... */ });
+conn.sendPacket(0x00, data);
+
+conn.enableCompression(256);
+conn.enableEncryption(sharedSecret);
+conn.disconnect();
+```
+
+## Veri Tipleri
+
+Minecraft protokolü özel veri tipleri kullanır:
+
+| Tip | Boyut | Açıklama |
+|-----|-------|----------|
+| VarInt | 1-5 byte | Değişken uzunluklu integer |
+| VarLong | 1-10 byte | Değişken uzunluklu long |
+| String | N byte | Length-prefixed UTF-8 |
+| UUID | 16 byte | İki Long olarak |
+| Boolean | 1 byte | 0x00 veya 0x01 |
+| Byte | 1 byte | İşaretli (-128 to 127) |
+| UByte | 1 byte | İşaretsiz (0-255) |
+| Short | 2 byte | Big-endian |
+| Int | 4 byte | Big-endian |
+| Long | 8 byte | Big-endian, BigInt |
+| Float | 4 byte | IEEE 754 |
+| Double | 8 byte | IEEE 754 |
+| Position | 8 byte | x(26) \| z(26) \| y(12) |
+
+## Paket Yapısı
+
+```
+Sıkıştırmasız:
+┌─────────┬───────────┬──────┐
+│ Length   │ Packet ID │ Data │
+│ VarInt   │ VarInt    │ ...  │
+└─────────┴───────────┴──────┘
+
+Sıkıştırmalı:
+┌─────────┬─────────────┬──────────────────┐
+│ Length   │ Data Length  │ Compressed Data  │
+│ VarInt   │ VarInt (0=no)│ Zlib            │
+└─────────┴─────────────┴──────────────────┘
+```
+
+## Encryption
+
+AES/CFB8 şifreleme, Login sırasında etkinleştirilir:
+
+```typescript
+import { generateSharedSecret, encryptRSA, computeServerHash } from 'specprotocol';
+
+const secret = generateSharedSecret();           // 16 byte random
+const encrypted = encryptRSA(publicKey, secret);  // RSA PKCS1
+const hash = computeServerHash(serverId, secret, publicKey); // Notch's hex digest
+```
+
+## Protokol State'leri
+
+### Handshake (0x00)
+```typescript
+import { buildHandshakePacket, PROTOCOL_VERSION, NextState } from 'specprotocol';
+```
+
+### Login
+```typescript
+import {
+  LoginServerboundPackets,
+  LoginClientboundPackets,
+  buildLoginStartPacket,
+  buildEncryptionResponsePacket,
+  // ...
+} from 'specprotocol';
+```
+
+### Play (1.21.4)
+
+**Serverbound (Client → Server):**
+
+| ID | Paket |
+|----|-------|
+| `0x00` | Confirm Teleportation |
+| `0x06` | Chat Message |
+| `0x0A` | Client Information |
+| `0x13` | Interact |
+| `0x18` | Keep Alive |
+| `0x1A` | Position |
+| `0x1B` | Position + Rotation |
+| `0x24` | Player Action |
+| `0x2F` | Set Held Item |
+| `0x36` | Swing Arm |
+
+**Clientbound (Server → Client):**
+
+| ID | Paket |
+|----|-------|
+| `0x01` | Spawn Entity |
+| `0x09` | Block Update |
+| `0x1D` | Disconnect |
+| `0x27` | Keep Alive |
+| `0x28` | Chunk Data |
+| `0x2C` | Login (Play) |
+| `0x3A` | Player Abilities |
+| `0x40` | Player Info Update |
+| `0x42` | Synchronize Player Position |
+| `0x5B` | Set Health |
+| `0x73` | System Chat |

package/docs/api/world.md

@@ -0,0 +1,138 @@
+# 🌍 World (Dünya) Yönetimi
+
+## World Sınıfı
+
+```typescript
+bot.world  // World instance'ına erişim
+```
+
+### Properties
+
+```typescript
+bot.world.dimension    // string — "minecraft:overworld", "minecraft:the_nether", vb.
+bot.world.seaLevel     // number — Deniz seviyesi (varsayılan: 63)
+```
+
+### Blok Erişimi
+
+```typescript
+// Tek blok oku
+const block = bot.world.getBlock(10, 64, 20);
+// Döndürür: { stateId: number } | null
+
+// Blok güncelle
+bot.world.setBlock(10, 64, 20, 1);
+```
+
+### Chunk Yönetimi
+
+```typescript
+// Chunk var mı?
+bot.world.hasChunk(0, 0);  // boolean (chunk X, chunk Z)
+
+// Chunk al
+const chunk = bot.world.getChunk(0, 0);  // ChunkColumn | undefined
+```
+
+## ChunkColumn
+
+Bir chunk kolonu, 24 tane `ChunkSection` (16x16x16) içerir (Y: -64 → 319).
+
+```typescript
+const chunk = bot.world.getChunk(0, 0);
+
+// Section'a erişim (0-23 arası, Y offset: -64)
+const section = chunk?.getSection(4); // Y: 0-15 arası section
+```
+
+## ChunkSection
+
+```typescript
+// Blok al (section-içi koordinatlar: 0-15)
+const block = section?.getBlock(8, 0, 8); // { stateId: number }
+
+// Blok set et
+section?.setBlock(8, 0, 8, 42);
+```
+
+## Block Update Event
+
+```typescript
+bot.on('blockUpdate', (x, y, z, stateId) => {
+  console.log(`(${x}, ${y}, ${z}) → stateId: ${stateId}`);
+});
+```
+
+---
+
+# 👾 Entity (Varlık) Yönetimi
+
+## EntityManager
+
+```typescript
+bot.entities  // EntityManager instance'ına erişim
+```
+
+### Varlık Sorgulama
+
+```typescript
+// ID ile bul
+const entity = bot.entities.getById(42);
+
+// UUID ile bul
+const player = bot.entities.getByUUID('550e8400-...');
+
+// En yakını bul
+const nearest = bot.entities.getNearestTo(bot.position);
+
+// Filtreli en yakın
+const nearestMob = bot.entities.getNearestTo(bot.position, (e) => {
+  return e.id !== bot.entityId; // Kendini hariç tut
+});
+
+// Yarıçapta ara
+const nearby = bot.entities.getInRadius(bot.position, 10);
+
+// Tüm varlıklar
+const all = bot.entities.getAll();
+```
+
+## Entity Sınıfı
+
+```typescript
+entity.id         // number — Entity ID
+entity.uuid       // string — UUID
+entity.type       // number — Entity type ID
+entity.position   // Vec3 — Pozisyon
+entity.velocity   // Vec3 — Hız vektörü
+entity.yaw        // number — Yatay yön (derece)
+entity.pitch      // number — Dikey yön (derece)
+entity.onGround   // boolean — Yerde mi?
+entity.metadata    // Map<number, any> — NBT metadata
+```
+
+## PlayerEntity
+
+`Entity`'den türer, ek player bilgileri içerir:
+
+```typescript
+if (entity instanceof PlayerEntity) {
+  entity.username  // string
+  entity.gameMode  // number
+  entity.ping      // number
+}
+```
+
+## Entity Events
+
+```typescript
+// Yeni varlık doğduğunda
+bot.on('entitySpawn', (entity: Entity) => {
+  console.log(`Yeni: ${entity.id} pos=${entity.position}`);
+});
+
+// Varlık kaldırıldığında
+bot.on('entityRemove', (entityId: number) => {
+  console.log(`Kaldırıldı: ${entityId}`);
+});
+```

package/docs/first-bot.md

@@ -0,0 +1,114 @@
+# 🤖 İlk Botunuzu Yazın
+
+Bu rehber adım adım bir Minecraft botu oluşturmanızı gösterir.
+
+## 1. Proje Oluşturun
+
+```bash
+mkdir my-mc-bot && cd my-mc-bot
+npm init -y
+npm install specprotocol
+npm install -D typescript @types/node tsx
+```
+
+## 2. Bot Kodunu Yazın
+
+`src/index.ts` dosyası oluşturun:
+
+```typescript
+import { createBot, LogLevel } from 'specprotocol';
+
+async function main() {
+  // Sunucuya bağlan
+  const bot = await createBot({
+    host: 'localhost',
+    port: 25565,
+    username: 'MyFirstBot',
+    auth: 'offline',
+    logLevel: LogLevel.INFO,
+  });
+
+  // Dünyada doğduğunda
+  bot.on('spawn', () => {
+    console.log(`✅ Bot doğdu! Pozisyon: ${bot.position}`);
+    bot.chat('Merhaba herkese!');
+  });
+
+  // Chat mesajı geldiğinde
+  bot.on('chat', (message, isOverlay) => {
+    if (isOverlay) return; // Actionbar mesajlarını atla
+
+    console.log(`💬 ${message}`);
+
+    // Komutlara yanıt ver
+    if (message.includes('!ping')) {
+      bot.chat('Pong! 🏓');
+    }
+
+    if (message.includes('!pos')) {
+      const pos = bot.position;
+      bot.chat(`Pozisyonum: X=${pos.x.toFixed(1)} Y=${pos.y.toFixed(1)} Z=${pos.z.toFixed(1)}`);
+    }
+
+    if (message.includes('!health')) {
+      bot.chat(`❤️ Can: ${bot.health}/20 | 🍖 Açlık: ${bot.food}/20`);
+    }
+  });
+
+  // Sağlık değiştiğinde
+  bot.on('health', (health, food, saturation) => {
+    console.log(`❤️ Can: ${health} | 🍖 Yemek: ${food}`);
+
+    if (health <= 0) {
+      console.log('💀 Bot öldü!');
+    }
+  });
+
+  // Pozisyon sunucu tarafından güncellendiğinde
+  bot.on('position', (pos) => {
+    console.log(`📍 Yeni pozisyon: ${pos}`);
+  });
+
+  // Sunucudan atıldığında
+  bot.on('kicked', (reason) => {
+    console.log(`🚫 Sunucudan atıldı: ${reason}`);
+  });
+
+  // Bağlantı hatası
+  bot.on('error', (err) => {
+    console.error('❌ Hata:', err.message);
+  });
+
+  // Bağlantı kesildiğinde
+  bot.on('end', () => {
+    console.log('🔌 Bağlantı kesildi');
+    process.exit(0);
+  });
+
+  // CTRL+C ile düzgün kapatma
+  process.on('SIGINT', () => {
+    bot.disconnect();
+  });
+}
+
+main().catch(console.error);
+```
+
+## 3. Çalıştırın
+
+```bash
+npx tsx src/index.ts
+```
+
+## 4. Test Edin
+
+Minecraft istemcinizle aynı sunucuya bağlanın ve chat'e yazın:
+- `!ping` — Bot "Pong! 🏓" yanıtı verir
+- `!pos` — Bot kendi pozisyonunu yazar
+- `!health` — Bot sağlık bilgisini yazar
+
+## Sonraki Adımlar
+
+- [Bot API Referansı](./api/bot.md) — Tüm bot metodları
+- [Event Sistemi](./api/events.md) — Tüm olaylar
+- [Plugin Sistemi](./api/plugins.md) — Kendi eklentinizi yazın

package/docs/getting-started.md

@@ -0,0 +1,103 @@
+# 🚀 Kurulum & Hızlı Başlangıç
+
+## Kurulum
+
+```bash
+npm install specprotocol
+```
+
+> **Gereksinimler:** Node.js ≥ 18, Minecraft Java Edition 1.21.4 sunucusu
+
+## Hızlı Başlangıç
+
+### Offline Mod (Cracked Sunucu)
+
+```typescript
+import { createBot } from 'specprotocol';
+
+const bot = await createBot({
+  host: 'localhost',
+  port: 25565,
+  username: 'MyBot',
+  auth: 'offline',
+});
+
+bot.on('spawn', () => {
+  console.log('Bot dünyada doğdu!');
+  bot.chat('Merhaba dünya! 🤖');
+});
+```
+
+### Microsoft Girişli (Online Sunucu)
+
+```typescript
+import { createBot } from 'specprotocol';
+
+const bot = await createBot({
+  host: 'play.example.com',
+  port: 25565,
+  username: 'SteveBot',
+  auth: 'microsoft',
+});
+
+// Microsoft giriş yapıldığında terminalde bir kod ve URL gösterilir.
+// Tarayıcıda URL'yi açıp kodu girin, bot otomatik bağlanacak.
+```
+
+## Tüm Seçenekler
+
+```typescript
+const bot = await createBot({
+  // Zorunlu
+  host: 'localhost',          // Sunucu adresi
+  username: 'BotAdi',        // Bot kullanıcı adı
+
+  // Opsiyonel
+  port: 25565,                // Sunucu portu (varsayılan: 25565)
+  auth: 'offline',            // 'offline' veya 'microsoft'
+  viewDistance: 10,            // İstenen görüş mesafesi
+  logLevel: LogLevel.INFO,    // DEBUG, INFO, WARN, ERROR
+  plugins: [],                // Yüklenecek eklentiler
+});
+```
+
+## LogLevel Seviyeleri
+
+```typescript
+import { LogLevel } from 'specprotocol';
+
+LogLevel.DEBUG  // Her şeyi logla (paket detayları dahil)
+LogLevel.INFO   // Normal bilgiler (bağlantı, spawn, vb.)
+LogLevel.WARN   // Sadece uyarılar ve hatalar
+LogLevel.ERROR  // Sadece hatalar
+```
+
+## Proje Yapısı
+
+Tipik bir bot projesi şöyle görünür:
+
+```
+my-bot/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts          # Ana bot dosyası
+│   └── plugins/
+│       └── my-plugin.ts  # Kendi eklentiniz
+```
+
+### Minimal tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}
+```

package/docs/guides/architecture.md

@@ -0,0 +1,122 @@
+# 🏗️ Mimari & Tasarım Kararları
+
+## Genel Bakış
+
+SpecProtocol, modüler katmanlı bir mimariye sahiptir:
+
+```
+┌──────────────────────────────────────────┐
+│              Bot (Orkestratör)            │
+├────────┬─────────┬───────────┬───────────┤
+│ World  │ Entity  │ Plugins   │ Auth      │
+│ Manager│ Manager │ Manager   │ Module    │
+├────────┴─────────┴───────────┴───────────┤
+│             Protocol Layer               │
+├────────┬─────────┬───────────┬───────────┤
+│ Packet │ Types   │ Compress  │ Encrypt   │
+│ Frame  │ VarInt  │ Zlib      │ AES/CFB8  │
+├────────┴─────────┴───────────┴───────────┤
+│           TCP Connection (net)            │
+└──────────────────────────────────────────┘
+```
+
+## Tasarım Kararları
+
+### 1. Sıfırdan Yazılmış Protokol
+
+**Neden?**
+- `node-minecraft-protocol` gibi kütüphanelere bağımlılık yok
+- Her byte üzerinde tam kontrol
+- Eğitim amaçlı: protokolün nasıl çalıştığını anlama
+- Özelleştirme: istenen herhangi bir versiyona uyarlama
+
+### 2. TypeScript-First
+
+**Neden?**
+- Compile-time hata yakalama
+- IDE otomatik tamamlama
+- Tip-güvenli event sistemi
+- Daha okunabilir API
+
+### 3. Event-Driven Mimari
+
+**Neden?**
+- Node.js'in doğal async yapısına uygun
+- Gevşek bağlı bileşenler
+- Plugin sistemi kolayca entegre olur
+- Kullanıcı dostane API
+
+### 4. Plugin Sistemi
+
+**Neden?**
+- Modülerlik: özellikler bağımsız olarak eklenebilir/kaldırılabilir
+- Genişletilebilirlik: topluluk katkısına açık
+- Test edilebilirlik: her plugin bağımsız test edilebilir
+- BotAPI interface ile circular dependency önleme
+
+## Bağlantı Akışı (Detaylı)
+
+```
+1. TCP Socket → net.createConnection()
+2. Handshake Paketi → Protocol Version + Host + Port + NextState
+3. Login Start → Username + UUID
+4. [Opsiyonel] Encryption Request/Response → RSA + AES/CFB8
+5. Set Compression → Zlib threshold
+6. Login Success → Authenticated username + UUID
+7. Login Acknowledged → Geçiş: Login → Configuration
+8. Configuration State:
+   - Plugin Message → Sunucu bilgileri
+   - Feature Flags → Sunucu özellikleri
+   - Known Packs → Kaynak paket müzakeresi
+   - Registry Data × 12 → Biome, dimension, entity tipleri vb.
+   - Update Tags → Blok/item etiketleri
+   - Finish Configuration → Geçiş: Configuration → Play
+9. Play State:
+   - Login (Play) → Entity ID, dimension, game mode
+   - Player Abilities → Uçma hızı, yürüme hızı
+   - Synchronize Player Position → İlk spawn pozisyonu
+   - Chunk Data × N → Dünya verisi
+   - Keep Alive ← → 30 saniyede bir, cevap verilmezse kick
+```
+
+## Dosya Yapısı
+
+```
+src/
+├── index.ts              # Public API — sadece gerekli exportlar
+├── bot.ts                # Bot: ana sınıf, tüm alt sistemleri koordine eder
+├── types.ts              # BotAPI interface (circular dep çözümü)
+│
+├── utils/
+│   ├── vec3.ts           # 3D vektör: pozisyon, hız, yön hesaplamaları
+│   ├── logger.ts         # Seviyeli loglama: DEBUG → INFO → WARN → ERROR
+│   └── events.ts         # TypedEventEmitter: tip-güvenli olaylar
+│
+├── protocol/
+│   ├── types.ts          # VarInt, VarLong, String, UUID, BufferReader/Writer
+│   ├── packet.ts         # Paket framing, splitting, registry
+│   ├── connection.ts     # TCP bağlantı yönetimi + compression + encryption
+│   ├── compression.ts    # Zlib deflate/inflate
+│   ├── encryption.ts     # AES/CFB8 + RSA + server hash
+│   └── states/
+│       ├── handshake.ts  # Handshake paketi
+│       ├── login.ts      # Login state paketleri
+│       └── play.ts       # Play state paketleri (1.21.4 packet ID'leri)
+│
+├── auth/
+│   ├── offline.ts        # Offline UUID generation (MD5-based v3)
+│   └── microsoft.ts      # Microsoft OAuth2 → Xbox → XSTS → MC → Profile
+│
+├── entity/
+│   └── entity.ts         # Entity, PlayerEntity, EntityManager
+│
+├── world/
+│   ├── block.ts          # Block, ChunkSection, ChunkColumn
+│   └── world.ts          # World: chunk depolama, blok erişimi
+│
+└── plugins/
+    ├── plugin-manager.ts # Plugin yaşam döngüsü yönetimi
+    └── built-in/
+        ├── chat.ts       # ChatPlugin: mesaj gönder/al
+        └── combat.ts     # CombatPlugin: saldırı, item kullanma
+```