LUEE - Lulu's Universal Egg Engine

Framework-Agnostic enterprise-grade egg hatching system for Roblox.

🎯 Features

Core Features

• ✅ Dynamic Batch Hatching: 1 to 1000+ eggs in single request
• ✅ Flexible Rarity System: Fully customizable tiers
• ✅ Rarity-Specific Luck: Per-rarity luck multipliers
• ✅ Weight-Based Probability: Precise odds (1/1M+)

Enterprise-Grade

• ✅ Pity System: Guaranteed drops after threshold
• ✅ Pre-flight Checks: Validate before processing
• ✅ Weight Caching: 1000x performance boost
• ✅ Luck Stacking: Multi-source luck aggregation

Architecture

• ✅ Framework-Agnostic: Works with Knit, AGF, Vanilla, or any custom framework
• ✅ SOLID Principles: Clean, maintainable architecture
• ✅ Strict Type Safety: 100% Luau type coverage
• ✅ Zero Dependencies: Core has no external requirements

🏗️ Architecture

LUEE follows the "Core & Bridge" pattern:

LUEE/
├── Core/                    ← Framework-agnostic (Pure Lua)
│   ├── Types.lua
│   ├── Configuration/       ← Game data (eggs, rarities, pity)
│   ├── Utilities/           ← Pure functions (WeightedRandom, PityTracker, etc)
│   └── Modules/             ← Business logic
│       ├── LuckManager      ← Stateful luck management
│       └── EggHatcher       ← Main hatching engine
│
├── Bridge/                  ← Framework adapters (Optional)
│   ├── KnitBridge           ← Knit Framework wrapper
│   └── VanillaBridge        ← Vanilla Roblox wrapper
│
└── Examples/                ← Integration examples
    ├── KnitExample
    └── VanillaExample

🚀 Installation

Method 1: Wally (Recommended)

[dependencies]
LUEE = "lulushu/luee@2.0.0"

Method 2: Manual

1. Download source
2. Place src/ folder in ReplicatedStorage as LUEE
3. Require the init module

📖 Quick Start

Option A: Knit Framework

local Knit = require(ReplicatedStorage.Packages.Knit)
local KnitBridge = require(ReplicatedStorage.LUEE.Bridge.KnitBridge)

-- Install LUEE into Knit
KnitBridge.Install(Knit, {
    EconomyProvider = MyEconomyService,
    InventoryProvider = MyInventoryService,
    DataProvider = MyProfileService,
})

Knit.Start():andThen(function()
    local EggService = Knit.GetService("EggService")
    
    -- Hatch eggs
    local result, err = EggService:HatchBatch(player, "BasicEgg", 3)
    if result then
        print(`Hatched {#result.Results} pets!`)
    end
end)

Option B: Vanilla Roblox

local LUEE = require(ReplicatedStorage.LUEE.Bridge.VanillaBridge)

-- Initialize
LUEE.Initialize({
    EconomyProvider = MyEconomyModule,
    InventoryProvider = MyInventoryModule,
    DataProvider = MyDataModule,
})

-- Get instances
local eggHatcher = LUEE.GetEggHatcher()

-- Hatch eggs
local result, err = eggHatcher:HatchBatch(player, "BasicEgg", 3)

Option C: Custom Framework / Direct Usage

local LuckManager = require(ReplicatedStorage.LUEE.Core.Modules.LuckManager)
local EggHatcher = require(ReplicatedStorage.LUEE.Core.Modules.EggHatcher)

-- Create instances
local luckManager = LuckManager.new()
luckManager:Initialize()

local hatcher = EggHatcher.new({
    LuckManager = luckManager,
    -- Providers are optional
})
hatcher:Initialize()

-- Use directly
local result, err = hatcher:HatchBatch(player, "BasicEgg", 3)

Luck Source Ekleme

local LuckService = Knit.GetService("LuckService")

-- x2 Potion ekle (1 saat)
LuckService:AddLuckSource(player, {
    Name = "LuckPotion_x2",
    Type = "Multiplicative",
    Value = 2.0,
    ExpiresAt = os.time() + 3600,
})

-- +0.5 Gamepass ekle (kalıcı)
LuckService:AddLuckSource(player, {
    Name = "VIP_Gamepass",
    Type = "Additive",
    Value = 0.5,
    ExpiresAt = nil,
})

Yeni Egg Ekleme

EggRegistry.lua dosyasını düzenleyin:

["YourEgg"] = {
    Id = "YourEgg",
    DisplayName = "Your Egg",
    Price = 1000,
    Currency = "Coins",
    Icon = "rbxassetid://...",
    Rarities = {
        ["Common"] = {
            Rarity = "Common",
            Pets = {
                { Id = "Pet1", Name = "Pet Name", Model = "rbxassetid://...", Rarity = "Common" },
            },
        },
    },
},

Yeni Nadirlik Ekleme

RarityRegistry.lua dosyasını düzenleyin:

{
    Id = "YourRarity",
    DisplayName = "Your Rarity",
    Weight = 100,
    Color = Color3.fromRGB(255, 100, 0),
    ParticleEffectId = "rbxassetid://...",
    SoundEffectId = "rbxassetid://...",
    GlobalLuckMultiplier = 2.0,  -- Opsiyonel
},

🔧 Entegrasyonlar

Economy System

EggService.lua içinde TODO olarak işaretlenmiş kısımları doldurun:

-- Balance check
local totalCost = eggConfig.Price * amount
local hasBalance = YourEconomyService:HasCurrency(player, eggConfig.Currency, totalCost)

-- Deduct currency
YourEconomyService:RemoveCurrency(player, eggConfig.Currency, totalCost)

Inventory System

-- Capacity check
local availableSlots = YourInventoryService:GetAvailableSlots(player)

-- Add pets
for _, result in results do
    YourInventoryService:AddPet(player, result.PetId)
end

Data Persistence (ProfileService)

local playerData = YourProfileService:GetProfile(player)

-- Pity counters player data'da saklanır
-- playerData.PityCounters = { ["Secret"] = 150, ["Rainbow"] = 500 }

-- Save after hatching
YourProfileService:SaveProfile(player)

📊 Pity System

Pity system otomatik olarak aktiftir. Ayarlar için PityConfig.lua:

{
    Enabled = true,
    ThresholdPerRarity = {
        ["Secret"] = 1000,   -- 1000 açılışta garanti
        ["Rainbow"] = 5000,  -- 5000 açılışta garanti
    },
    MultiplierOnPity = 100,  -- x100 weight boost
}

🎨 Client-Side Implementation

Client tarafı için (UI, animasyonlar vb.) kendi implementasyonunuzu yapmalısınız. Server'dan gelen BatchHatchResult objesini kullanarak UI'ı güncelleyebilirsiniz.

🧪 Testing

Weight hesaplama doğruluğunu test etmek için:

local WeightedRandom = require(ReplicatedStorage.Shared.Utilities.WeightedRandom)

-- 1 milyon kez test et
local iterations = 1000000
local results = {Common = 0, Rare = 0, Secret = 0}

for i = 1, iterations do
    local result = WeightedRandom.SelectSimple(
        {"Common", "Rare", "Secret"},
        {10000, 1000, 1}
    )
    results[result] += 1
end

-- Expected: Common ~90.8%, Rare ~9.1%, Secret ~0.009%
print("Common:", results.Common / iterations * 100, "%")
print("Rare:", results.Rare / iterations * 100, "%")
print("Secret:", results.Secret / iterations * 100, "%")

📜 Lisans

MIT License - Projenizde özgürce kullanabilirsiniz.

🤝 Katkı

Bu sistem SOLID prensiplere sıkı sıkıya bağlıdır. Değişiklik yaparken:

• Single Responsibility prensibine uyun
• Type safety'yi koruyun
• Test ekleyin
• Documentation güncelleyin

📞 Destek

Sorunlar için GitHub Issues kullanın.

---

Made with ❤️ by LUEE Team