https://github.com/mrdav30/swiftcollections
A high-performance, memory-efficient library of collections designed for game development, simulations, and other performance-critical applications.
https://github.com/mrdav30/swiftcollections
collections csharp data-structures dotnet game-development memory-management object-pooling observables performance unity
Last synced: 14 days ago
JSON representation
A high-performance, memory-efficient library of collections designed for game development, simulations, and other performance-critical applications.
- Host: GitHub
- URL: https://github.com/mrdav30/swiftcollections
- Owner: mrdav30
- License: mit
- Created: 2025-01-02T15:54:54.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-21T04:15:37.000Z (over 1 year ago)
- Last Synced: 2025-04-23T17:13:09.882Z (about 1 year ago)
- Topics: collections, csharp, data-structures, dotnet, game-development, memory-management, object-pooling, observables, performance, unity
- Language: C#
- Homepage:
- Size: 272 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# SwiftCollections
[](https://github.com/mrdav30/SwiftCollections/actions/workflows/build-and-test.yml)
[](https://mrdav30.github.io/SwiftCollections/)
[](https://www.nuget.org/packages/SwiftCollections)
[](https://www.nuget.org/packages/SwiftCollections)
[](https://github.com/mrdav30/SwiftCollections/blob/main/LICENSE)
[](https://github.com/mrdav30/SwiftCollections)
SwiftCollections is a performance-oriented collection library for .NET systems that care about hot-path cost: simulations, games, spatial queries, deterministic runtimes, and allocation-sensitive tooling.
The standard .NET collections are excellent general-purpose defaults. SwiftCollections is for the places where you need more control over storage layout, pooling, dense iteration, externally owned integer IDs, deterministic string hashing, or broad-phase spatial query structures. It is not meant to replace every `List` or `Dictionary` in an application. It is meant to give performance-critical code a sharper set of tools.
## Why Use It
- Low-allocation collection types for repeated simulation and gameplay loops.
- Hash tables, lists, queues, stacks, buckets, packed sets, sparse sets, and sparse maps with APIs designed for predictable hot-path behavior.
- Dense integer-ID membership and value lookup through `SwiftSparseSet` and `SwiftSparseMap`.
- Stable-handle storage through `SwiftBucket` and generation-checked handles through `SwiftGenerationalBucket`.
- Spatial query structures: BVH, spatial hash, and octree implementations over `System.Numerics` volumes, plus fixed-point companions through `SwiftCollections.FixedMathSharp`.
- Optional MemoryPack serialization in standard packages, with lean variants for projects that want the same core APIs without MemoryPack.
- Benchmarks and high coverage are part of the repo workflow, not an afterthought.
## Packages
Choose the package that matches your runtime and serialization needs.
| Package | Use When |
| --- | --- |
| `SwiftCollections` | You want the core collections with MemoryPack support. |
| `SwiftCollections.Lean` | You want the core collections without the MemoryPack dependency. |
| `SwiftCollections.FixedMathSharp` | You need fixed-point BVH, octree, or spatial hash volume wrappers backed by FixedMathSharp. |
| `SwiftCollections.FixedMathSharp.Lean` | You need the fixed-point companion without MemoryPack. |
```bash
dotnet add package SwiftCollections
dotnet add package SwiftCollections.Lean
dotnet add package SwiftCollections.FixedMathSharp
dotnet add package SwiftCollections.FixedMathSharp.Lean
```
The standard and lean variants expose the same core collection APIs. The difference is whether MemoryPack is included. If you are targeting Unity Burst AOT or already have a serializer pipeline, prefer the lean variants.
Unity package support lives in a separate repository: [SwiftCollections-Unity](https://github.com/mrdav30/SwiftCollections-Unity).
## Picking A Container
| Use case | Better fit |
| --- | --- |
| General key/value lookup with arbitrary keys | `SwiftDictionary` |
| General unique values | `SwiftHashSet` |
| Fast list, queue, stack, or sorted-list operations | `SwiftList`, `SwiftQueue`, `SwiftStack`, `SwiftSortedList` |
| Store objects and receive stable integer slots | `SwiftBucket` |
| Store objects and guard against stale handles | `SwiftGenerationalBucket` |
| Track membership for compact externally owned integer IDs | `SwiftSparseSet` |
| Attach values to compact externally owned integer IDs | `SwiftSparseMap` |
| Store densely iterated unique values with hash-backed membership checks | `SwiftPackedSet` |
| Arbitrary, huge, or widely sparse integer IDs | `SwiftHashSet` or `SwiftDictionary` |
| Broad-phase spatial queries | `SwiftBVH`, `SwiftSpatialHash`, `SwiftOctree` |
More detail is available in the [library overview](https://github.com/mrdav30/SwiftCollections/blob/main/docs/OVERVIEW.md).
## Quick Examples
### Sparse Membership For External IDs
```csharp
using SwiftCollections;
var activeBodies = new SwiftSparseSet();
activeBodies.Add(42);
activeBodies.Add(128);
if (activeBodies.Contains(42))
{
activeBodies.Remove(42);
}
foreach (int bodyId in activeBodies)
{
// Dense iteration over active IDs.
}
var sortedBodyIds = new SwiftList(activeBodies.Count);
activeBodies.CopySortedKeysTo(sortedBodyIds);
```
### Sparse Values For External IDs
```csharp
using System.Numerics;
using SwiftCollections;
var positions = new SwiftSparseMap();
positions[128] = new Vector3(10, 0, 4);
if (positions.TryGetValue(128, out Vector3 position))
{
positions[128] = position + new Vector3(1, 0, 0);
}
var sortedPositionIds = new SwiftList(positions.Count);
positions.CopySortedKeysTo(sortedPositionIds);
```
### Scratch List Sorting
```csharp
using SwiftCollections;
var keys = new SwiftList { 12, 4, 8 };
keys.SortInPlace();
// keys: 4, 8, 12
```
### Stable Handles
```csharp
using System;
using SwiftCollections;
var bodies = new SwiftGenerationalBucket();
SwiftHandle handle = bodies.Add("player");
if (bodies.TryGet(handle, out string body))
{
Console.WriteLine(body);
}
bodies.Remove(handle);
```
### Spatial Queries
```csharp
using System.Numerics;
using SwiftCollections;
using SwiftCollections.Query;
var bvh = new SwiftBVH(capacity: 128);
bvh.Insert(
1,
new BoundVolume(
new Vector3(0, 0, 0),
new Vector3(1, 1, 1)));
var results = new SwiftList();
bvh.Query(
new BoundVolume(
new Vector3(-1, -1, -1),
new Vector3(2, 2, 2)),
results);
```
## Serialization And Diagnostics
Most core types expose state-backed serialization support. Standard packages include MemoryPack support; lean packages compile the same public collection surface without taking a MemoryPack dependency. `net8.0` builds use System.Text.Json converter implementations where supported, while older targets use compatibility shims.
Diagnostics are opt-in through `SwiftCollections.Diagnostics`. Disabled diagnostic writes are designed to avoid doing formatting work when the requested level is below the channel minimum, and guard helpers use lazy exception-message formatting for condition-gated throws.
## Development
Build the solution:
```bash
dotnet build SwiftCollections.slnx -c Debug
```
Run the unit tests:
```bash
dotnet test tests/SwiftCollections.Tests/SwiftCollections.Tests.csproj -c Debug --no-build
```
Run coverage with the shared runsettings:
```bash
dotnet test tests/SwiftCollections.Tests/SwiftCollections.Tests.csproj -c Debug --no-build --collect:"XPlat Code Coverage" --settings tests/SwiftCollections.Tests/coverlet.runsettings
```
Run benchmarks:
```bash
dotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- list
dotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- dictionary
dotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- query --list flat
dotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- all --list flat
```
## Compatibility
- Library targets: `netstandard2.1` and `net8.0`
- Test target: `net8.0`
- Benchmark target: `net8`
- CI covers `Release` and `ReleaseLean` on Windows and Linux
## Community And License
Questions and discussion are welcome in the [Discord community](https://discord.gg/mhwK2QFNBA). Bug reports and feature requests should be opened as GitHub issues.
SwiftCollections is licensed under the MIT License. See `LICENSE`, `NOTICE`, and `COPYRIGHT` for license, branding, and authorship details.