{"id":"fadeluc-123/cellar","name":"cellar","scope":"fadeluc-123","platform":"roblox","description":"Pools Roblox instances: declare a category, fill it with copies, take them out with get and give them back with rebound.","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"Apache-2.0","licenseRating":"safe","licenseCaveats":["Modified files must carry a notice of changes. If the package ships a NOTICE file, its attributions must be preserved."],"licenseVerified":true,"dependencies":{},"integrity":"ea001cbba6b733fab6213d8ee8b7bff01715d892c82d27fbc7dd6e310113e22d","likes":0,"downloads":0,"install":"forest install fadeluc-123/cellar","url":"https://forest.dev/p/roblox/fadeluc-123/cellar","files":"https://api.forest.dev/ai/package/roblox/fadeluc-123/cellar/files","readme":"# Cellar\n\nInstance pooling for Roblox. A game clones copies of a template once, parks them out of sight, takes one out when it needs it and gives it back when it is done, so it reuses copies instead of cloning and destroying them.\n\n## Contents\n\n- [What Cellar is](#what-cellar-is)\n- [Install](#install)\n- [A short example](#a-short-example)\n- [How each function works](#how-each-function-works)\n- [Limits](#limits)\n- [API](#api)\n- [Moving from ObjectCache 3.5.2](#moving-from-objectcache-352)\n- [Testing Cellar](#testing-cellar)\n- [License](#license)\n\n## What Cellar is\n\nSome things in a game come and go many times a second: tracers, shell casings, bullet holes, sound voices. Cloning a new instance for each one and destroying it afterward puts a clone and a destroy on every use. A pool clones them once, ahead of time, and hands the same copies out again and again, so taking a copy on a path that runs every frame costs no clone.\n\nCellar keeps those pools. Each pool is a category: a name, such as `FX/Casing/Rifle`, and a parent where its copies live. `add` fills a category with clones of a template. `get` takes copies out, and `rebound` gives one back, which puts it under the category's parent again and parks it at one point far below the map, (0, -100,000, 0). `remove` destroys idle copies, and `getAll` lists a category's copies, idle and out.\n\nCellar is one table per realm. Every category name is shared by all the code on the server, and each client has its own set, so a category the server declares does not exist on a client. Prefix each name with the system that owns it, as `FX/Impact` and `Loot/Crate` do.\n\nNothing in Cellar yields, so no call waits and none returns a Promise. It has no dependencies, opens no remote and holds no game values. Its source is strict-mode Luau written for luau-lsp's new type checker, and a game requires it with full types.\n\nCellar replaces ObjectCache. It is rewritten from ObjectCache 3.5.2's source as a new package, with that version's known bugs fixed. [Moving from ObjectCache 3.5.2](#moving-from-objectcache-352) says what a game changes, and `CHANGELOG.md` lists every change.\n\n## Install\n\nCellar is the Wally package `fadeluc-123/cellar`, realm `shared`, so the server and every client can require it. Add it to your game's `wally.toml` under `[dependencies]`:\n\n```toml\n[dependencies]\nCellar = \"fadeluc-123/cellar@^0.1.0\"\n```\n\nThe name on the left is the name Wally gives the package's entry in `Packages/`, so with `Cellar` the require below reads `Packages.Cellar`. Cellar has no dependencies of its own, so this one line is all it needs.\n\n`^0.1.0` takes any 0.1.x release and never 0.2.0, since Wally follows Cargo's rules, where the first nonzero number marks a breaking change. So while Cellar is on 0.x, a change to a function's name, its argument order or its return shape, or to a behavior a known consumer relies on, comes only in a new minor version, such as 0.2.0, and a game moves to it by editing this line. New API and fixes come in a patch, such as 0.1.1, which `^0.1.0` picks up.\n\n### Typed install\n\nCellar is fully typed, but Wally hides the types. It installs each package under `Packages/_Index/` and puts a one-line file at `Packages/Cellar` that points at it, and that file loses every exported type, so `require(Packages.Cellar)` comes back as `any`. Run these three commands after every install, from one Lune script in `.lune/` so none of them gets skipped:\n\n```sh\nwally install\nrojo sourcemap sourcemap.project.json --output sourcemap.json\nwally-package-types --sourcemap sourcemap.json Packages/\n```\n\n`wally install` installs the packages. `rojo sourcemap` writes a map of your place to `sourcemap.json`. `sourcemap.project.json` is the project file a Whiteoak game builds its sourcemap from, so name whichever project file maps your place. `wally-package-types` reads that map and rewrites the one-line files with the types included. In a Whiteoak game, Rojo and `wally-package-types` come from its `rokit.toml`. Until the last two commands run, a `--!strict` script sees Cellar as `any`, and the checker checks none of your calls into it.\n\nCellar's types are written for luau-lsp's new type checker. luau-lsp's command line and its VS Code extension both run the old checker unless told otherwise, so pass `--flag:LuauSolverV2=true` to every `luau-lsp analyze`, in CI and by hand, and give the editor the same flags in `.vscode/settings.json`:\n\n```json\n{\n\t\"luau-lsp.sourcemap.rojoProjectFile\": \"sourcemap.project.json\",\n\t\"luau-lsp.fflags.enableNewSolver\": true,\n\t\"luau-lsp.fflags.enableByDefault\": true,\n\t\"luau-lsp.fflags.sync\": false\n}\n```\n\nThe first line names the project file the editor builds its sourcemap from. `enableNewSolver` turns the new checker on, `enableByDefault` turns on every boolean Luau flag the way `luau-lsp analyze` does, and `sync: false` stops the extension copying Roblox's live Luau flags, so a change Roblox makes to them never reaches your editor unannounced.\n\nThen require Cellar bare, with no annotation:\n\n```lua\nlocal Cellar = require(ReplicatedStorage.Packages.Cellar)\n```\n\nAn annotation on that line would replace the module's own type, and every function's type with it. Bare, every call into Cellar is checked, and the exported type `Cellar.Copies` is there for what `getAll` returns. The public functions carry Moonwave doc comments, so the editor shows each one's notes on hover.\n\n## A short example\n\nImpact markers: anchored single parts that a client shows at each hit point and parks again a few seconds later. The game keeps the numbers in its config module `ReplicatedStorage.Shared.Config.Impacts`:\n\n```lua\n--[[\n    Tuning for the pooled impact markers: the Cellar category they live\n    in, how many are cloned at boot and how long each one stays out\n--]]\n\n--!strict\nreturn {\n\tcategory = \"FX/Impact\",\n\tcount = 32, -- Copies cloned at boot, and the most hits that show a marker at once\n\tlifetime = 5, -- Seconds a marker stays out before it is parked again\n}\n```\n\nThe client module that pools the markers:\n\n```lua\n--[[\n    Impact markers pooled through Cellar on the client: anchored single\n    parts cloned into their own folder at boot, shown at a hit point and\n    parked again once their lifetime is up. A hit shows nothing while\n    every marker is already out\n--]]\n\n--!strict\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal Workspace = game:GetService(\"Workspace\")\nlocal Packages = ReplicatedStorage.Packages\n\nlocal Cellar = require(Packages.Cellar)\n\nlocal Assets = ReplicatedStorage:WaitForChild(\"Assets\") :: Folder -- Boot-time wait: Assets may not have replicated yet\n\nlocal IMPACT_CATEGORY: string = require(ReplicatedStorage.Shared.Config.Impacts).category\nlocal IMPACT_COUNT: number = require(ReplicatedStorage.Shared.Config.Impacts).count\nlocal IMPACT_LIFETIME: number = require(ReplicatedStorage.Shared.Config.Impacts).lifetime\n\nlocal Impacts = {}\n\n--[[\n    Declares the impact category with its own folder and\n    clones every marker it will show, once, at boot\n--]]\n\nfunction Impacts.fill()\n\t-- The template must be anchored, since parked copies sit below FallenPartsDestroyHeight\n\tlocal template = Assets:FindFirstChild(\"Impact\") :: BasePart?\n\tif not template then\n\t\treturn warn(`Impacts: no Impact template in {Assets:GetFullName()}`)\n\tend\n\n\tlocal folder: Folder = Instance.new(\"Folder\")\n\tfolder.Name = \"Impacts\"\n\tfolder.Parent = Workspace\n\n\tCellar:create(IMPACT_CATEGORY, folder)\n\tCellar:add(template, IMPACT_COUNT, folder, IMPACT_CATEGORY)\nend\n\n--[[\n    Shows one marker at a hit point and parks it again\n    once its lifetime is up, or shows nothing when every\n    marker is already out\n--]]\n\nfunction Impacts.show(position: Vector3)\n\tlocal copies: { Instance }? = Cellar:get(nil, IMPACT_CATEGORY)\n\tif not copies then\n\t\treturn\n\tend\n\n\tlocal marker = copies[1] :: BasePart\n\tmarker.CFrame = CFrame.new(position)\n\n\ttask.delay(IMPACT_LIFETIME, function ()\n\t\tCellar:rebound(marker)\n\tend)\nend\n\nreturn Impacts\n```\n\nCall `Impacts.fill()` once when the client boots, then `Impacts.show(position)` for each hit.\n\n`fill` finds the template at `ReplicatedStorage.Assets.Impact`, makes a folder in the Workspace for the parked markers, declares the category with that folder as its parent and clones 32 markers into it. `show` takes one marker with `get`, moves it to the hit and gives it back with `rebound` once its lifetime has passed. While all 32 markers are out, `get` returns nil and that hit shows none. The template is anchored because a parked copy sits below the height where the engine destroys unanchored parts ([Limits](#limits)).\n\nA copy comes back typed `Instance`, since a category can hold any kind of instance, so `show` casts the one it takes to `BasePart` at the call.\n\n## How each function works\n\nEvery function is called with a colon on the table the require returns, as `Cellar:get(...)`. A `count`, in `add`, `get` and `remove`, is a whole number of 1 or more, and any other count errors at the call, naming the function and the value. The snippets below name their categories and counts with constants a game reads from its config, as the example does, and assume a `casing` template and a `casingFolder` folder.\n\n### create\n\n`Cellar:create(category: string, parent: Instance?): boolean`\n\nDeclares a category. `category` is its name, which may carry slashes, as `FX/Casing/Rifle` does. `parent` is where the category's copies live: `add` parents each new copy there, and `rebound` puts each returned copy back there.\n\nA second `create` of a name already declared warns, returns `false` and leaves the first category as it was.\n\nA category declared with no parent takes its parent from the first `add`, as [add](#add) explains.\n\n```lua\nCellar:create(CASING_CATEGORY, casingFolder)\n```\n\n### add\n\n`Cellar:add(template: Instance, count: number?, parent: Instance?, category: string): boolean`\n\nClones `template` `count` times, once when `count` is nil. Each clone is parked, parented and put on the category's idle list before `add` returns, so the copies are ready for the next `get`. `add` runs at runtime as well as at boot, so a pool can grow while the game plays.\n\nThe template need not be in the DataModel. `Clone` does not ask, so a tree built in memory works as well as a model in `ReplicatedStorage`.\n\nA category has one parent. The third argument is optional, and `nil` means the category's parent. A category declared with no parent takes the parent the first `add` passes, or the Workspace when that `add` passes none, so the first `add` always settles it. After that, an `add` that names a different parent errors at the call, naming both. A pool that needs two folders is two categories.\n\n```lua\nCellar:create(CASING_CATEGORY)\nCellar:add(casing, CASING_COUNT, casingFolder, CASING_CATEGORY) -- Settles the category's parent on casingFolder\nCellar:add(casing, CASING_COUNT, nil, CASING_CATEGORY) -- Adds more copies under casingFolder\nCellar:add(casing, CASING_COUNT, Workspace, CASING_CATEGORY) -- Errors, since the category's parent is casingFolder\n```\n\n`add` raises an error at the call, so it reaches the code that called it, when:\n\n- `template` is nil;\n- `category` was never declared with `create`;\n- `template.Archivable` is false, since `Clone` returns nil for such an instance, and the message names the template;\n- `parent` differs from the category's parent.\n\n### get\n\n`Cellar:get(count: number?, category: string, name: string?): { Instance }?`\n\nTakes copies off the idle list and marks them out. It always returns an array: `Cellar:get(nil, category)` gives `{ copy }`, and a count gives up to that many copies, fewer when fewer are idle. With a `name`, it takes only copies with that name.\n\nIt returns nil, and takes nothing, when the category was never declared, when the category has no idle copy, or when a named `get` finds no copy with that name. It never waits for a category to appear.\n\n```lua\nlocal casings: { Instance }? = Cellar:get(CASING_BURST, CASING_CATEGORY)\nlocal pines: { Instance }? = Cellar:get(nil, TREE_CATEGORY, \"Pine\")\n```\n\n`get` takes from the end of the idle list, so nothing shifts and its cost does not grow with the pool. `add` and `rebound` put copies on that end, so the idle list is last in, first out: the copy given back most recently is the next one `get` hands out. A named `get` scans the list once to find its copies, so its cost does grow with the pool.\n\nA copy is typed `Instance`. A caller that knows it pooled parts casts at the call, as in `local marker = copies[1] :: BasePart`.\n\n### rebound\n\n`Cellar:rebound(copy: Instance): boolean`\n\nGives back a copy taken with `get`. It parents the copy to its category's parent, parks it ([Parking](#parking)) and puts it back on the idle list.\n\nIt resets only position and parent. Anything else the copy changed while it was out comes back with it ([Limits](#limits)).\n\n`rebound` warns and returns `false` for a copy that is not out, because it was never taken or was already given back, and for a copy that was destroyed. A destroyed copy never rejoins the pool.\n\n```lua\nCellar:rebound(marker)\n```\n\n### remove\n\n`Cellar:remove(category: string, count: number?): boolean`\n\nDestroys up to `count` idle copies, one when `count` is nil, taking from the end of the idle list. Copies that are out are left alone.\n\nAn unknown category raises an error at the call. A category with no idle copy makes `remove` warn and return `false`.\n\n`remove` keeps ObjectCache's name, and it destroys every copy it takes.\n\n```lua\nCellar:remove(CASING_CATEGORY, CASING_SURPLUS)\n```\n\n### getAll\n\n`Cellar:getAll(category: string): Cellar.Copies?`\n\nGives a category's copies as two fresh arrays, `idle` and `out`, for a caller that walks every copy, such as a texture quality change that swaps every pooled copy's textures. Changing the arrays changes nothing in the pool. Each array keeps its list's order: the last entry of `idle` is the next copy `get` takes, and `out` lists copies in the order `get` took them. An unknown category returns nil.\n\n```lua\nexport type Copies = {\n\tidle: { Instance },\n\tout: { Instance },\n}\n```\n\nEach call allocates both arrays, so `getAll` belongs at boot or on a settings change, never on a path that runs every frame. Cellar has no call that lists category names, so a caller that walks several categories keeps its own list of them.\n\n```lua\nlocal copies: Cellar.Copies? = Cellar:getAll(TREE_CATEGORY)\nif copies then\n\tfor _, copy: Instance in copies.idle do\n\t\tapplyQuality(copy)\n\tend\n\n\tfor _, copy: Instance in copies.out do\n\t\tapplyQuality(copy)\n\tend\nend\n```\n\nHere `applyQuality` is the game's own function.\n\n### Parking\n\nA copy is parked when `add` makes it and each time `rebound` takes it back. Parking moves a Model with `PivotTo` and a BasePart through its `CFrame`, to `CFrame.new(0, -100000, 0)`, one finite point 100,000 studs below the origin. Anything else, such as a Sound or an AudioPlayer, stays where it is.\n\nAt 100,000 studs a 32-bit position rounds to 1/128 of a stud, so a pooled Model's parts come back at most about 0.004 studs from their places.\n\n### A destroyed copy\n\nEach copy's `Destroying` event is connected when `add` makes it, and the connection takes the copy off whichever list holds it, idle or out. The copy owns that connection, so it ends with the copy, and nothing leaks.\n\nUnder deferred signals, a copy's `Destroying` may not have run yet when `rebound` is called on it, and a destroyed instance's `Parent` is locked. `rebound` guards its `Parent` write, so it warns and returns `false` there too, rather than throwing. For the same reason `get` never hands out an idle copy whose `Parent` is nil, which is how a copy destroyed under deferred signals looks before its `Destroying` runs, and drops it from the idle list.\n\n## Limits\n\n- Pooled parts must be anchored. The park point sits below `Workspace.FallenPartsDestroyHeight`, where the engine takes an unanchored part out of the world by setting its `Parent` to nil, without destroying it. `getAll` still li","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/fadeluc-123/roblox/cellar/0.1.0/readme"}