NSGo Game

ai

game/ai provides deterministic game AI building blocks stepped cleanly on game.Loop: grid AStar pathfinding, 2D NavMesh navigation with funnel smoothing, steering behaviors, and behavior trees.

import "github.com/nsgo-dev/game/packages/game/ai"

Nothing in ai uses background goroutines or hidden global randomness.

Grid A* pathfinding

AStar searches any Grid or weighted CostGrid (BoolGrid, CostMap, or the adapter GridFunc), reusing its internal buffers across calls:

grid := ai.GridFunc{
	Cols: levelMap.Width,
	Rows: levelMap.Height,
	Walk: func(col, row int) bool {
		return levelMap.FlagsAt(col, row)&tilemap.TileSolid == 0
	},
	Cost: func(col, row int) float64 {
		if isMud(col, row) {
			return 2.5
		}
		return 1
	},
}

astar := ai.NewAStar()
astar.Diagonal = true // NoCornerCutting is true by default

path, cost, ok := astar.Find(grid, ai.Cell{Col: 1, Row: 1}, ai.Cell{Col: 18, Row: 10})
_, _ = path, cost
_ = ok

Use astar.FindInto(dst, grid, start, goal) to reuse a caller-owned []ai.Cell buffer with zero allocations per search. NewBoolGrid and NewCostMap provide flat-slice grids when you do not already have a tilemap.

2D NavMesh with funnel smoothing

For open arenas or non-grid worlds, build a NavMesh from convex 2D polygons. BuildNavMesh normalizes polygon winding, automatically connects adjacent polygons along shared edges (including partial collinear overlaps), and FindPath runs portal-graph A* followed by Simple Stupid Funnel Algorithm string-pulling:

mesh := ai.BuildNavMesh([][]core.Point{
	{{X: 0, Y: 0}, {X: 120, Y: 0}, {X: 120, Y: 80}, {X: 0, Y: 80}},
	{{X: 120, Y: 20}, {X: 240, Y: 20}, {X: 240, Y: 100}, {X: 120, Y: 100}},
})

waypoints, ok := mesh.FindPath(core.Point{X: 16, Y: 16}, core.Point{X: 220, Y: 85})
_ = waypoints
_ = ok

Inspect mesh geometry with Contains(p), FindPolygon(p), NearestPolygon(p), Neighbors(index), Polygon(index), and PolygonCount().

Steering behaviors

Agent integrates smooth 2D steering forces (MaxSpeed, MaxForce, Radius) on fixed steps via Agent.Step(force, dt):

agent := ai.Agent{
	Pos:      core.Point{X: 20, Y: 20},
	MaxSpeed: 120,
	MaxForce: 300,
	Radius:   10,
}
var followState ai.PathFollowState

// Inside game.Loop.Update:
force := ai.Combine(agent.MaxForce,
	ai.WeightedForce{Force: ai.FollowPath(agent, waypoints, &followState, 8, false), Weight: 1.0},
	ai.WeightedForce{Force: ai.Separation(agent, nearbyAgents, 24), Weight: 1.5},
)
agent.Step(force, dt)

Built-in steering functions:

Function Behavior
Seek(a, target) Accelerates toward target at MaxSpeed.
Arrive(a, target, slowRadius) Scales desired speed smoothly down to zero inside slowRadius.
Flee(a, threat, panicRadius) Accelerates away from threat while closer than panicRadius (or always if <= 0).
FollowPath(a, path, &state, radius, loop) Follows waypoints, using Arrive on the final waypoint when loop is false.
Separation(a, neighbors, desiredSep) Pushes away from close neighbors (defaults to a.Radius + neighbor.Radius when <= 0).
Wander(a, &state, radius, dist, jitter, nextRand) Smooth random wandering using your deterministic nextRand() float32 in [0, 1).
Combine(maxForce, forces...) Sums weighted forces and clamps magnitude to maxForce.

Behavior trees

Compose enemy decision logic from Node trees returning StatusSuccess, StatusFailure, or StatusRunning on each Tick(dt):

tree := ai.Selector(
	ai.Guard(playerInRange, ai.Sequence(
		ai.Cooldown(1500*time.Millisecond, ai.Action(attackPlayer)),
		ai.Wait(300*time.Millisecond),
	)),
	ai.Sequence(
		ai.Condition(hasPatrolPath),
		ai.Action(patrolStep),
	),
)

// Inside game.Loop.Update:
tree.Tick(dt)

Available nodes:

  • Composites: Sequence, Selector (preempts and resets lower-priority running branches when a higher-priority branch succeeds or runs), Parallel(policy, ...) (RequireAll or RequireOne).
  • Decorators: Guard(cond, child), Cooldown(d, child), Inverter, Succeeder, Failer, Repeater(count, child), UntilFail.
  • Leaves: Action(fn), Condition(fn), Wait(d).
Edit this page