Package openmw.nearbyΒΆ

OpenMW version: 0.49.0
core.API_REVISION: 58 *

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.findNearestNavMeshPosition(position, options)

Finds a nearest position on navigation mesh to the given position within given search area.

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.getObjectByFormId(formId)

Return an object by RefNum/FormId.

nearby.items

Everything nearby that is derived from openmw.types#Item.

nearby.players

List of nearby players.

Type AgentBounds

AgentBounds.halfExtents
AgentBounds.shapeType

Type AreaCosts

AreaCosts.door

Value >= 0, used in combination with NAVIGATOR_FLAGS.OpenDoor (default: 2).

AreaCosts.ground

Value >= 0, used in combination with NAVIGATOR_FLAGS.Walk (default: 1).

AreaCosts.pathgrid

Value >= 0, used in combination with NAVIGATOR_FLAGS.UsePathgrid (default: 1).

AreaCosts.water

Value >= 0, used in combination with NAVIGATOR_FLAGS.Swim (default: 1).

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 CastRayOptions

CastRayOptions.collisionType

Object types to work with (see openmw.nearby#COLLISION_TYPE)

CastRayOptions.ignore

An object to ignore (specify here the source of the ray)

CastRayOptions.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.

Type CastRenderingRayOptions

CastRenderingRayOptions.ignore

A list of openmw.core#GameObject to ignore while doing the ray cast

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.FindStraightPathFailed

Couldn't map path over polygons into world coordinates.

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.

FIND_PATH_STATUS.TargetPolygonNotFound

adjusted 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;

Type FindNearestNavMeshPositionOptions

FindNearestNavMeshPositionOptions.agentBounds

Identifies which navmesh to use.

FindNearestNavMeshPositionOptions.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).

FindNearestNavMeshPositionOptions.searchAreaHalfExtents

Defines AABB like area half extents around given position (default: (1 + 2 * CellGridRadius) * CellSize * (1, 1, 1) where CellGridRadius and depends on cell type to cover the whole active grid).

Type FindPathOptions

FindPathOptions.agentBounds

identifies which navmesh to use.

FindPathOptions.areaCosts

a table defining relative cost for each type of area.

FindPathOptions.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).

FindPathOptions.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).

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 NavMeshOptions

NavMeshOptions.agentBounds

Identifies which navmesh to use.

NavMeshOptions.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).

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_util#util.bitOr.

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

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.

Parameters

Return value

openmw.util#Vector3, #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

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,
        radius = 10,
    })
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

Return value

#RayCastingResult:

openmw.core#ObjectList nearby.containers

List of nearby containers.

openmw.core#ObjectList nearby.doors

List of nearby doors.

nearby.findNearestNavMeshPosition(position, options)

Finds a nearest position on navigation mesh to the given position within given search area.

Parameters

Return value

openmw.util#Vector3, #nil:

Usages:

  • local navMeshPosition = nearby.findNearestNavMeshPosition(position)
  • local navMeshPosition = nearby.findNearestNavMeshPosition(position, {
        includeFlags = nearby.NAVIGATOR_FLAGS.Swim,
    })
  • local navMeshPosition = nearby.findNearestNavMeshPosition(position, {
        agentBounds = Actor.getPathfindingAgentBounds(self),
    })
  • local navMeshPosition = nearby.findNearestNavMeshPosition(position, {
        searchAreaHalfExtents = util.vector3(1000, 1000, 1000),
        includeFlags = nearby.NAVIGATOR_FLAGS.Walk,
    })
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

Return values

  1. #FINDPATHSTATUS:

  2. #list<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),
    })
nearby.findRandomPointAroundCircle(position, maxRadius, options)

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.

Parameters

  • openmw.util#Vector3 position : Center of the search circle.

  • #number maxRadius : Approximate maximum search distance.

  • #NavMeshOptions options : An optional table with additional optional arguments.

Return value

openmw.util#Vector3, #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),
    })
nearby.getObjectByFormId(formId)

Return an object by RefNum/FormId.

Note: the function always returns openmw.core#GameObject and doesn't validate that the object exists in the game world. If it doesn't exist or not yet loaded to memory), then obj:isValid() will be false.

Parameter

  • #string formId : String returned by core.getFormId

Return value

openmw.core#GameObject:

Usage:

local obj = nearby.getObjectByFormId(core.getFormId('Morrowind.esm', 128964))
openmw.core#ObjectList nearby.items

Everything nearby that is derived from openmw.types#Item.

openmw.core#ObjectList nearby.players

List of nearby players.

Currently (since multiplayer is not yet implemented) always has one element.

Type AgentBounds

A table of parameters identifying navmesh

Field(s)

openmw.util#Vector3 AgentBounds.halfExtents
#COLLISION_SHAPE_TYPE AgentBounds.shapeType

Type AreaCosts

A table of parameters to specify relative path cost per each area type

Field(s)

#number AreaCosts.door

Value >= 0, used in combination with NAVIGATOR_FLAGS.OpenDoor (default: 2).

#number AreaCosts.ground

Value >= 0, used in combination with NAVIGATOR_FLAGS.Walk (default: 1).

#number AreaCosts.pathgrid

Value >= 0, used in combination with NAVIGATOR_FLAGS.UsePathgrid (default: 1).

#number AreaCosts.water

Value >= 0, used in combination with NAVIGATOR_FLAGS.Swim (default: 1).

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 CastRayOptions

A table of parameters for nearby.castRay

Field(s)

#number CastRayOptions.collisionType

Object types to work with (see openmw.nearby#COLLISION_TYPE)

openmw.core#GameObject CastRayOptions.ignore

An object to ignore (specify here the source of the ray)

#number CastRayOptions.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.

Type CastRenderingRayOptions

A table of parameters for nearby.castRenderingRay and nearby.asyncCastRenderingRay

Field(s)

#table CastRenderingRayOptions.ignore

A list of openmw.core#GameObject to ignore while doing the ray cast

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.FindStraightPathFailed

Couldn't map path over polygons into world coordinates.

#number FIND_PATH_STATUS.InitNavMeshQueryFailed

Couldn't initialize required data due to bad input or bad navigation mesh data.

#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.

#number FIND_PATH_STATUS.TargetPolygonNotFound

adjusted 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;

Type FindNearestNavMeshPositionOptions

A table of parameters for nearby.findNearestNavMeshPosition

Field(s)

#AgentBounds FindNearestNavMeshPositionOptions.agentBounds

Identifies which navmesh to use.

#number FindNearestNavMeshPositionOptions.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).

openmw.util#Vector3 FindNearestNavMeshPositionOptions.searchAreaHalfExtents

Defines AABB like area half extents around given position (default: (1 + 2 * CellGridRadius) * CellSize * (1, 1, 1) where CellGridRadius and depends on cell type to cover the whole active grid).

Type FindPathOptions

A table of parameters for nearby.findPath

Field(s)

#AgentBounds FindPathOptions.agentBounds

identifies which navmesh to use.

#AreaCosts FindPathOptions.areaCosts

a table defining relative cost for each type of area.

#number FindPathOptions.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).

#number FindPathOptions.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).

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 NavMeshOptions

A table of parameters for nearby.findRandomPointAroundCircle and nearby.castNavigationRay

Field(s)

#AgentBounds NavMeshOptions.agentBounds

Identifies which navmesh to use.

#number NavMeshOptions.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).

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)