adaptive-tier

Client FPS and device performance governor with multi-tier hysteresis for dynamic LOD and particle scaling.

---

Production Origin: This package was extracted and generalized from infrastructure developed for Kabbrawl, a private competitive multiplayer Roblox experience. Kabbrawl itself remains proprietary; this package contains only reusable infrastructure and no proprietary assets or game-specific content.

---

📱 Why Adaptive Performance Governance?

Over 60% of Roblox players access experiences on mobile devices or budget hardware with limited thermal headrooms. A dense visual effect or particle system that runs smoothly at 60 FPS on desktop may drop budget phones to 15 FPS.

However, naive FPS checking creates rapid visual flicker: if a frame drops for 1 second, the game drops graphic settings, immediately spikes to 60 FPS, raises graphics settings, and drops again in an endless loop.

adaptive-tier solves this using:

1. Sliding-Window Sampling: Measures average FPS over sustained periods (e.g. 3 seconds) rather than single frame hiccups.
2. Multi-Tier Hysteresis: Requires higher recovery thresholds to upgrade fidelity tiers than to degrade them, preventing visual oscillation.

---

✨ Features

• 3 Performance Tiers: High, Mid, Low.
• Hysteresis Thresholds: Low threshold (35 FPS), Mid threshold (50 FPS), High recovery (55 FPS).
• Reactive Subscriptions: Clean listener callbacks to dynamically throttle particle emitter rates, disable depth-of-field, or toggle mesh LODs.

---

🚀 Installation

Via Wally

Add adaptive-tier to your wally.toml:

[dependencies]
AdaptiveTier = "zenukopublic/adaptive-tier@1.0.0"

---

📖 Quickstart

local AdaptiveTier = require(Packages.AdaptiveTier)

local governor = AdaptiveTier.new({
    sampleDurationSeconds = 3.0,
})

-- Listen for performance shifts
governor:onTierChanged(function(tier)
    if tier == "Low" then
        particleEmitter.Rate = 50
        lighting.Bloom.Enabled = false
    elseif tier == "Mid" then
        particleEmitter.Rate = 250
        lighting.Bloom.Enabled = true
    else -- "High"
        particleEmitter.Rate = 800
        lighting.Bloom.Enabled = true
    end
end)

governor:start()

---

🧪 Testing

Run standalone unit tests headlessly with Lune:

lune run tests/adaptive_tier.test.luau

---

📄 License

MIT License. Free for personal and commercial use.