{"id":"luluwux/luee","name":"luee","scope":"luluwux","platform":"roblox","description":"Enterprise-grade framework-agnostic egg hatching system for Roblox","version":"2.0.1","latest":"2.0.1","versions":["2.0.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"7fe3c8ab3f6bc01a28293640b011af7ac787abdd6aff781bd1fff1f9b17c2085","likes":0,"downloads":0,"install":"forest install luluwux/luee","url":"https://forest.dev/p/roblox/luluwux/luee","files":"https://api.forest.dev/ai/package/roblox/luluwux/luee/files","readme":"# LUEE - Lulu's Universal Egg Engine\r\n\r\n**Framework-Agnostic** enterprise-grade egg hatching system for Roblox.\r\n\r\n[![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://github.com)\r\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\r\n[![Type Safety](https://img.shields.io/badge/strict--typing-100%25-brightgreen)](https://luau-lang.org)\r\n\r\n## 🎯 Features\r\n\r\n### Core Features\r\n- ✅ **Dynamic Batch Hatching**: 1 to 1000+ eggs in single request\r\n- ✅ **Flexible Rarity System**: Fully customizable tiers\r\n- ✅ **Rarity-Specific Luck**: Per-rarity luck multipliers\r\n- ✅ **Weight-Based Probability**: Precise odds (1/1M+)\r\n\r\n### Enterprise-Grade\r\n- ✅ **Pity System**: Guaranteed drops after threshold\r\n- ✅ **Pre-flight Checks**: Validate before processing\r\n- ✅ **Weight Caching**: 1000x performance boost\r\n- ✅ **Luck Stacking**: Multi-source luck aggregation\r\n\r\n### Architecture\r\n- ✅ **Framework-Agnostic**: Works with Knit, AGF, Vanilla, or any custom framework\r\n- ✅ **SOLID Principles**: Clean, maintainable architecture\r\n- ✅ **Strict Type Safety**: 100% Luau type coverage\r\n- ✅ **Zero Dependencies**: Core has no external requirements\r\n\r\n## 🏗️ Architecture\r\n\r\nLUEE follows the **\"Core & Bridge\"** pattern:\r\n\r\n```\r\nLUEE/\r\n├── Core/                    ← Framework-agnostic (Pure Lua)\r\n│   ├── Types.lua\r\n│   ├── Configuration/       ← Game data (eggs, rarities, pity)\r\n│   ├── Utilities/           ← Pure functions (WeightedRandom, PityTracker, etc)\r\n│   └── Modules/             ← Business logic\r\n│       ├── LuckManager      ← Stateful luck management\r\n│       └── EggHatcher       ← Main hatching engine\r\n│\r\n├── Bridge/                  ← Framework adapters (Optional)\r\n│   ├── KnitBridge           ← Knit Framework wrapper\r\n│   └── VanillaBridge        ← Vanilla Roblox wrapper\r\n│\r\n└── Examples/                ← Integration examples\r\n    ├── KnitExample\r\n    └── VanillaExample\r\n```\r\n\r\n## 🚀 Installation\r\n\r\n### Method 1: Wally (Recommended)\r\n\r\n```toml\r\n[dependencies]\r\nLUEE = \"lulushu/luee@2.0.0\"\r\n```\r\n\r\n### Method 2: Manual\r\n\r\n1. Download source\r\n2. Place `src/` folder in `ReplicatedStorage` as `LUEE`\r\n3. Require the init module\r\n\r\n## 📖 Quick Start\r\n\r\n### Option A: Knit Framework\r\n\r\n```lua\r\nlocal Knit = require(ReplicatedStorage.Packages.Knit)\r\nlocal KnitBridge = require(ReplicatedStorage.LUEE.Bridge.KnitBridge)\r\n\r\n-- Install LUEE into Knit\r\nKnitBridge.Install(Knit, {\r\n    EconomyProvider = MyEconomyService,\r\n    InventoryProvider = MyInventoryService,\r\n    DataProvider = MyProfileService,\r\n})\r\n\r\nKnit.Start():andThen(function()\r\n    local EggService = Knit.GetService(\"EggService\")\r\n    \r\n    -- Hatch eggs\r\n    local result, err = EggService:HatchBatch(player, \"BasicEgg\", 3)\r\n    if result then\r\n        print(`Hatched {#result.Results} pets!`)\r\n    end\r\nend)\r\n```\r\n\r\n### Option B: Vanilla Roblox\r\n\r\n```lua\r\nlocal LUEE = require(ReplicatedStorage.LUEE.Bridge.VanillaBridge)\r\n\r\n-- Initialize\r\nLUEE.Initialize({\r\n    EconomyProvider = MyEconomyModule,\r\n    InventoryProvider = MyInventoryModule,\r\n    DataProvider = MyDataModule,\r\n})\r\n\r\n-- Get instances\r\nlocal eggHatcher = LUEE.GetEggHatcher()\r\n\r\n-- Hatch eggs\r\nlocal result, err = eggHatcher:HatchBatch(player, \"BasicEgg\", 3)\r\n```\r\n\r\n### Option C: Custom Framework / Direct Usage\r\n\r\n```lua\r\nlocal LuckManager = require(ReplicatedStorage.LUEE.Core.Modules.LuckManager)\r\nlocal EggHatcher = require(ReplicatedStorage.LUEE.Core.Modules.EggHatcher)\r\n\r\n-- Create instances\r\nlocal luckManager = LuckManager.new()\r\nluckManager:Initialize()\r\n\r\nlocal hatcher = EggHatcher.new({\r\n    LuckManager = luckManager,\r\n    -- Providers are optional\r\n})\r\nhatcher:Initialize()\r\n\r\n-- Use directly\r\nlocal result, err = hatcher:HatchBatch(player, \"BasicEgg\", 3)\r\n```\r\n\r\n### Luck Source Ekleme\r\n\r\n```lua\r\nlocal LuckService = Knit.GetService(\"LuckService\")\r\n\r\n-- x2 Potion ekle (1 saat)\r\nLuckService:AddLuckSource(player, {\r\n    Name = \"LuckPotion_x2\",\r\n    Type = \"Multiplicative\",\r\n    Value = 2.0,\r\n    ExpiresAt = os.time() + 3600,\r\n})\r\n\r\n-- +0.5 Gamepass ekle (kalıcı)\r\nLuckService:AddLuckSource(player, {\r\n    Name = \"VIP_Gamepass\",\r\n    Type = \"Additive\",\r\n    Value = 0.5,\r\n    ExpiresAt = nil,\r\n})\r\n```\r\n\r\n### Yeni Egg Ekleme\r\n\r\n`EggRegistry.lua` dosyasını düzenleyin:\r\n\r\n```lua\r\n[\"YourEgg\"] = {\r\n    Id = \"YourEgg\",\r\n    DisplayName = \"Your Egg\",\r\n    Price = 1000,\r\n    Currency = \"Coins\",\r\n    Icon = \"rbxassetid://...\",\r\n    Rarities = {\r\n        [\"Common\"] = {\r\n            Rarity = \"Common\",\r\n            Pets = {\r\n                { Id = \"Pet1\", Name = \"Pet Name\", Model = \"rbxassetid://...\", Rarity = \"Common\" },\r\n            },\r\n        },\r\n    },\r\n},\r\n```\r\n\r\n### Yeni Nadirlik Ekleme\r\n\r\n`RarityRegistry.lua` dosyasını düzenleyin:\r\n\r\n```lua\r\n{\r\n    Id = \"YourRarity\",\r\n    DisplayName = \"Your Rarity\",\r\n    Weight = 100,\r\n    Color = Color3.fromRGB(255, 100, 0),\r\n    ParticleEffectId = \"rbxassetid://...\",\r\n    SoundEffectId = \"rbxassetid://...\",\r\n    GlobalLuckMultiplier = 2.0,  -- Opsiyonel\r\n},\r\n```\r\n\r\n## 🔧 Entegrasyonlar\r\n\r\n### Economy System\r\n\r\n`EggService.lua` içinde TODO olarak işaretlenmiş kısımları doldurun:\r\n\r\n```lua\r\n-- Balance check\r\nlocal totalCost = eggConfig.Price * amount\r\nlocal hasBalance = YourEconomyService:HasCurrency(player, eggConfig.Currency, totalCost)\r\n\r\n-- Deduct currency\r\nYourEconomyService:RemoveCurrency(player, eggConfig.Currency, totalCost)\r\n```\r\n\r\n### Inventory System\r\n\r\n```lua\r\n-- Capacity check\r\nlocal availableSlots = YourInventoryService:GetAvailableSlots(player)\r\n\r\n-- Add pets\r\nfor _, result in results do\r\n    YourInventoryService:AddPet(player, result.PetId)\r\nend\r\n```\r\n\r\n### Data Persistence (ProfileService)\r\n\r\n```lua\r\nlocal playerData = YourProfileService:GetProfile(player)\r\n\r\n-- Pity counters player data'da saklanır\r\n-- playerData.PityCounters = { [\"Secret\"] = 150, [\"Rainbow\"] = 500 }\r\n\r\n-- Save after hatching\r\nYourProfileService:SaveProfile(player)\r\n```\r\n\r\n## 📊 Pity System\r\n\r\nPity system otomatik olarak aktiftir. Ayarlar için `PityConfig.lua`:\r\n\r\n```lua\r\n{\r\n    Enabled = true,\r\n    ThresholdPerRarity = {\r\n        [\"Secret\"] = 1000,   -- 1000 açılışta garanti\r\n        [\"Rainbow\"] = 5000,  -- 5000 açılışta garanti\r\n    },\r\n    MultiplierOnPity = 100,  -- x100 weight boost\r\n}\r\n```\r\n\r\n## 🎨 Client-Side Implementation\r\n\r\nClient tarafı için (UI, animasyonlar vb.) kendi implementasyonunuzu yapmalısınız. Server'dan gelen `BatchHatchResult` objesini kullanarak UI'ı güncelleyebilirsiniz.\r\n\r\n## 🧪 Testing\r\n\r\nWeight hesaplama doğruluğunu test etmek için:\r\n\r\n```lua\r\nlocal WeightedRandom = require(ReplicatedStorage.Shared.Utilities.WeightedRandom)\r\n\r\n-- 1 milyon kez test et\r\nlocal iterations = 1000000\r\nlocal results = {Common = 0, Rare = 0, Secret = 0}\r\n\r\nfor i = 1, iterations do\r\n    local result = WeightedRandom.SelectSimple(\r\n        {\"Common\", \"Rare\", \"Secret\"},\r\n        {10000, 1000, 1}\r\n    )\r\n    results[result] += 1\r\nend\r\n\r\n-- Expected: Common ~90.8%, Rare ~9.1%, Secret ~0.009%\r\nprint(\"Common:\", results.Common / iterations * 100, \"%\")\r\nprint(\"Rare:\", results.Rare / iterations * 100, \"%\")\r\nprint(\"Secret:\", results.Secret / iterations * 100, \"%\")\r\n```\r\n\r\n## 📜 Lisans\r\n\r\nMIT License - Projenizde özgürce kullanabilirsiniz.\r\n\r\n## 🤝 Katkı\r\n\r\nBu sistem SOLID prensiplere sıkı sıkıya bağlıdır. Değişiklik yaparken:\r\n\r\n- Single Responsibility prensibine uyun\r\n- Type safety'yi koruyun\r\n- Test ekleyin\r\n- Documentation güncelleyin\r\n\r\n## 📞 Destek\r\n\r\nSorunlar için GitHub Issues kullanın.\r\n\r\n---\r\n\r\n**Made with ❤️ by LUEE Team**\r\n","readmeTruncated":false}