ns-physics

ns-physics is a performant Golang physics engine that uses a dynamic AABB tree for broadphase collision detection and supports various collider types, including boxes, spheres, and meshes. It is designed for use in real-time applications such as games and simulations.

Features

• Dynamic AABB Tree: Efficient broadphase collision detection.
• Collider Types: Support for box, sphere, and mesh colliders.
• Raycasting: Perform raycasts to detect intersections with colliders.
• Overlap Queries: Detect overlapping objects using AABBs.
• Point Containment Queries: Check if a point is contained within any collider.
• Transformable Colliders: Apply transformations to colliders and update their bounds dynamically.
• Benchmarking: Includes benchmarks for performance testing.

Limitations

ns-physics was created purely for server-side raycasting and overlapping usage, not as a real-time physics simulation. ns-physics does not have any physics simulation capabilities. If you decide to add simulation capabilities, please feel free to submit a pull request.

Installation

To use ns-physics, you need to have Go installed. You can install the library by running:

go get github.com/f-feary/ns-physics

Usage

Creating a Scene

import (
	"github.com/go-gl/mathgl/mgl32"
	"github.com/f-feary/ns-physics"
)

func main() {
	scene := physics.Scene{Tree: physics.DynamicAABBTree{}}

	// Add a BoxCollider
	boxNode := physics.NewSceneNode(1)
	boxNode.AddBoxCollider(
		physics.AABB{Min: mgl32.Vec3{-1, -1, -1}, Max: mgl32.Vec3{1, 1, 1}},
		mgl32.Ident4(),
	)
	scene.Tree.Insert(boxNode)

	// Add a SphereCollider
	sphereNode := physics.NewSceneNode(1)
	sphereNode.AddSphereCollider(mgl32.Vec3{5, 0, 0}, 1)
	scene.Tree.Insert(sphereNode)
}

Performing a Raycast

ray := physics.Ray{
	Origin:    mgl32.Vec3{-10, 0, 0},
	Direction: mgl32.Vec3{1, 0, 0},
	MaxLength: 20,
}
result := scene.Raycast(ray, 1)

if result != nil {
	fmt.Printf("Hit node ID: %d at distance: %f\n", result.Node.GetID(), result.Distance)
} else {
	fmt.Println("No hit detected")
}

Overlap Query

aabb := physics.AABB{
	Min: mgl32.Vec3{-2, -2, -2},
	Max: mgl32.Vec3{2, 2, 2},
}
results := scene.OverlapQuery(aabb, 1)

fmt.Printf("Found %d overlapping nodes\n", len(results))

Point Containment Query

point := mgl32.Vec3{0.5, 0.5, 0.5}
results := scene.PointContainmentQuery(point, 1)

fmt.Printf("Found %d nodes containing the point\n", len(results))

Optimizations

ns-physics includes several optimizations to ensure high performance in real-time applications:

• Bounding Volume Hierarchy (BVH): The BVH is used to accelerate collision detection by hierarchically organizing colliders. This reduces the number of intersection tests required, especially for complex meshes or large scenes.
• Dynamic AABB Tree: A dynamic AABB tree is used for broadphase collision detection. It efficiently handles dynamic objects by incrementally updating the tree structure.
• RaycastAny: The RaycastAny method provides a fast way to determine if a ray intersects any object in the scene without guaranteeing the closest hit. This is useful for early exits in scenarios like visibility checks.
• Layer Mask Filtering: Layer masks allow filtering of objects during queries, reducing unnecessary computations by excluding irrelevant objects.
• Transform Caching: Transformed collider bounds are cached to avoid redundant computations during queries.
• Efficient AABB Merging: AABBs are merged efficiently during tree updates and queries to minimize overhead.

These optimizations make ns-physics suitable for large-scale simulations and real-time applications where performance is critical.

Benchmarks

Run the included benchmarks to test the performance of the library:

go test -bench=.

License

This project is licensed under the MIT License. See the LICENSE file for details.