dao::world
The world’s geometry: rays, line of sight, screen positions, paths and rooms.
Declared in dao/World.h.
Classes
| Class | |
|---|---|
| Hit | One shape that a ray hit, laid out exactly as the game stores it. |
| ModelBox | A creature model’s bounding box, the one the game uses for drawing. |
| PathSearch | The result of a path search by Pathfind. |
| Room | A room of the current area. |
| ScreenPoint | A point in the world as drawn on the screen, in pixels from the top left of the game’s view (the window’s client area). |
| Sight | The result of a line-of-sight test: whether the view is clear, and where it is blocked if not. |
| ViewSize | The size of the game’s view, in pixels. |
| WalkPath | The path a creature walks: its waypoints from start to end, and the one it is heading for. |
Functions
AimAt()
std::optional<ScreenPoint> AimAt(ObjectId object)
Returns a pixel to click to target an object: a point inside the object as drawn, where the cursor finds it before any other object.
It tries heights from about a person’s middle outward, and returns the first point whose eight neighbouring pixels also hit the object. Failing that, it returns the point with the most such neighbours (ScreenPoint::around), because the game’s cursor can miss at an object’s edge.
Returns nullopt if the object is not in view, or another object is in front of it at every point tried
CreatureShowDistance()
std::optional<float> CreatureShowDistance()
Returns how far from the camera the game shows a creature, in metres, as it stands now.
The game’s own goes by the graphics detail the player chose: 30, 35, 50 or 60. A creature farther from the camera than this is faded out and taken out of the scene, and its animations stop with it. An attack’s impact is an event of its animation, so such a creature’s commands still run and end, but its blows never land.
Returns nullopt in a build of the game the library does not know
CurrentArea()
CCArea * CurrentArea()
Returns the area the player is in.
Returns null before a game is loaded
CurrentPath()
std::optional<WalkPath> CurrentPath(ObjectId creature)
Returns the path a creature’s movement most recently found.
A path appears a frame or more after a move is ordered, and not while the game is paused. A creature keeps its last path after it arrives, so check its current command (CCObject::CurrentCommand) to tell whether it is walking.
Returns nullopt if the creature does not exist or has no path
FindPath()
std::optional<WalkPath> FindPath(ObjectId creature, const Vector &to, ObjectId toward=kInvalidObject)
Finds the path a creature would walk to a point, like Pathfind, and returns only the path.
if (const auto path = dao::world::FindPath(creature, enemyPosition, enemy))
spdlog::info("{:.1f} m to walk", path->Length());
Returns nullopt if no path reaches the destination
FirstHit()
std::optional<Hit> FirstHit(const Vector &from, const Vector &to, std::uint32_t mask=groups::kSight)
Returns the nearest shape on the segment between two points.
| Parameter | |
|---|---|
mask |
the collision groups to hit; groups::kSight by default |
Returns nullopt if nothing lies between them
LineOfSight()
Sight LineOfSight(const Vector &from, const Vector &to, ObjectId ignore=kInvalidObject)
Returns whether one point can be seen from another, using the same test as the game’s scripts.
Only the nearest shape in groups::kSight counts. A placeable blocks the view only if it is a door (or of base type 8), so a chest in front of a wall leaves the view clear, just as the scripts see it.
| Parameter | |
|---|---|
ignore |
an object that should not block the view, or kInvalidObject |
Returns not clear off the game thread or with no area loaded
LineOfSight()
Sight LineOfSight(ObjectId viewer, ObjectId target)
Returns whether target is in line of sight of viewer, using the same test as the scripts’ CheckLineOfSightObject: from kEyeHeight above one’s position to kEyeHeight above the other’s.
Returns not clear if either object is missing, they are in different areas, or the call is off the game thread
ModelBoxOf()
std::optional<ModelBox> ModelBoxOf(ObjectId creature)
Returns a creature’s model box.
Call on the game thread.
Returns nullopt if the id is not a creature, its model is not of a kind this can read, or the call is off the game thread
ObstaclePlaced()
std::optional<bool> ObstaclePlaced(ObjectId creature)
Returns whether a creature is marked on the pathfinding grid right now.
A standing creature marks the cells under it as an obstacle, which other creatures’ paths avoid and which the game checks when it fits attackers around a target (the melee rings of dao/Attack.h). A creature places its mark during its own update, so while the game is paused a creature that has just stopped may not be marked yet. Call on the game thread.
Returns nullopt if there is no such creature
Pathfind()
PathSearch Pathfind(ObjectId creature, const Vector &to, ObjectId toward=kInvalidObject)
Finds the path a creature would walk to a point, using the game’s pathfinder, without affecting the creature: its current path, movement and orders are left alone.
Where a straight walk works, the path is just its two ends. Otherwise the search runs for at most 40 ms. When a long walk across open ground gives up part way, the search goes on from where it stopped, up to six times. Call on the game thread.
| Parameter | |
|---|---|
creature |
the creature that would walk |
to |
the destination. If the creature does not fit there, the nearest free place up to 2 m back toward the creature is used, as for a click. |
toward |
a creature standing at the destination, which is not treated as an obstacle, so that a path to an enemy reaches it; or kInvalidObject |
Returns the search, including the path if one reaches the destination
PickAt()
std::vector<Hit> PickAt(std::int32_t x, std::int32_t y)
Returns everything under a pixel, nearest first, as the cursor would find it there.
It casts the camera’s ray through the pixel with groups::kCursor and objects’ selection volumes, and skips effects hidden from the cursor with dao::vfx::SetPickable.
The first object is the one a click there would most likely act on. For what the game itself has under the cursor, see GameModeExplore (dao/GameModes.h).
| Parameter | |
|---|---|
x |
pixels from the left of the view |
y |
pixels from the top of the view |
Returns no hits for a pixel outside the view, off the game thread, or when no world is drawn
Raycast()
std::vector<Hit> Raycast(const Vector &origin, const Vector &direction, std::uint32_t mask=groups::kCursor, bool selectionVolumes=false)
Returns every shape along a ray in the current area, nearest first.
| Parameter | |
|---|---|
origin |
where the ray starts |
direction |
the ray’s direction, of any non-zero length; the ray has no end |
mask |
the collision groups to hit; groups::kCursor by default |
selectionVolumes |
true to also hit objects’ selection volumes, as the cursor does. An object may then appear twice, once for its body and once for its volume. |
Returns at most 32 hits. None off the game thread, with no area loaded, or for a zero direction.
RoomAt()
std::optional<Room> RoomAt(const Vector &point)
Returns the room that contains a point, using the area’s own lookup.
For a point in no room, returns the nearest room by its bounds, with distance set to how far away it is.
Returns nullopt if the area has no rooms, or off the game thread
RoomOf()
std::optional<Room> RoomOf(ObjectId object)
Returns the room an object is in: the room the object records for itself, which is the one the game goes by.
Returns nullopt if there is no such object, or its area has no rooms
Rooms()
std::vector<Room> Rooms()
Returns every room of the current area.
Returns none before an area is loaded, or off the game thread
ScreenSize()
std::optional<ViewSize> ScreenSize()
Returns the size of the game’s view in pixels, which is the window’s client area.
Returns nullopt off the game thread or when no world is drawn
SetCreatureShowDistance()
bool SetCreatureShowDistance(std::optional<float> metres)
Holds the distance from the camera within which the game shows a creature at metres, or with nullopt gives it back to the game.
The game sets the distance itself whenever it applies the graphics detail, so the library puts the plugin’s back each frame for as long as it is held. It is one distance for every creature of the game, not one creature’s, and it is not saved. Farther creatures drawn and animated cost frame time. The area’s rooms are still loaded only around the camera, to some 120 m.
| Parameter | |
|---|---|
metres |
more than 0, or nullopt for the game’s own |
Returns false, with nothing changed, for a distance that is not more than 0, or in a build of the game the library does not know
ToScreen()
std::optional<ScreenPoint> ToScreen(const Vector &point)
Returns where a point in the world appears on the screen.
Returns nullopt off the game thread or when no world is drawn
Variables
kEyeHeight
constexpr float kEyeHeight = 1.8F
The height above a creature’s position, in metres, that the scripts’ line-of-sight test looks from and to.