refactor

Author: selimanac

NAVMESH_API.md

@@ -12,7 +12,7 @@ Defold Graph Pathfinder Extension - Navigation mesh pathfinding with polygon-bas
 - [Spatial Index](#spatial-index)
 - [Statistics](#statistics)
 - [Enumerations](#enumerations)
-- [Complete Example](#complete-example)
+
 
 ---
 
@@ -288,7 +288,6 @@ end
 - `agent_radius = 0`: No portal offsetting, path hugs walls
 - `agent_radius > 0`: Portals offset inward by radius, provides collision clearance
 - Narrow portals (< `agent_radius * collapse_threshold`) collapse to midpoint
-- Recommended: Set `agent_radius` to character's collision radius
 
 ### pathfinder.navmesh_cell_at_position()
 
@@ -523,214 +522,6 @@ end
 
 ---
 
-## Complete Example
-
-Here's a complete example demonstrating navmesh pathfinding in a 3D game:
-
-```lua
--- navmesh_controller.script
-
-go.property("navmesh_buffer", resource.buffer("/assets/level1.navmesh"))
-
-local COLORS = {
-    RED = vmath.vector4(1, 0, 0, 1),
-    GREEN = vmath.vector4(0, 1, 0, 1),
-    BLUE = vmath.vector4(0, 0, 1, 1)
-}
-
--- State
-local player_position = vmath.vector3()
-local target_position = vmath.vector3()
-local current_path = {}
-local path_length = 0
-local path_index = 1
-local grid = {}
-
--- Constants
-local MOVE_SPEED = 5.0
-local WAYPOINT_RADIUS = 0.5
-local AGENT_RADIUS = 0.5
-
--- Utility: Convert screen coordinates to world plane
-local function screen_to_world(camera_url, screen_x, screen_y)
-    local PLANE_POINT = vmath.vector3(0, 0, 0)
-    local PLANE_NORMAL = vmath.vector3(0, 1, 0)
-    
-    local p0 = camera.screen_to_world(vmath.vector3(screen_x, screen_y, 0), camera_url)
-    local p1 = camera.screen_to_world(vmath.vector3(screen_x, screen_y, 1), camera_url)
-    
-    local dir = p1 - p0
-    local denom = vmath.dot(PLANE_NORMAL, dir)
-    if math.abs(denom) < 0.000001 then
-        return nil
-    end
-    
-    local t = vmath.dot(PLANE_POINT - p0, PLANE_NORMAL) / denom
-    if t < 0 then
-        return nil
-    end
-    
-    return p0 + dir * t
-end
-
-function init(self)
-    msg.post(".", "acquire_input_focus")
-    
-    -- Initialize navmesh system
-    pathfinder.navmesh_init(
-        600,   -- max_cells
-        6,     -- max_edges_per_cell
-        32,    -- pool_block_size
-        16,    -- cache_size
-        256,   -- max_cache_path_length
-        5,     -- min_cell_size
-        10,    -- max_cell_size
-        1000,  -- max_grid_dim
-        false  -- debug
-    )
-    
-    -- Optional: Customize funnel tolerances
-    pathfinder.navmesh_set_funnel(0.002, 0.1, 0.001)
-    
-    -- Load navmesh from buffer
-    local buffer = resource.get_buffer(self.navmesh_buffer)
-    pathfinder.navmesh_set_buffer(buffer)
-    
-    -- Get spatial index for visualization
-    grid = pathfinder.navmesh_get_spatial_index()
-    
-    -- Initialize player position
-    player_position = go.get_position()
-    
-    print("Navmesh initialized successfully")
-end
-
-function final(self)
-    pathfinder.navmesh_shutdown()
-end
-
-function update(self, dt)
-    -- Follow current path
-    if path_index <= path_length then
-        local waypoint = current_path[path_index]
-        local target = vmath.vector3(waypoint.x, 0, waypoint.y)
-        
-        -- Move towards waypoint
-        local to_target = target - player_position
-        local distance = vmath.length(to_target)
-        
-        if distance < WAYPOINT_RADIUS then
-            -- Reached waypoint, move to next
-            path_index = path_index + 1
-        else
-            -- Move towards waypoint
-            local direction = vmath.normalize(to_target)
-            player_position = player_position + direction * MOVE_SPEED * dt
-            go.set_position(player_position)
-        end
-    end
-    
-    -- Draw current path
-    draw_path(path_length, current_path)
-    
-    -- Draw spatial index grid (for debugging)
-    draw_spatial_grid(grid)
-    
-    -- Display stats periodically
-    self.stats_timer = (self.stats_timer or 0) + dt
-    if self.stats_timer >= 1.0 then
-        self.stats_timer = 0
-        local stats = pathfinder.navmesh_get_stats()
-        print(string.format("Cache: %d/%d, Hit Rate: %d%%",
-            stats.path_cache.cache_entries,
-            stats.path_cache.cache_capacity,
-            stats.path_cache.cache_hit_rate))
-    end
-end
-
-function on_input(self, action_id, action)
-    if action_id == hash("mouse_click") and action.pressed then
-        -- Get world position from click
-        local world_pos = screen_to_world(msg.url("/camera#camera"), action.x, action.y)
-        if not world_pos then
-            return
-        end
-        
-        target_position = world_pos
-        
-        -- Find path from player to target
-        local length, status, status_text, path = pathfinder.navmesh_find_path(
-            player_position.x,  -- start_x
-            player_position.z,  -- start_y (using Z for 3D)
-            target_position.x,  -- goal_x
-            target_position.z,  -- goal_y
-            128,                -- max_path_length
-            AGENT_RADIUS,       -- agent_radius
-            true                -- enable_fallback
-        )
-        
-        if status == pathfinder.PathStatus.SUCCESS then
-            print("Path found with", length, "waypoints")
-            current_path = path
-            path_length = length
-            path_index = 1
-        elseif status == pathfinder.PathStatus.SUCCESS_START_FALLBACK then
-            print("Path found (start position corrected)")
-            current_path = path
-            path_length = length
-            path_index = 1
-        elseif status == pathfinder.PathStatus.SUCCESS_GOAL_FALLBACK then
-            print("Path found (goal position corrected)")
-            current_path = path
-            path_length = length
-            path_index = 1
-        elseif status == pathfinder.PathStatus.ERROR_NO_PATH then
-            print("No path exists to target")
-        else
-            print("Pathfinding failed:", status_text)
-        end
-    end
-end
-
--- Draw path as connected lines
-function draw_path(length, path)
-    for i = 1, length - 1 do
-        local from_node = path[i]
-        local to_node = path[i + 1]
-        msg.post("@render:", "draw_line", {
-            start_point = vmath.vector3(from_node.x, 0, from_node.y),
-            end_point = vmath.vector3(to_node.x, 0, to_node.y),
-            color = COLORS.GREEN
-        })
-    end
-end
-
--- Draw spatial index grid
-function draw_spatial_grid(grid)
-    if grid.vertical then
-        for _, line in ipairs(grid.vertical) do
-            msg.post("@render:", "draw_line", {
-                start_point = line.start_position,
-                end_point = line.end_position,
-                color = vmath.vector4(1, 0, 0, 0.2)  -- Semi-transparent red
-            })
-        end
-    end
-    
-    if grid.horizontal then
-        for _, line in ipairs(grid.horizontal) do
-            msg.post("@render:", "draw_line", {
-                start_point = line.start_position,
-                end_point = line.end_position,
-                color = vmath.vector4(1, 0, 0, 0.2)  -- Semi-transparent red
-            })
-        end
-    end
-end
-```
-
----
-
 ## Performance Tips
 
 ### Cache Configuration
@@ -763,11 +554,7 @@ pathfinder.navmesh_init(
 - **Medium meshes** (200-500 cells): `pool_block_size = 64`
 - **Large meshes** (>500 cells): `pool_block_size = 128`
 
-### Agent Radius
 
-- Set to character's collision radius for realistic clearance
-- Increase for safety margin (e.g., 1.2× collision radius)
-- Use 0 only if characters can move exactly along walls
 
 ### Fallback Strategy