Integrate flow field pathfinder into game simulation

assets/test/shaders/pathfinding/demo_0_flow_field.frag.glsl

@@ -1,24 +1,33 @@
 #version 330
 
-in float v_cost;
+/// Flow field value
+in float flow_val;
+
+/// Integration field flags
+in float int_val;
 
 out vec4 outcol;
 
+int WAVEFRONT_BLOCKED = 0x04;
+int LINE_OF_SIGHT = 0x20;
+int PATHABLE = 0x10;
+
 void main() {
-    int cost = int(v_cost);
-    if (bool(cost & 0x40)) {
+    int flow_flags = int(flow_val) & 0xF0;
+    int int_flags = int(int_val);
+    if (bool(int_flags & WAVEFRONT_BLOCKED)) {
         // wavefront blocked
         outcol = vec4(0.9, 0.9, 0.9, 1.0);
         return;
     }
 
-    if (bool(cost & 0x20)) {
+    if (bool(int_flags & LINE_OF_SIGHT)) {
         // line of sight
         outcol = vec4(1.0, 1.0, 1.0, 1.0);
         return;
     }
 
-    if (bool(cost & 0x10)) {
+    if (bool(flow_flags & PATHABLE)) {
         // pathable
         outcol = vec4(0.7, 0.7, 0.7, 1.0);
         return;

assets/test/shaders/pathfinding/demo_0_flow_field.vert.glsl

@@ -1,15 +1,18 @@
 #version 330
 
 layout(location=0) in vec3 position;
-layout(location=1) in float cost;
+layout(location=1) in float flow_cell;
+layout(location=2) in float int_cell;
 
 uniform mat4 model;
 uniform mat4 view;
 uniform mat4 proj;
 
-out float v_cost;
+out float flow_val;
+out float int_val;
 
 void main() {
 	gl_Position = proj * view * model * vec4(position, 1.0);
-    v_cost = cost;
+    flow_val = flow_cell;
+    int_val = int_cell;
 }

doc/code/pathfinding/README.md

@@ -109,13 +109,12 @@ a path request is made, the main influence on performance is the A\* algorithm.
 a limited number of portals, the A\* search should overall be very cheap.
 
 The resulting list of sectors and portals is subsequently used in the low-level flow
-field calculations. As a first step, the pathfinder uses its integrator to generate
+field calculations. More details can be found in the [field types](field_types.md) document.
+As a first step, the pathfinder uses its integrator to generate
 a flow field for each identified sector. Generation starts with the target sector
 and ends with the start sector. Flow field results are passed through at the cells
 of the identified portals to make the flow between sectors seamless.
 
-<!-- TODO: More descriptions of cost/integration/flow field calculations -->
-
 In a second step, the pathfinder follows the movement vectors in the flow fields from
 the start cell to the target cell. Waypoints are created for every direction change, so
 that game entities can travel in straight lines between them. The list of waypoints

doc/code/pathfinding/field_types.md

@@ -0,0 +1,78 @@
+# Field Types
+
+This document describes the field types used in the flow field pathfinding system.
+
+Most of the descriptions are based on the [*Crowd Pathfinding and Steering Using Flow Field Tiles*](http://www.gameaipro.com/GameAIPro/GameAIPro_Chapter23_Crowd_Pathfinding_and_Steering_Using_Flow_Field_Tiles.pdf) article by Elijah Emerson.
+
+## Cost Field
+
+A cost field is a square grid of cells that record the cost of movement on the location
+of each cell. Higher cost values indicate that it is less desirable to move through that cell.
+The field is usually initialized at the start of the game and persists for the lifetime of
+the entire pathfinding grid. During gameplay, individual cell costs may be altered to reflect
+changes in the environment.
+
+Cost values are represented as `uint8_t` (0-255) values. The range of usable cost values
+is `1` to `254`. `255` is a special value that represents an impassable cell. `0` is reserved
+for initialization and should not be used for flow field calculations.
+
+![Cost Field](images/cost_field.png)
+
+- **green**: minimum cost
+- **red**: maximum cost
+- **black**: impassable cell
+
+## Integration Field
+
+The integration field is created from a cost field when a path is requested. For a specific
+target cell, the integration field stores the accumulated cost of reaching that cell from
+every other cell in the field.
+
+Integration values are calculated using a wavefront algorithm. The algorithm starts at the
+target cell(s) and propagates outward, updating the integration value of each cell it visits.
+The integration value is calculated by adding the cost value of the current cell to the lowest
+integration value of the 4 cardinal neighbors. The integration value of the target cell(s) is `0`.
+
+Integration values are represented as `uint16_t` (0-65535) values. The range of usable integration
+values is `1` to `65534`. `65535` is a special value that represents an unreachable cell. During
+initialization, all cells are set to `65535`.
+
+An additional refinement step in the form of line-of-sight testing may be performed before the
+integration values are calculated. This step flags every cell that is in line of sight of the
+target cell. This allows for smoother pathing, as game entities can move in a straight line to
+the target cell. The algorithm for this step is described in more detail in section 23.6.2
+of the [*Crowd Pathfinding and Steering Using Flow Field Tiles*](http://www.gameaipro.com/GameAIPro/GameAIPro_Chapter23_Crowd_Pathfinding_and_Steering_Using_Flow_Field_Tiles.pdf) article.
+
+In addition to the integration values, the integration field also stores flags for each cell:
+
+- `FOUND`: cell has been visited
+- `TARGET`: cell is a target cell
+- `LOS`: cell is in line of sight of target cell
+- `WAVEFRONT_BLOCKED`: cell is blocking line of sight to target cell
+
+![Integration Field](images/integration_field.png)
+
+- **green**: lower integration values
+- **purple**: higher integration values
+- **black**: unreachable cell
+
+## Flow Field
+
+Creating the flow field is the final step in the flow field calculation. The field
+is created from the integration field. Cells in the flow field store the direction to
+the neighbor cell with the lowest *integrated* cost. Thus, directions create a "flow"
+towards the target cell. Following the directions from anywhere on the field will lead
+to the shortest path to the target cell.
+
+Flow field values are represented as `uint8_t` values. The 4 least significant bits are used
+to store the direction to the neighbor cell with the lowest integrated cost. Therefore, 8
+directions can be represented. The 4 most significant bits are used for flags:
+- `PATHABLE`: cell is passable
+- `LOS`: cell is in line of sight of target cell
+- `TARGET`: cell is a target cell
+
+![Flow Field](images/flow_field.png)
+
+- **white**: line of sight
+- **bright/dark grey**: passable cells (not in line of sight)
+- **black**: impassable cell

etc/gdb_pretty/printers.py

@@ -291,7 +291,7 @@ class PathFlowTypePrinter:
     FLOW_FLAGS: dict = {
         0x10: 'PATHABLE',
         0x20: 'LOS',
-        0x40: 'WAVEFRONT_BLOCKED',
+        0x40: 'TARGET',
         0x80: 'UNUSED',
     }
 
@@ -333,8 +333,14 @@ def children(self):
 
 # Integrated flags
 INTEGRATED_FLAGS: dict = {
-    0x01: 'LOS',
-    0x02: 'WAVEFRONT_BLOCKED',
+    0x01: 'UNUSED',
+    0x02: 'FOUND',
+    0x04: 'WAVEFRONT_BLOCKED',
+    0x08: 'UNUSED',
+    0x10: 'UNUSED',
+    0x20: 'LOS',
+    0x40: 'TARGET',
+    0x80: 'UNUSED',
 }
 
 
@@ -410,6 +416,5 @@ def children(self):
 
 
 # TODO: curve types
-# TODO: pathfinding types
 # TODO: input event codes
 # TODO: eigen types https://github.com/dmillard/eigengdb

libopenage/coord/chunk.cpp

@@ -1,8 +1,20 @@
-// Copyright 2016-2018 the openage authors. See copying.md for legal info.
+// Copyright 2016-2024 the openage authors. See copying.md for legal info.
 
 #include "chunk.h"
 
+#include "coord/tile.h"
+
+
 namespace openage {
 namespace coord {
 
-}} // namespace openage::coord
+tile_delta chunk_delta::to_tile(tile_t tiles_per_chunk) const {
+	return tile_delta{this->ne * tiles_per_chunk, this->se * tiles_per_chunk};
+}
+
+tile chunk::to_tile(tile_t tiles_per_chunk) const {
+	return tile{this->ne * tiles_per_chunk, this->se * tiles_per_chunk};
+}
+
+} // namespace coord
+} // namespace openage

libopenage/coord/chunk.h

@@ -12,10 +12,14 @@ namespace coord {
 
 struct chunk_delta : CoordNeSeRelative<chunk_t, chunk, chunk_delta> {
 	using CoordNeSeRelative<chunk_t, chunk, chunk_delta>::CoordNeSeRelative;
+
+	tile_delta to_tile(tile_t tiles_per_chunk) const;
 };
 
 struct chunk : CoordNeSeAbsolute<chunk_t, chunk, chunk_delta> {
 	using CoordNeSeAbsolute<chunk_t, chunk, chunk_delta>::CoordNeSeAbsolute;
+
+	tile to_tile(tile_t tiles_per_chunk) const;
 };
 
 struct chunk3_delta : CoordNeSeUpRelative<chunk_t, chunk3, chunk3_delta> {

libopenage/coord/tile.cpp

@@ -1,4 +1,4 @@
-// Copyright 2016-2023 the openage authors. See copying.md for legal info.
+// Copyright 2016-2024 the openage authors. See copying.md for legal info.
 
 #include "tile.h"
 
@@ -8,55 +8,86 @@
 
 namespace openage::coord {
 
+phys2_delta tile_delta::to_phys2() const {
+	return phys2_delta{phys2::elem_t::from_int(this->ne),
+	                   phys2::elem_t::from_int(this->se)};
+}
 
-tile3 tile::to_tile3(tile_t up) const {
-	return tile3(this->ne, this->se, up);
+phys3_delta tile_delta::to_phys3(tile_t up) const {
+	return phys3_delta{phys3::elem_t::from_int(this->ne),
+	                   phys3::elem_t::from_int(this->se),
+	                   phys3::elem_t::from_int(up)};
 }
 
+tile3 tile::to_tile3(tile_t up) const {
+	return tile3{this->ne, this->se, up};
+}
 
 phys2 tile::to_phys2() const {
-	return phys2{phys3::elem_t::from_int(this->ne), phys3::elem_t::from_int(this->se)};
+	return phys2{phys3::elem_t::from_int(this->ne),
+	             phys3::elem_t::from_int(this->se)};
 }
 
-
 phys3 tile::to_phys3(tile_t up) const {
 	return this->to_tile3(up).to_phys3();
 }
 
+phys2 tile::to_phys2_center() const {
+	return phys2{phys3::elem_t::from_int(this->ne) + 0.5,
+	             phys3::elem_t::from_int(this->se) + 0.5};
+}
+
+phys3 tile::to_phys3_center(tile_t up) const {
+	return phys3{phys3::elem_t::from_int(this->ne) + 0.5,
+	             phys3::elem_t::from_int(this->se) + 0.5,
+	             phys3::elem_t::from_int(up)};
+}
 
 chunk tile::to_chunk() const {
 	return chunk{
 		static_cast<chunk::elem_t>(util::div(this->ne, tiles_per_chunk)),
 		static_cast<chunk::elem_t>(util::div(this->se, tiles_per_chunk))};
 }
 
-
 tile_delta tile::get_pos_on_chunk() const {
 	return tile_delta{
 		util::mod(this->ne, tiles_per_chunk),
 		util::mod(this->se, tiles_per_chunk)};
 }
 
+tile_delta tile3_delta::to_tile() const {
+	return tile_delta{this->ne, this->se};
+}
+
+phys3_delta tile3_delta::to_phys3() const {
+	return phys3_delta{phys3::elem_t::from_int(this->ne),
+	                   phys3::elem_t::from_int(this->se),
+	                   phys3::elem_t::from_int(up)};
+}
+
+tile tile3::to_tile() const {
+	return tile{this->ne, this->se};
+}
 
 phys2 tile3::to_phys2() const {
 	return this->to_tile().to_phys2();
 }
 
-
 phys3 tile3::to_phys3() const {
-	return phys3{
-		phys3::elem_t::from_int(this->ne),
-		phys3::elem_t::from_int(this->se),
-		phys3::elem_t::from_int(this->up)};
+	return phys3{phys3::elem_t::from_int(this->ne),
+	             phys3::elem_t::from_int(this->se),
+	             phys3::elem_t::from_int(this->up)};
 }
 
-
-phys2_delta tile_delta::to_phys2() const {
-	return phys2_delta(this->ne, this->se);
+phys2 tile3::to_phys2_center() const {
+	return phys2{phys3::elem_t::from_int(this->ne) + 0.5,
+	             phys3::elem_t::from_int(this->se) + 0.5};
 }
 
-phys3_delta tile_delta::to_phys3(tile_t up) const {
-	return phys3_delta(this->ne, this->se, up);
+phys3 tile3::to_phys3_center() const {
+	return phys3{phys3::elem_t::from_int(this->ne) + 0.5,
+	             phys3::elem_t::from_int(this->se) + 0.5,
+	             phys3::elem_t::from_int(this->up)};
 }
 
 } // namespace openage::coord

libopenage/coord/tile.h

@@ -20,6 +20,7 @@ namespace coord {
 struct tile_delta : CoordNeSeRelative<tile_t, tile, tile_delta> {
 	using CoordNeSeRelative<tile_t, tile, tile_delta>::CoordNeSeRelative;
 
+	// coordinate conversions
 	phys2_delta to_phys2() const;
 	phys3_delta to_phys3(tile_t up = 0) const;
 };
@@ -34,8 +35,12 @@ struct tile : CoordNeSeAbsolute<tile_t, tile, tile_delta> {
 	 * elevation.
 	 */
 	tile3 to_tile3(tile_t up = 0) const;
+
 	phys2 to_phys2() const;
 	phys3 to_phys3(tile_t up = 0) const;
+	phys2 to_phys2_center() const;
+	phys3 to_phys3_center(tile_t up = 0) const;
+
 	chunk to_chunk() const;
 	tile_delta get_pos_on_chunk() const;
 };
@@ -45,9 +50,7 @@ struct tile3_delta : CoordNeSeUpRelative<tile_t, tile3, tile3_delta> {
 
 	// coordinate conversions
 	// simply discards the UP component of the coordinate delta.
-	constexpr tile_delta to_tile() const {
-		return tile_delta{this->ne, this->se};
-	}
+	tile_delta to_tile() const;
 	phys3_delta to_phys3() const;
 };
 
@@ -56,11 +59,12 @@ struct tile3 : CoordNeSeUpAbsolute<tile_t, tile3, tile3_delta> {
 
 	// coordinate conversions
 	// simply discards the UP component of the coordinate.
-	constexpr tile to_tile() const {
-		return tile{this->ne, this->se};
-	}
+	tile to_tile() const;
+
 	phys2 to_phys2() const;
 	phys3 to_phys3() const;
+	phys2 to_phys2_center() const;
+	phys3 to_phys3_center() const;
 };
 
 

libopenage/gamestate/CMakeLists.txt

@@ -5,6 +5,7 @@ add_sources(libopenage
     game_state.cpp
 	game.cpp
 	manager.cpp
+    map.cpp
 	player.cpp
     simulation.cpp
 	terrain_chunk.cpp