Heightfield

Unity dev project for the Heightfield package — a Burst-compatible compact heightfield store and sampler for fast ground-query workloads.

High-performance terrain height storage using dual-pool quantized data structures.

New here? See Getting Started for a guided walkthrough.

Contents

• Packages/com.heightfield.delta/ — the package itself. Install this in your own project.
• Assets/Benchmark/ — play-mode benchmark harness comparing heightfield sampling against Physics.Raycast.

Features

• Dual-pool quantization: Heights stored as decimetres — small ranges (±12.7m) in sbyte, larger ranges (±3276.7m) in int16
• Bilinear sampling: Smooth height interpolation
• PhysX rasterization: Convert scene geometry into heightfield data using batched raycasts
• Burst-compatible: All core types are unmanaged structs with [BurstCompile] support
• NativeContainer-based: Thread-safe readonly views for use in jobs

Installing the package

Add to your Unity project's Packages/manifest.json:

"com.heightfield.delta": "https://github.com/rjohnson06/Heightfield.git?path=Packages/com.heightfield.delta"

The ?path= fragment tells UPM to pull only the package subfolder — the rest of this dev project is ignored.

Alternatively, in Unity's Package Manager, click + → Add package from git URL and paste the URL above.

Requirements

• Unity 6000.0+
• Burst 1.8+
• Collections 2.1+
• Mathematics 1.3+

Developed against Unity 6000.4.2f1.

Quick Start

using Heightfield;
using Unity.Collections;
using Unity.Mathematics;

// Grid config is fixed at construction — every cell is cellStride × cellStride.
var store = new HeightFieldStore(
    cellStride: 8, sampleSize: 1.0, gridCellWorldSize: 100.0,
    expectedChunks: 64, expectedSamples16: 100000, expectedSamples8: 100000,
    Allocator.Persistent);

// Add height data for a cell (heights.Length must equal cellStride * cellStride)
long key = HeightfieldCells.PackCellId(0, 0);
var heights = new NativeArray<double>(64, Allocator.Temp);
// ... fill heights ...
store.Add(key, heights, start: double3.zero);

// Sample heights — grid config comes from the store.
var ro = store.AsReadonly();
ro.TrySampleHeightBilinear_WorldPos(worldPos, out double height);

store.Dispose();

Rasterize Scene Geometry

// Rasterize GameObjects with colliders into a heightfield
var config = HeightfieldRasterizer.Config.Default;
var result = HeightfieldRasterizer.RasterizeGameObjects(selectedObjects, config, ref store);

Editor Tool

Open Tools → Heightfield → Rasterizer for an interactive editor window that lets you:

1. Select GameObjects with colliders
2. Configure grid and raycast parameters
3. Rasterize into a heightfield
4. Visualize results in the Scene view

Architecture

Cell Grid

The world is divided into a regular grid of cells. Each cell is identified by a long key packed from integer (cellX, cellZ) coordinates:

key = (cellX << 32) | (uint)cellZ

Quantization

Heights are stored as decimetres (0.1m precision) relative to a per-cell reference height. The dual-pool design automatically selects the optimal storage:

• sbyte pool: ±12.7m range, 1 byte per sample
• int16 pool: ±3276.7m range, 2 bytes per sample

Memory Management

Remove(key) compacts the pool inline by shifting the tail — no separate reclaim step is needed.

Running the benchmark

1. Open the project in Unity 6000.0+.
2. Open Assets/Benchmark/Benchmark.unity.
3. Press Play. The on-screen overlay reports ms/frame, µs/agent, and fps.
4. Use the overlay buttons to flip between:
   • Source: Heightfield vs. Physics.Raycast.
   • Interpolation: Bilinear, Fast (late-decode bilinear), or Nearest. Heightfield only.
   • Slice cache: per-agent cached HeightSlice lookup. Heightfield only.

Every mode switch logs a cumulative summary to the console (duration, frames, ms/frame, µs/agent with min/max) for side-by-side comparison.

Key inspector fields on HeightfieldBenchmarkJobHarness

• agentCount — how many agents to spawn.
• propCount, propMinSize, propMaxSize — scatter random BoxColliders to stress PhysX broadphase (also gets baked into the heightfield).
• interpolation, useSliceCache — sampler variants; see on-screen buttons.
• spawnSeed, propSeed — deterministic layouts for repeatable A/B runs.

Tests

Tests are in Packages/com.heightfield.delta/Tests/Editor/ (pure data tests) and Packages/com.heightfield.delta/Tests/Runtime/ (PhysX raycast tests). Run them via Unity's Test Runner window.

Project layout

Assets/
  Benchmark/                             # harness + scene
Packages/
  com.heightfield.delta/                 # the package (shipped via ?path= URL)
  manifest.json
ProjectSettings/

Notes

The package identifier (com.heightfield.delta / "Heightfield Delta Store") is legacy from when the package shipped a per-cell delta-layer store. That functionality has been removed; the identifier rename is pending.