From 4a20ed38a8441da73a0844de5330f91c25d1b8d5 Mon Sep 17 00:00:00 2001 From: Richard Fine Date: Sat, 12 Sep 2020 01:11:56 -0400 Subject: [PATCH] Document public API for pathfinder Add comments explaining the externally-visible points in the pathfinding code. --- src/openrct2/peep/GuestPathfinding.h | 29 +++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/src/openrct2/peep/GuestPathfinding.h b/src/openrct2/peep/GuestPathfinding.h index d6e1312efc..990463e972 100644 --- a/src/openrct2/peep/GuestPathfinding.h +++ b/src/openrct2/peep/GuestPathfinding.h @@ -18,15 +18,42 @@ struct Peep; struct Guest; struct TileElement; +// The tile position of the place the peep is trying to get to (park entrance/exit, ride +// entrance/exit, or the end of the queue line for a ride). +// +// This gets copied into Peep::PathfindGoal. The two separate variables are needed because +// when the goal changes the peep's pathfind history needs to be reset. extern TileCoordsXYZ gPeepPathFindGoalPosition; -extern bool gPeepPathFindIgnoreForeignQueues; + +// When the heuristic pathfinder is examining neighboring tiles, one possibility is that it finds a +// queue tile; furthermore, this queue tile may or may not be for the ride that the peep is trying +// to get to, if any. This first var is used to store the ride that the peep is currently headed to. extern ride_id_t gPeepPathFindQueueRideIndex; +// Furthermore, staff members don't care about this stuff; even if they are e.g. a mechanic headed +// to a particular ride, they have no issues with walking over queues for other rides to get there. +// This bool controls that behaviour - if true, the peep will not path over queues for rides other +// than their target ride, and if false, they will treat it like a regular path. +// +// In practice, if this is false, gPeepPathFindQueueRideIndex is always RIDE_ID_NULL. +extern bool gPeepPathFindIgnoreForeignQueues; + +// Given a peep 'peep' at tile 'loc', who is trying to get to 'gPeepPathFindGoalPosition', decide +// the direction the peep should walk in from the current tile. Direction peep_pathfind_choose_direction(const TileCoordsXYZ& loc, Peep* peep); + +// Reset the peep's stored goal, which means they will forget any stored pathfinding history +// on the next choose_direction call. void peep_reset_pathfind_goal(Peep* peep); +// Test whether the given tile can be walked onto, if the peep is currently at height currentZ and +// moving in direction currentDirection. bool is_valid_path_z_and_direction(TileElement* tileElement, int32_t currentZ, int32_t currentDirection); +// Overall guest pathfinding AI. Sets up Peep::DestinationX/DestinationY (which they move to in a +// straight line, no pathfinding). Called whenever the guest has arrived at their previously set destination. +// +// Returns 0 if the guest has successfully had a new destination set up, nonzero otherwise. int32_t guest_path_finding(Guest* peep); #if defined(DEBUG_LEVEL_1) && DEBUG_LEVEL_1