{"id":"zenukopublic/adaptive-tier","name":"adaptive-tier","scope":"zenukopublic","platform":"roblox","description":"Client FPS and device performance governor with multi-tier hysteresis for dynamic LOD and particle scaling.","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"5e3501e305829bfdfebfcede35621870baefacd2474ccd7cb437eafdde1c1bef","likes":0,"downloads":0,"install":"forest install zenukopublic/adaptive-tier","url":"https://forest.dev/p/roblox/zenukopublic/adaptive-tier","files":"https://api.forest.dev/ai/package/roblox/zenukopublic/adaptive-tier/files","readme":"# `adaptive-tier`\n\n> **Client FPS and device performance governor with multi-tier hysteresis for dynamic LOD and particle scaling.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Language: Luau](https://img.shields.io/badge/Language-Luau-blue.svg)](https://luau-lang.org/)\n[![Wally: Available](https://img.shields.io/badge/Wally-Available-brightgreen.svg)](https://wally.run/)\n\n---\n\n> **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.\n\n---\n## 📱 Why Adaptive Performance Governance?\n\nOver 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.\n\nHowever, 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.\n\n**`adaptive-tier`** solves this using:\n1. **Sliding-Window Sampling:** Measures average FPS over sustained periods (e.g. 3 seconds) rather than single frame hiccups.\n2. **Multi-Tier Hysteresis:** Requires higher recovery thresholds to upgrade fidelity tiers than to degrade them, preventing visual oscillation.\n\n---\n\n## ✨ Features\n\n* **3 Performance Tiers:** `High`, `Mid`, `Low`.\n* **Hysteresis Thresholds:** Low threshold (35 FPS), Mid threshold (50 FPS), High recovery (55 FPS).\n* **Reactive Subscriptions:** Clean listener callbacks to dynamically throttle particle emitter rates, disable depth-of-field, or toggle mesh LODs.\n\n---\n\n## 🚀 Installation\n\n### Via Wally\nAdd `adaptive-tier` to your `wally.toml`:\n\n```toml\n[dependencies]\nAdaptiveTier = \"zenukopublic/adaptive-tier@1.0.0\"\n```\n\n---\n\n## 📖 Quickstart\n\n```luau\nlocal AdaptiveTier = require(Packages.AdaptiveTier)\n\nlocal governor = AdaptiveTier.new({\n    sampleDurationSeconds = 3.0,\n})\n\n-- Listen for performance shifts\ngovernor:onTierChanged(function(tier)\n    if tier == \"Low\" then\n        particleEmitter.Rate = 50\n        lighting.Bloom.Enabled = false\n    elseif tier == \"Mid\" then\n        particleEmitter.Rate = 250\n        lighting.Bloom.Enabled = true\n    else -- \"High\"\n        particleEmitter.Rate = 800\n        lighting.Bloom.Enabled = true\n    end\nend)\n\ngovernor:start()\n```\n\n---\n\n## 🧪 Testing\n\nRun standalone unit tests headlessly with [Lune](https://github.com/lune-org/lune):\n```bash\nlune run tests/adaptive_tier.test.luau\n```\n\n---\n\n## 📄 License\n\nMIT License. Free for personal and commercial use.\n","readmeTruncated":false}