world3d
game/world3d provides 3D world-building primitives built on math3d: heightmap terrain, multi-level 3D navigation meshes, modular 3D mesh GridMaps, procedural scattered foliage with frustum/distance culling, and floating-origin chunk streaming.
import "github.com/nsgo-dev/game/packages/game/world3d"
Heightmap terrain (Heightmap)
Load a grayscale heightmap image (LoadHeightmapGray) or populate Heights directly, then sample bilinear heights and normals, raycast against triangles, and build chunked TerrainMesh geometry:
hm := world3d.LoadHeightmapGray(grayImg, 2.0, 40.0)
y, ok := hm.HeightAt(player.X, player.Z)
normal := hm.NormalAt(player.X, player.Z)
hit, hitOK := hm.Raycast(ray, 500)
// Build a 32x32 cell mesh chunk for GPU upload:
chunkMesh := hm.BuildMesh(0, 0, 32, 32)
_, _, _, _, _ = y, ok, normal, hit, chunkMesh
_ = hitOK
Multi-level 3D NavMesh
Build a 3D NavMesh from convex walkable polygons (ramps, bridges, and stacked floors). BuildNavMesh filters polygons steeper than maxSlopeRad, links shared edges in 3D, and runs portal A* with 3D string-pulling in FindPath:
nav := world3d.BuildNavMesh(walkablePolys, math3d.DegToRad(45))
if path, ok := nav.FindPath(startPos, goalPos); ok {
follow3DWaypoints(path)
}
Use nav.FindPolygon(p) to locate the closest walkable polygon vertically within VerticalTolerance (supporting stacked floors and overpasses).
Modular 3D GridMap
Place reusable 3D mesh tiles on an integer GridCoord{X, Y, Z} lattice with 24 axis-aligned cube orientations (GridOrientationMat4), fast collision box extraction, DDA raycasting, and frustum-culled instanced batches:
lib, err := world3d.LoadMeshLibraryFromGLTF(gltfBytes) // or world3d.NewMeshLibrary()
if err != nil {
return err
}
grid := world3d.NewGridMap(math3d.Vec3{X: 2, Y: 2, Z: 2}, lib)
floorDef, _ := lib.ByName("stone_floor")
grid.FillBox(world3d.GridCoord{X: 0, Y: 0, Z: 0}, world3d.GridCoord{X: 15, Y: 0, Z: 15}, floorDef.ID, 0)
batches = grid.BuildInstances(&frustum, batches[:0])
colliders := grid.CollisionBoxesIn(playerAABB)
hit, ok := grid.Raycast(ray, 100)
_, _, _, _ = batches, colliders, hit, ok
Procedural foliage culling (FoliageField)
Deterministically scatter grass, rocks, or trees across a Heightmap constrained by slope, height, and an optional DensityMap, then collect frustum- and distance-culled instances scaled by a QualityProfile:
field := world3d.Scatter(hm, world3d.FoliageLayer{
Name: "grass",
MeshID: grassMeshID,
MaterialID: grassMatID,
Density: 1.5,
MinScale: 0.8,
MaxScale: 1.3,
AlignToNormal: 0.6,
MaxSlopeDeg: 35,
BaseMaxDistance: 80,
Seed: 42,
}, hm.Bounds())
quality := world3d.DefaultQualityProfile(world3d.QualityHigh)
visible = field.CollectVisible(camPos, frustum, quality, visible[:0])
Each returned FoliageInstance provides its world Transform and a smooth distance Fade factor in [0, 1].
Floating-origin chunk streaming
Prevent float32 jitter far from the world origin with FloatingOrigin (WorldPos64 in float64) and load/unload surrounding world chunks asynchronously with ChunkStreamer[T]:
origin := world3d.NewFloatingOrigin(512) // rebase when player exceeds 512m from local origin
streamer := world3d.NewChunkStreamer(world3d.ChunkStreamerConfig[*ChunkData]{
ChunkSize: 64,
LoadRadius: 3,
UnloadRadius: 5,
MaxIntegrationsPerFrame: 2,
Workers: 2,
Loader: loadChunkAsync,
OnLoad: attachChunk,
OnUnload: releaseChunk,
})
defer streamer.Close()
// Each frame:
if rebased, shift := origin.Update(playerLocalPos); rebased {
rebaseSceneObjects(shift) // shift Mat4 transforms with world3d.RebaseMat4(m, shift)
}
streamer.Update(origin.LocalToWorld(playerLocalPos))