Skip to main content

Kill

Kills a character from an agent in one of two ways, decided and finished on the server, and announced as a "Kill" event on Agent.Events with { Kind, Victim, Duration } so a client Replica can present it: replica:On("Kill", ...).

  • [Kill.Live]: the victim is held next to the killer while both play an animation, then dies.
  • [Kill.BlackBox]: announced at once, resolved after a delay; the client cuts to black.
  • [Kill.Scare]: the live hold without the death, announced as "Scare"; the victim is let go.

A kill that was announced and then cancelled (or lost to another cause of death) emits "KillCancelled" with { Kind, Victim }, so the client can put its screen back; a scare cut short emits "ScareCancelled".

Types​

KillHandle​

</>
interface KillHandle {
Finished: Signal<boolean>--

Fired once: true when the victim died, false when cancelled.

Cancel: (self: KillHandle) → ()--

Releases the victim alive.

}

What both kill functions return.

Functions​

Live​

</>
Kill.Live(
agent: Agent,--

The killer.

victim: Model,--

The character to kill. Needs a Humanoid (or a Health provider) and a PrimaryPart.

) → KillHandle

Types

​

interface LiveKillOptions {
Duration: number?--

Seconds the hold lasts before the victim dies. Default 1.5.

Offset: CFrame?--

Where the victim is held, relative to the killer's pivot. Default 2.5 studs in front, facing the killer.

KillerAnimation: number | string?--

Played on the killer: an animation asset id, or the name of a one-shot on the killer's Locomotion. Default none.

VictimAnimation: number?--

Animation asset id played on the victim. Default none.

Health: HealthProvider?--

Where the victim's health lives, when not on the Humanoid.

}

Emits Kill with Kind = "Live", anchors the victim's root, holds it at Offset from the killer every frame, plays the animations, and after Duration sets the victim's health to zero (bypassing a ForceField, as a kill should). Cancel releases the victim alive.

Finishes false at once, with a warning, when the victim has no humanoid or root, is dead, or is already held by another live kill, or when the agent is not running. Finishes false if the killer is destroyed or the victim dies of something else during the hold.

Scare​

</>
Kill.Scare(
agent: Agent,--

The scarer.

victim: Model,--

The character to grab. Needs a Humanoid (or a Health provider) and a PrimaryPart.

options: ScareOptions?
) → KillHandle--

Finishes true when the hold ran its course and the victim was let go, false when cut short.

Types

​

interface ScareOptions {
Duration: number?--

Seconds the hold lasts before the victim is let go. Default 1.

Offset: CFrame?--

Where the victim is held, relative to the killer's pivot. Default 2.5 studs in front, facing the killer.

Damage: number?--

Dealt when the hold ends. Default 0.

KillerAnimation: number | string?--

Played on the killer: an asset id, or a Locomotion one-shot name. Default none.

VictimAnimation: number?--

Animation asset id played on the victim. Default none.

Health: HealthProvider?--

Where the victim's health lives, when not on the Humanoid.

}

The live hold without the death: emits Scare with Kind = "Scare", holds the victim at Offset while both animations play, deals Damage when the time is up, and releases them. A jump scare, a grab that throws the player off, a bite that does not finish them. The same refusals as Kill.Live; a victim already held by a kill or another scare is refused.

BlackBox​

</>
Kill.BlackBox(
agent: Agent,--

The killer.

victim: Model,--

The character to kill.

) → KillHandle

Types

​

interface BlackBoxKillOptions {
Delay: number?--

Seconds between the announcement and the death. Default 0.6.

Health: HealthProvider?--

Where the victim's health lives, when not on the Humanoid.

Finish: ((victim: Model) → ())?--

Called after Delay instead of killing: respawn the player, teleport them, end the round. With it the black box is timing and events only.

}

Emits Kill with Kind = "BlackBox" at once and sets the victim's health to zero after Delay. Cancel within the delay spares them. Finishes false if the victim died of something else meanwhile, or if the agent was not running to begin with.

For a game where nobody dies, give Finish: it is called after Delay in place of the kill, and the handle finishes true all the same. The event, its payload and the cancel are unchanged, so the client's black screen does not know the difference. 

VluxyAI.Combat.Kill.BlackBox(agent, character, {
	Finish = function(victim)
		local player = Players:GetPlayerFromCharacter(victim)
		if player then player:LoadCharacter() end
	end,
})
Show raw api
{
    "functions": [
        {
            "name": "Live",
            "desc": "Emits `Kill` with `Kind = \"Live\"`, anchors the victim's root, holds it at `Offset` from the\nkiller every frame, plays the animations, and after `Duration` sets the victim's health to\nzero (bypassing a ForceField, as a kill should). `Cancel` releases the victim alive.\n\nFinishes `false` at once, with a warning, when the victim has no humanoid or root, is dead, or\nis already held by another live kill, or when the agent is not running. Finishes `false` if the\nkiller is destroyed or the victim dies of something else during the hold.",
            "params": [
                {
                    "name": "agent",
                    "desc": "The killer.",
                    "lua_type": "Agent"
                },
                {
                    "name": "victim",
                    "desc": "The character to kill. Needs a Humanoid (or a `Health` provider) and a PrimaryPart.",
                    "lua_type": "Model"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "LiveKillOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "KillHandle"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 399,
                "path": "lib/Combat/Kill.luau"
            }
        },
        {
            "name": "Scare",
            "desc": "The live hold without the death: emits `Scare` with `Kind = \"Scare\"`, holds the victim at\n`Offset` while both animations play, deals `Damage` when the time is up, and releases them.\nA jump scare, a grab that throws the player off, a bite that does not finish them. The same\nrefusals as [Kill.Live]; a victim already held by a kill or another scare is refused.",
            "params": [
                {
                    "name": "agent",
                    "desc": "The scarer.",
                    "lua_type": "Agent"
                },
                {
                    "name": "victim",
                    "desc": "The character to grab. Needs a Humanoid (or a `Health` provider) and a PrimaryPart.",
                    "lua_type": "Model"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "ScareOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "Finishes `true` when the hold ran its course and the victim was let go, `false` when cut short.",
                    "lua_type": "KillHandle"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 433,
                "path": "lib/Combat/Kill.luau"
            }
        },
        {
            "name": "BlackBox",
            "desc": "Emits `Kill` with `Kind = \"BlackBox\"` at once and sets the victim's health to zero after\n`Delay`. `Cancel` within the delay spares them. Finishes `false` if the victim died of\nsomething else meanwhile, or if the agent was not running to begin with.\n\nFor a game where nobody dies, give `Finish`: it is called after `Delay` in place of the kill,\nand the handle finishes `true` all the same. The event, its payload and the cancel are\nunchanged, so the client's black screen does not know the difference.\n\n```lua\nVluxyAI.Combat.Kill.BlackBox(agent, character, {\n\tFinish = function(victim)\n\t\tlocal player = Players:GetPlayerFromCharacter(victim)\n\t\tif player then player:LoadCharacter() end\n\tend,\n})\n```",
            "params": [
                {
                    "name": "agent",
                    "desc": "The killer.",
                    "lua_type": "Agent"
                },
                {
                    "name": "victim",
                    "desc": "The character to kill.",
                    "lua_type": "Model"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "BlackBoxKillOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "KillHandle"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 480,
                "path": "lib/Combat/Kill.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "LiveKillOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Duration",
                    "lua_type": "number?",
                    "desc": "Seconds the hold lasts before the victim dies. Default `1.5`."
                },
                {
                    "name": "Offset",
                    "lua_type": "CFrame?",
                    "desc": "Where the victim is held, relative to the killer's pivot. Default 2.5 studs in front, facing the killer."
                },
                {
                    "name": "KillerAnimation",
                    "lua_type": "number | string?",
                    "desc": "Played on the killer: an animation asset id, or the name of a one-shot on the killer's [Locomotion]. Default none."
                },
                {
                    "name": "VictimAnimation",
                    "lua_type": "number?",
                    "desc": "Animation asset id played on the victim. Default none."
                },
                {
                    "name": "Health",
                    "lua_type": "HealthProvider?",
                    "desc": "Where the victim's health lives, when not on the Humanoid."
                }
            ],
            "source": {
                "line": 104,
                "path": "lib/Combat/Kill.luau"
            }
        },
        {
            "name": "ScareOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Duration",
                    "lua_type": "number?",
                    "desc": "Seconds the hold lasts before the victim is let go. Default `1`."
                },
                {
                    "name": "Offset",
                    "lua_type": "CFrame?",
                    "desc": "Where the victim is held, relative to the killer's pivot. Default 2.5 studs in front, facing the killer."
                },
                {
                    "name": "Damage",
                    "lua_type": "number?",
                    "desc": "Dealt when the hold ends. Default `0`."
                },
                {
                    "name": "KillerAnimation",
                    "lua_type": "number | string?",
                    "desc": "Played on the killer: an asset id, or a [Locomotion] one-shot name. Default none."
                },
                {
                    "name": "VictimAnimation",
                    "lua_type": "number?",
                    "desc": "Animation asset id played on the victim. Default none."
                },
                {
                    "name": "Health",
                    "lua_type": "HealthProvider?",
                    "desc": "Where the victim's health lives, when not on the Humanoid."
                }
            ],
            "source": {
                "line": 123,
                "path": "lib/Combat/Kill.luau"
            }
        },
        {
            "name": "BlackBoxKillOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Delay",
                    "lua_type": "number?",
                    "desc": "Seconds between the announcement and the death. Default `0.6`."
                },
                {
                    "name": "Health",
                    "lua_type": "HealthProvider?",
                    "desc": "Where the victim's health lives, when not on the Humanoid."
                },
                {
                    "name": "Finish",
                    "lua_type": "((victim: Model) -> ())?",
                    "desc": "Called after `Delay` instead of killing: respawn the player, teleport them, end the round. With it the black box is timing and events only."
                }
            ],
            "source": {
                "line": 140,
                "path": "lib/Combat/Kill.luau"
            }
        },
        {
            "name": "KillHandle",
            "desc": "What both kill functions return.",
            "fields": [
                {
                    "name": "Finished",
                    "lua_type": "Signal<boolean>",
                    "desc": "Fired once: `true` when the victim died, `false` when cancelled."
                },
                {
                    "name": "Cancel",
                    "lua_type": "(self: KillHandle) -> ()",
                    "desc": "Releases the victim alive."
                }
            ],
            "source": {
                "line": 155,
                "path": "lib/Combat/Kill.luau"
            }
        }
    ],
    "name": "Kill",
    "desc": "Kills a character from an agent in one of two ways, decided and finished on the server, and\nannounced as a `\"Kill\"` event on [Agent].Events with `{ Kind, Victim, Duration }` so a client\n[Replica] can present it: `replica:On(\"Kill\", ...)`.\n\n- [Kill.Live]: the victim is held next to the killer while both play an animation, then dies.\n- [Kill.BlackBox]: announced at once, resolved after a delay; the client cuts to black.\n- [Kill.Scare]: the live hold without the death, announced as `\"Scare\"`; the victim is let go.\n\nA kill that was announced and then cancelled (or lost to another cause of death) emits\n`\"KillCancelled\"` with `{ Kind, Victim }`, so the client can put its screen back; a scare cut\nshort emits `\"ScareCancelled\"`.",
    "source": {
        "line": 259,
        "path": "lib/Combat/Kill.luau"
    }
}