{"id":"stewhook/flux","name":"flux","scope":"stewhook","platform":"roblox","description":"A modular, high-performance object pooling framework for Roblox","version":"1.2.0","latest":"1.2.0","versions":["1.1.1","1.1.2","1.1.3","1.1.4","1.2.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"fdffe9bf81474103287bb9ca2518b0c58011acc1df968f1c13558fbc5a27d520","likes":0,"downloads":0,"install":"forest install stewhook/flux","url":"https://forest.dev/p/roblox/stewhook/flux","files":"https://api.forest.dev/ai/package/roblox/stewhook/flux/files","readme":"# stewhook — Flux\r\n```sql\r\n__/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\__/\\\\\\______________/\\\\\\________/\\\\\\__/\\\\\\_______/\\\\\\_        \r\n _\\/\\\\\\///////////__\\/\\\\\\_____________\\/\\\\\\_______\\/\\\\\\_\\///\\\\\\___/\\\\\\/__       \r\n  _\\/\\\\\\_____________\\/\\\\\\_____________\\/\\\\\\_______\\/\\\\\\___\\///\\\\\\\\\\\\/____      \r\n   _\\/\\\\\\\\\\\\\\\\\\\\\\_____\\/\\\\\\_____________\\/\\\\\\_______\\/\\\\\\_____\\//\\\\\\\\______     \r\n    _\\/\\\\\\///////______\\/\\\\\\_____________\\/\\\\\\_______\\/\\\\\\______\\/\\\\\\\\______    \r\n     _\\/\\\\\\_____________\\/\\\\\\_____________\\/\\\\\\_______\\/\\\\\\______/\\\\\\\\\\\\_____   \r\n      _\\/\\\\\\_____________\\/\\\\\\_____________\\//\\\\\\______/\\\\\\_____/\\\\\\////\\\\\\___  \r\n       _\\/\\\\\\_____________\\/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\__\\///\\\\\\\\\\\\\\\\\\/____/\\\\\\/___\\///\\\\\\_ \r\n        _\\///______________\\///////////////_____\\/////////_____\\///_______\\///__\r\n```\r\nFlux is a fast, modular, and scalable instance pooling framework that handles all back-end logic required to create an efficient instance pool while giving you the flexibility to create & recycle objects with custom (and potentially dynamic) logic / data.\r\n\r\n## ❔ How does it work?\r\nFlux manages your instances across two internal pools: Hot Storage (active & in use), and Cold Storage (idle & stored away).\r\nWhen creating an instance, Flux will first check to see if the pool is at capacity.\r\n\r\nFlux (by default) operates using an O(1) queue datastructure. Recycling the oldest instances, prioritizing cold state over hot state. This results in an extremely fast pooling framework that maintains speed regardless of pool size.\r\n#### If the object pool isn't at capacity, Flux will:\r\n1. Create an instance from scratch using your Factory Function.\r\n2. Apply the Construction Function to the created instance.\r\n3. Add this instance to the pool.\r\n#### If the object pool is at capacity, Flux will:\r\n1. Check Cold Storage and retrieve the oldest instance.\r\n2. If Cold Storage is empty it, retrieve the oldest instance from Hot Storage.\r\n3. Apply the Construction Function to the retrieved instance.\r\n4. Cycle the instance through the pool.\r\n\r\n## 📖 API Reference\r\n### Public Fields (Config)\r\n`pool.size : number`\\\r\n`pool.timeout : number`\\\r\n`pool.hotSpot : Instance`\\\r\n`pool.coldSpot : Instance`\\\r\n`pool.factoryFunction : () -> Instance`\r\n\r\n### Public Methods\r\n`Flux.new(config?) -> pool`\\\r\n`pool:construct(constructFn, opts) -> instance`\\\r\n`pool:store(instance)`\\\r\n`pool:destroy(instance)`\\\r\n`pool:wipe()`\\\r\n`pool:getActiveCount() -> number`\\\r\n`pool:getIdleCount() -> number`\r\n\r\n## 👀 Usage\r\n### Importing Flux\r\n```luau\r\nlocal Flux = require(ReplicatedStorage.Flux)\r\n```\r\n### Creating & Configuring a Pool\r\nBuilding the pool foundation.\r\n```luau\r\nlocal pool = Flux.new()\r\npool.size = 100 -- Max instances in the pool.\r\npool.hotSpot = Workspace -- Where instances go when created.\r\npool.coldSpot = ReplicatedStorage -- Where instances go when stored.\r\npool.timeout = 10 -- How long instances exist before being automatically cleaned (set this to 0 for no timeout)\r\npool.factoryFunction = function()\r\n\tlocal block = Instance.new(\"Part\")\r\n\tblock.Size = Vector3.new(2, 2, 2)\r\n\tblock.CollisionGroup = \"Blocks\"\r\n\treturn block\r\nend -- The function that handles object creation from scratch.\r\n```\r\n### Defining Pool Behaviors\r\nThe constructFunction serves as the customizable creation function that handles instance setup. It can take an optional opts table (\"string\" : any Roblox value). The opts table allows for the passing of dynamic and custom data to be used within the construction function such as colors, players, etc.\r\n```luau\r\nlocal function constructFunction(instance: Part, opts)\r\n\t-- Expected Options\r\n\t-- opts = {\r\n\t--\tcolor = any Brickcolor\r\n\t-- }\r\n\tlocal fountainStrength = 150\r\n\tlocal fountainWidth = 10.0\r\n\tlocal fountainAngle = Vector3.new((math.random()*2-1)*fountainWidth, fountainStrength, (math.random()*2-1)*fountainWidth)\r\n\tinstance.BrickColor = opts.color\r\n\tinstance.Position = fountainFolder.LaunchPoint.Position\r\n\tinstance.AssemblyLinearVelocity = fountainAngle\r\nend\r\n```\r\n### Creating & Recycling Instances\r\nWherever you would consider running Instance.new() or :Clone() replace it with pool:construct(). This allows you the same functionality of creating an instance from scratch using your factory function (expensive), while giving you the ability to recycle old instances depending on pool size (cheap).\r\n```luau\r\nlocal fountainActive = false\r\n\r\nlocal opts = {\r\n\tcolor = BrickColor.Blue()\r\n}\r\n\t\r\nwhile fountainActive do\r\n\tpool:construct(\r\n    \tconstructFunction,\r\n    \topts\r\n  \t)\r\n  \ttask.wait(.01)\r\nend\r\n```\r\n### Manual Storing of Instances\r\nIn the event you'd like to manually store an instance into cold storage. Run pool:store(instance). This provides all background cleanup while storing the instance into cold storage. Cold storage items take priority in being recycled compared to hot storage items.\r\n```luau\r\n-- Example\r\npool:store(instance)\r\n```\r\n\r\n## ⚙️ Installation\r\n### Install from Roblox\r\n[Download the model from the Roblox library.](https://create.roblox.com/store/asset/120278572872003/Flux)\r\n### Install from Wally\r\n```\r\nflux = \"stewhook/flux@1.1.4\"\r\n```\r\n","readmeTruncated":false}