Skip to main content

Awareness

A Types.Sense that turns sightings and noises into a detection meter, the way a stealth game does it: a player who steps into view is not hunted at once but makes the enemy suspicious, then alerted if they stay; a noise nudges the meter; silence drains it. Exposed as VluxyAI.Senses.Awareness. Add it after Sight, Hearing and Sounds, since it reads what they wrote. 

:AddSense(VluxyAI.Senses.Sight.new({ Range = 40 }))
:AddSense(VluxyAI.Senses.Hearing.new(noises))
:AddSense(VluxyAI.Senses.Awareness.new({ Rise = 0.8, Fall = 0.2 }))

Interrupts = {
	{ To = "Hunt", When = When.Equals("AwarenessLevel", "Alerted"), Except = { "Hunt", "Attack" } },
	{ To = "Investigate", When = When.Equals("AwarenessLevel", "Suspicious"), Except = { "Hunt", "Attack", "Investigate" } },
},
Investigate = States.Investigate({ Target = "LastKnownPosition", Then = "Patrol" }),

Types​

AwarenessSource​

</>
interface AwarenessSource {
Name: string--

Written to LastKnownSource when this source is the latest.

While: string?--

A blackboard key that is non-nil every tick the stimulus is present, such as SeenTarget. The meter rises at Rise * Weight per second.

At: string?--

A blackboard key holding a timestamp that changes per event, such as HeardAt. The meter jumps by Weight once per new value.

Position: string?--

The blackboard key holding where it is, copied to LastKnownPosition.

Weight: number?--

Default 1.

}

AwarenessOptions​

</>
interface AwarenessOptions {
Rise: number | (agent: Agent) → number?--

How much the meter rises per second per unit of While weight, or a function of the agent (closer means faster, say). Default 1.

Fall: number?--

How much it drains per second when no source is present. Default 0.25.

Suspicious: number?--

The level at which AwarenessLevel becomes "Suspicious". Default 0.3.

Alerted: number?--

The level at which it becomes "Alerted". Default 1.

Sources: {AwarenessSource}?--

What feeds the meter. Default: SeenTarget at weight 1, HeardAt at 0.5, HeardSoundAt at 0.3.

Key: string?--

The agent.Data key for the counted timestamps. Default "Awareness".

Prefix: string?--

Prepended to every key this sense writes, so two instances can coexist. Default "".

}

Functions​

new​

</>
Awareness.new(options: AwarenessOptions?) → Awareness

Errors

TypeDescription
"unknown option"
stringA source without a `Name`, or with neither `While` nor `At`.

Tick​

</>
Awareness.Tick(
self: Awareness,
agent: Agent,
deltaTime: number
) → ()

Reads the sources, moves the meter and writes the keys listed above to agent.Blackboard.

Configure​

</>
Awareness.Configure(
self: Awareness,
patch: AwarenessOptions--

The options to change; the rest keep their values.

) → ()

Changes options after construction, for difficulty and pacing: a director widening the cone or shortening the memory mid-round. The same rules as new apply.

Errors

TypeDescription
"unknown option"
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "",
            "params": [
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "AwarenessOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Awareness"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"unknown option\"",
                    "desc": ""
                },
                {
                    "lua_type": "string",
                    "desc": "A source without a `Name`, or with neither `While` nor `At`."
                }
            ],
            "source": {
                "line": 136,
                "path": "lib/Senses/Awareness.luau"
            }
        },
        {
            "name": "Tick",
            "desc": "Reads the sources, moves the meter and writes the keys listed above to `agent.Blackboard`.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Awareness"
                },
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                },
                {
                    "name": "deltaTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 177,
                "path": "lib/Senses/Awareness.luau"
            }
        },
        {
            "name": "Configure",
            "desc": "Changes options after construction, for difficulty and pacing: a director widening the cone\nor shortening the memory mid-round. The same rules as `new` apply.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Awareness"
                },
                {
                    "name": "patch",
                    "desc": "The options to change; the rest keep their values.",
                    "lua_type": "AwarenessOptions"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"unknown option\"",
                    "desc": ""
                }
            ],
            "source": {
                "line": 257,
                "path": "lib/Senses/Awareness.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "AwarenessSource",
            "desc": "",
            "fields": [
                {
                    "name": "Name",
                    "lua_type": "string",
                    "desc": "Written to `LastKnownSource` when this source is the latest."
                },
                {
                    "name": "While",
                    "lua_type": "string?",
                    "desc": "A blackboard key that is non-nil every tick the stimulus is present, such as `SeenTarget`. The meter rises at `Rise * Weight` per second."
                },
                {
                    "name": "At",
                    "lua_type": "string?",
                    "desc": "A blackboard key holding a timestamp that changes per event, such as `HeardAt`. The meter jumps by `Weight` once per new value."
                },
                {
                    "name": "Position",
                    "lua_type": "string?",
                    "desc": "The blackboard key holding where it is, copied to `LastKnownPosition`."
                },
                {
                    "name": "Weight",
                    "lua_type": "number?",
                    "desc": "Default `1`."
                }
            ],
            "source": {
                "line": 41,
                "path": "lib/Senses/Awareness.luau"
            }
        },
        {
            "name": "AwarenessOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Rise",
                    "lua_type": "number | (agent: Agent) -> number?",
                    "desc": "How much the meter rises per second per unit of `While` weight, or a function of the agent (closer means faster, say). Default `1`."
                },
                {
                    "name": "Fall",
                    "lua_type": "number?",
                    "desc": "How much it drains per second when no source is present. Default `0.25`."
                },
                {
                    "name": "Suspicious",
                    "lua_type": "number?",
                    "desc": "The level at which `AwarenessLevel` becomes `\"Suspicious\"`. Default `0.3`."
                },
                {
                    "name": "Alerted",
                    "lua_type": "number?",
                    "desc": "The level at which it becomes `\"Alerted\"`. Default `1`."
                },
                {
                    "name": "Sources",
                    "lua_type": "{ AwarenessSource }?",
                    "desc": "What feeds the meter. Default: `SeenTarget` at weight 1, `HeardAt` at 0.5, `HeardSoundAt` at 0.3."
                },
                {
                    "name": "Key",
                    "lua_type": "string?",
                    "desc": "The `agent.Data` key for the counted timestamps. Default `\"Awareness\"`."
                },
                {
                    "name": "Prefix",
                    "lua_type": "string?",
                    "desc": "Prepended to every key this sense writes, so two instances can coexist. Default `\"\"`."
                }
            ],
            "source": {
                "line": 78,
                "path": "lib/Senses/Awareness.luau"
            }
        }
    ],
    "name": "Awareness",
    "desc": "A [Types.Sense] that turns sightings and noises into a detection meter, the way a stealth\ngame does it: a player who steps into view is not hunted at once but makes the enemy\nsuspicious, then alerted if they stay; a noise nudges the meter; silence drains it. Exposed\nas `VluxyAI.Senses.Awareness`. Add it after [Sight], [Hearing] and [Sounds], since it reads\nwhat they wrote.\n\n```lua\n:AddSense(VluxyAI.Senses.Sight.new({ Range = 40 }))\n:AddSense(VluxyAI.Senses.Hearing.new(noises))\n:AddSense(VluxyAI.Senses.Awareness.new({ Rise = 0.8, Fall = 0.2 }))\n\nInterrupts = {\n\t{ To = \"Hunt\", When = When.Equals(\"AwarenessLevel\", \"Alerted\"), Except = { \"Hunt\", \"Attack\" } },\n\t{ To = \"Investigate\", When = When.Equals(\"AwarenessLevel\", \"Suspicious\"), Except = { \"Hunt\", \"Attack\", \"Investigate\" } },\n},\nInvestigate = States.Investigate({ Target = \"LastKnownPosition\", Then = \"Patrol\" }),\n```",
    "source": {
        "line": 128,
        "path": "lib/Senses/Awareness.luau"
    }
}