Skip to main content

Watched

A Types.Sense that writes who is looking at the agent. An observer sees the agent when the agent's pivot is inside the observer's FieldOfView cone within Range, and (unless RequireLineOfSight is off) a ray from the observer's eye to the pivot reaches the agent's entity. Writes WatchedBy, IsWatched, WatchedAt and UnwatchedFor, which is what a freeze-when-seen state reads. UnwatchedFor is math.huge until the first time it is watched.

By default an observer's eye is its character's head, so "looking" means the head's facing, which on a default rig is the walk direction rather than the camera. A game that wants the real camera direction replicates it to the server and passes Eye.

Types​

WatchedOptions​

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

Studs from which an observer can see the agent. Default 60.

FieldOfView: number?--

The full angle of the observer's view cone, in degrees. Default 90.

RequireLineOfSight: boolean?--

Cast a ray from the observer to the agent, or trust the cone alone. Default true.

Targets: ((agent: Agent) → {BasePart})?--

Who might be looking. Default Perception.AliveRoots, every alive player's root.

Ignore: ((agent: Agent) → {Instance})?--

Extra instances the observer's ray passes through, on top of the observer's own character. Default none.

Eye: ((root: BasePart) → CFrame?)?--

Where an observer looks from and which way: a replicated camera, say. nil falls back to the default. Default the head's CFrame when the character has one, else the root's.

Prefix: string?--

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

}

Functions​

new​

</>
Watched.new(options: WatchedOptions?) → Watched

Errors

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

Tick​

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

Checks every observer, and writes the keys listed above to agent.Blackboard.

Destroy​

</>
Watched.Destroy(self: Watched) → ()

Nothing to release; present so the sense satisfies Types.Sense and any cleanup helper.

Configure​

</>
Watched.Configure(
self: Watched,
patch: WatchedOptions--

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": "WatchedOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Watched"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"unknown option\"",
                    "desc": "A key not in `WatchedOptions`."
                },
                {
                    "lua_type": "\"Range must be zero or more\"",
                    "desc": ""
                }
            ],
            "source": {
                "line": 129,
                "path": "lib/Senses/Watched.luau"
            }
        },
        {
            "name": "Tick",
            "desc": "Checks every observer, and writes the keys listed above to `agent.Blackboard`.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Watched"
                },
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                },
                {
                    "name": "deltaTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 154,
                "path": "lib/Senses/Watched.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Nothing to release; present so the sense satisfies [Types.Sense] and any cleanup helper.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Watched"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 208,
                "path": "lib/Senses/Watched.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": "Watched"
                },
                {
                    "name": "patch",
                    "desc": "The options to change; the rest keep their values.",
                    "lua_type": "WatchedOptions"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"unknown option\"",
                    "desc": ""
                }
            ],
            "source": {
                "line": 220,
                "path": "lib/Senses/Watched.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "WatchedOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Range",
                    "lua_type": "number?",
                    "desc": "Studs from which an observer can see the agent. Default `60`."
                },
                {
                    "name": "FieldOfView",
                    "lua_type": "number?",
                    "desc": "The full angle of the observer's view cone, in degrees. Default `90`."
                },
                {
                    "name": "RequireLineOfSight",
                    "lua_type": "boolean?",
                    "desc": "Cast a ray from the observer to the agent, or trust the cone alone. Default `true`."
                },
                {
                    "name": "Targets",
                    "lua_type": "((agent: Agent) -> { BasePart })?",
                    "desc": "Who might be looking. Default [Perception.AliveRoots], every alive player's root."
                },
                {
                    "name": "Ignore",
                    "lua_type": "((agent: Agent) -> { Instance })?",
                    "desc": "Extra instances the observer's ray passes through, on top of the observer's own character. Default none."
                },
                {
                    "name": "Eye",
                    "lua_type": "((root: BasePart) -> CFrame?)?",
                    "desc": "Where an observer looks from and which way: a replicated camera, say. `nil` falls back to the default. Default the head's CFrame when the character has one, else the root's."
                },
                {
                    "name": "Prefix",
                    "lua_type": "string?",
                    "desc": "Prepended to every key this sense writes, so two instances can coexist. Default `\"\"`."
                }
            ],
            "source": {
                "line": 62,
                "path": "lib/Senses/Watched.luau"
            }
        }
    ],
    "name": "Watched",
    "desc": "A [Types.Sense] that writes who is looking at the agent. An observer sees the agent when the\nagent's pivot is inside the observer's `FieldOfView` cone within `Range`, and (unless\n`RequireLineOfSight` is off) a ray from the observer's eye to the pivot reaches the agent's\nentity. Writes `WatchedBy`, `IsWatched`, `WatchedAt` and `UnwatchedFor`, which is what a\nfreeze-when-seen state reads. `UnwatchedFor` is `math.huge` until the first time it is watched.\n\nBy default an observer's eye is its character's head, so \"looking\" means the head's facing,\nwhich on a default rig is the walk direction rather than the camera. A game that wants the\nreal camera direction replicates it to the server and passes `Eye`.",
    "source": {
        "line": 121,
        "path": "lib/Senses/Watched.luau"
    }
}