Skip to main content

VetraCast

The internal representation of one in-flight projectile. Returned by Vetra:Fire for callers that need to introspect or modify a bullet mid-flight.

Prefer BulletContext

Weapon scripts should interact with BulletContext rather than VetraCast directly. VetraCast exposes internal solver state, mutating it outside of the documented methods can produce physics errors that are difficult to debug.

The methods below (GetPosition, SetVelocity, Pause, etc.) are safe to call and are the intended way to read or modify a bullet mid-flight from within signal handlers.

Properties​

Alive​

This item is read only and cannot be modified. Read Only
</>
VetraCast.Alive: boolean

true while the cast is being simulated. Set to false as the very first action in termination so re-entrant calls are no-ops.

Paused​

</>
VetraCast.Paused: boolean

When true, the solver skips this cast entirely each frame. TotalRuntime does not advance while paused, so resumption picks up seamlessly from the exact state the bullet was in when paused.

Use VetraCast:Pause and VetraCast:Resume rather than writing this field directly.

UserData​

</>
VetraCast.UserData: {[any]: any}

Free-form table for weapon-specific metadata. Shared with the linked BulletContext and passed unchanged on every signal emission.

Functions​

GetPosition​

</>
VetraCast:GetPosition() → Vector3

Returns the bullet's current world-space position using the analytic kinematic formula P(t) = Origin + V₀t + ½At². Always accurate to the current simulation time regardless of when in the frame it is called.

GetVelocity​

</>
VetraCast:GetVelocity() → Vector3

Returns the bullet's current velocity vector. The magnitude of this vector is the current speed in studs per second.

GetAcceleration​

</>
VetraCast:GetAcceleration() → Vector3

Returns the constant acceleration vector for the active trajectory segment. This is the pre-computed sum of gravity, extra acceleration, wind, and any initial drag deceleration for this segment, not workspace.Gravity alone.

SetPosition​

</>
VetraCast:SetPosition(position: Vector3) → ()

Teleports the bullet to a new world-space position without changing its velocity or acceleration. Opens a new trajectory segment if simulation time has already elapsed on the current one.

SetVelocity​

</>
VetraCast:SetVelocity(velocity: Vector3) → ()

Changes the bullet's velocity to the given vector. Opens a new trajectory segment if needed.

TIP

Call VetraCast:ResetBounceState after a sharp velocity change to prevent the corner-trap detector from falsely triggering on the new trajectory.

SetAcceleration​

</>
VetraCast:SetAcceleration(acceleration: Vector3) → ()

Replaces the bullet's constant acceleration for future simulation. Because acceleration is constant within a segment, this always opens a new segment unless the current one has zero elapsed time.

AddPosition​

</>
VetraCast:AddPosition(offset: Vector3) → ()

Translates the bullet by an offset in world space. Equivalent to SetPosition(GetPosition() + offset).

AddVelocity​

</>
VetraCast:AddVelocity(delta: Vector3) → ()

Adds a delta to the bullet's current velocity. Useful for impulse effects such as explosion knockback applied mid-flight.

AddAcceleration​

</>
VetraCast:AddAcceleration(delta: Vector3) → ()

Adds a delta to the bullet's constant acceleration. Useful for variable forces that build up over time via repeated calls, such as thrust or dynamic wind.

Pause​

</>
VetraCast:Pause() → ()

Pauses simulation for this cast. The solver skips it entirely each frame until VetraCast:Resume is called. TotalRuntime does not advance while paused, so the bullet resumes from exactly the same kinematic state.

Useful for cutscenes, slow-motion effects, or deferred spawning patterns.

Resume​

</>
VetraCast:Resume() → ()

Resumes a previously paused cast. Has no effect if the cast is not paused.

IsPaused​

</>
VetraCast:IsPaused() → boolean

Returns whether this cast is currently paused.

ResetBounceState​

</>
VetraCast:ResetBounceState() → ()

Resets the corner-trap detector state for this cast.

Clears BouncePositionHistory, LastBounceTime, and VelocityDirectionEMA back to their initial values.

Call this after any programmatic mid-flight velocity change (e.g. SetVelocity, AddVelocity) that deliberately reverses or sharply redirects the bullet. Without this, the EMA-based corner-trap detector may falsely terminate the cast on the next bounce.

ResetPierceState​

</>
VetraCast:ResetPierceState() → ()

Resets the pierce state for this cast.

Clears PiercedInstances, resets PierceCount to 0, and restores the original FilterDescendantsInstances on the cast's RaycastParams.

Typically called from an OnBounce handler when ResetPierceOnBounce is not sufficient, for example, if you only want to reset pierce state after specific bounces rather than all of them.

Terminate​

</>
VetraCast:Terminate() → ()

Terminates this cast immediately.

Equivalent to calling context:Terminate() on the linked BulletContext. Fires OnTerminated. Calling Terminate on an already-dead cast is a no-op.

Show raw api
{
    "functions": [
        {
            "name": "GetPosition",
            "desc": "Returns the bullet's current world-space position using the analytic\nkinematic formula `P(t) = Origin + V₀t + ½At²`. Always accurate to the\ncurrent simulation time regardless of when in the frame it is called.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 61,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "GetVelocity",
            "desc": "Returns the bullet's current velocity vector. The magnitude of this vector\nis the current speed in studs per second.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 69,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "GetAcceleration",
            "desc": "Returns the constant acceleration vector for the active trajectory segment.\nThis is the pre-computed sum of gravity, extra acceleration, wind, and\nany initial drag deceleration for this segment, not `workspace.Gravity` alone.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 78,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "SetPosition",
            "desc": "Teleports the bullet to a new world-space position without changing its\nvelocity or acceleration. Opens a new trajectory segment if simulation\ntime has already elapsed on the current one.",
            "params": [
                {
                    "name": "position",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 89,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "SetVelocity",
            "desc": "Changes the bullet's velocity to the given vector. Opens a new trajectory\nsegment if needed.\n\n:::tip\nCall [VetraCast:ResetBounceState] after a sharp velocity change to prevent\nthe corner-trap detector from falsely triggering on the new trajectory.\n:::",
            "params": [
                {
                    "name": "velocity",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 102,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "SetAcceleration",
            "desc": "Replaces the bullet's constant acceleration for future simulation. Because\nacceleration is constant within a segment, this always opens a new segment\nunless the current one has zero elapsed time.",
            "params": [
                {
                    "name": "acceleration",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 111,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "AddPosition",
            "desc": "Translates the bullet by an offset in world space. Equivalent to\n`SetPosition(GetPosition() + offset)`.",
            "params": [
                {
                    "name": "offset",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 119,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "AddVelocity",
            "desc": "Adds a delta to the bullet's current velocity. Useful for impulse effects\nsuch as explosion knockback applied mid-flight.",
            "params": [
                {
                    "name": "delta",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 127,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "AddAcceleration",
            "desc": "Adds a delta to the bullet's constant acceleration. Useful for variable\nforces that build up over time via repeated calls, such as thrust or dynamic wind.",
            "params": [
                {
                    "name": "delta",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 135,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "Pause",
            "desc": "Pauses simulation for this cast. The solver skips it entirely each frame\nuntil [VetraCast:Resume] is called. `TotalRuntime` does not advance while\npaused, so the bullet resumes from exactly the same kinematic state.\n\nUseful for cutscenes, slow-motion effects, or deferred spawning patterns.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 146,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "Resume",
            "desc": "Resumes a previously paused cast. Has no effect if the cast is not paused.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 151,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "IsPaused",
            "desc": "Returns whether this cast is currently paused.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 158,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "ResetBounceState",
            "desc": "Resets the corner-trap detector state for this cast.\n\nClears `BouncePositionHistory`, `LastBounceTime`, and `VelocityDirectionEMA`\nback to their initial values.\n\nCall this after any programmatic mid-flight velocity change (e.g.\n`SetVelocity`, `AddVelocity`) that deliberately reverses or sharply\nredirects the bullet. Without this, the EMA-based corner-trap detector may\nfalsely terminate the cast on the next bounce.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 173,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "ResetPierceState",
            "desc": "Resets the pierce state for this cast.\n\nClears `PiercedInstances`, resets `PierceCount` to 0, and restores the\noriginal `FilterDescendantsInstances` on the cast's `RaycastParams`.\n\nTypically called from an `OnBounce` handler when `ResetPierceOnBounce`\nis not sufficient, for example, if you only want to reset pierce state\nafter specific bounces rather than all of them.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 185,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "Terminate",
            "desc": "Terminates this cast immediately.\n\nEquivalent to calling `context:Terminate()` on the linked [BulletContext].\nFires `OnTerminated`. Calling `Terminate` on an already-dead cast is a no-op.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 193,
                "path": "docs/VetraCast.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "Alive",
            "desc": "`true` while the cast is being simulated. Set to `false` as the very\nfirst action in termination so re-entrant calls are no-ops.",
            "lua_type": "boolean",
            "readonly": true,
            "source": {
                "line": 31,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "Paused",
            "desc": "When `true`, the solver skips this cast entirely each frame.\n`TotalRuntime` does not advance while paused, so resumption picks up\nseamlessly from the exact state the bullet was in when paused.\n\nUse [VetraCast:Pause] and [VetraCast:Resume] rather than writing this\nfield directly.",
            "lua_type": "boolean",
            "source": {
                "line": 43,
                "path": "docs/VetraCast.lua"
            }
        },
        {
            "name": "UserData",
            "desc": "Free-form table for weapon-specific metadata. Shared with the linked\n[BulletContext] and passed unchanged on every signal emission.",
            "lua_type": "{[any]: any}",
            "source": {
                "line": 51,
                "path": "docs/VetraCast.lua"
            }
        }
    ],
    "types": [],
    "name": "VetraCast",
    "desc": "The internal representation of one in-flight projectile. Returned by\n[Vetra:Fire] for callers that need to introspect or modify a bullet\nmid-flight.\n\n:::warning Prefer BulletContext\nWeapon scripts should interact with [BulletContext] rather than `VetraCast`\ndirectly. `VetraCast` exposes internal solver state, mutating it outside\nof the documented methods can produce physics errors that are difficult\nto debug.\n\nThe methods below (`GetPosition`, `SetVelocity`, `Pause`, etc.) are safe\nto call and are the intended way to read or modify a bullet mid-flight\nfrom within signal handlers.\n:::",
    "source": {
        "line": 19,
        "path": "docs/VetraCast.lua"
    }
}