Skip to main content

Hearing

A Types.Sense that listens to a noise signal. Make one with VluxyAI.Signal.new(), hand it to every agent that should hear, and fire it with (position, loudness?, kind?, source?) whenever something makes a sound. Each tick the sense keeps the loudest noise within Range * loudness studs of the agent (the nearest on a tie) that Accept lets through, and writes HeardPosition, HeardAt, HeardLoudness, HeardKind, HeardSource and HeardStrength, which stay for Memory seconds and then clear. 

-- During a chase, hear only the chased player.
VluxyAI.Senses.Hearing.new(noises, {
	Accept = function(source, agent)
		local chased = agent.Blackboard.ChaseTarget
		return chased == nil or source == chased
	end,
})
``` One instance may serve many agents: noises
are buffered per agent, and each agent's tick empties only its own buffer.

Types​

HearingOptions​

</>
interface HearingOptions {
Range: number?--

Studs a noise of loudness 1 carries. A noise is heard within Range * loudness. Default 30.

Memory: number?--

Seconds the heard keys outlive the last heard noise. Default 5.

Occlusion: number?--

Loudness multiplier per wall between the noise and the agent, 0 to 1. 1 (the default) casts no rays; 0.5 halves a noise per wall.

OcclusionWalls: number?--

Walls counted at most. Default 3.

MinStrength: number?--

A noise arriving weaker than this (see HeardStrength) is not heard. Default 0.

Accept: ((
source: Instance?,
agent: Agent
) → boolean)?--

Checked for every noise before the loudest is picked; a noise it returns false for is not heard. source is the noise's fourth argument (nil when it had none). Default: every noise is heard.

Prefix: string?--

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

}

Functions​

new​

</>
Hearing.new(
noises: NoiseSignal,--

Fired with a position, an optional loudness (default 1), an optional kind and an optional source.

options: HearingOptions?
) → Hearing

Errors

TypeDescription
"unknown option"A key not in `HearingOptions`.
"Range must be zero or more"
"MinStrength must be zero or more"

Strength​

</>
Hearing.Strength(
loudness: number,--

The noise's loudness as it arrives, after walls.

distance: number,--

Studs between the noise and the listener.

range: number--

The sense's Range.

) → number--

loudness * (1 - distance / (range * loudness)), never below 0; the full loudness when the reach is 0.

How strongly a noise arrives, written as HeardStrength. Pure.

Tick​

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

Judges every noise buffered for this agent since its last tick, writes the keys listed above to agent.Blackboard and empties the buffer. The first tick registers the agent, so it hears noises fired from then on.

Destroy​

</>
Hearing.Destroy(
self: Hearing,
agent: Types.Agent?
) → ()

Disconnects from the noise signal and drops every agent's buffer. The signal itself is yours; it is not destroyed.

Configure​

</>
Hearing.Configure(
self: Hearing,
patch: HearingOptions--

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": "noises",
                    "desc": "Fired with a position, an optional loudness (default `1`), an optional kind and an optional source.",
                    "lua_type": "NoiseSignal"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "HearingOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Hearing"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"unknown option\"",
                    "desc": "A key not in `HearingOptions`."
                },
                {
                    "lua_type": "\"Range must be zero or more\"",
                    "desc": ""
                },
                {
                    "lua_type": "\"MinStrength must be zero or more\"",
                    "desc": ""
                }
            ],
            "source": {
                "line": 149,
                "path": "lib/Senses/Hearing.luau"
            }
        },
        {
            "name": "Strength",
            "desc": "How strongly a noise arrives, written as `HeardStrength`. Pure.",
            "params": [
                {
                    "name": "loudness",
                    "desc": "The noise's loudness as it arrives, after walls.",
                    "lua_type": "number"
                },
                {
                    "name": "distance",
                    "desc": "Studs between the noise and the listener.",
                    "lua_type": "number"
                },
                {
                    "name": "range",
                    "desc": "The sense's `Range`.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "`loudness * (1 - distance / (range * loudness))`, never below `0`; the full loudness when the reach is `0`.",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 182,
                "path": "lib/Senses/Hearing.luau"
            }
        },
        {
            "name": "Tick",
            "desc": "Judges every noise buffered for this agent since its last tick, writes the keys listed above\nto `agent.Blackboard` and empties the buffer. The first tick registers the agent, so it hears\nnoises fired from then on.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Hearing"
                },
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                },
                {
                    "name": "deltaTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 249,
                "path": "lib/Senses/Hearing.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Disconnects from the noise signal and drops every agent's buffer. The signal itself is yours;\nit is not destroyed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Hearing"
                },
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Types.Agent?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 333,
                "path": "lib/Senses/Hearing.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": "Hearing"
                },
                {
                    "name": "patch",
                    "desc": "The options to change; the rest keep their values.",
                    "lua_type": "HearingOptions"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"unknown option\"",
                    "desc": ""
                }
            ],
            "source": {
                "line": 359,
                "path": "lib/Senses/Hearing.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "HearingOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Range",
                    "lua_type": "number?",
                    "desc": "Studs a noise of loudness `1` carries. A noise is heard within `Range * loudness`. Default `30`."
                },
                {
                    "name": "Memory",
                    "lua_type": "number?",
                    "desc": "Seconds the heard keys outlive the last heard noise. Default `5`."
                },
                {
                    "name": "Occlusion",
                    "lua_type": "number?",
                    "desc": "Loudness multiplier per wall between the noise and the agent, `0` to `1`. `1` (the default) casts no rays; `0.5` halves a noise per wall."
                },
                {
                    "name": "OcclusionWalls",
                    "lua_type": "number?",
                    "desc": "Walls counted at most. Default `3`."
                },
                {
                    "name": "MinStrength",
                    "lua_type": "number?",
                    "desc": "A noise arriving weaker than this (see `HeardStrength`) is not heard. Default `0`."
                },
                {
                    "name": "Accept",
                    "lua_type": "((source: Instance?, agent: Agent) -> boolean)?",
                    "desc": "Checked for every noise before the loudest is picked; a noise it returns `false` for is not heard. `source` is the noise's fourth argument (`nil` when it had none). Default: every noise is heard."
                },
                {
                    "name": "Prefix",
                    "lua_type": "string?",
                    "desc": "Prepended to every key this sense writes, so two instances can coexist. Default `\"\"`."
                }
            ],
            "source": {
                "line": 76,
                "path": "lib/Senses/Hearing.luau"
            }
        }
    ],
    "name": "Hearing",
    "desc": "A [Types.Sense] that listens to a noise signal. Make one with `VluxyAI.Signal.new()`, hand it\nto every agent that should hear, and fire it with `(position, loudness?, kind?, source?)`\nwhenever something makes a sound. Each tick the sense keeps the loudest noise within\n`Range * loudness` studs of the agent (the nearest on a tie) that `Accept` lets through, and\nwrites `HeardPosition`, `HeardAt`, `HeardLoudness`, `HeardKind`, `HeardSource` and\n`HeardStrength`, which stay for `Memory` seconds and then clear.\n\n```lua\n-- During a chase, hear only the chased player.\nVluxyAI.Senses.Hearing.new(noises, {\n\tAccept = function(source, agent)\n\t\tlocal chased = agent.Blackboard.ChaseTarget\n\t\treturn chased == nil or source == chased\n\tend,\n})\n``` One instance may serve many agents: noises\nare buffered per agent, and each agent's tick empties only its own buffer.",
    "source": {
        "line": 139,
        "path": "lib/Senses/Hearing.luau"
    }
}