Struct Sphere3D

A 3D sphere represented by a Center point and a Radius. The canonical Scylla type for sphere-shaped bounds, area-of-effect queries, AI awareness radii, and any "ball that can be placed anywhere in space" use case.

Implements
Inherited Members
Namespace: Scylla.Core.Util.Geom
Assembly: ScyllaCore.dll
Syntax
[Serializable]
public struct Sphere3D : IEquatable<Sphere3D>
Remarks

Unity provides no standalone sphere value type (only the UnityEngine.SphereCollider component), so this struct fills that gap for purely geometric operations that do not require a physics component.

Radius is expected to be non-negative. Behaviour with a negative radius is undefined.

Equality comparisons use Approximately(float, float, float) for each component, so two spheres that differ only by floating-point rounding are considered equal.

When you need a capsule (two spheres connected by a cylinder segment), see Capsule3D. To obtain a conservative bounding box, call ToAABB3D().

Constructors

Sphere3D(Vector3, float)

Initializes a new Sphere3D with the supplied center and radius.

Declaration
public Sphere3D(Vector3 center, float radius)
Parameters
Type Name Description
Vector3 center

The center of the sphere in world (or local) space.
float radius

The radius of the sphere in world units. Should be non-negative.

Fields

Center

Center of the sphere in world (or local) space.

Declaration
[SerializeField]
public Vector3 Center
Field Value
Type Description
Vector3

Empty

A zero-radius sphere centered at the world origin. Useful as a default or "uninitialized" sentinel value.

Declaration
public static readonly Sphere3D Empty
Field Value
Type Description
Sphere3D

Radius

Radius of the sphere in world units. Expected to be non-negative; a negative radius produces undefined results in intersection and containment queries.

Declaration
[SerializeField]
public float Radius
Field Value
Type Description
float

Unit

A sphere with radius 1 centered at the world origin. Useful as a reference shape or base for scaled copies.

Declaration
public static readonly Sphere3D Unit
Field Value
Type Description
Sphere3D

Properties

Diameter

The diameter of the sphere (twice the radius), in world units.

Declaration
public readonly float Diameter { get; }
Property Value
Type Description
float

SurfaceArea

The surface area of the sphere, in square world units. Computed as 4 * pi * r^2.

Declaration
public readonly float SurfaceArea { get; }
Property Value
Type Description
float

Volume

The volume enclosed by the sphere, in cubic world units. Computed as (4/3) * pi * r^3.

Declaration
public readonly float Volume { get; }
Property Value
Type Description
float

Methods

ClosestPoint(Vector3)

Returns the closest point on or inside the sphere to point. If point is already inside the sphere, it is returned unchanged.

Declaration
public readonly Vector3 ClosestPoint(Vector3 point)
Parameters
Type Name Description
Vector3 point

The query point in world space.
Returns
Type Description
Vector3

The point on the sphere's surface nearest to point when outside, or point itself when inside.

Contains(Vector3)

Returns true if point is inside or exactly on the surface of this sphere. Uses squared distance to avoid a square root.

Declaration
public readonly bool Contains(Vector3 point)
Parameters
Type Name Description
Vector3 point

The world-space point to test.
Returns
Type Description
bool

true if the squared distance from point to Center is less than or equal to Radius * Radius; false otherwise.

Distance(Vector3)

Returns the Euclidean distance from point to the sphere's surface. Returns zero if point is inside or on the boundary.

Declaration
public readonly float Distance(Vector3 point)
Parameters
Type Name Description
Vector3 point

The query point in world space.
Returns
Type Description
float

A non-negative distance in world units. Zero indicates the point is inside or touching the sphere.

Encapsulate(Vector3)

Grows this sphere minimally to include point. If the point is already inside the sphere, the sphere is unchanged. This method mutates the sphere in place.

Declaration
public void Encapsulate(Vector3 point)
Parameters
Type Name Description
Vector3 point

The world-space point to include in the sphere.
Remarks

When the point lies outside the sphere, both the center and the radius are adjusted so that the sphere passes through the new point while still containing the original sphere. The new radius is the average of the old radius and the distance to the point, and the center shifts by half the gap distance along the direction to the point.

Equals(Sphere3D)

Returns true if this sphere and other are approximately equal, comparing Center (component-wise) and Radius using Approximately(float, float, float).

Declaration
public readonly bool Equals(Sphere3D other)
Parameters
Type Name Description
Sphere3D other

The sphere to compare against.
Returns
Type Description
bool

true if all four float components are within EPSILON of each other; false otherwise.

Equals(object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
object obj
Returns
Type Description
bool
Overrides

FromPoints(ReadOnlySpan<Vector3>)

Returns a sphere that encloses every point in points. Uses the two-pass Ritter bounding-sphere algorithm: the result is not guaranteed to be minimal but is fast and suitable for typical bounds queries. Returns Empty when the input span is empty.

Declaration
public static Sphere3D FromPoints(ReadOnlySpan<Vector3> points)
Parameters
Type Name Description
ReadOnlySpan<Vector3> points

A read-only span of points to enclose. May be empty, in which case Empty is returned.
Returns
Type Description
Sphere3D

A Sphere3D that contains all supplied points. The sphere may be slightly larger than the true minimum bounding sphere.
Remarks

The Ritter algorithm runs in two passes. The first pass finds two extreme points (the point farthest from an arbitrary seed, then the point farthest from that) to form an initial diameter. The second pass expands the sphere incrementally to encompass any remaining outlier. Time complexity is O(n) with no heap allocation.

For a tighter result at higher cost, consider iterative refinement approaches such as Welzl's algorithm. The Ritter result is typically within a few percent of optimal for uniformly distributed point clouds.

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
int
Overrides

Intersects(in AABB3D)

Returns true if this sphere overlaps the axis-aligned box box. Tests whether the distance from the sphere's center to the closest point on the box is within the sphere's radius.

Declaration
public readonly bool Intersects(in AABB3D box)
Parameters
Type Name Description
AABB3D box

The axis-aligned box to test against.
Returns
Type Description
bool

true if any part of the sphere's volume intersects or touches the box; false otherwise.

Intersects(in Sphere3D)

Returns true if this sphere and other overlap (including boundary contact). The test uses squared distance to avoid a square root.

Declaration
public readonly bool Intersects(in Sphere3D other)
Parameters
Type Name Description
Sphere3D other

The sphere to test against.
Returns
Type Description
bool

true if the squared distance between the centers is less than or equal to (Radius + other.Radius)^2; false if the spheres are separated.

IntersectsRay(Ray, out float)

Tests whether a ray hits this sphere. On a hit, distance receives the parametric distance along the ray to the first intersection point. If the ray origin is inside the sphere, the distance is zero and the method returns true.

Declaration
public readonly bool IntersectsRay(Ray ray, out float distance)
Parameters
Type Name Description
Ray ray

The ray to test. The direction should be normalized for distance to correspond to world-space units.
float distance

When this method returns true, this parameter contains the distance along the ray to the nearest intersection point (zero if the origin is inside the sphere). Undefined when the method returns false.
Returns
Type Description
bool

true if the ray intersects the sphere; false if it misses entirely or points away from the sphere from outside.
Remarks

The implementation uses the standard geometric ray-sphere test: compute the discriminant b*b - c where b is the dot product of the ray direction with the vector from the ray origin to the sphere center, and c is the squared distance from the origin to the center minus the squared radius. A negative discriminant means no intersection. The returned distance is clamped to zero for origins inside the sphere.

ToAABB3D()

Returns the smallest axis-aligned box that fully encloses this sphere. The resulting box has the same center and half-extents of (Radius, Radius, Radius) along all three axes.

Declaration
public readonly AABB3D ToAABB3D()
Returns
Type Description
AABB3D

An AABB3D centered at Center with half-extents equal to Radius on every axis.

ToString()

Returns a human-readable string representation of this sphere in the format Sphere3D[Center=(x,y,z), Radius=r].

Declaration
public override string ToString()
Returns
Type Description
string

A formatted string describing the sphere's center and radius.
Overrides

Operators

operator ==(Sphere3D, Sphere3D)

Approximate equality operator. Delegates to Equals(Sphere3D); two spheres that differ only by floating-point rounding are considered equal.

Declaration
public static bool operator ==(Sphere3D left, Sphere3D right)
Parameters
Type Name Description
Sphere3D left

The left operand.
Sphere3D right

The right operand.
Returns
Type Description
bool

true if the spheres are approximately equal; false otherwise.

operator !=(Sphere3D, Sphere3D)

Approximate inequality operator. Returns the negation of operator ==(Sphere3D, Sphere3D).

Declaration
public static bool operator !=(Sphere3D left, Sphere3D right)
Parameters
Type Name Description
Sphere3D left

The left operand.
Sphere3D right

The right operand.
Returns
Type Description
bool

true if the spheres are not approximately equal; false otherwise.

Implements

See Also