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:
MoveAndSlideupdates both the returnedMoveResultand the body'sGrounded,OnCeiling,OnLeftWall, andOnRightWallflags, plus per-tileContacts(Col,Row,Flags,NormalX,NormalY). - One-way platforms: tiles marked
TileOneWayblock downward motion only when the body starts at or above the tile's top edge, unlessBody.OneWayDropistrue. - Custom
TileGrid: implementTileSize() (float32, float32),GridSize() (int, int), andTileFlagsAt(col, row int) TileFlagsto plug atilemap.Tilemapor any custom map directly intoMoveAndSlideandWorld.
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).