walkableHeight scale appears incorrect when used with Three.js units

[niko-dellic]

Hi @isaac-mason,

When using recast-navigation-js with Three.js, it seems that the walkableHeight parameter is not scaled as expected. First, the default value is set to 2 (although type definition says the limit is >= 3):

However, in practice, setting it to 2 does not restrict agents from walking under ceilings lower than 2 meters:

In the screenshot above, the grid is generated underneath the entirety of the ramp above, even when the ceiling height is less than 2 meters.
To achieve the expected behavior (e.g., preventing agents from walking under obstacles lower than 2 meters), I have to set walkableHeight to around 40. This suggests the value is being interpreted as 1/20th of the intended unit scale.

In reality, setting a 40 meter clearance would look like this:

Steps to Reproduce:
1. Set up a Three.js scene using recast-navigation-js.
2. Add a ceiling or overhang at a height of 1.8 meters.
3. Build the navmesh with walkableHeight: 2.
4. Observe that agents can still walk under the obstacle.
5. Change walkableHeight to 20.
6. Observe that agents are now correctly blocked by the 1.8m ceiling.

Expected Behavior:

A walkableHeight value of 2 should block areas with less than 2 meters of clearance.

Actual Behavior:

A much higher value (approximately 20x, e.g., 40) is required to achieve the expected behavior.

Environment:
• recast-navigation-js version: 0.39.0
• Three.js version: 0.173.0
• Browser: Tested on Chrome, Safari, Arc
• Platform: MacOS, Windows

Additional Context:

I suspect this might be related to a mismatch in assumed world scale or units. If the navigation mesh builder is working in decimeters or some internal units, it would be helpful to make that more explicit in the documentation or normalize it to match common engine unit conventions (like meters in Three.js).

[isaac-mason]

Hi @niko-dellic, the issue you are likely experiencing is that the walkableHeight config is in voxel units, and not world units. You'll need to do walkableHeight * recastConfig.ch (cell height).

It's important to note that a core step in recast's navmesh generation logic is voxelization of input triangles - so many navmesh generation config options actually refer to voxel units ("vx"). See: https://recast-navigation-js.isaacmason.com/?path=/story/debug-three-debug-drawer--heightfield-walkable

There is for sure some documentation cleanup to be done! Hope this helps in the meantime!

[niko-dellic]

Hi @isaac-mason,

Thank you for clarifying, makes sense! Would this also apply to things such as walkableClimb? Say if I want the max walkableClimb to be 0.3 meters, would I need to do 0.3 * recastConfig.ch?

[niko-dellic]

@isaac-mason perhaps I'm not perfectly clear. In the example above, my cell height was 0.16. If I apply the formula:

walkableHeight * recastConfig.ch

it would be:

2 * 0.16 = 0.32

This appears to have the opposite effect since I am trying to get closer to 40 in this case. I could do:

walkableHeight * (recastConfig.ch * 100)

which would then be:

2 * 16 = 32

but this leads me to believe I am failing to grasp the correct conversion between real world units and voxels scale. Any docs or further explanation would be greatly appreciated!

Thanks again for such an amazing library, I've been following it for the past 8 months and am excited to see what else you come up with.

Cheers,
Niko

[isaac-mason]

Hi @niko-dellic , sorry, my earlier message on the conversion was misleading.
Can you try doing the same as in this example? See: https://github.com/isaac-mason/recast-navigation-js/blob/main/packages%2Frecast-navigation%2F.storybook%2Fstories%2Fcrowd%2Fsingle-agent.stories.tsx#L60

e.g.

const walkableHeightWorld = 1
const ch = 0.2
const walkableHeightVoxels = Math.ceil(walkableHeightWorld / ch)

const config = {
  ch,
  walkableHeight: walkableHeightVoxels
}

I will do a pass over the docs to make sure all units are specified clearly. Walkable climb and walkable radius for example are also in voxel units yes - walkable climb uses cell height and walkable radius uses cell size.

[niko-dellic]

H @isaac-mason ,

Thanks for clarifying, I think the difference in the first example and the second is division rather than multiplication. This seems to work well:

Thanks again for all of your help. Cheers!

[isaac-mason]

Glad to see your issue resolved 🙂

I'll convert this to a discussion so it can remain visible for others having similar issues, and will track documentation improvements with: #457