{"id":"gamingguy84/objectpool","name":"objectpool","scope":"gamingguy84","platform":"roblox","description":"A high-performance generic object pooling module for Roblox Instances written in strict Luau.","version":"0.0.2","latest":"0.0.2","versions":["0.0.1","0.0.2"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"21558bfd334d6d11e7ce2d162cb66275ba2a90798c7013237017d5fdb8d5930e","likes":0,"downloads":0,"install":"forest install gamingguy84/objectpool","url":"https://forest.dev/p/roblox/gamingguy84/objectpool","files":"https://api.forest.dev/ai/package/roblox/gamingguy84/objectpool/files","readme":"# ObjectPool\r\n\r\nA high-performance generic object pooling module for Roblox Instances written in strict Luau.\r\n\r\nDesigned for systems that frequently create and destroy Instances such as:\r\n\r\n- Bullets\r\n- Particle effects\r\n- NPCs\r\n- Sound emitters\r\n- UI elements\r\n- Trails and beams\r\n- Temporary gameplay objects\r\n\r\nThe module minimizes allocation pressure and garbage collection overhead by reusing cloned Instances instead of repeatedly allocating new ones.\r\n\r\nFeatures\r\n- Strict Luau support (`--!strict`)\r\n- Generic typing\r\n- Explicit self parameters (no colon syntax)\r\n- Dynamic pool expansion\r\n- Prewarming support\r\n- Acquire / Release lifecycle\r\n- Bulk release support\r\n- Destroy support\r\n- Optional reset callbacks\r\n- Defensive validation\r\n- Low allocation overhead\r\n- Automatic transient state reset\r\n  \r\n## Installation\r\n\r\nPlace `Notwork` in an accessible location (e.g. `ReplicatedStorage`)\r\n\r\nRequire it normally via `require`\r\n\r\nExample:\r\n``` lua\r\nlocal bulletTemplate = ReplicatedStorage.Assets.Bullet\r\n\r\nlocal bulletPool = ObjectPool.new(\r\n\tbulletTemplate,\r\n\t100, -- initial size\r\n\t25   -- expansion size\r\n)\r\n```\r\n\r\n## API\r\n\r\n`ObjectPool.new`\r\n\r\nCreates a new pool.\r\n\r\n``` lua\r\nObjectPool.new(\r\n\ttemplate: T,\r\n\tinitialSize: number?,\r\n\texpandSize: number?,\r\n\treset: ((instance: T) -> ())?\r\n): Pool<T>\r\n```\r\n\r\n`ObjectPool.Acquire`\r\n\r\nAcquires an Instance from the pool.\r\n\r\n``` lua\r\nObjectPool.Acquire(\r\n\tself: Pool<T>,\r\n\tparent: Instance?\r\n): T\r\n```\r\n\r\n`ObjectPool.Release`\r\n\r\nReturns an Instance to the pool.\r\n\r\n``` lua\r\nObjectPool.Release(\r\n\tself: Pool<T>,\r\n\tinstance: T\r\n)\r\n```\r\n\r\nThe module throws errors for:\r\n\r\n- Releasing foreign instances\r\n- Double releasing\r\n- Using a destroyed pool\r\n\r\n`ObjectPool.ReleaseAll`\r\n\r\nReleases every active object.\r\n\r\n``` lua\r\nObjectPool.ReleaseAll(\r\n\tself: Pool<T>\r\n)\r\n```\r\n\r\n`ObjectPool.Prewarm`\r\n\r\nAdds additional preallocated Instances.\r\n\r\n``` lua\r\nObjectPool.Prewarm(\r\n\tself: Pool<T>,\r\n\tamount: number\r\n)\r\n```\r\n\r\n`ObjectPool.Expand`\r\n\r\nManually expands the pool.\r\n\r\n``` lua\r\nObjectPool.Expand(\r\n\tself: Pool<T>,\r\n\tamount: number?\r\n)\r\n```\r\n\r\nIf no amount is specified, ExpandSize is used.\r\n\r\n`ObjectPool.Destroy`\r\n\r\nDestroys the pool and all managed Instances.\r\n\r\n``` lua\r\nObjectPool.Destroy(\r\n\tself: Pool<T>\r\n)\r\n```\r\n\r\n`ObjectPool.GetAvailableCount`\r\n\r\nReturns available pooled objects.\r\n\r\n``` lua\r\nObjectPool.GetAvailableCount(\r\n\tself: Pool<T>\r\n): number\r\n```\r\n\r\n`ObjectPool.GetInUseCount`\r\n\r\nReturns currently active objects.\r\n\r\n``` lua\r\nObjectPool.GetInUseCount(\r\n\tself: Pool<T>\r\n): number\r\n```\r\n\r\nAutomatic Reset Behavior\r\n\r\nThe module automatically resets common transient state when objects are released.\r\n\r\nBasePart properties:\r\n- AssemblyLinearVelocity = Vector3.zero\r\n- AssemblyAngularVelocity = Vector3.zero\r\n- Anchored = false\r\n- Parent = nil\r\n  \r\nParticleEmitter properties:\r\n\r\n- Enabled = false\r\n  \r\nTrail properties:\r\n- Enabled = false\r\n  \r\nBeam properties:\r\n\r\n- Enabled = false\r\n  \r\nSound properties:\r\n- Playing = false\r\n- TimePosition = 0\r\n  \r\n## Custom Reset Logic\r\n\r\nYou may provide a custom reset callback.\r\n\r\n``` lua\r\nlocal function resetBullet(bullet)\r\n\tbullet.Transparency = 0\r\n\tbullet.Color = Color3.new(1, 1, 1)\r\nend\r\n\r\nlocal bulletPool = ObjectPool.new(\r\n\tbulletTemplate,\r\n\t100,\r\n\t25,\r\n\tresetBullet\r\n)\r\n```\r\n\r\nThe custom reset callback executes after built-in transient reset behavior.\r\n\r\n## Type Support\r\n\r\nThe module is fully generic.\r\n\r\n``` lua\r\nlocal pool: ObjectPool.Pool<BasePart>\r\n```\r\n\r\nWorks with any Roblox Instance subtype.\r\n\r\nExample: Bullet System\r\n``` lua\r\nlocal ObjectPool = require(ReplicatedStorage.Packages.ObjectPool)\r\n\r\nlocal bulletTemplate = ReplicatedStorage.Assets.Bullet\r\n\r\nlocal bulletPool = ObjectPool.new(\r\n\tbulletTemplate,\r\n\t200,\r\n\t50\r\n)\r\n\r\nlocal function fireBullet(origin: CFrame)\r\n\tlocal bullet = ObjectPool.Acquire(\r\n\t\tbulletPool,\r\n\t\tworkspace.Projectiles\r\n\t)\r\n\r\n\tbullet.CFrame = origin\r\n\tbullet.AssemblyLinearVelocity =\r\n\t\torigin.LookVector * 500\r\n\r\n\ttask.delay(5, function()\r\n\t\tObjectPool.Release(bulletPool, bullet)\r\n\tend)\r\nend\r\n```\r\n\r\n## Performance Notes\r\n\r\nObject pooling significantly reduces:\r\n\r\n- Instance allocation spikes\r\n- Garbage collection pauses\r\n- Physics initialization overhead\r\n- Replication churn\r\n\r\nBest suited for:\r\n\r\n- High-frequency spawning systems\r\n- Fast projectiles\r\n- Visual effects\r\n- Temporary gameplay entities\r\n  \r\n### Best Practices\r\n- Prewarm Large Systems\r\n\r\n``` lua\r\nObjectPool.Prewarm(pool, 500)\r\n```\r\n\r\nAvoid runtime allocation spikes during gameplay.\r\n\r\n- Always Release\r\n\r\nEvery acquired object should eventually be released.\r\n\r\nBad:\r\n\r\n``` lua\r\nlocal bullet = ObjectPool.Acquire(pool)\r\n```\r\n\r\nGood:\r\n\r\n``` lua\r\nlocal bullet = ObjectPool.Acquire(pool)\r\n\r\nObjectPool.Release(pool, bullet)\r\n```\r\n\r\n- Avoid Manual Destruction\r\n\r\nDo not manually destroy pooled objects.\r\n\r\nBad:\r\n\r\n``` lua\r\nbullet:Destroy()\r\n```\r\n\r\nGood:\r\n\r\n``` lua\r\nObjectPool.Release(pool, bullet)\r\n```\r\n","readmeTruncated":false}