feat!: migrate roadnetwork extension to pathetic library

The Hydrazine pathfinding engine had accumulated critical limitations. Being unmaintained, it couldn't support Minecraft's expanded world height limits from 1.17/1.18, restricting where pathfinding could operate. Entity capabilities were limited, and extending behavior required modifying core classes rather than composing new functionality. On top of this, many blocks weren't handled correctly, making it impossible to find paths in numerous scenarios.

Another problem was the lack of debugging visibility. When paths failed, there was no way to understand why, making troubleshooting frustrating and time-consuming as the road network system grew more sophisticated.

Pathetic's processor-based architecture solves these issues with fine-grained control through composable validators and cost functions. This allows us to model entity constraints while maintaining clean separation of concerns.

The new debug visualization records pathfinding decisions step-by-step, making it much easier to understand why paths fail. Performance improvements to existing systems come from block property caching, physics result reuse, and smarter per-node edge recalculation strategies.

Author: steveb05

code_generator/entitylist.json

@@ -18,6 +18,7 @@ struct Entity {
 #[derive(Debug, Deserialize, Serialize)]
 #[serde(untagged)]
 enum EntityDimension {
+    NonExistant(String),
     Simple(f64),
     Complex(HashMap<String, f64>),
 }
@@ -43,49 +44,6 @@ fn format_property(property: &str, value: &str) -> String {
     }
 }
 
-fn generate_kotlin_code<F>(entities: &[Entity], property_accessor: F) -> Vec<String>
-where
-    F: Fn(&Entity) -> &EntityDimension,
-{
-    entities
-        .iter()
-        .flat_map(|entity| generate_entity_code(entity, &property_accessor))
-        .collect()
-}
-
-fn generate_entity_code<F>(entity: &Entity, property_accessor: F) -> Vec<String>
-where
-    F: Fn(&Entity) -> &EntityDimension,
-{
-    let entity_type = format!("EntityTypes.{}", entity.id.to_uppercase());
-
-    match property_accessor(entity) {
-        EntityDimension::Simple(value) => {
-            vec![format!(
-                "EntityDataMatcher({}) -> {}",
-                entity_type,
-                format_value(*value)
-            )]
-        }
-        EntityDimension::Complex(map) => map
-            .iter()
-            .flat_map(|(key, value)| {
-                key.split("<br>")
-                    .map(|condition_set| {
-                        let conditions = parse_conditions(condition_set);
-                        let matcher = format!(
-                            "EntityDataMatcher({}, {})",
-                            entity_type,
-                            conditions.join(", ")
-                        );
-                        format!("{} -> {}", matcher, format_value(*value))
-                    })
-                    .collect::<Vec<String>>()
-            })
-            .collect(),
-    }
-}
-
 fn parse_conditions(condition_set: &str) -> Vec<String> {
     condition_set
         .split(", ")
@@ -100,39 +58,150 @@ fn parse_conditions(condition_set: &str) -> Vec<String> {
         .collect()
 }
 
-fn write_kotlin_file(file_name: &str, content: &[String]) -> std::io::Result<()> {
-    let mut file = File::create(file_name)?;
-    writeln!(
-        file,
-        "//<editor-fold desc=\"Entity {} by properties\">",
-        file_name.split('.').next().unwrap()
-    )?;
-    for line in content {
-        writeln!(file, "        {}", line)?;
+fn should_use_default_eye_height(eye_height: Option<f64>, height: f64) -> bool {
+    let Some(eye_height) = eye_height else {
+        return true
+    };
+
+    const TOLERANCE: f64 = 0.001;
+    (eye_height - height * 0.85).abs() < TOLERANCE
+}
+
+fn extract_dimension_map(dimension: &EntityDimension) -> HashMap<String, f64> {
+    match dimension {
+        EntityDimension::NonExistant(_) => HashMap::new(),
+        EntityDimension::Simple(val) => {
+            let mut map = HashMap::new();
+            map.insert(String::new(), *val);
+            map
+        }
+        EntityDimension::Complex(map) => map.clone(),
     }
-    writeln!(file, "//</editor-fold>")?;
-    Ok(())
 }
 
-fn generate_property(
-    entities: &[Entity],
-    property_name: &str,
-    accessor: impl Fn(&Entity) -> &EntityDimension,
-) -> String {
-    let kotlin_code = generate_kotlin_code(&entities, accessor);
-    let file_name = format!("Entity{}Property.kt", property_name);
-    write_kotlin_file(&file_name, &kotlin_code).unwrap();
-    println!("{} generated successfully!", file_name);
-    file_name
+fn find_matching_value(map: &HashMap<String, f64>, target_condition: &str) -> Option<f64> {
+    if let Some(value) = map.get(target_condition) {
+        return Some(*value);
+    }
+
+    for (key, value) in map {
+        if conditions_match(key, target_condition) {
+            return Some(*value);
+        }
+    }
+
+    if target_condition.is_empty() {
+        map.get("")
+            .copied()
+            .or_else(|| map.values().next().copied())
+    } else {
+        None
+    }
+}
+
+fn conditions_match(key: &str, target: &str) -> bool {
+    if key.contains(target) || target.contains(key) {
+        return true;
+    }
+
+    if !target.is_empty() && !key.is_empty() {
+        let target_parts: std::collections::HashSet<_> = target.split(", ").collect();
+        let key_parts: std::collections::HashSet<_> = key.split(", ").collect();
+        target_parts.intersection(&key_parts).count() > 0
+    } else {
+        false
+    }
+}
+
+fn collect_all_conditions(
+    width_map: &HashMap<String, f64>,
+    height_map: &HashMap<String, f64>,
+    eye_height_map: &HashMap<String, f64>,
+) -> std::collections::HashSet<String> {
+    let mut all_conditions = std::collections::HashSet::new();
+
+    for key in width_map
+        .keys()
+        .chain(height_map.keys())
+        .chain(eye_height_map.keys())
+    {
+        for condition_set in key.split("<br>") {
+            all_conditions.insert(condition_set.to_string());
+        }
+    }
+
+    all_conditions
+}
+
+fn generate_entity_kotlin_entries(entity: &Entity) -> Vec<String> {
+    let entity_type = format!("EntityTypes.{}", entity.id.to_uppercase());
+
+    let width_map = extract_dimension_map(&entity.width);
+    let height_map = extract_dimension_map(&entity.height);
+    let eye_height_map = extract_dimension_map(&entity.eye_height);
+
+    let all_conditions = collect_all_conditions(&width_map, &height_map, &eye_height_map);
+
+    all_conditions
+        .iter()
+        .filter_map(|condition_set| {
+            let width = find_matching_value(&width_map, condition_set)?;
+            let height = find_matching_value(&height_map, condition_set)?;
+            let eye_height = find_matching_value(&eye_height_map, condition_set);
+
+            let eye_height_str = if should_use_default_eye_height(eye_height, height) {
+                String::new()
+            } else {
+                format!(", eyeHeight = {}", format_value(eye_height.expect("Should have used default value of eye height")))
+            };
+
+            let matcher = if condition_set.is_empty() {
+                format!("EntityDataMatcher({})", entity_type)
+            } else {
+                let conditions = parse_conditions(condition_set);
+                format!(
+                    "EntityDataMatcher({}, {})",
+                    entity_type,
+                    conditions.join(", ")
+                )
+            };
+
+            Some(format!(
+                "{} to EntityData(width = {}, height = {}{})",
+                matcher,
+                format_value(width),
+                format_value(height),
+                eye_height_str
+            ))
+        })
+        .collect()
+}
+
+fn generate_kotlin_entries(entities: &[Entity]) -> Vec<String> {
+    entities
+        .iter()
+        .flat_map(generate_entity_kotlin_entries)
+        .collect()
+}
+
+fn write_entity_data_entries(entries: &[String]) -> std::io::Result<()> {
+    let mut file = File::create("EntityTypeProperty_generated.kt")?;
+    writeln!(file, "//<editor-fold desc=\"Entity Data Map Entries\">")?;
+    for entry in entries {
+        writeln!(file, "        {},", entry)?;
+    }
+    writeln!(file, "//</editor-fold>")?;
+    Ok(())
 }
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let json_str = std::fs::read_to_string("entitylist.json")?;
     let entities = parse_json(&json_str)?;
 
-    generate_property(&entities, "EyeHeight", |e: &Entity| &e.eye_height);
-    generate_property(&entities, "Height", |e: &Entity| &e.height);
-    generate_property(&entities, "Width", |e: &Entity| &e.width);
+    let kotlin_entries = generate_kotlin_entries(&entities);
+    write_entity_data_entries(&kotlin_entries)?;
+
+    println!("Generated {} entity data entries", kotlin_entries.len());
 
     Ok(())
 }

code_generator/src/bin/entity_type_properties.rs

@@ -1,5 +1,6 @@
 package com.typewritermc.core.utils
 
+import kotlinx.coroutines.CancellationException
 import java.util.Locale.getDefault
 
 fun String.replaceAll(vararg pairs: Pair<String, String>): String {
@@ -30,7 +31,7 @@ fun tryCatch(error: (Exception) -> Unit = { it.printStackTrace() }, block: () ->
 suspend fun tryCatchSuspend(error: suspend (Exception) -> Unit = { it.printStackTrace() }, block: suspend () -> Unit) {
     try {
         block()
-    } catch (e: Throwable) {
+    } catch (_: CancellationException) {} catch (e: Throwable) {
         error(e)
     }
 }

engine/engine-core/src/main/kotlin/com/typewritermc/core/utils/Extensions.kt

@@ -168,6 +168,22 @@ interface Point<P : Point<P>> {
         return (this.x - x).squared() + (this.y - y).squared() + (this.z - z).squared()
     }
 
+    /**
+     * Computes the squared distance with weighted Y-axis contribution.
+     *
+     * Use this when vertical distance should have different importance than horizontal distance.
+     *
+     * @param x the X coordinate
+     * @param y the Y coordinate
+     * @param z the Z coordinate
+     * @param yWeight weight multiplier for Y-axis distance (default 0.5, range typically 0.0-1.0)
+     * @return the weighted squared distance
+     */
+    @Contract(pure = true)
+    fun distanceSquaredWeightedY(x: Double, y: Double, z: Double, yWeight: Double = 0.5): Double {
+        return (this.x - x).squared() + ((this.y - y).squared() * yWeight) + (this.z - z).squared()
+    }
+
     /**
      * Gets the squared distance between this point and another.
      *
@@ -179,6 +195,21 @@ interface Point<P : Point<P>> {
         return distanceSquared(point.x, point.y, point.z)
     }
 
+    /**
+     * Computes the squared distance to another point with weighted Y-axis contribution.
+     *
+     * Use this when vertical distance should have different importance than horizontal distance.
+     * See [distanceSquaredWeightedY] for details.
+     *
+     * @param point the other point
+     * @param yWeight weight multiplier for Y-axis distance (default 0.5)
+     * @return the weighted squared distance
+     */
+    @Contract(pure = true)
+    fun distanceSquaredWeightedY(point: Point<*>, yWeight: Double = 0.5): Double {
+        return distanceSquaredWeightedY(point.x, point.y, point.z, yWeight)
+    }
+
     @Contract(pure = true)
     fun distance(x: Double, y: Double, z: Double): Double {
         return sqrt(distanceSquared(x, y, z))

engine/engine-core/src/main/kotlin/com/typewritermc/core/utils/point/Point.kt

@@ -91,6 +91,21 @@ fun <WP1, WP2> WP1.distanceSqrt(point: WP2): Double?
     return distanceSquared(point)
 }
 
+/**
+ * Computes the weighted Y-distance between two world positions.
+ *
+ * Use this when vertical distance should have less impact on calculations.
+ *
+ * @param point the position to measure distance to
+ * @param yWeight weight applied to Y-axis distance (default 0.5)
+ * @return squared weighted distance, or null if positions are in different worlds
+ */
+fun <WP1, WP2> WP1.distanceSquaredWeightedY(point: WP2, yWeight: Double = 0.5): Double?
+        where WP1 : Point<WP1>, WP1 : WorldHolder<WP1>, WP2 : Point<WP2>, WP2 : WorldHolder<WP2> {
+    if (this.world != point.world) return null
+    return distanceSquaredWeightedY(point, yWeight)
+}
+
 fun Position.toBlockPosition(): Position {
     return Position(world, blockX.toDouble(), blockY.toDouble(), blockZ.toDouble(), 0f, 0f)
 }

engine/engine-core/src/main/kotlin/com/typewritermc/core/utils/point/Position.kt

@@ -60,6 +60,19 @@ data class Vector(
         return Vector(this.x / x, this.y / y, this.z / z)
     }
 
+    /**
+     * Computes the dot product between this vector and another vector.
+     *
+     * Use this to calculate projections, determine if vectors are perpendicular (result = 0),
+     * or measure similarity in direction (positive = same direction, negative = opposite).
+     *
+     * @param other the vector to compute the dot product with
+     * @return the dot product value
+     */
+    fun dot(other: Vector): Double {
+        return x * other.x + y * other.y + z * other.z
+    }
+
     fun normalize(): Vector {
         val length = length
         return if (length < EPSILON) {

engine/engine-core/src/main/kotlin/com/typewritermc/core/utils/point/Vector.kt

@@ -82,4 +82,47 @@ open class EntityState(
     override fun toString(): String {
         return "EntityState(eyeHeight=$eyeHeight, speed=$speed)"
     }
-}
+}
+
+/**
+ * Encapsulates the movement and interaction capabilities of an entity for which the pathfinding is being performed.
+ *
+ * @param height          The entity's height in blocks, used for vertical clearance checks.
+ * @param width           The entity's width in blocks, used for horizontal clearance checks.
+ * @param maxStepHeight   The maximum height in blocks the entity can step up without jumping.
+ * @param maxJumpHeight   The maximum height in blocks the entity can jump. This is measured
+ *                        from the surface of the starting block to the surface of the destination block.
+ * @param maxFallDistance The maximum vertical distance in blocks the entity will pathfind
+ *                        downwards in a single move.
+ * @param jumpStrength    The entity jump strength, used for jump velocity calculation
+ * @param canJump         Determines whether the entity can perform jumps.
+ * @param canInteract     Determines whether the entity can open interactable blocks like wooden
+ *                        doors, fence gates, and trapdoors.
+ * @param canSwim         Determines whether the entity can move through liquids.
+ * @param canClimb        Determines whether the entity can climb objects like ladders and vines.
+ */
+data class EntityPathingCapabilities(
+    val width: Double = 0.6,
+    val height: Double = 1.8,
+    val maxStepHeight: Double = 0.6,
+    val maxJumpHeight: Double = 1.25,
+    val maxFallDistance: Double = 2.1,
+    val jumpStrength: Double = 0.42,
+    val canJump: Boolean = true,
+    val canInteract: Boolean = false,
+    val canSwim: Boolean = false,
+    val canClimb: Boolean = false
+) {
+    companion object {
+        val DEFAULT = EntityPathingCapabilities()
+    }
+
+    init {
+        require(width > 0) { "Entity width must be positive, but was $width" }
+        require(height > 0) { "Entity height must be positive, but was $height" }
+        require(maxStepHeight >= 0) { "Max step height must be non-negative, but was $maxStepHeight" }
+        require(maxJumpHeight >= 0) { "Max jump height must be non-negative, but was $maxJumpHeight" }
+        require(maxFallDistance >= 0) { "Max fall distance must be non-negative, but was $maxFallDistance" }
+        require(jumpStrength >= 0) { "Entity jump strength must be non-negative, but was $jumpStrength" }
+    }
+}