# Package openmw.nearby¶

openmw.nearby provides read-only access to the nearest area of the game world.

Can be used only from local scripts.

## Usage:

local nearby = require('openmw.nearby')

## Type nearby

 nearby.COLLISION_TYPE Collision types that are used in castRay. nearby.activators List of nearby activators. nearby.actors List of nearby actors. nearby.asyncCastRenderingRay(callback, from, to) Asynchronously cast ray from one point to another and find the first visual intersection with anything in the scene. nearby.castNavigationRay(from, to, options) Finds a nearest to the ray target position starting from the initial position with resulting curve drawn on the navigation mesh surface. nearby.castRay(from, to, options) Cast ray from one point to another and return the first collision. nearby.castRenderingRay(from, to) Cast ray from one point to another and find the first visual intersection with anything in the scene. nearby.containers List of nearby containers. nearby.doors List of nearby doors. nearby.findPath(source, destination, options) Find path over navigation mesh from source to destination with given options. nearby.findRandomPointAroundCircle(position, maxRadius, options) Returns random location on navigation mesh within the reach of specified location. nearby.items Everything that can be picked up in the nearby.

## Type COLLISION_SHAPE_TYPE

 COLLISION_SHAPE_TYPE.Aabb Axis-Aligned Bounding Box is used for NPC and symmetric Creatures; COLLISION_SHAPE_TYPE.Cylinder is used for NPC and symmetric Creatures. COLLISION_SHAPE_TYPE.RotatingBox is used for Creatures with big difference in width and height;

## Type COLLISION_TYPE

 COLLISION_TYPE.Actor COLLISION_TYPE.AnyPhysical : World+Door+Actor+HeightMap+Projectile+Water COLLISION_TYPE.Camera Objects that should collide only with camera COLLISION_TYPE.Default Used by default: World+Door+Actor+HeightMap COLLISION_TYPE.Door COLLISION_TYPE.HeightMap COLLISION_TYPE.Projectile COLLISION_TYPE.VisualOnly Objects that were not intended to be part of the physics world COLLISION_TYPE.Water COLLISION_TYPE.World

## Type FIND_PATH_STATUS

 FIND_PATH_STATUS.EndPolygonNotFound destination position is too far from available navigation mesh. The status may appear when navigation mesh is not fully generated or position is outside of covered area; FIND_PATH_STATUS.FindPathOverPolygonsFailed Path over navigation mesh from source to destination does not exist or navigation mesh is not fully generated to provide the path; FIND_PATH_STATUS.InitNavMeshQueryFailed Couldn't initialize required data due to bad input or bad navigation mesh data. FIND_PATH_STATUS.MoveAlongSurfaceFailed Found path couldn't be smoothed due to imperfect algorithm implementation or bad navigation mesh data; FIND_PATH_STATUS.NavMeshNotFound Provided agentBounds don't have corresponding navigation mesh. For interior cells it means an agent with such agentBounds is present on the scene. For exterior cells only default agentBounds is supported; FIND_PATH_STATUS.PartialPath Last path point is not a destination but a nearest position among found; FIND_PATH_STATUS.StartPolygonNotFound source position is too far from available navigation mesh. The status may appear when navigation mesh is not fully generated or position is outside of covered area; FIND_PATH_STATUS.Success Path is found;

## Type NAVIGATOR_FLAGS

 NAVIGATOR_FLAGS.OpenDoor allow agent to open doors on the way; NAVIGATOR_FLAGS.Swim allow agent to swim on the water surface; NAVIGATOR_FLAGS.UsePathgrid allow agent to use predefined pathgrid imported from ESM files. NAVIGATOR_FLAGS.Walk allow agent to walk on the ground area;

## Type RayCastingResult

 RayCastingResult.hit Is there a collision? (true/false) RayCastingResult.hitNormal Normal to the surface in the collision point (nil if no collision) RayCastingResult.hitObject The object the ray has collided with (can be nil) RayCastingResult.hitPos Position of the collision point (nil if no collision)

## Type nearby

### Field(s)

#COLLISION_TYPE nearby.COLLISION_TYPE

Collision types that are used in castRay.

Several types can be combined with '+'.

openmw.core#ObjectList nearby.activators

List of nearby activators.

openmw.core#ObjectList nearby.actors

List of nearby actors.

nearby.asyncCastRenderingRay(callback, from, to)

Asynchronously cast ray from one point to another and find the first visual intersection with anything in the scene.

### Parameters

• openmw.async#Callback callback : The callback to pass the result to (should accept a single argument openmw.nearby#RayCastingResult).

• openmw.util#Vector3 from : Start point of the ray.

• openmw.util#Vector3 to : End point of the ray.

Finds a nearest to the ray target position starting from the initial position with resulting curve drawn on the navigation mesh surface.

### Return value

openmw.util#Vector3 or nil

### Usages:

• local position = nearby.castNavigationRay(from, to)
• local position = nearby.castNavigationRay(from, to, {
includeFlags = nearby.NAVIGATOR_FLAGS.Swim,
})
• local position = nearby.castNavigationRay(from, to, {
agentBounds = Actor.getPathfindingAgentBounds(self),
})
nearby.castRay(from, to, options)

Cast ray from one point to another and return the first collision.

### Parameters

• openmw.util#Vector3 from : Start point of the ray.

• openmw.util#Vector3 to : End point of the ray.

• #table options : An optional table with additional optional arguments. Can contain:
ignore - an object to ignore (specify here the source of the ray);
collisionType - object types to work with (see openmw.nearby#COLLISION_TYPE), several types can be combined with '+';
radius - the radius of the ray (zero by default). If not zero then castRay actually casts a sphere with given radius.
NOTE: currently ignore is not supported if radius>0.

### Return value

#RayCastingResult:

### Usages:

• if nearby.castRay(pointA, pointB).hit then print('obstacle between A and B') end
• local res = nearby.castRay(self.position, enemy.position, {ignore=self})
if res.hitObject and res.hitObject ~= enemy then obstacle = res.hitObject end
• local res = nearby.castRay(self.position, targetPos, {
collisionType=nearby.COLLISION_TYPE.HeightMap + nearby.COLLISION_TYPE.Water,
})
nearby.castRenderingRay(from, to)

Cast ray from one point to another and find the first visual intersection with anything in the scene.

As opposite to castRay can find an intersection with an object without collisions. In order to avoid threading issues can be used only in player scripts only in onFrame or in engine handlers for user input. In other cases use asyncCastRenderingRay instead.

### Parameters

• openmw.util#Vector3 from : Start point of the ray.

• openmw.util#Vector3 to : End point of the ray.

### Return value

#RayCastingResult:

openmw.core#ObjectList nearby.containers

List of nearby containers.

openmw.core#ObjectList nearby.doors

List of nearby doors.

nearby.findPath(source, destination, options)

Find path over navigation mesh from source to destination with given options.

Result is unstable since navigation mesh generation is asynchronous.

### Parameters

• openmw.util#Vector3 source : Initial path position.

• openmw.util#Vector3 destination : Final path position.

• #table options : An optional table with additional optional arguments. Can contain:

• agentBounds - a table identifying which navmesh to use, can contain:

• stepSize - a floating point number to define frequency of path points (default: 2 * math.max(halfExtents:x, halfExtents:y))

• includeFlags - allowed areas for agent to move, a sum of #NAVIGATOR_FLAGS values (default: NAVIGATOR_FLAGS.Walk + NAVIGATOR_FLAGS.Swim + NAVIGATOR_FLAGS.OpenDoor + NAVIGATOR_FLAGS.UsePathgrid);

• areaCosts - a table defining relative cost for each type of area, can contain:

• ground - a floating point number >= 0, used in combination with NAVIGATOR_FLAGS.Walk (default: 1);
• water - a floating point number >= 0, used in combination with NAVIGATOR_FLAGS.Swim (default: 1);
• door - a floating point number >= 0, used in combination with NAVIGATOR_FLAGS.OpenDoor (default: 2);
• pathgrid - a floating point number >= 0, used in combination with NAVIGATOR_FLAGS.UsePathgrid (default: 1);
• destinationTolerance - a floating point number representing maximum allowed distance between destination and a nearest point on the navigation mesh in addition to agent size (default: 1);

### Return value

#FIND_PATH_STATUS, a collection of openmw.util#Vector3

### Usages:

• local status, path = nearby.findPath(source, destination)
• local status, path = nearby.findPath(source, destination, {
includeFlags = nearby.NAVIGATOR_FLAGS.Walk + nearby.NAVIGATOR_FLAGS.OpenDoor,
areaCosts = {
door = 1.5,
},
})
• local status, path = nearby.findPath(source, destination, {
agentBounds = Actor.getPathfindingAgentBounds(self),
})

Returns random location on navigation mesh within the reach of specified location.

The location is not exactly constrained by the circle, but it limits the area.

### Return value

openmw.util#Vector3 or nil

### Usages:

• local position = nearby.findRandomPointAroundCircle(position, maxRadius)
• local position = nearby.findRandomPointAroundCircle(position, maxRadius, {
includeFlags = nearby.NAVIGATOR_FLAGS.Walk,
})
• local position = nearby.findRandomPointAroundCircle(position, maxRadius, {
agentBounds = Actor.getPathfindingAgentBounds(self),
})
openmw.core#ObjectList nearby.items

Everything that can be picked up in the nearby.

## Type COLLISION_SHAPE_TYPE

### Field(s)

#number COLLISION_SHAPE_TYPE.Aabb

Axis-Aligned Bounding Box is used for NPC and symmetric Creatures;

#number COLLISION_SHAPE_TYPE.Cylinder

is used for NPC and symmetric Creatures.

#number COLLISION_SHAPE_TYPE.RotatingBox

is used for Creatures with big difference in width and height;

## Type COLLISION_TYPE

### Field(s)

#number COLLISION_TYPE.Actor
#number COLLISION_TYPE.AnyPhysical

: World+Door+Actor+HeightMap+Projectile+Water

#number COLLISION_TYPE.Camera

Objects that should collide only with camera

#number COLLISION_TYPE.Default

Used by default: World+Door+Actor+HeightMap

#number COLLISION_TYPE.Door
#number COLLISION_TYPE.HeightMap
#number COLLISION_TYPE.Projectile
#number COLLISION_TYPE.VisualOnly

Objects that were not intended to be part of the physics world

#number COLLISION_TYPE.Water
#number COLLISION_TYPE.World

## Type FIND_PATH_STATUS

### Field(s)

#number FIND_PATH_STATUS.EndPolygonNotFound

destination position is too far from available navigation mesh. The status may appear when navigation mesh is not fully generated or position is outside of covered area;

#number FIND_PATH_STATUS.FindPathOverPolygonsFailed

Path over navigation mesh from source to destination does not exist or navigation mesh is not fully generated to provide the path;

#number FIND_PATH_STATUS.InitNavMeshQueryFailed

#number FIND_PATH_STATUS.MoveAlongSurfaceFailed

Found path couldn't be smoothed due to imperfect algorithm implementation or bad navigation mesh data;

#number FIND_PATH_STATUS.NavMeshNotFound

Provided agentBounds don't have corresponding navigation mesh. For interior cells it means an agent with such agentBounds is present on the scene. For exterior cells only default agentBounds is supported;

#number FIND_PATH_STATUS.PartialPath

Last path point is not a destination but a nearest position among found;

#number FIND_PATH_STATUS.StartPolygonNotFound

source position is too far from available navigation mesh. The status may appear when navigation mesh is not fully generated or position is outside of covered area;

#number FIND_PATH_STATUS.Success

Path is found;

## Type NAVIGATOR_FLAGS

### Field(s)

#number NAVIGATOR_FLAGS.OpenDoor

allow agent to open doors on the way;

#number NAVIGATOR_FLAGS.Swim

allow agent to swim on the water surface;

#number NAVIGATOR_FLAGS.UsePathgrid

allow agent to use predefined pathgrid imported from ESM files.

#number NAVIGATOR_FLAGS.Walk

allow agent to walk on the ground area;

## Type RayCastingResult

Result of raycasing

### Field(s)

#boolean RayCastingResult.hit

Is there a collision? (true/false)

openmw.util#Vector3 RayCastingResult.hitNormal

Normal to the surface in the collision point (nil if no collision)

openmw.core#GameObject RayCastingResult.hitObject

The object the ray has collided with (can be nil)

openmw.util#Vector3 RayCastingResult.hitPos

Position of the collision point (nil if no collision)