### Use Models as Templates in Luau

Source: https://context7.com/pyseph/objectcache/llms.txt

Initialize a cache using a Model template, which utilizes BulkMoveTo for efficient movement of welded parts.

```luau
-- Create a model template with welded parts
local missileTemplate = Instance.new("Model")
missileTemplate.Name = "Missile"

local body = Instance.new("Part")
body.Name = "Body"
body.Size = Vector3.new(1, 1, 4)
body.Anchored = true
body.Parent = missileTemplate

local fin1 = Instance.new("Part")
fin1.Size = Vector3.new(0.1, 1, 1)
fin1.Position = body.Position + Vector3.new(0.5, 0, 1.5)
fin1.Parent = missileTemplate

-- Weld fin to body
local weld = Instance.new("WeldConstraint")
weld.Part0 = body
weld.Part1 = fin1
weld.Parent = fin1

-- Set PrimaryPart (required for model templates)
missileTemplate.PrimaryPart = body

-- Create cache with model template
local missileCache = ObjectCache.new(missileTemplate, 50)

-- Get and return models just like parts
local function launchMissile(targetCFrame: CFrame)
    local missile = missileCache:GetPart(targetCFrame)
    return missile
end

local function destroyMissile(missile: BasePart)
    missileCache:ReturnPart(missile)
end
```

--------------------------------

### Initialize ObjectCache

Source: https://context7.com/pyseph/objectcache/llms.txt

Create a new cache instance using a template part or model, with optional pre-allocation and container settings.

```luau
local ObjectCache = require(path.to.ObjectCache)

-- Create a cache with a simple part template
local bulletTemplate = Instance.new("Part")
bulletTemplate.Size = Vector3.new(0.2, 0.2, 2)
bulletTemplate.Anchored = true
bulletTemplate.CanCollide = false
bulletTemplate.Material = Enum.Material.Neon
bulletTemplate.Color = Color3.fromRGB(255, 255, 0)

-- Initialize cache with 100 pre-allocated bullets in a custom container
local cacheContainer = Instance.new("Folder")
cacheContainer.Name = "BulletCache"
cacheContainer.Parent = workspace

local bulletCache = ObjectCache.new(bulletTemplate, 100, cacheContainer)
```

--------------------------------

### Complete Bullet System with ObjectCache

Source: https://context7.com/pyseph/objectcache/llms.txt

This Luau script demonstrates a full bullet system using ObjectCache for efficient object pooling. It includes initialization, firing bullets, updating their movement and collision detection, and cleanup. Ensure ObjectCache is required and a bullet template is configured.

```luau
local ObjectCache = require(path.to.ObjectCache)
local RunService = game:GetService("RunService")

-- Configuration
local BULLET_SPEED = 500
local BULLET_LIFETIME = 3
local INITIAL_POOL_SIZE = 200

-- Create bullet template
local bulletTemplate = Instance.new("Part")
bulletTemplate.Name = "Bullet"
bulletTemplate.Size = Vector3.new(0.2, 0.2, 1)
bulletTemplate.Anchored = true
bulletTemplate.CanCollide = false
bulletTemplate.Material = Enum.Material.Neon
bulletTemplate.Color = Color3.fromRGB(255, 200, 0)

-- Initialize cache
local bulletCache = ObjectCache.new(bulletTemplate, INITIAL_POOL_SIZE)
bulletCache:SetExpandAmount(50)

-- Active bullet tracking
local activeBullets: {[BasePart]: {velocity: Vector3, lifetime: number}} = {}

local function fireBullet(origin: Vector3, direction: Vector3)
    local bulletCFrame = CFrame.lookAt(origin, origin + direction)
    local bullet = bulletCache:GetPart(bulletCFrame)

    activeBullets[bullet] = {
        velocity = direction.Unit * BULLET_SPEED,
        lifetime = 0
    }
end

local function updateBullets(deltaTime: number)
    for bullet, data in pairs(activeBullets) do
        data.lifetime += deltaTime

        -- Check lifetime
        if data.lifetime >= BULLET_LIFETIME then
            bulletCache:ReturnPart(bullet)
            activeBullets[bullet] = nil
            continue
        end

        -- Raycast for collision
        local movement = data.velocity * deltaTime
        local rayResult = workspace:Raycast(bullet.Position, movement)

        if rayResult then
            -- Hit something - return bullet
            bulletCache:ReturnPart(bullet)
            activeBullets[bullet] = nil
            -- Handle damage, effects, etc.
        else
            -- Move bullet
            bullet.CFrame = bullet.CFrame + movement
        end
    end
end

RunService.Heartbeat:Connect(updateBullets)

-- Cleanup function
local function destroyBulletSystem()
    activeBullets = {}
    bulletCache:Destroy()
end

return {
    fire = fireBullet,
    destroy = destroyBulletSystem
}
```

--------------------------------

### Retrieve Parts from Cache

Source: https://context7.com/pyseph/objectcache/llms.txt

Use GetPart to pull objects from the pool. Passing a CFrame argument allows for immediate, batched positioning.

```luau
-- Get a part and position it immediately (recommended for best performance)
local function fireBullet(origin: CFrame)
    local bullet = bulletCache:GetPart(origin)

    -- Bullet is now positioned at origin and ready for use
    -- Additional setup if needed
    bullet.Color = Color3.fromRGB(255, 0, 0)

    return bullet
end

-- Get a part without positioning (position it manually later)
local function spawnProjectile()
    local projectile = bulletCache:GetPart()
    projectile.CFrame = CFrame.new(0, 10, 0) -- Manual positioning
    return projectile
end

-- Example: Fire multiple bullets in a spread pattern
local function fireSpread(origin: Vector3, direction: Vector3, count: number)
    local bullets = {}
    for i = 1, count do
        local angle = math.rad((i - count/2) * 5)
        local spreadCFrame = CFrame.new(origin, origin + direction) * CFrame.Angles(0, angle, 0)
        bullets[i] = bulletCache:GetPart(spreadCFrame)
    end
    return bullets
end
```

--------------------------------

### ObjectCache API Methods

Source: https://github.com/pyseph/objectcache/blob/main/README.md

Constructor and primary methods for managing part lifecycle and retrieval.

```luau
ObjectCacheConstructor.new(Template: BasePart, CacheSize: number?, CachesContainer: Folder?) -> ObjectCache

ObjectCache:GetPart(PartCFrame: CFrame?): BasePart

ObjectCache:ReturnPart(Part: BasePart)

ObjectCache:Destroy()
```

--------------------------------

### ObjectCache Constructor

Source: https://github.com/pyseph/objectcache/blob/main/README.md

Initializes a new ObjectCache instance with a template part.

```APIDOC
## Constructor

### Description
Creates a new ObjectCache instance to manage a pool of parts based on a provided template.

### Method
new

### Parameters
#### Arguments
- **Template** (BasePart) - Required - The part or model to be used as the template for the cache.
- **CacheSize** (number) - Optional - The initial size of the cache.
- **CachesContainer** (Folder) - Optional - The folder where cached objects will be stored.
```

--------------------------------

### Configure Auto-Expand Amount in Luau

Source: https://context7.com/pyseph/objectcache/llms.txt

Define the batch size for automatic pool growth, useful for balancing memory usage across different hardware.

```luau
-- Set a smaller expansion amount for memory-constrained scenarios
bulletCache:SetExpandAmount(25)

-- Set a larger expansion amount for high-throughput scenarios
bulletCache:SetExpandAmount(100)

-- Example: Configure based on device performance
local function configureForDevice()
    local isLowEnd = game:GetService("UserInputService").TouchEnabled
    if isLowEnd then
        bulletCache:SetExpandAmount(10) -- Smaller batches on mobile
    else
        bulletCache:SetExpandAmount(100) -- Larger batches on PC
    end
end
```

--------------------------------

### Return Parts to Cache

Source: https://context7.com/pyseph/objectcache/llms.txt

Return objects to the pool using ReturnPart, which automatically moves them away from the playable area.

```luau
-- Return a single part to the cache
local function destroyBullet(bullet: BasePart)
    bulletCache:ReturnPart(bullet)
    -- Bullet is now queued to be moved away and available for reuse
end

-- Example: Bullet system with automatic cleanup
local activeBullets = {}

local function fireBullet(origin: CFrame, velocity: Vector3)
    local bullet = bulletCache:GetPart(origin)
    activeBullets[bullet] = {
        velocity = velocity,
        lifetime = 0,
        maxLifetime = 5
    }
end

local function updateBullets(deltaTime: number)
    for bullet, data in pairs(activeBullets) do
        data.lifetime += deltaTime

        if data.lifetime >= data.maxLifetime then
            -- Return expired bullet to cache
            bulletCache:ReturnPart(bullet)
            activeBullets[bullet] = nil
        else
            -- Move bullet
            bullet.CFrame = bullet.CFrame + data.velocity * deltaTime
        end
    end
end

game:GetService("RunService").Heartbeat:Connect(updateBullets)
```

--------------------------------

### ObjectCache:GetPart

Source: https://github.com/pyseph/objectcache/blob/main/README.md

Retrieves a part from the cache, optionally setting its CFrame immediately.

```APIDOC
## ObjectCache:GetPart

### Description
Retrieves an object from the cache. Providing a CFrame allows the module to use BulkMoveTo for optimized positioning.

### Parameters
#### Arguments
- **PartCFrame** (CFrame) - Optional - The target CFrame to move the part to upon retrieval.

### Response
- **Returns** (BasePart) - The retrieved part or model.
```

--------------------------------

### ObjectCache:ReturnPart

Source: https://github.com/pyseph/objectcache/blob/main/README.md

Returns a part to the cache for future reuse.

```APIDOC
## ObjectCache:ReturnPart

### Description
Returns a previously retrieved part to the cache pool.

### Parameters
#### Arguments
- **Part** (BasePart) - Required - The part or model to return to the cache.
```

--------------------------------

### ExpandCache

Source: https://context7.com/pyseph/objectcache/llms.txt

Manually adds a specified number of objects to the cache pool to pre-allocate capacity.

```APIDOC
## ExpandCache(amount)

### Description
Manually adds more objects to the cache pool. This is useful for pre-allocating additional capacity before heavy usage periods.

### Parameters
- **amount** (number) - Required - The number of objects to add to the pool.
```

--------------------------------

### Check Part Status

Source: https://context7.com/pyseph/objectcache/llms.txt

Verify if a part is currently active or available in the pool using IsInUse.

```luau
-- Check if a specific part is currently active
local function isBulletActive(bullet: BasePart): boolean
    return bulletCache:IsInUse(bullet)
end

-- Example: Safe return that checks status first
local function safeReturnPart(part: BasePart)
    if bulletCache:IsInUse(part) then
        bulletCache:ReturnPart(part)
        print("Part returned to cache")
    else
        print("Part is already in cache pool")
    end
end

-- Example: Count active parts
local function countActiveBullets(bullets: {BasePart}): number
    local count = 0
    for _, bullet in bullets do
        if bulletCache:IsInUse(bullet) then
            count += 1
        end
    end
    return count
end
```

--------------------------------

### Update

Source: https://context7.com/pyseph/objectcache/llms.txt

Forces an immediate update of all queued part movements.

```APIDOC
## Update()

### Description
Forces an immediate update of all queued part movements. Normally movements are batched and executed automatically, but this can force immediate execution.
```

--------------------------------

### Expand Cache Capacity in Luau

Source: https://context7.com/pyseph/objectcache/llms.txt

Manually increase the pool size to pre-allocate capacity for high-demand scenarios.

```luau
-- Pre-expand cache before a wave of enemies
local function prepareForBossWave()
    bulletCache:ExpandCache(500) -- Add 500 more bullets to the pool
    print("Cache expanded for boss wave")
end

-- Example: Dynamic expansion based on gameplay
local function onWaveStart(waveNumber: number)
    local expectedBullets = waveNumber * 100
    bulletCache:ExpandCache(expectedBullets)
end
```

--------------------------------

### SetExpandAmount

Source: https://context7.com/pyseph/objectcache/llms.txt

Configures the number of objects created when the cache automatically expands.

```APIDOC
## SetExpandAmount(amount)

### Description
Configures how many objects are created when the cache automatically expands (when GetPart is called but the pool is empty). Default is 50.

### Parameters
- **amount** (number) - Required - The number of objects to create during automatic expansion.
```

--------------------------------

### Destroy

Source: https://context7.com/pyseph/objectcache/llms.txt

Cleans up the cache by destroying the container folder and all cached objects.

```APIDOC
## Destroy()

### Description
Cleans up the cache by destroying the container folder and all cached objects.
```

--------------------------------

### Force Update Movements in Luau

Source: https://context7.com/pyseph/objectcache/llms.txt

Trigger an immediate update of all queued movements to ensure parts are positioned correctly before physics checks.

```luau
-- Force immediate update of all pending movements
bulletCache:Update()

-- Example: Ensure parts are moved before a physics check
local function checkCollisions()
    bulletCache:Update() -- Ensure all parts are in their final positions

    -- Now perform collision detection
    for bullet, data in pairs(activeBullets) do
        local rayResult = workspace:Raycast(bullet.Position, data.velocity.Unit * 2)
        if rayResult then
            handleHit(bullet, rayResult)
        end
    end
end
```

--------------------------------

### ObjectCache:Destroy

Source: https://github.com/pyseph/objectcache/blob/main/README.md

Cleans up the ObjectCache instance.

```APIDOC
## ObjectCache:Destroy

### Description
Destroys the ObjectCache instance and cleans up all managed objects.
```

--------------------------------

### Destroy Cache in Luau

Source: https://context7.com/pyseph/objectcache/llms.txt

Clean up the cache container and all associated objects to free memory.

```luau
-- Clean up when done with the cache
local function cleanup()
    bulletCache:Destroy()
    bulletCache = nil
end

-- Example: Cleanup on game end or scene change
game.Players.PlayerRemoving:Connect(function(player)
    if player == game.Players.LocalPlayer then
        cleanup()
    end
end)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.