Skip to main content

PierceBuilder

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

CAUTION

Pierce and bounce are mutually exclusive per hit. Pierce is evaluated first.

Functions​

Filter​

</>
PierceBuilder:Filter(callback: (
context: BulletContext,
result: RaycastResult,
velocity: Vector3
) → boolean) → PierceBuilder

Pierce gate. Return true to pierce; false treats the hit as terminal.

Signature: (context: BulletContext, result: RaycastResult, velocity: Vector3) -> boolean

Default: nil (no piercing)

Max​

</>
PierceBuilder:Max(value: number) → PierceBuilder

Maximum total surfaces the bullet can pierce over its lifetime.

Default: 3

SpeedThreshold​

</>
PierceBuilder:SpeedThreshold(value: number) → PierceBuilder

Minimum speed (studs/s) required to attempt a pierce.

Default: 50

SpeedRetention​

</>
PierceBuilder:SpeedRetention(value: number) → PierceBuilder

Fraction of speed retained per pierce. Must be in [0, 1].

Default: 0.8

NormalBias​

</>
PierceBuilder:NormalBias(value: number) → PierceBuilder

Minimum approach angle for pierce. Must be in [0, 1]. 1.0 = all angles; 0.0 = perpendicular only.

Default: 1.0

PierceDepth​

</>
PierceBuilder:PierceDepth(value: number) → PierceBuilder

Maximum wall thickness per pierce in studs. 0 = no per-pierce limit.

Default: 0

PierceForce​

</>
PierceBuilder:PierceForce(value: number) → PierceBuilder

Total momentum force budget for penetration. 0 = disabled.

Default: 0

ThicknessLimit​

</>
PierceBuilder:ThicknessLimit(value: number) → PierceBuilder

Hard cap on wall thickness for the exit-point raycast in studs.

Default: 500

Done​

</>
PierceBuilder:Done() → BehaviorBuilder

Returns the root BehaviorBuilder.

Show raw api
{
    "functions": [
        {
            "name": "Filter",
            "desc": "Pierce gate. Return `true` to pierce; `false` treats the hit as terminal.\n\nSignature: `(context: BulletContext, result: RaycastResult, velocity: Vector3) -> boolean`\n\nDefault: `nil` (no piercing)",
            "params": [
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(context: BulletContext, result: RaycastResult, velocity: Vector3) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 212,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "Max",
            "desc": "Maximum total surfaces the bullet can pierce over its lifetime.\n\nDefault: `3`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 222,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "SpeedThreshold",
            "desc": "Minimum speed (studs/s) required to attempt a pierce.\n\nDefault: `50`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 232,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "SpeedRetention",
            "desc": "Fraction of speed retained per pierce. Must be in `[0, 1]`.\n\nDefault: `0.8`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 242,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "NormalBias",
            "desc": "Minimum approach angle for pierce. Must be in `[0, 1]`.\n`1.0` = all angles; `0.0` = perpendicular only.\n\nDefault: `1.0`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 253,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "PierceDepth",
            "desc": "Maximum wall thickness per pierce in studs. `0` = no per-pierce limit.\n\nDefault: `0`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 263,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "PierceForce",
            "desc": "Total momentum force budget for penetration. `0` = disabled.\n\nDefault: `0`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 273,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "ThicknessLimit",
            "desc": "Hard cap on wall thickness for the exit-point raycast in studs.\n\nDefault: `500`",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PierceBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 283,
                "path": "docs/SubBuilders.lua"
            }
        },
        {
            "name": "Done",
            "desc": "Returns the root [BehaviorBuilder].",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "BehaviorBuilder"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 289,
                "path": "docs/SubBuilders.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PierceBuilder",
    "desc": "Sub-builder for pierce configuration. Opened via [BehaviorBuilder:Pierce].\nCall `:Done()` to return to the root [BehaviorBuilder].\n\n:::caution\nPierce and bounce are mutually exclusive per hit. Pierce is evaluated first.\n:::",
    "source": {
        "line": 200,
        "path": "docs/SubBuilders.lua"
    }
}