See !114 !116

[[TOC]]

Any agent that needs to see another agent needs to use the new Vision feature.

IMPORTANT: Any agent that wants to be "seen" ALSO needs to add the Vision Feature. e.g. if a Moth prey can be seen by a predator, both the Predator and the Moth need to use Vision.

useFeature Vision

Visibility is determined by looking at the intersection of a vision cone polygon drawn from the center of the viewer agent with the bounding rectangle of the target agent. If any points intersect the target is considered visible.

The cone is determined by the viewDistance and viewAngle properties. The vision cone polygon is drawn with four points: the center of the agent, a left edge projected a viewDistance away at half the viewAngle, a middle point viewDistance away, and a right angle viewDistance away. The basic shape is like a squashed kite, though with larger angles it starts to distort.

Vision is implemented as a polygonal "cone" cast in front of the agent's current direction.

• Direction is set by movement: it is the angle between the agent's last point and the current point.
• The cone is not quite a triangle. We add an extra point to stretch out the center of the cone so that the view area is larger. This is necessary because if you detect an agent on the edge of the cone, then turn towards the agent, turning will cause you to lose sight of the agent with a triangular vision area.
• Vision can be really difficult to debug, so we've hacked in a placeholder method that will draw the vision cone in front of the agent. You can remove the vision cone by commenting out feat-vision.ts:98: // agent.debug = visionPath;

Sets a flag that makes an agent visible or invisible to a vision cone. Use this for example to detect whether a moth can be seen by a predator and therefore targeted during SeekAgent.

Using the feature will automatically set visionable to true. If the agent does not useFeature Vision, then they will not be detectable by other agent vision cones.

featProp Vision visionable setTo true

Default: true

If an agent's visionable is false, then during the Vision feature m_update cycle, other agents will not be able to see the agent even if it is detectable within the vision cone.

featCall Vision monitor <blueprint> where <blueprint> is the name of another blueprint, e.g. Moth.

This will register the agent with the Vision feature. During the AGENTS_UPDATE loop, the system will update the agent with information about which other agents it can see. Use the sees and doesNotSee conditions to test for visibility.

viewDistance determines how far an agent can see. The distance is measured center to center, in game world units. The setViewDistance method has been replaced by the viewDistance property.

Default: 250

featProp Vision viewDistance <method> <value>

where <method> is a GVarNumber method like setTo and <value> is any number between 0 and 1000.

You can change the max to be greater than 1000, but that's probably larger than most playfields.

viewAngle determines the width of the vision cone in degrees. For example, a viewAngle of 45 would draw a cone that is 45 degrees wide.

Default: 90

featProp Vision viewAngle <method> <value>

where <method> is a GVarNumber method like setTo and <value> is any number between 0 and 180.

Currently the system system doesn't really support angles greater than 180. In fact angles greater than about 120 start to get weird as we're drawing a simplified cone shape to optimize the calculations.

If larger view angles are necessary, we should re-implement the vision system to add more "spokes" to the view poly to keep it from "collapsing" at the greater angles.

True when the target bounds is within the vision cone of the source agent.

when <sourceBlueprint> sees <targetBlueprint> [[ ... ]] where <sourceBlueprint> is the name of agent doing the seeing (e.g. "Predator"), and ` is the target being seen, (e.g. "Moth").

This is a when condition test.

• <sourceBlueprint> must have the Vision feature
• <targetBlueprint> must also have the Vision feature
• <targetBlueprint> visionable property must be true

when <blueprintA> doesNotSee <blueprintB> [[ ... ]] where <blueprint> is the name of another blueprint, e.g. Moth.

This is a when condition test. It requires that <blueprintA> have the Vision feature, otherwise <blueprintB> will never be seen.

The Vision feature works similar to the Touches feature in that you need to first register a target blueprint to monitor, and then you can use various conditional statements.

# BLUEPRINT Predator
# PROGRAM DEFINE
useFeature Vision
featCall Vision monitor Moth
# PROGRAM UPDATE
when Predator sees Moth [[
  featCall Moth.Costume setGlow 0.1
]]

Sets the threshold for color detection. Agent colors are detectable against a background color if the difference between the agent color and the background color is greater than the threshold value.

NOTE: This uses the Agent's Costume and the target Agent's background Agent color property. It does NOT detect a sprite's color by sampling the spritesheet/image.

The default value is 0, which will match any value, so detection is always possible.

The detection uses difference <= threshold. So if the difference is 0.2 and the threshold is set to 0.2, the difference does NOT exceed the threshold and the color is NOT detected.

These are all GVarNumbers, sop use the setTo and value methods to interact with them.

featProp Vision colorHueDetectionThreshold setTo <value>

where <value> is a number from 0 to 1.

The isCamouflaged method returns true if the target agent can not be detected against the background color.

NOTE: You shouldn't need to use this method. This is mostly a private method.

graph TD
    A[Agent:Predator] -->|vision| B[Agent:Moth]
    B --> |touches:bounds-in-bounds| C[Agent:Tree]

featCall Vision isCamouflaged <backgroundColor> <hueRange> <saturationRange> <valueRange>

where

• <backgroundColor> is a number
• <hueRange> is a number between 0 and 1
• <saturationRange> is a number between 0 and 1
• <valueRange> is a number between 0 and 1

If the difference between the agent color H/S/V and the backgroundColor H/S/V is within the H/S/V range, then the agent is considered camouflaged.

In general, this is used by Vision feature itself in m_IsTargetColorVisible to determine the visibility of a target agent. While it can be used in an ifExpr, use it with careful consideration as it tests the current agent's color against the background color. In most cases you'll be wanting to test some other target agent and against an arbitrary background color, which is set automatically via m_IsTargetColorVisible

Checks to see if agent can see the color of the target agent against its background agent (an agent that it is in side of, using the binb test).

This is used by predators to determine if they can see a moth against its background tree or sky object.

This uses the color*DetectionThreshold values to determine visibility.

See 5583efa7894e84f5a5d6449557e6eb078c27ac34

featCall Vision canSeeColorOfAgent <target>

Where <target> is a target agent.

The <target> agent requires the following features for this to work:

• Vision -- to set visibility
• Costume -- to determine color
• Touches -- to determine the background agent that the target agent is on top of