Skip to main content

When

Builders for the When of a Types.Transition or a Types.Interrupt. Exposed as VluxyAI.When. 

local When = VluxyAI.When

Interrupts = {
	{ To = "Hunt", When = When.Has("SeenTarget"), Except = { "Hunt", "Attack" } },
	{ To = "Investigate", When = When.New("HeardAt"), Except = { "Hunt", "Attack" } },
},
States = {
	Hunt = { Transitions = {
		{ To = "Attack", When = When.Below("SeenDistance", 4) },
		{ To = "Search", When = When.Missing("SeenPosition") },
	} },
	Search = { Transitions = { { To = "Patrol", When = When.Timer("Search") } } },
}

Functions​

Has​

</>
When.Has(key: string) → (agent: Agent) → boolean--

true while Blackboard[key] is not nil.

Missing​

</>
When.Missing(key: string) → (agent: Agent) → boolean--

true while Blackboard[key] is nil.

Equals​

</>
When.Equals(
key: string,
value: any
) → (agent: Agent) → boolean--

true while Blackboard[key] == value.

Below​

</>
When.Below(
key: string,--

A number on the blackboard, such as SeenDistance or Awareness.

limit: number
) → (agent: Agent) → boolean--

true while the value is a number below limit. A missing key is not below anything.

Above​

</>
When.Above(
key: string,
limit: number
) → (agent: Agent) → boolean--

true while the value is a number above limit.

New​

</>
When.New(
key: string--

A memory key that changes with each new event: HeardAt, HeardSoundAt, LastKnownAt.

) → (agent: Agent) → boolean--

true once per distinct value.

"Something new is here." Reads Agent:IsNew and, when it is true, calls Agent:Acknowledge before returning, so the same noise fires one transition and not one per tick. A state may acknowledge earlier itself, and a state that wants to react again to the same value may clear the key.

Timer​

</>
When.Timer(name: string) → (agent: Agent) → boolean--

Agent:TimerDone for name. A timer never started counts as done.

SafeSighted​

</>
When.SafeSighted(
cooldown: string?--

The timer a stare leaves behind. Default "States.StareCooldown", the one States.Stare starts.

) → (agent: Agent) → boolean--

true when SafeWatch reports someone in a safe area, and either the agent was just chasing them (SafeWasChased) or cooldown has run out.

When to stop at the door of a safe room: someone the agent can see is in one, or the one it was chasing just got in. After a stare, cooldown keeps it from staring again at once, except at someone it was chasing.

InStateFor​

</>
When.InStateFor(seconds: number) → (agent: Agent) → boolean--

true once the agent has been in its current state for seconds.

PathDone​

</>
When.PathDone(agent: Agent) → boolean--

The navigator reports Arrived or Failed: there is nothing more to walk.

Not a builder: use it as a When directly. The usual end of a patrol leg or a search point.

Arrived​

</>
When.Arrived(agent: Agent) → boolean--

The navigator reports Arrived.

PathFailed​

</>
When.PathFailed(agent: Agent) → boolean--

The navigator reports Failed: no path, or one that ends short.

All​

</>
When.All(...: (agent: Agent) → boolean) → (agent: Agent) → boolean--

true when every predicate is. Stops at the first false.

Any​

</>
When.Any(...: (agent: Agent) → boolean) → (agent: Agent) → boolean--

true when any predicate is. Stops at the first true.

Not​

</>
When.Not(predicate: (agent: Agent) → boolean) → (agent: Agent) → boolean--

The opposite.

Show raw api
{
    "functions": [
        {
            "name": "Has",
            "desc": "",
            "params": [
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "`true` while `Blackboard[key]` is not `nil`.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 50,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Missing",
            "desc": "",
            "params": [
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "`true` while `Blackboard[key]` is `nil`.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 61,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Equals",
            "desc": "",
            "params": [
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "`true` while `Blackboard[key] == value`.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 73,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Below",
            "desc": "",
            "params": [
                {
                    "name": "key",
                    "desc": "A number on the blackboard, such as `SeenDistance` or `Awareness`.",
                    "lua_type": "string"
                },
                {
                    "name": "limit",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "`true` while the value is a number below `limit`. A missing key is not below anything.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 85,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Above",
            "desc": "",
            "params": [
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "limit",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "`true` while the value is a number above `limit`.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 98,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "New",
            "desc": "\"Something new is here.\" Reads [Agent:IsNew] and, when it is true, calls [Agent:Acknowledge]\nbefore returning, so the same noise fires one transition and not one per tick. A state may\nacknowledge earlier itself, and a state that wants to react again to the same value may clear\nthe key.",
            "params": [
                {
                    "name": "key",
                    "desc": "A memory key that changes with each new event: `HeardAt`, `HeardSoundAt`, `LastKnownAt`.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "`true` once per distinct value.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 115,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Timer",
            "desc": "",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "[Agent:TimerDone] for `name`. A timer never started counts as done.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 130,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "SafeSighted",
            "desc": "When to stop at the door of a safe room: someone the agent can see is in one, or the one it\nwas chasing just got in. After a stare, `cooldown` keeps it from staring again at once, except\nat someone it was chasing.",
            "params": [
                {
                    "name": "cooldown",
                    "desc": "The timer a stare leaves behind. Default `\"States.StareCooldown\"`, the one [States.Stare] starts.",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "`true` when [SafeWatch] reports someone in a safe area, and either the agent was just chasing them (`SafeWasChased`) or `cooldown` has run out.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 145,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "InStateFor",
            "desc": "",
            "params": [
                {
                    "name": "seconds",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "`true` once the agent has been in its current state for `seconds`.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 158,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "PathDone",
            "desc": "Not a builder: use it as a `When` directly. The usual end of a patrol leg or a search point.",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                }
            ],
            "returns": [
                {
                    "desc": "The navigator reports `Arrived` or `Failed`: there is nothing more to walk.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 171,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Arrived",
            "desc": "",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                }
            ],
            "returns": [
                {
                    "desc": "The navigator reports `Arrived`.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 181,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "PathFailed",
            "desc": "",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                }
            ],
            "returns": [
                {
                    "desc": "The navigator reports `Failed`: no path, or one that ends short.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 190,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "All",
            "desc": "",
            "params": [
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "`true` when every predicate is. Stops at the first `false`.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 199,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Any",
            "desc": "",
            "params": [
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "`true` when any predicate is. Stops at the first `true`.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 216,
                "path": "lib/Brain/When.luau"
            }
        },
        {
            "name": "Not",
            "desc": "",
            "params": [
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "The opposite.",
                    "lua_type": "(agent: Agent) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 233,
                "path": "lib/Brain/When.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "When",
    "desc": "Builders for the `When` of a [Types.Transition] or a [Types.Interrupt]. Exposed as\n`VluxyAI.When`.\n\n```lua\nlocal When = VluxyAI.When\n\nInterrupts = {\n\t{ To = \"Hunt\", When = When.Has(\"SeenTarget\"), Except = { \"Hunt\", \"Attack\" } },\n\t{ To = \"Investigate\", When = When.New(\"HeardAt\"), Except = { \"Hunt\", \"Attack\" } },\n},\nStates = {\n\tHunt = { Transitions = {\n\t\t{ To = \"Attack\", When = When.Below(\"SeenDistance\", 4) },\n\t\t{ To = \"Search\", When = When.Missing(\"SeenPosition\") },\n\t} },\n\tSearch = { Transitions = { { To = \"Patrol\", When = When.Timer(\"Search\") } } },\n}\n```",
    "source": {
        "line": 44,
        "path": "lib/Brain/When.luau"
    }
}