FastCast2

https://github.com/weenachuangkud/fastcast2
Admin
FastCast2 is a powerful modern Roblox projectile library designed to simulate thousands of...
Tokens:10,603
Snippets:101
Trust Score:6.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Commit message examples

Source: https://github.com/weenachuangkud/fastcast2/blob/main/CONTRIBUTING.md

Follow these conventional commit message formats when submitting changes.

```text
fix: prevent nil reference in ObjectCache
```

```text
feat: add BulkMoveTo support for parts.
```

```text
docs: improve usage example for parallel mode.
```

```text
chore: update Luau types in Caster.
```

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

### Initialize Serial Caster with ObjectCache

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Example of initializing a Serial Caster with ObjectCache enabled for part pooling.

```lua
caster:Init("BulkMoveTo", true, projectileTemplate, 500, workspace)
```

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

### Initialize and Fire a Basic Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

A minimal example showing how to instantiate a caster, initialize it, and trigger a raycast fire.

```lua
local caster = FastCast2.new()
caster:Init("BulkMoveTo", false)

caster.Hit = function(cast, result, velocity, bullet)
	print("Hit:", result.Instance)
end

caster:RaycastFire(origin, direction, 500, behavior)
```

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

### Execute Fire Methods

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Concrete examples of firing different projectile types using the shared fire interface.

```lua
-- Raycast: simple line-of-sight
caster:RaycastFire(Vector3.new(0, 5, 0), Vector3.new(0, 0, -1), 500, behavior)

-- Blockcast: pass a Vector3 size after origin
caster:BlockcastFire(Vector3.new(0, 5, 0), Vector3.new(2, 4, 2), Vector3.new(0, 0, -1), 500, behavior)

-- Spherecast: pass a radius after origin
caster:SpherecastFire(Vector3.new(0, 5, 0), 3, Vector3.new(0, 0, -1), 500, behavior)
```

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

### Cast Manipulation

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Methods to get, set, and sync properties of active casts.

```APIDOC
## Cast Manipulation

### Description
Methods to manipulate active casts. Note: After using Set or Add methods, you must call Caster:SyncChangesToCast(cast) to push state to the worker VM.

### Methods
- **FastCast:GetPositionCast(cast)**
- **FastCast:GetVelocityCast(cast)**
- **FastCast:GetAccelerationCast(cast)**
- **FastCast:SetVelocityCast(cast, velocity)**
- **FastCast:SetAccelerationCast(cast, acceleration)**
- **FastCast:SetPositionCast(cast, position)**
- **FastCast:AddPositionCast(cast, position)**
- **FastCast:AddVelocityCast(cast, velocity)**
- **FastCast:AddAccelerationCast(cast, acceleration)**
- **Caster:SyncChangesToCast(cast)**
- **FastCast:TerminateCast(cast)**
```

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

### Implement Serial Mode Projectile Firing

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

A complete example of setting up a serial caster to fire projectiles from the player's head on the main thread.

```lua
-- Services
local Rep = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

-- Requires
local FastCast2 = require(Rep:WaitForChild("FastCast2"))
local FastCastEnums = require(Rep:WaitForChild("FastCast2"):WaitForChild("FastCastEnums"))

-- CONSTANTS
local SPEED = 500

-- Variables
local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local Head = character:WaitForChild("Head")
local Mouse = player:GetMouse()

local ProjectileContainer = workspace:WaitForChild("Projectiles")
local ProjectileTemplate = Rep:WaitForChild("Projectile")

-- CastParams
local CastParams = RaycastParams.new()
CastParams.FilterDescendantsInstances = {character}
CastParams.FilterType = Enum.RaycastFilterType.Exclude
CastParams.IgnoreWater = true

-- Behavior (FastCastBehavior)
local behavior = FastCast2.newBehavior()
behavior.MaxDistance = 1000
behavior.RaycastParams = CastParams
behavior.HighFidelityBehavior = FastCastEnums.HighFidelityBehavior.Default
behavior.HighFidelitySegmentSize = 1
behavior.Acceleration = Vector3.new(0, -workspace.Gravity/2.3, 0)
behavior.CosmeticBulletContainer = ProjectileContainer
behavior.CosmeticBulletTemplate = ProjectileTemplate


-- Serial Caster (runs on main thread, simpler)
local Caster = FastCast2.new()
Caster:Init("BulkMoveTo", false) -- movementMode, useObjectCache

-- Events (can be set before Init)
Caster.Hit = function(cast, result, velocity, bullet)
	print("Hit: " .. result.Instance.Name)
end

-- Fire
local function fire()
	local origin = Head.Position
	local direction = (Mouse.Hit.Position - origin).Unit
	Caster:RaycastFire(origin, direction, SPEED, behavior)
end

-- Input
game:GetService("UserInputService").InputBegan:Connect(function(input, gameProcessed)
	if gameProcessed then return end
	if input.UserInputType == Enum.UserInputType.MouseButton1 then
		fire()
	end
end)
```

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

### Cast Manipulation Methods

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Static methods for getting, setting, and adding properties to an active cast, as well as terminating it.

```lua
-- Getters
FastCast:GetPositionCast(cast) → Vector3
FastCast:GetVelocityCast(cast) → Vector3
FastCast:GetAccelerationCast(cast) → Vector3

-- Setters (modifies trajectory, triggers CancelHighResCast)
FastCast:SetVelocityCast(cast, velocity) → ()
FastCast:SetAccelerationCast(cast, acceleration) → ()
FastCast:SetPositionCast(cast, position) → ()

-- Adders (relative modification)
FastCast:AddPositionCast(cast, position) → ()
FastCast:AddVelocityCast(cast, velocity) → ()
FastCast:AddAccelerationCast(cast, acceleration) → ()

-- Termination
FastCast:TerminateCast(cast) → ()
```

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

### Cast Manipulation Methods

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Methods for getting, setting, and modifying the physical properties of an active cast, such as position, velocity, and acceleration.

```APIDOC
## FastCast Manipulation Methods

### Description
These static methods on the `FastCast` object allow for the retrieval and modification of active cast trajectories. In parallel mode, `caster:SyncChangesToCast(cast)` must be called after modifications.

### Methods
- **GetPositionCast(cast)** -> Vector3
- **GetVelocityCast(cast)** -> Vector3
- **GetAccelerationCast(cast)** -> Vector3
- **SetVelocityCast(cast, velocity)** -> ()
- **SetAccelerationCast(cast, acceleration)** -> ()
- **SetPositionCast(cast, position)** -> ()
- **AddPositionCast(cast, position)** -> ()
- **AddVelocityCast(cast, velocity)** -> ()
- **AddAccelerationCast(cast, acceleration)** -> ()
- **TerminateCast(cast)** -> ()
```

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

### Mid-flight Cast Modification

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Example of modifying a projectile's trajectory during a hit event, including synchronization for parallel mode.

```lua
local function onHit(cast, result, velocity, bullet)
	-- Deflect the projectile upward on hit
	FastCast.SetVelocityCast(cast, Vector3.new(0, 100, 0))
	FastCast.SetPositionCast(cast, result.Position + Vector3.new(0, 2, 0))

	-- In parallel mode, push changes to the worker VM
	if caster.SyncChangesToCast then
		caster:SyncChangesToCast(cast)
	end
end
```

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

### Manipulate Casts

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Methods to get, set, or modify cast properties. Changes must be synced to the worker VM.

```luau
--// Cast Manipulation  (use FastCast static methods)

FastCast:GetPositionCast(cast) → Vector3
FastCast:GetVelocityCast(cast) → Vector3
FastCast:GetAccelerationCast(cast) → Vector3

FastCast:SetVelocityCast(cast, velocity) → ()
FastCast:SetAccelerationCast(cast, acceleration) → ()
FastCast:SetPositionCast(cast, position) → ()

FastCast:AddPositionCast(cast, position) → ()
FastCast:AddVelocityCast(cast, velocity) → ()
FastCast:AddAccelerationCast(cast, acceleration) → ()

-- ⚠ After any Set/Add, sync changes to push state to the worker VM:
Caster:SyncChangesToCast(cast) → ()

FastCast:TerminateCast(cast) → ()
-- TerminateCast fires CastTerminating, returns cosmetic to cache, and unregisters the cast.
-- Call from Hit/Pierced callback to stop a cast early:
-- caster.Hit = function(cast) FastCast:TerminateCast(cast) end
```

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

### Initialize Parallel Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Sets up a high-performance caster using multiple VMs. Requires specifying VM and container locations in the workspace.

```lua
local Caster = FastCast2.newParallel()
Caster:Init(
	4,                 -- numWorkers
	workspace,         -- VM folder parent
	"FastCastVMs",     -- VM folder name
	workspace,         -- container parent
	"VMContainer",     -- container name
	"VM",              -- VM name
	"BulkMoveTo",      -- movementMode
	nil,               -- FastCastEventsModule (optional)
	false              -- useObjectCache
)

-- Events work the same as serial
Caster.Hit = function(cast, result, velocity, bullet)
	print("Hit: " .. result.Instance.Name)
end

--[[
	-- Except:
	-- Caster.CanPierce
	--> You will have to use FastCastEventsModule for that
]]

-- Fire the same as serial
Caster:RaycastFire(origin, direction, SPEED, behavior)
Caster:BlockcastFire(origin, Vector3.new(2, 4, 2), direction, SPEED, behavior)
Caster:SpherecastFire(origin, 3, direction, SPEED, behavior)
```

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

### Clone and Sync FastCast2 with Rojo

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Commands to clone the repository and synchronize it with a Roblox place using the Rojo CLI.

```bash
git clone https://github.com/weenachuangkud/FastCast2.git
cd FastCast2
rm -rf .git
```

```bash
rojo sync -o <place-name>
```

```bash
rojo serve
```

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

### Configure BenchmarkClient Settings

Source: https://github.com/weenachuangkud/fastcast2/blob/main/benchmarks/README.md

Modify these variables at the top of the BenchmarkClient script to adjust simulation parameters.

```lua
local Parallel = true          -- true = parallel, false = serial
local numWorkers = 4           -- number of VM workers (parallel only)
local ProjectileAmount = 500   -- projectiles per benchmark run
local Instanced = true         -- use cosmetic bullet instances
local VisualizeCasts = false   -- show cast ray visualization
local BENCH_TIME = 6           -- seconds to simulate after creation
local MovementMode = "BulkMoveTo"
local ObjectCacheEnabled = false
```

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

### FastCast.new()

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Initializes a Serial Caster that runs simulations on the main thread.

```APIDOC
## FastCast.new()

### Description
Creates a new Serial Caster instance. Serial Caster runs all cast simulations on the main thread.

### Method
`caster:Init(movementMode, useObjectCache, template, cacheSize, cacheHolder)`

### Parameters
- **movementMode** (string) - Required - "BulkMoveTo" or "Motor6D"
- **useObjectCache** (boolean) - Required - Enable part pooling via ObjectCache
- **Template** (BasePart | Model) - Optional - Template for ObjectCache
- **CacheSize** (number) - Optional - Pre-allocated cache size (default 500)
- **CacheHolder** (Instance) - Optional - Parent for cached objects (default workspace)
```

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

### Initialize Serial Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Creates and initializes a standard Serial Caster instance.

```lua
local caster = FastCast2.new()
caster:Init(movementMode, useObjectCache, template, cacheSize, cacheHolder)
```

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

### Configure BenchmarkServer Settings

Source: https://github.com/weenachuangkud/fastcast2/blob/main/benchmarks/README.md

Modify these variables at the top of the BenchmarkServer script to adjust server-side simulation parameters.

```lua
local numWorkers = 4
local Instanced = false
local MovementMode = "BulkMoveTo"
local UseObjectCache = false
local ProjectileAmount = 500
local VisualizeCasts = false
local VELOCITY = 6
```

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

### Use Blockcast and Spherecast

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Alternative firing methods that use volume-based detection instead of standard raycasting.

```lua
-- Blockcast: pass a Vector3 size after origin
Caster:BlockcastFire(origin, Vector3.new(2, 4, 2), direction, SPEED, behavior)

-- Spherecast: pass a number radius after origin
Caster:SpherecastFire(origin, 3, direction, SPEED, behavior)
```

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

### Configure Parallel Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Methods to update caster settings after initialization.

```luau
--// Configuration

Caster:SetFastCastEventsModule(moduleScript: ModuleScript) → ()
Caster:SetMovementModeEnabled(enabled: boolean, mode: "BulkMoveTo" | "Motor6D") → ()
Caster:SetObjectCacheEnabled(enabled, Template?, CacheSize?, CacheHolder?) → ()
```

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

### Caster:Init

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Initializes the parallel caster with worker VMs and configuration settings. Must be called before any fire methods.

```APIDOC
## Caster:Init

### Description
Initializes the parallel caster instance. This must be called before any fire methods are invoked.

### Parameters
- **numWorkers** (number) - Required - Number of Actor VMs (must be > 1).
- **newParent** (Folder) - Required - Parent for the FastCastVMs Folder.
- **newName** (string) - Required - Name for the FastCastVMs Folder.
- **ContainerParent** (Folder) - Required - Parent for worker VM Containers.
- **VMContainerName** (string) - Required - Name for VM Containers.
- **VMname** (string) - Required - Name given to each worker VM.
- **movementMode** ("BulkMoveTo" | "Motor6D") - Required - Movement method.
- **FastCastEventsModule** (ModuleScript?) - Optional - ModuleScript returning a FastCastEvents table.
- **useObjectCache** (boolean) - Required - Enable ObjectCache for this Caster.
- **Template** (BasePart | Model?) - Optional - Template for ObjectCache.
- **CacheSize** (number?) - Optional - Number of objects to pre-allocate.
- **CacheHolder** (Instance?) - Optional - Parent for cached objects.
```

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

### Caster:Init()

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Initializes the Caster instance with movement and caching settings. Must be called before any fire methods.

```APIDOC
## Caster:Init()

### Description
Initializes the Caster. This must be called before any Fire methods.

### Parameters
- **movementMode** (string) - Required - "BulkMoveTo" or "Motor6D".
- **useObjectCache** (boolean) - Required - Enable ObjectCache.
- **Template** (BasePart | Model) - Optional - Template for ObjectCache.
- **CacheSize** (number) - Optional - Number of objects to pre-allocate.
- **CacheHolder** (Instance) - Optional - Parent for cached objects.
```

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

### Caster Serial Mode Configuration and Lifecycle

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Comprehensive reference for initializing, configuring events, and managing the lifecycle of a Serial Caster.

```luau
--// Construct & Init

local Caster = FastCast2.new()  -- Construct a new Serial Caster

Caster:Init(
    movementMode: "BulkMoveTo" | "Motor6D",  -- Movement method for cosmetic bullets.
    useObjectCache: boolean,                  -- Enable ObjectCache for this Caster.
    Template: BasePart | Model?,              -- Template for ObjectCache (if enabled).
    CacheSize: number?,                       -- Number of objects to pre-allocate.
    CacheHolder: Instance?                    -- Parent for cached objects.
)
-- ⚠ Must be called before any Fire methods — nothing happens without Init!


--// Events (assign callbacks before Init)

Caster.Hit = function(cast, result, velocity, cosmeticBullet) end
Caster.Pierced = function(cast, result, velocity, cosmeticBullet) end
Caster.LengthChanged = function(cast, lastPoint, rayDir, rayDisplacement) end
Caster.CastFire = function(cast, origin, direction, velocity, behavior) end
Caster.CastTerminating = function(cast) end
Caster.CanPierce = function(cast, result, velocity, cosmeticBullet) -> boolean end

--// Fire Methods

Caster:RaycastFire(origin, direction, velocity, BehaviorData)
Caster:BlockcastFire(origin, Size, direction, velocity, BehaviorData)
Caster:SpherecastFire(origin, Radius, direction, velocity, BehaviorData)

-- Example:
-- caster:RaycastFire(Vector3.new(0,5,0), Vector3.new(0,0,-1), 500, behavior)
-- caster:BlockcastFire(Vector3.new(0,5,0), Vector3.new(2,2,2), Vector3.new(0,0,-1), 500, behavior)
-- caster:SpherecastFire(Vector3.new(0,5,0), 3, Vector3.new(0,0,-1), 500, behavior)


--// Configuration

Caster:SetMovementModeEnabled(enabled: boolean, mode: "BulkMoveTo" | "Motor6D") → ()
Caster:SetObjectCacheEnabled(enabled: boolean, Template?, CacheSize?, CacheHolder?) → ()


--// Lifecycle

Caster:Destroy() → ()
```

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

### Configure FastCastBehavior

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Initializes and configures a new FastCastBehavior object to define projectile physics, visual settings, and event triggers.

```luau
local behavior = FastCast2.newBehavior()

behavior.RaycastParams = RaycastParams.new()
behavior.MaxDistance = 1000
behavior.Acceleration = Vector3.new(0, -196.2, 0)
behavior.HighFidelityBehavior = 1  -- Default | Automatic(2) | Always(3)
behavior.HighFidelitySegmentSize = 0.5
behavior.CosmeticBulletTemplate = somePart  -- Visual projectile
behavior.CosmeticBulletContainer = workspace  -- Parent for non-cached bullets
behavior.AutoIgnoreContainer = true
behavior.VisualizeCasts = false
behavior.VisualizeCastSettings = { ... }  -- Debug viz colors/sizes
behavior.UserData = {}  -- Arbitrary data accessible on the cast

behavior.FastCastEventsConfig = {
    UseLengthChanged = false,
    UseHit = true,
    UsePierced = true,
    UseCastTerminating = true,
    UseCanPierce = true,
    UseCastFire = true
}

behavior.FastCastEventsModuleConfig = {
    UseLengthChanged = false,
    UseHit = true,
    UsePierced = true,
    UseCastTerminating = true,
    UseCanPierce = true,
    UseCastFire = true
}
```

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

### Create a new branch for contributions

Source: https://github.com/weenachuangkud/fastcast2/blob/main/CONTRIBUTING.md

Use these commands to create a new branch for your work before making changes.

```bash
git checkout -b fix/something
```

```bash
git checkout -b feature/new-cool-things
```

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

### Initialize Parallel Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Constructs and initializes a parallel caster instance. Must be called before any fire methods.

```luau
--// Construct & Init

local Caster = FastCast2.newParallel()

Caster:Init(
    numWorkers: number,                 -- Number of Actor VMs. Must be > 1.
    newParent: Folder,                  -- Parent for the FastCastVMs Folder.
    newName: string,                    -- Name for the FastCastVMs Folder.
    ContainerParent: Folder,            -- Parent for worker VM Containers.
    VMContainerName: string,            -- Name for VM Containers.
    VMname: string,                     -- Name given to each worker VM.
    movementMode: "BulkMoveTo" | "Motor6D",  -- Movement method.
    FastCastEventsModule: ModuleScript?,-- ModuleScript returning a FastCastEvents table.
    useObjectCache: boolean,            -- Enable ObjectCache for this Caster.
    Template: BasePart | Model?,        -- Template for ObjectCache (if enabled).
    CacheSize: number?,                 -- Number of objects to pre-allocate.
    CacheHolder: Instance?              -- Parent for cached objects.
)
-- ⚠ Must be called before any Fire methods — nothing happens without Init!
```

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

### Configure Parallel Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Methods for configuring a Parallel Caster instance at runtime.

```lua
caster:SetFastCastEventsModule(moduleScript)  -- Parallel only
caster:SetMovementModeEnabled(enabled, mode)
caster:SetObjectCacheEnabled(enabled, template?, cacheSize?, cacheHolder?)
```

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

### Lifecycle Management

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Method to clean up resources associated with a caster.

```lua
caster:Destroy()  -- Cleans up all resources, actors, caches
```

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

### ActiveCast StateInfo Structure

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Contains runtime state, visualization settings, and trajectory data for an active cast.

```lua
cast.StateInfo.TotalRuntime: number
cast.StateInfo.HighFidelityBehavior: number
cast.StateInfo.HighFidelitySegmentSize: number
cast.StateInfo.IsActivelyResimulating: boolean
cast.StateInfo.CancelHighResCast: boolean
cast.StateInfo.VisualizeCasts: boolean
cast.StateInfo.VisualizeCastSettings: VisualizeCastSettings
cast.StateInfo.FastCastEventsConfig: FastCastEventsConfig
cast.StateInfo.FastCastEventsModuleConfig: FastCastEventsModuleConfig  -- Parallel only

cast.StateInfo.Trajectory = {
    StartTime: number,
    EndTime: number,            -- -1 if still active
    Origin: Vector3,
    InitialVelocity: Vector3,
    Acceleration: Vector3
}
```

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

### Implement FastCastEventsModule

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Define callback functions in a ModuleScript for high-frequency event handling in parallel mode.

```lua
-- In a ModuleScript (e.g., ReplicatedStorage.FastCastEventsModule)
local module = {}

module.Hit = function(cast, result, velocity, bullet)
    print("Hit:", result.Instance)
end

module.CanPierce = function(cast, result, velocity, bullet)
    return result.Instance:GetAttribute("CanPierce") == true
end

module.LengthChanged = function(cast, lastPoint, rayDir, displacement)
    -- Called every frame - more efficient than BindableEvent routing
end

return module
```

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

### Event Configuration

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Defining which events are enabled for standard and parallel execution modes.

```lua
behavior.FastCastEventsConfig = {
    UseLengthChanged = false,
    UseHit = true,
    UsePierced = true,
    UseCastTerminating = true,
    UseCanPierce = true,
    UseCastFire = true
}

behavior.FastCastEventsModuleConfig = {  -- Parallel only
    UseLengthChanged = false,
    UseHit = true,
    UsePierced = true,
    UseCastTerminating = true,
    UseCanPierce = true,
    UseCastFire = true
}
```

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

### FastCast2.new()

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Constructs a new Caster instance.

```APIDOC
## FastCast2.new()

### Description
Creates a new instance of a FastCast2 Caster.

### Signature
`FastCast2.new() -> Caster`
```

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

### Benchmark Output Format

Source: https://github.com/weenachuangkud/fastcast2/blob/main/benchmarks/README.md

The standard output format printed by both benchmark scripts after a simulation run.

```text
=== MODE BENCHMARK ===
ObjectCache Disabled
VisualizeCasts: Disabled
HighFidelityBehavior: Default
MovementMode: BulkMoveTo
Instanceless
numWorkers:    4
Firing 500 projectiles...
=== CREATION COMPLETE ===
Delta: xx.xx ms
Average FPS: xx.xx
Max FPS: xx.xx
Min FPS: xx.xx
=== SIMULATION COMPLETE ===
...
=== DONE ===
Delta: xx.xx ms
Average FPS: xx.xx
Max FPS: xx.xx
Min FPS: xx.xx
```

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

### FastCast.newParallel()

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Initializes a Parallel Caster that runs simulations on separate Actor VMs.

```APIDOC
## FastCast.newParallel()

### Description
Creates a new Parallel Caster instance for high-performance scenarios using Actor-based worker VMs.

### Method
`caster:Init(numWorkers, newParent, newName, ContainerParent, VMContainerName, VMname, movementMode, fastCastEventsModule, useObjectCache, template, cacheSize, CacheHolder)`

### Parameters
- **numWorkers** (number) - Required - Number of Actor VMs (must be > 1)
- **newParent** (Folder) - Required - Parent for the FastCastVMs Folder
- **newName** (string) - Required - Name for the FastCastVMs Folder
- **ContainerParent** (Folder) - Required - Parent for worker VM Containers
- **VMContainerName** (string) - Required - Name for VM Containers
- **VMname** (string) - Required - Name given to each worker VM
- **movementMode** (string) - Required - "BulkMoveTo" or "Motor6D"
- **fastCastEventsModule** (ModuleScript) - Optional - FastCastEvents module
- **useObjectCache** (boolean) - Required - Enable ObjectCache
- **template** (BasePart | Model) - Optional - ObjectCache template
- **cacheSize** (number) - Optional - ObjectCache size
- **CacheHolder** (Instance) - Optional - ObjectCache parent
```

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

### Fire Methods

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Methods to initiate projectile casts using different shapes.

```APIDOC
## Fire Methods

### Description
Methods to fire projectiles in parallel mode.

### Methods
- **Caster:RaycastFire(origin, direction, velocity, BehaviorData)**
- **Caster:BlockcastFire(origin, Size, direction, velocity, BehaviorData)**
- **Caster:SpherecastFire(origin, Radius, direction, velocity, BehaviorData)**
```

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

### Register FastCastEventsModule

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Links the event module to a parallel caster instance after initialization.

```lua
Caster:SetFastCastEventsModule(pathTo.FastCastEventsModule)
```

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

### Initialize ObjectCache for Bullet Pooling

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Configures the caster to use object pooling, which reuses bullet instances to improve performance.

```lua
local Caster = FastCast2.new()
Caster:Init("BulkMoveTo", true, ProjectileTemplate, 500, workspace)
--                                    ^template   ^size  ^holder
```

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

### Fire Methods for Parallel Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Methods to initiate ray, block, or sphere casts. These function similarly to serial mode.

```luau
--// Fire Methods (same as Serial)

Caster:RaycastFire(origin, direction, velocity, BehaviorData)
Caster:BlockcastFire(origin, Size, direction, velocity, BehaviorData)
Caster:SpherecastFire(origin, Radius, direction, velocity, BehaviorData)

-- Example:
-- caster:RaycastFire(Vector3.new(0,5,0), Vector3.new(0,0,-1), 500, behavior)
-- caster:BlockcastFire(Vector3.new(0,5,0), Vector3.new(2,2,2), Vector3.new(0,0,-1), 500, behavior)
-- caster:SpherecastFire(Vector3.new(0,5,0), 3, Vector3.new(0,0,-1), 500, behavior)
```

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

### Configure Motor6D Movement Mode

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Enables high-performance Motor6D movement mode and provides methods to toggle modes at runtime.

```lua
local Caster = FastCast2.new()
Caster:Init("Motor6D", false) -- movementMode = "Motor6D"
```

```lua
Caster:SetMovementModeEnabled(true, "Motor6D")   -- enable Motor6D
Caster:SetMovementModeEnabled(true, "BulkMoveTo") -- switch back
```

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

### Caster:Fire Methods

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Methods to initiate projectile firing using different casting techniques.

```APIDOC
## Caster:RaycastFire / BlockcastFire / SpherecastFire

### Description
Initiates a projectile fire using raycasting, blockcasting, or spherecasting.

### Methods
- `Caster:RaycastFire(origin, direction, velocity, BehaviorData)`
- `Caster:BlockcastFire(origin, Size, direction, velocity, BehaviorData)`
- `Caster:SpherecastFire(origin, Radius, direction, velocity, BehaviorData)`
```

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

### ActiveCast RayInfo Structure

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Defines the raycasting parameters and world context for the projectile.

```lua
cast.RayInfo.Parameters: RaycastParams
cast.RayInfo.WorldRoot: WorldRoot
cast.RayInfo.MaxDistance: number
cast.RayInfo.CosmeticBulletObject: Instance?
cast.RayInfo.Size: Vector3       -- Blockcast only
cast.RayInfo.Radius: number      -- Spherecast only
```

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

### Implement FastCastEventsModule

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Defines custom event handlers for parallel casters, specifically required for logic like piercing.

```lua
-- Services
local Rep = game:GetService("ReplicatedStorage")

-- Modules

local FastCast2 = Rep:WaitForChild("FastCast2")

-- Requires
local TypeDef = require(FastCast2:WaitForChild("TypeDefinitions"))

-- Module

local module: TypeDef.FastCastEvents = {}

local debounce = false
local debounce_time = 0.2

module.LengthChanged = function(cast : TypeDef.ActiveCastData)
	if not debounce then
		debounce = true
		print("OnLengthChanged Test")
		task.delay(debounce_time, function()
			debounce = false
		end)
	end
end

module.CastFire = function()
	print("CastFire!")
end

module.CastTerminating = function()
	print("CastTerminating!")
end

module.Hit = function()
	print("Hit!")
end

module.CanPierce = function(cast : TypeDef.ActiveCastData, resultOfCast : RaycastResult, segmentVelocity, CosmeticBulletObject)
	local CanPierce = false
	if resultOfCast.Instance:GetAttribute("CanPierce") == true then
		CanPierce = true
	end
	print(CanPierce)
	return CanPierce
end

module.Pierced = function()
	print("Pierced!")
end


return module
```

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

### Caster Lifecycle

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Method for cleaning up resources associated with a caster instance.

```APIDOC
## caster:Destroy()

### Description
Cleans up all resources, actors, and caches associated with the caster instance.
```

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

### Fire Methods Interface

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

The shared interface for firing projectiles using different geometric shapes.

```lua
caster:RaycastFire(origin, direction, velocity, BehaviorData?)
caster:BlockcastFire(origin, Size, direction, velocity, BehaviorData?)
caster:SpherecastFire(origin, Radius, direction, velocity, BehaviorData?)
```

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

### FastCastBehavior

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Configuration object used to define the physical and visual properties of a projectile cast.

```APIDOC
## FastCastBehavior

### Description
Defines the behavior settings for a projectile cast, including physics parameters, visual templates, and event configurations.

### Properties
- **RaycastParams** (RaycastParams) - Parameters for the raycast engine.
- **MaxDistance** (number) - Maximum distance the projectile can travel.
- **Acceleration** (Vector3) - Acceleration applied to the projectile (e.g., gravity).
- **HighFidelityBehavior** (number) - Fidelity mode (Default, Automatic, or Always).
- **HighFidelitySegmentSize** (number) - Segment size for high-fidelity calculations.
- **CosmeticBulletTemplate** (Instance) - Visual representation of the projectile.
- **CosmeticBulletContainer** (Instance) - Parent container for non-cached bullets.
- **AutoIgnoreContainer** (boolean) - Whether to automatically ignore the container in raycasts.
- **VisualizeCasts** (boolean) - Toggle for debug visualization.
- **UserData** (table) - Arbitrary data storage for the cast.
- **FastCastEventsConfig** (table) - Configuration for enabled events.
- **FastCastEventsModuleConfig** (table) - Configuration for parallel event processing.
```

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

### Assign Caster Events

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Defines event callbacks for the caster. These can be assigned before or after initialization.

```lua
caster.Hit = function(cast, result, velocity, cosmeticBullet) end
caster.Pierced = function(cast, result, velocity, cosmeticBullet) end
caster.LengthChanged = function(cast, lastPoint, rayDir, rayDisplacement) end
caster.CastFire = function(cast, origin, direction, velocity, behavior) end
caster.CastTerminating = function(cast) end
caster.CanPierce = function(cast, result, velocity, cosmeticBullet) -> boolean end
```

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

### caster:SetFastCastEventsModule(pathToModule)

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Registers a ModuleScript to handle high-frequency events directly, bypassing BindableEvent overhead for improved performance in parallel mode.

```APIDOC
## caster:SetFastCastEventsModule(pathToModule)

### Description
Registers a ModuleScript that provides direct callbacks for FastCast events. This is intended for parallel-mode usage to handle high-frequency events like LengthChanged efficiently.

### Parameters
- **pathToModule** (Instance) - Required - The ModuleScript containing the event callback functions (Hit, CanPierce, LengthChanged).
```

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

### ActiveCastData

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Data structure representing an active projectile cast, containing state information and ray parameters.

```APIDOC
## ActiveCastData

### Description
Provides access to the current state and configuration of an active projectile cast.

### Properties
- **ID** (number) - Unique identifier for the cast.
- **Type** (number) - Cast type (1=Raycast, 2=Blockcast, 3=Spherecast).
- **CFrame** (CFrame) - Current CFrame of the cosmetic bullet.
- **UserData** (any) - Custom data associated with the cast.
- **StateInfo** (table) - Contains runtime statistics, trajectory data, and event configurations.
- **RayInfo** (table) - Contains raycast parameters, world root, and geometric constraints (Size/Radius).
```

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

### ActiveCast Data Structure Properties

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/api-reference.md

Defines the core properties of an ActiveCast object, including its unique identifier and cast variant type.

```lua
cast.ID: number              -- Unique identifier
cast.CFrame: CFrame          -- Current cosmetic bullet CFrame
cast.UserData: any           -- From behavior.UserData
cast.CastVariant: {          -- Cast type info
    CastType: number,        -- 1=Raycast, 2=Blockcast, 3=Spherecast
    Size: Vector3?,          -- Blockcast only
    Radius: number?          -- Spherecast only
}
```

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

### Access ActiveCastData

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Describes the properties available on an active cast object, including state information and ray parameters.

```luau
cast.ID: number              -- Unique cast identifier
cast.Type: number            -- 1=Raycast, 2=Blockcast, 3=Spherecast
cast.CFrame: CFrame          -- Current cosmetic bullet CFrame
cast.UserData: any           -- Custom data from behavior.UserData
cast.CastVariant: table      -- { CastType, Size?|Radius? }

--// cast.StateInfo

cast.StateInfo.TotalRuntime: number
cast.StateInfo.HighFidelityBehavior: number
cast.StateInfo.HighFidelitySegmentSize: number
cast.StateInfo.IsActivelyResimulating: boolean
cast.StateInfo.CancelHighResCast: boolean
cast.StateInfo.FastCastEventsConfig: FastCastEventsConfig
cast.StateInfo.FastCastEventsModuleConfig: FastCastEventsModuleConfig  -- Parallel only
cast.StateInfo.VisualizeCasts: boolean
cast.StateInfo.VisualizeCastSettings: VisualizeCastSettings

cast.StateInfo.Trajectory = {
    StartTime: number,
    EndTime: number,            -- -1 if still active
    Origin: Vector3,
    InitialVelocity: Vector3,
    Acceleration: Vector3
}

--// cast.RayInfo

cast.RayInfo.Parameters: RaycastParams
cast.RayInfo.WorldRoot: WorldRoot
cast.RayInfo.MaxDistance: number
cast.RayInfo.CosmeticBulletObject: Instance?
cast.RayInfo.Size: Vector3       -- Blockcast only
cast.RayInfo.Radius: number      -- Spherecast only
```

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

### Caster:Destroy()

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Cleans up the Caster instance.

```APIDOC
## Caster:Destroy()

### Description
Destroys the Caster instance and cleans up resources.
```

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

### Destroy Caster

Source: https://github.com/weenachuangkud/fastcast2/blob/main/docs/cheatsheet.md

Cleans up the caster instance.

```luau
--// Lifecycle

Caster:Destroy() → ()
```

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

### Manipulate Active Casts

Source: https://github.com/weenachuangkud/fastcast2/blob/main/README.md

Provides methods to read and modify the state of active casts, such as position, velocity, and acceleration.

```lua
-- Read state
local pos = FastCast2:GetPositionCast(cast)
local vel = FastCast2:GetVelocityCast(cast)
local accel = FastCast2:GetAccelerationCast(cast)

-- Modify state (automatically rebases trajectory)
FastCast2:SetPositionCast(cast, Vector3.new(0, 50, 0))
FastCast2:SetVelocityCast(cast, Vector3.new(0, 100, 0))
FastCast2:SetAccelerationCast(cast, Vector3.new(0, -workspace.Gravity, 0))

-- Relative changes
FastCast2:AddPositionCast(cast, Vector3.new(0, 10, 0))
FastCast2:AddVelocityCast(cast, Vector3.new(0, 20, 0))
FastCast2:AddAccelerationCast(cast, Vector3.new(0, -50, 0))

-- Terminate a cast early (fires CastTerminating and cleans up)
FastCast2:TerminateCast(cast)
```
Tokens:
Raw