Skip to main content

Config

Tuning for a stagger. Every number here is what the balance model, the procedural pose and the joint "muscles" read, so a preset is nothing more than a table of these values.

The defaults describe a shove on an average character. Intensity (passed to Stagger.Begin) scales the starting lurch and how much balance is lost, so one preset covers a range of hits. 

Stagger.RegisterPreset("Drunk", Stagger.Presets.Default, {
	BalanceDrain = 0.05,
	MaxDuration = 12,
	StutterChance = 0.7,
})

Properties​

Presets​

</>
Config.Presets: {[string]: Config}

Built in presets, all reachable as Stagger.Presets:

  • Default: a solid shove.
  • Light: a bump; short, usually recovered.
  • Heavy: an explosion or a car; long lurch, almost always ends on the floor.
  • Drunk: slow drain, lots of half steps, long before anything is decided.

Functions​

extend​

</>
Config.extend(
base: Config,
overrides: {[string]: any}?
) → Config

Types

​

interface Config {
StartBalance: number--

Balance the character starts with at intensity 1, from 0 (falls at once) to 1 (barely bothered). Intensity above 1 lowers it further. Default 0.6.

BalanceDrain: number--

Balance lost per second just from being off balance, scaled by how fast the character is still lurching. Default 0.15.

LurchSpeed: number--

Studs per second the character is thrown forward at intensity 1. Default 14.

MaxWalkSpeed: number--

Cap on the stumble speed fed to Humanoid.WalkSpeed. Default 22.

StepInterval: number--

Seconds between catch-up steps, before randomisation. Default 0.34.

StepDuration: number--

How long one leg swing lasts. Default 0.22.

StepBalanceGain: number--

Balance regained by a clean step. Default 0.14.

StepMomentumKeep: number--

Fraction of the lurch that survives a clean step (lower stops sooner). Default 0.7.

MomentumHold: number--

How much a low balance stops the lurch slowing down, from 0 (friction and steps always slow it) to 1 (at zero balance it keeps its full speed until the character falls or steps back above half balance). Default 1.

StutterChance: number--

Chance a step is a half step: shorter, weaker, closer to the next. This is the "stutter". Default 0.45.

MisstepChance: number--

Chance (times how off balance the character is) that a step goes wrong: a sideways kick and a balance loss. Default 0.35.

RecoverSpeed: number--

Once the lurch is slower than this many studs per second... Default 2.5.

RecoverBalance: number--

...and balance is above this, the character has recovered. Default 0.6.

MinDuration: number--

Never recover before this many seconds, and never fall before three quarters of it. Default 1.2.

MaxDuration: number--

Force an outcome after this many seconds: recover if balance is above 0.5, otherwise fall. Default 6.

AirFallTime: number--

Seconds with no floor under the character before they fall over (walked off a ledge mid-stagger). Default 0.35.

MaxLean: number--

Radians the torso leans into the lurch at full speed. Default 0.55.

ArmRaise: number--

Radians the arms come out sideways when balance is low. Default 1.1.

ArmFlail: number--

Radians of arm windmilling on top of the raise. Default 0.5.

StepSwing: number--

Radians a stepping leg swings forward at the hip. Default 0.7.

KneeBend: number--

Radians the knee bends during a step. Default 0.9.

HeadCounter: number--

How much the head counter-rotates to stay level (0 none, 1 fully). Default 0.7.

Steering: number--

Radians per second the player's walk input can bend the lurch towards where they are walking. 0 ignores input (and turns the controls off for the stagger). Default 2.5.

CatchGain: number--

Balance per second a player earns back by walking with the stumble (running it out). Default 0.35.

CatchBrake: number--

Extra studs per second per second the lurch slows while they do. Default 4.

TurnSpeed: number--

Radians per second the body turns to face the way it is being thrown. 0 (the default) keeps them facing where they were when hit: shoved from the front they stagger backwards. Either way the heading is held so the Humanoid can't swing them round.

ReHitBalanceLoss: number--

Extra balance lost when hit again mid-stagger, on top of keeping the lower balance and adding the lurches together. Default 0.2.

MuscleStrength: number--

AnimationConstraint.AngularStrength for the upper body while staggering. Below 1 the arms and torso lag the animation and swing with the body: this is the Euphoria look. Default 0.3.

MuscleDamping: number--

AnimationConstraint.AngularDamping for the upper body while staggering. Default 0.9.

LimpStrength: number--

AngularStrength for every joint while ragdolled. 0 is a rag; a little keeps some tone. Default 0.04.

LimpDamping: number--

AngularDamping while ragdolled. Default 1.

RagdollDuration: number--

Seconds to stay ragdolled before standing up on their own. 0 means stay down until Stagger.Recover is called. Default 3.

GetUpTime: number--

Seconds the get-up animation takes after a ragdoll: arms push, knees come under, then the rise. Default 1.3.

GetUpDuration: number--

Seconds a character who recovered on their feet (never fell) stays in Recovering before the stagger is over. After a ragdoll the stagger ends with the get-up instead. Default 0.25.

RagdollInAir: boolean--

A stagger that starts with no ground under the character ragdolls them instead. Default true.

DisableControls: boolean--

On a player's own client, disable the PlayerModule controls for the duration. Default true.

}

Builds a config from base with overrides applied on top. Unknown keys and wrong types raise an error so typos in presets are caught early.

Show raw api
{
    "functions": [
        {
            "name": "extend",
            "desc": "Builds a config from `base` with `overrides` applied on top. Unknown keys and wrong types\nraise an error so typos in presets are caught early.",
            "params": [
                {
                    "name": "base",
                    "desc": "",
                    "lua_type": "Config"
                },
                {
                    "name": "overrides",
                    "desc": "",
                    "lua_type": "{ [string]: any }?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Config"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 156,
                "path": "packages/src/Stagger/Config.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Presets",
            "desc": "Built in presets, all reachable as `Stagger.Presets`:\n\n- `Default`: a solid shove.\n- `Light`: a bump; short, usually recovered.\n- `Heavy`: an explosion or a car; long lurch, almost always ends on the floor.\n- `Drunk`: slow drain, lots of half steps, long before anything is decided.",
            "lua_type": "{ [string]: Config }",
            "source": {
                "line": 183,
                "path": "packages/src/Stagger/Config.luau"
            }
        }
    ],
    "types": [
        {
            "name": "Config",
            "desc": "",
            "fields": [
                {
                    "name": "StartBalance",
                    "lua_type": "number",
                    "desc": "Balance the character starts with at intensity 1, from 0 (falls at once) to 1 (barely bothered). Intensity above 1 lowers it further. Default `0.6`."
                },
                {
                    "name": "BalanceDrain",
                    "lua_type": "number",
                    "desc": "Balance lost per second just from being off balance, scaled by how fast the character is still lurching. Default `0.15`."
                },
                {
                    "name": "LurchSpeed",
                    "lua_type": "number",
                    "desc": "Studs per second the character is thrown forward at intensity 1. Default `14`."
                },
                {
                    "name": "MaxWalkSpeed",
                    "lua_type": "number",
                    "desc": "Cap on the stumble speed fed to `Humanoid.WalkSpeed`. Default `22`."
                },
                {
                    "name": "StepInterval",
                    "lua_type": "number",
                    "desc": "Seconds between catch-up steps, before randomisation. Default `0.34`."
                },
                {
                    "name": "StepDuration",
                    "lua_type": "number",
                    "desc": "How long one leg swing lasts. Default `0.22`."
                },
                {
                    "name": "StepBalanceGain",
                    "lua_type": "number",
                    "desc": "Balance regained by a clean step. Default `0.14`."
                },
                {
                    "name": "StepMomentumKeep",
                    "lua_type": "number",
                    "desc": "Fraction of the lurch that survives a clean step (lower stops sooner). Default `0.7`."
                },
                {
                    "name": "MomentumHold",
                    "lua_type": "number",
                    "desc": "How much a low balance stops the lurch slowing down, from 0 (friction and steps always slow it) to 1 (at zero balance it keeps its full speed until the character falls or steps back above half balance). Default `1`."
                },
                {
                    "name": "StutterChance",
                    "lua_type": "number",
                    "desc": "Chance a step is a half step: shorter, weaker, closer to the next. This is the \"stutter\". Default `0.45`."
                },
                {
                    "name": "MisstepChance",
                    "lua_type": "number",
                    "desc": "Chance (times how off balance the character is) that a step goes wrong: a sideways kick and a balance loss. Default `0.35`."
                },
                {
                    "name": "RecoverSpeed",
                    "lua_type": "number",
                    "desc": "Once the lurch is slower than this many studs per second... Default `2.5`."
                },
                {
                    "name": "RecoverBalance",
                    "lua_type": "number",
                    "desc": "...and balance is above this, the character has recovered. Default `0.6`."
                },
                {
                    "name": "MinDuration",
                    "lua_type": "number",
                    "desc": "Never recover before this many seconds, and never fall before three quarters of it. Default `1.2`."
                },
                {
                    "name": "MaxDuration",
                    "lua_type": "number",
                    "desc": "Force an outcome after this many seconds: recover if balance is above 0.5, otherwise fall. Default `6`."
                },
                {
                    "name": "AirFallTime",
                    "lua_type": "number",
                    "desc": "Seconds with no floor under the character before they fall over (walked off a ledge mid-stagger). Default `0.35`."
                },
                {
                    "name": "MaxLean",
                    "lua_type": "number",
                    "desc": "Radians the torso leans into the lurch at full speed. Default `0.55`."
                },
                {
                    "name": "ArmRaise",
                    "lua_type": "number",
                    "desc": "Radians the arms come out sideways when balance is low. Default `1.1`."
                },
                {
                    "name": "ArmFlail",
                    "lua_type": "number",
                    "desc": "Radians of arm windmilling on top of the raise. Default `0.5`."
                },
                {
                    "name": "StepSwing",
                    "lua_type": "number",
                    "desc": "Radians a stepping leg swings forward at the hip. Default `0.7`."
                },
                {
                    "name": "KneeBend",
                    "lua_type": "number",
                    "desc": "Radians the knee bends during a step. Default `0.9`."
                },
                {
                    "name": "HeadCounter",
                    "lua_type": "number",
                    "desc": "How much the head counter-rotates to stay level (0 none, 1 fully). Default `0.7`."
                },
                {
                    "name": "Steering",
                    "lua_type": "number",
                    "desc": "Radians per second the player's walk input can bend the lurch towards where they are walking. `0` ignores input (and turns the controls off for the stagger). Default `2.5`."
                },
                {
                    "name": "CatchGain",
                    "lua_type": "number",
                    "desc": "Balance per second a player earns back by walking with the stumble (running it out). Default `0.35`."
                },
                {
                    "name": "CatchBrake",
                    "lua_type": "number",
                    "desc": "Extra studs per second per second the lurch slows while they do. Default `4`."
                },
                {
                    "name": "TurnSpeed",
                    "lua_type": "number",
                    "desc": "Radians per second the body turns to face the way it is being thrown. `0` (the default) keeps them facing where they were when hit: shoved from the front they stagger backwards. Either way the heading is held so the Humanoid can't swing them round."
                },
                {
                    "name": "ReHitBalanceLoss",
                    "lua_type": "number",
                    "desc": "Extra balance lost when hit again mid-stagger, on top of keeping the lower balance and adding the lurches together. Default `0.2`."
                },
                {
                    "name": "MuscleStrength",
                    "lua_type": "number",
                    "desc": "`AnimationConstraint.AngularStrength` for the upper body while staggering. Below 1 the arms and torso lag the animation and swing with the body: this is the Euphoria look. Default `0.3`."
                },
                {
                    "name": "MuscleDamping",
                    "lua_type": "number",
                    "desc": "`AnimationConstraint.AngularDamping` for the upper body while staggering. Default `0.9`."
                },
                {
                    "name": "LimpStrength",
                    "lua_type": "number",
                    "desc": "`AngularStrength` for every joint while ragdolled. 0 is a rag; a little keeps some tone. Default `0.04`."
                },
                {
                    "name": "LimpDamping",
                    "lua_type": "number",
                    "desc": "`AngularDamping` while ragdolled. Default `1`."
                },
                {
                    "name": "RagdollDuration",
                    "lua_type": "number",
                    "desc": "Seconds to stay ragdolled before standing up on their own. `0` means stay down until [Stagger.Recover] is called. Default `3`."
                },
                {
                    "name": "GetUpTime",
                    "lua_type": "number",
                    "desc": "Seconds the get-up animation takes after a ragdoll: arms push, knees come under, then the rise. Default `1.3`."
                },
                {
                    "name": "GetUpDuration",
                    "lua_type": "number",
                    "desc": "Seconds a character who recovered on their feet (never fell) stays in `Recovering` before the stagger is over. After a ragdoll the stagger ends with the get-up instead. Default `0.25`."
                },
                {
                    "name": "RagdollInAir",
                    "lua_type": "boolean",
                    "desc": "A stagger that starts with no ground under the character ragdolls them instead. Default `true`."
                },
                {
                    "name": "DisableControls",
                    "lua_type": "boolean",
                    "desc": "On a player's own client, disable the PlayerModule controls for the duration. Default `true`."
                }
            ],
            "source": {
                "line": 59,
                "path": "packages/src/Stagger/Config.luau"
            }
        }
    ],
    "name": "Config",
    "desc": "Tuning for a stagger. Every number here is what the balance model, the procedural pose and\nthe joint \"muscles\" read, so a preset is nothing more than a table of these values.\n\nThe defaults describe a shove on an average character. Intensity (passed to [Stagger.Begin])\nscales the starting lurch and how much balance is lost, so one preset covers a range of hits.\n\n```lua\nStagger.RegisterPreset(\"Drunk\", Stagger.Presets.Default, {\n\tBalanceDrain = 0.05,\n\tMaxDuration = 12,\n\tStutterChance = 0.7,\n})\n```",
    "source": {
        "line": 18,
        "path": "packages/src/Stagger/Config.luau"
    }
}