NSGo Game

physics

game/physics provides 2D collision shapes (Box and Circle), exact overlap contacts, anti-tunneling tile resolution with MoveAndSlide, and deterministic spatial queries and raycasts on World.

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

Coordinates follow NSGo's screen space: X increases to the right and Y increases downward.

Shapes and overlap tests

Box{X, Y, W, H} (top-left origin) and Circle{X, Y, R} (centered) unify under Shape (BoxShape(b), CircleShape(c)). Test pairs directly with TestBoxBox, TestCircleCircle, TestBoxCircle, TestCircleBox, or TestShapes:

playerBox := physics.Box{X: 32, Y: 48, W: 14, H: 20}
coin := physics.Circle{X: 44, Y: 54, R: 6}

if c := physics.TestBoxCircle(playerBox, coin); c.Hit {
	// Normal points from B (coin) toward A (playerBox);
	// translating A by (NormalX*Depth, NormalY*Depth) separates them.
	_ = c
}

Shapes that only touch along an edge or corner with zero penetration report Hit == false. Empty shapes (W <= 0, H <= 0, or R <= 0) never overlap anything.

MoveAndSlide and TileGrid

MoveAndSlide advances a *Body by (VX*dt, VY*dt) against any TileGrid on each fixed game.Loop step, resolving X before Y, zeroing velocity along blocked axes, and subdividing large displacements so fast bodies cannot tunnel through single-tile walls or platforms:

grid := physics.NewGrid(40, 20, 16, 16)
grid.FillRect(0, 18, 40, 2, physics.TileSolid)
grid.FillRect(10, 14, 6, 1, physics.TileOneWay)

player := physics.NewBoxBody(32, 200, 12, 16)
player.Tag = "player"

// Inside game.Loop.Update:
player.VY += 900 * float32(dt.Seconds()) // gravity
player.OneWayDrop = actions.Pressed("down") && actions.JustPressed("jump")

res := physics.MoveAndSlide(player, grid, dt)
if res.Grounded && actions.JustPressed("jump") {
	player.VY = -320
}
  • Contact flags: MoveAndSlide updates both the returned MoveResult and the body's Grounded, OnCeiling, OnLeftWall, and OnRightWall flags, plus per-tile Contacts (Col, Row, Flags, NormalX, NormalY).
  • One-way platforms: tiles marked TileOneWay block downward motion only when the body starts at or above the tile's top edge, unless Body.OneWayDrop is true.
  • Custom TileGrid: implement TileSize() (float32, float32), GridSize() (int, int), and TileFlagsAt(col, row int) TileFlags to plug a tilemap.Tilemap or any custom map directly into MoveAndSlide and World.

World queries and raycasts

World groups movable Bodies and an optional Tiles (TileGrid) for deterministic point, overlap, and raycast queries:

world := &physics.World{Tiles: grid}
world.Add(player, enemy, trigger)

// Point query (bodies in World.Bodies order)
clicked := world.QueryPoint(mouseWorld.X, mouseWorld.Y)

// Shape overlap against bodies and solid tiles
hitbox := physics.BoxShape(physics.Box{X: attackX, Y: attackY, W: 24, H: 16})
hits := world.QueryOverlapMask(hitbox, physics.QueryBodies|physics.QueryTiles)
for _, h := range hits {
	if h.Body != nil && h.Body.Tag == "enemy" {
		damageEnemy(h.Body)
	}
}

// Raycast for line of sight or hitscan weapons
if hit, ok := world.RaycastFirst(gunPos, targetPos, physics.QueryAll); ok {
	spawnImpactSpark(hit.Point, hit.NormalX, hit.NormalY)
}

QueryMask flags (zero value means QueryAll):

Mask Targets included
QueryBodies All bodies in World.Bodies (returned in slice order).
QueryTiles Solid tiles (TileSolid) in World.Tiles.
QueryOneWay One-way tiles (TileOneWay); raycasts hit them only when entering the top edge moving downward.
QueryAll QueryBodies | QueryTiles | QueryOneWay.

World.Raycast returns all hits along the segment sorted by ascending normalized distance T in [0, 1] (bodies before tiles on ties), while RaycastFirst returns the closest hit. Remove bodies cleanly with world.Remove(b).

Edit this page