Introduce serial and parallel caster modes with SoA simulation architecture

.gitignore

@@ -10,4 +10,8 @@
 
 # Moonwave related stuff
 /node_modules
-/package-lock.json
+/package-lock.json
+
+# FastCast2 related stuff
+/src/*.legacy.luau
+.aider*

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+## Project Overview
+
+FastCast2 is a Roblox projectile library written in Luau, providing high-performance raycasting, blockcasting, and spherecasting with parallel scripting support. It is an unofficial continuation of the original FastCast library.
+
+- **Language**: Luau (Roblox)
+- **Build Tool**: Rojo (`rojo sync`, `rojo serve`)
+- **Documentation**: Moonwave
+- **Repository**: https://github.com/weenachuangkud/FastCast2
+
+## Development Commands
+
+- **Sync to Roblox**: `rojo sync -o <place-name>`
+- **Serve live**: `rojo serve` (then connect via Studio → Plugins → Rojo)
+- **Build docs**: `moonwave build`
+- **Publish docs**: `moonwave build --publish`
+
+## Project Structure
+
+```
+src/FastCast2/           # Main source code (synced to ReplicatedStorage)
+.default.project.json    # Rojo project configuration
+```
+
+## Testing
+
+There are no automated tests in this project. Testing is done manually through Roblox Studio.
+
+## Code Style
+
+- Uses Luau static typing
+- Follows standard Luau conventions (PascalCase for types, camelCase for variables)
+- Modules are required via `require(path)`
+
+## Important Notes
+
+- Requires Roblox Studio to run/test code
+- Parallel casting requires `VMsDispatcher` module
+- Cosmetic bullets should have `CanTouch = false`, `CanCollide = false`, `CanQuery = false`
+
+## Agent Skills
+To understand specific project workflows, refer to the skills defined here:
+- @skills/architecture.md

Benchmarks/benchParallel.client.luau

@@ -0,0 +1,154 @@
+-- Services
+local RS = game:GetService("RunService")
+local Rep = game:GetService("ReplicatedStorage")
+local UIS = game:GetService("UserInputService")
+local RepFirst = game:GetService("ReplicatedFirst")
+
+-- Requires
+local FastCast = require(Rep:WaitForChild("FastCast2"))
+
+-- Variables
+local ProjectileContainer = Instance.new("Folder")
+ProjectileContainer.Name = "FastCast2PJ_Parallel"
+ProjectileContainer.Parent = workspace
+local ProjectileTemplate = Instance.new("Part")
+ProjectileTemplate.Name = "Projectile"
+ProjectileTemplate.Parent = Rep
+ProjectileTemplate.Size = Vector3.new(1,1,1)
+ProjectileTemplate.CanCollide = false
+ProjectileTemplate.Anchored = true
+ProjectileTemplate.CanQuery = false
+ProjectileTemplate.CanTouch = false
+ProjectileTemplate.Position = Vector3.new(1,1,1)
+ProjectileTemplate.Massless = true
+
+-- FPS tracking
+local startTime = tick()
+local updateRate = 0.5
+local fpsTable = {}
+local averageFps = 0
+local maxFps = 0
+local minFps = math.huge
+local currentFps = 0
+
+RS.Heartbeat:Connect(function(dt: number)
+	local fps = 1/dt
+	currentFps = fps
+	if fps > maxFps then
+		maxFps = fps
+	end
+	if fps < minFps then
+		minFps = fps
+	end
+	table.insert(fpsTable, fps)
+
+	if tick() >= startTime + updateRate then
+		local totalFps = 0
+		for _, vFps in fpsTable do 
+			totalFps += vFps
+		end
+		averageFps = totalFps / #fpsTable
+		fpsTable = {}
+		startTime = tick()
+	end
+end)
+
+-- CastParams
+local CastParams = RaycastParams.new()
+CastParams.FilterDescendantsInstances = {}
+CastParams.FilterType = Enum.RaycastFilterType.Exclude
+CastParams.IgnoreWater = true
+
+-- Behavior
+local castBehavior = FastCast.newBehavior()
+castBehavior.MaxDistance = 999999999
+castBehavior.RaycastParams = CastParams
+castBehavior.HighFidelityBehavior = 1
+castBehavior.HighFidelitySegmentSize = 1
+castBehavior.Acceleration = Vector3.new(0, 0, 0)
+castBehavior.AutoIgnoreContainer = true
+castBehavior.CosmeticBulletContainer = ProjectileContainer
+castBehavior.CosmeticBulletTemplate = ProjectileTemplate
+
+-- Parallel Caster
+local Caster = FastCast.newParallel()
+Caster:Init(
+	4,              -- numWorkers
+	RepFirst,       -- newParent
+	"CastVMs",      -- newName
+	RepFirst,       -- ContainerParent
+	"CastVMContainer", -- VMContainerName
+	"CastVM",       -- VMname
+	true,           -- useBulkMoveTo
+	nil,            -- FastCastEventsModule (optional for parallel)
+	false,          -- useObjectCache
+	nil,            -- Template
+	500,            -- CacheSize
+	workspace       -- CacheHolder
+)
+
+local activeCasts = {}
+
+Caster.CastFire:Connect(function(cast)
+	table.insert(activeCasts, cast)
+end)
+
+-- Functions
+local function summary()
+	print(string.format("Delta: %.2f ms", 1000 / currentFps))
+	print(string.format("Average FPS: %.2f", averageFps))
+	print(string.format("Max FPS: %.2f", maxFps))
+	print(string.format("Min FPS: %.2f", minFps))
+end
+
+-- Benchmark
+local isBenchmarking = false
+local AMOUNT = 5000
+local BENCH_TIME = 5
+
+UIS.InputBegan:Connect(function(input, gp)
+	if gp then return end
+	if isBenchmarking then return end
+	if input.KeyCode == Enum.KeyCode.P then
+		isBenchmarking = true
+		print("=== PARALLEL MODE BENCHMARK ===")
+		print(string.format("Firing %d casts...", AMOUNT))
+
+		for i = 1, AMOUNT do
+			Caster:RaycastFire(
+				Vector3.new(
+					math.random(-1, 1) * 5000,
+					math.random(-1, 1) * 5000,
+					math.random(-1, 1) * 5000
+				),
+				Vector3.new(
+					math.random(-1, 1) * 5000,
+					math.random(-1, 1) * 5000,
+					math.random(-1, 1) * 5000
+				),
+				35,
+				castBehavior
+			)
+		end
+
+		print("=== CREATION COMPLETE ===")
+		summary()
+
+		task.wait(BENCH_TIME)
+
+		print("=== SIMULATION COMPLETE ===")
+		summary()
+
+		print("=== CLEANUP ===")
+		for i = #activeCasts, 1, -1 do
+			Caster:TerminateCast(activeCasts[i])
+		end
+		activeCasts = {}
+
+		print("=== DONE ===")
+		summary()
+		isBenchmarking = false
+	end
+end)
+
+print("Press P to start Parallel benchmark")

Benchmarks/benchSerial.client.luau

@@ -0,0 +1,147 @@
+-- Services
+local RS = game:GetService("RunService")
+local Rep = game:GetService("ReplicatedStorage")
+local UIS = game:GetService("UserInputService")
+
+-- Requires
+local FastCast = require(Rep:WaitForChild("FastCast2"))
+
+-- Variables
+local ProjectileContainer = Instance.new("Folder")
+ProjectileContainer.Name = "FastCast2PJ"
+ProjectileContainer.Parent = workspace
+local ProjectileTemplate = Instance.new("Part")
+ProjectileTemplate.Name = "Projectile"
+ProjectileTemplate.Parent = Rep
+ProjectileTemplate.Size = Vector3.new(1,1,1)
+ProjectileTemplate.CanCollide = false
+ProjectileTemplate.Anchored = true
+ProjectileTemplate.CanQuery = false
+ProjectileTemplate.CanTouch = false
+ProjectileTemplate.Position = Vector3.new(1,1,1)
+ProjectileTemplate.Massless = true
+
+-- FPS tracking
+local startTime = tick()
+local updateRate = 0.5
+local fpsTable = {}
+local averageFps = 0
+local maxFps = 0
+local minFps = math.huge
+local currentFps = 0
+
+RS.Heartbeat:Connect(function(dt: number)
+	local fps = 1/dt
+	currentFps = fps
+	if fps > maxFps then
+		maxFps = fps
+	end
+	if fps < minFps then
+		minFps = fps
+	end
+	table.insert(fpsTable, fps)
+
+	if tick() >= startTime + updateRate then
+		local totalFps = 0
+		for _, vFps in fpsTable do 
+			totalFps += vFps
+		end
+		averageFps = totalFps / #fpsTable
+		fpsTable = {}
+		startTime = tick()
+	end
+end)
+
+-- CastParams
+local CastParams = RaycastParams.new()
+CastParams.FilterDescendantsInstances = {}
+CastParams.FilterType = Enum.RaycastFilterType.Exclude
+CastParams.IgnoreWater = true
+
+-- Behavior
+local castBehavior = FastCast.newBehavior()
+castBehavior.MaxDistance = 999999999
+castBehavior.RaycastParams = CastParams
+castBehavior.HighFidelityBehavior = 1
+castBehavior.HighFidelitySegmentSize = 1
+castBehavior.Acceleration = Vector3.new(0, 0, 0)
+castBehavior.AutoIgnoreContainer = true
+castBehavior.CosmeticBulletContainer = ProjectileContainer
+castBehavior.CosmeticBulletTemplate = ProjectileTemplate
+
+-- Serial Caster
+local Caster = FastCast.new()
+Caster:Init(
+	true,  -- useBulkMoveTo
+	false  -- useObjectCache
+)
+
+local activeCasts = {}
+
+Caster.CastFire:Connect(function(cast)
+	table.insert(activeCasts, cast)
+end)
+
+-- Functions
+local function summary()
+	print(string.format("Delta: %.2f ms", 1000 / currentFps))
+	print(string.format("Average FPS: %.2f", averageFps))
+	print(string.format("Max FPS: %.2f", maxFps))
+	print(string.format("Min FPS: %.2f", minFps))
+end
+
+-- Benchmark
+local isBenchmarking = false
+local AMOUNT = 5000
+local BENCH_TIME = 5
+
+UIS.InputBegan:Connect(function(input, gp)
+	if gp then return end
+	if isBenchmarking then return end
+	if input.KeyCode == Enum.KeyCode.E then
+		isBenchmarking = true
+		print("=== SERIAL MODE BENCHMARK ===")
+		print(string.format("Firing %d casts...", AMOUNT))
+
+		for i = 1, AMOUNT do
+			local direction = Vector3.new(
+				math.random() * 2 - 1,
+				math.random() * 2 - 1,
+				math.random() * 2 - 1
+			)
+			if direction.Magnitude == 0 then
+				direction = Vector3.new(0, 0, 1)
+			end
+			Caster:RaycastFire(
+				Vector3.new(
+					math.random() * 2 - 1,
+					math.random() * 2 - 1,
+					math.random() * 2 - 1
+				) * 5000,
+				direction,
+				35,
+				castBehavior
+			)
+		end
+
+		print("=== CREATION COMPLETE ===")
+		summary()
+
+		task.wait(BENCH_TIME)
+
+		print("=== SIMULATION COMPLETE ===")
+		summary()
+
+		print("=== CLEANUP ===")
+		for i = #activeCasts, 1, -1 do
+			Caster:TerminateCast(activeCasts[i])
+		end
+		activeCasts = {}
+
+		print("=== DONE ===")
+		summary()
+		isBenchmarking = false
+	end
+end)
+
+print("Press E to start benchmark")