Expose INVALID_ID constant to Lua API

[Copilot]

pathfinder.navmesh_cell_at_position() returns UINT32_MAX (4294967295) when a position is not in any navmesh cell, but this constant was not exposed to Lua. Documentation referenced non-existent pathfinder.INVALID_CELL_ID, causing example code to fail.

Changes

• pathfinder.cpp: Expose pathfinder::INVALID_ID constant in LuaInit() as pathfinder.INVALID_ID
• annotations.lua: Add type annotation for IDE support
• NAVMESH_API.md: Fix documentation to reference correct constant name

Usage

local cell_id, center_x, center_y = pathfinder.navmesh_cell_at_position(x, z)

if cell_id == pathfinder.INVALID_ID then  -- Now works correctly
    print("Position is outside navmesh")
else
    print("Position is in cell", cell_id)
end

The constant value is 4294967295 (UINT32_MAX), consistent with C++ definition in pathfinder_constants.h.

Original prompt

Fix Missing INVALID_ID Constant in Lua API

Problem

The pathfinder.navmesh_cell_at_position() function returns 4294967295 (UINT32_MAX) when a position is not in any cell, but this constant is not exposed to Lua. The documentation references pathfinder.INVALID_CELL_ID which doesn't exist, causing the example code to fail.

Current Behavior

local cell_id, center_x, center_y = pathfinder.navmesh_cell_at_position(x, z)
-- Returns: cell_id = 4294967295 when position not in any cell

if cell_id ~= pathfinder.INVALID_CELL_ID then  -- ERROR: INVALID_CELL_ID doesn't exist
    -- ...
end

Root Cause

The C++ code uses pathfinder::INVALID_ID (defined as UINT32_MAX in pathfinder_constants.h), but this constant is never exposed to Lua like the PathStatus and PathSmoothStyle enums are.

Required Changes

1. Expose INVALID_ID to Lua in graph_pathfinder/src/pathfinder.cpp

In the LuaInit() function (around line 1490), add the INVALID_ID constant before the PathStatus enum section:

static void LuaInit(lua_State* L)
{
    int top = lua_gettop(L);

    // Init Lua interface
    luaL_register(L, MODULE_NAME, Module_methods);

    // ----------------------------
    // INVALID_ID constant
    // ----------------------------
    lua_pushnumber(L, (lua_Number)pathfinder::INVALID_ID);
    lua_setfield(L, -2, "INVALID_ID");

    // ----------------------------
    // PathStatus enum
    // ----------------------------
    lua_newtable(L); // PathStatus table
    // ... (existing PathStatus code)

2. Add to Lua annotations in graph_pathfinder/annotations.lua

Add the constant definition after the pathfinder table declaration (around line 10):

---@class pathfinder
local pathfinder = {}

---Invalid ID constant for cells and nodes (UINT32_MAX = 4294967295)
---Used to indicate invalid cell ID when position is not in any navmesh cell
---@type number
pathfinder.INVALID_ID = 4294967295

3. Fix documentation in NAVMESH_API.md

Update the pathfinder.navmesh_cell_at_position() example (around line 306) to use the correct constant:

function validate_spawn_point(self, x, z)
    local cell_id, center_x, center_y = pathfinder.navmesh_cell_at_position(x, z)
    
    if cell_id ~= pathfinder.INVALID_ID then
        print("Position is walkable, in cell", cell_id)
        print("Cell center:", center_x, center_y)
        return true
    else
        print("Position is not walkable (outside navmesh)")
        return false
    end
end

Also update the Returns section to clarify:

**Returns:**
- `cell_id` (number): ID of cell containing position, or `pathfinder.INVALID_ID` (4294967295) if not found
- `center_x` (number): X coordinate of cell center
- `center_y` (number): Y coordinate of cell center

Testing

After these changes, users can properly check for invalid cells:

local cell_id = pathfinder.navmesh_cell_at_position(x, z)

if cell_id == pathfinder.INVALID_ID then
    print("Position is outside navmesh")
else
    print("Position is in cell", cell_id)
end

Files to Modify

1. graph_pathfinder/src/pathfinder.cpp - Add constant exposure in LuaInit()
2. graph_pathfinder/annotations.lua - Add constant annotation
3. NAVMESH_API.md - Fix example code and documentation

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.