Skip to main content

PhysicsBuilder

Sub-builder for physics configuration. Opened via BehaviorBuilder:Physics. Call :Done() to return to the root BehaviorBuilder.

Functions​

MaxDistance​

</>
PhysicsBuilder:MaxDistance(value: number) → PhysicsBuilder

Maximum distance in studs the bullet can travel before expiring.

Default: 500

MaxSpeed​

</>
PhysicsBuilder:MaxSpeed(value: number) → PhysicsBuilder

Maximum speed in studs per second. Bullet terminates if speed exceeds this.

Default: math.huge (no cap)

MinSpeed​

</>
PhysicsBuilder:MinSpeed(value: number) → PhysicsBuilder

Minimum speed in studs per second. Bullet terminates when speed drops below this.

Default: 1

Gravity​

</>
PhysicsBuilder:Gravity(value: Vector3) → PhysicsBuilder

Gravitational acceleration. Pass a negative-Y vector for downward gravity.

Default: Vector3.new(0, -workspace.Gravity, 0) (read at construction time)

Acceleration​

</>
PhysicsBuilder:Acceleration(value: Vector3) → PhysicsBuilder

Extra constant acceleration layered on top of gravity, e.g. rocket thrust.

Default: Vector3.zero

RaycastParams​

</>
PhysicsBuilder:RaycastParams(value: RaycastParams) → PhysicsBuilder

RaycastParams used for all raycasts during this cast's lifetime.

Priority order, Vetra:Fire resolves params using:

  1. BulletContext.RaycastParams, per-bullet filter (highest priority).
  2. Behavior.RaycastParams, this setter, if called.
  3. Empty RaycastParams.new(), catch-all fallback.
Overridden by BulletContext

If the BulletContext passed to Vetra:Fire has its own RaycastParams set, it takes priority over this value. This setter acts as the behavior-wide default when no per-bullet filter is provided.

Default: nil (not set, defers to BulletContext or the fallback)

CastFunction​

</>
PhysicsBuilder:CastFunction(value: (
origin: Vector3,
direction: Vector3,
params: RaycastParams
) → RaycastResult?) → PhysicsBuilder

Optional custom cast function replacing workspace:Raycast. Use for Spherecast, Blockcast, or any custom raycast wrapper.

Signature: (origin: Vector3, direction: Vector3, params: RaycastParams) -> RaycastResult?

Serial solver only

Silently ignored by Vetra.newParallel(), functions cannot cross Actor boundaries via message serialization.

Default: nil

BulletMass​

</>
PhysicsBuilder:BulletMass(value: number) → PhysicsBuilder

Mass of the bullet in game units. Used by penetration and impact-force calculations. Set to 0 to disable mass-based scaling.

Default: 0

Done​

</>
PhysicsBuilder:Done() → BehaviorBuilder

Returns the root BehaviorBuilder.

Show raw api
{
    "functions": [
        {
            "name": "MaxDistance",
            "desc": "Maximum distance in studs the bullet can travel before expiring.\n\nDefault: `500`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 19,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "MaxSpeed",
            "desc": "Maximum speed in studs per second. Bullet terminates if speed exceeds this.\n\nDefault: `math.huge` (no cap)",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 29,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "MinSpeed",
            "desc": "Minimum speed in studs per second. Bullet terminates when speed drops below this.\n\nDefault: `1`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 39,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "Gravity",
            "desc": "Gravitational acceleration. Pass a negative-Y vector for downward gravity.\n\nDefault: `Vector3.new(0, -workspace.Gravity, 0)` (read at construction time)",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 49,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "Acceleration",
            "desc": "Extra constant acceleration layered on top of gravity, e.g. rocket thrust.\n\nDefault: `Vector3.zero`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 59,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "RaycastParams",
            "desc": "`RaycastParams` used for all raycasts during this cast's lifetime.\n\n**Priority order**, [Vetra:Fire] resolves params using:\n1. `BulletContext.RaycastParams`, per-bullet filter (highest priority).\n2. `Behavior.RaycastParams`, this setter, if called.\n3. Empty `RaycastParams.new()`, catch-all fallback.\n\n:::warning Overridden by BulletContext\nIf the `BulletContext` passed to [Vetra:Fire] has its own `RaycastParams`\nset, it takes priority over this value. This setter acts as the\nbehavior-wide default when no per-bullet filter is provided.\n:::\n\nDefault: `nil` (not set, defers to BulletContext or the fallback)",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "RaycastParams"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 80,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "CastFunction",
            "desc": "Optional custom cast function replacing `workspace:Raycast`. Use for\n`Spherecast`, `Blockcast`, or any custom raycast wrapper.\n\nSignature: `(origin: Vector3, direction: Vector3, params: RaycastParams) -> RaycastResult?`\n\n:::caution Serial solver only\nSilently ignored by `Vetra.newParallel()`, functions cannot cross Actor\nboundaries via message serialization.\n:::\n\nDefault: `nil`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "(origin: Vector3, direction: Vector3, params: RaycastParams) -> RaycastResult?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 98,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "BulletMass",
            "desc": "Mass of the bullet in game units. Used by penetration and impact-force\ncalculations. Set to `0` to disable mass-based scaling.\n\nDefault: `0`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PhysicsBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 109,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "Done",
            "desc": "Returns the root [BehaviorBuilder].",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "BehaviorBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 115,
                "path": "docs/SubBuilders.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PhysicsBuilder",
    "desc": "Sub-builder for physics configuration. Opened via [BehaviorBuilder:Physics].\nCall `:Done()` to return to the root [BehaviorBuilder].",
    "source": {
        "line": 9,
        "path": "docs/SubBuilders.lua"
    }
}