Volume Octree Module

Technical Docs · Spatial Module

VolumeOctree

3D 공간 분할 & 데이터 관리 시스템

3D 공간을 재귀적으로 8분할하여 대규모 월드 데이터를 효율적으로 저장·조회하는 옥트리 모듈. NativeList<Node> 기반 구조와 Morton Key 인코딩을 결합하여 청크 단위 고속 탐색을 지원합니다.

Generic T (unmanaged) NativeList 기반 Morton Key 인코딩 Chunk 통합 관리

maxDepth

X

Y

Z

CORE COMPONENTS

주요 구성 요소

🌐

VolumeOctree<T>

단일 옥트리 구조

제네릭 데이터 T(unmanaged)를 노드에 저장하는 단일 옥트리. 내부는 NativeList<Node> 기반이며, 루트에서 maxDepth까지 동적으로 분할됩니다.

Set (point, value) 포인트 위치에 값 저장 · 자식 노드 동적 생성

TryGet (point, out value) 존재하는 경로만 탐색 · 리프 노드 값 반환

🗂️

VolumeOctreeChunks<T>

청크 통합 관리자

월드 공간을 origin · chunkSize 기준으로 청크로 나누어 여러 옥트리를 통합 관리합니다. Morton Key 인코딩으로 3D 인덱스를 단일 정수 키로 변환해 고속 검색을 지원합니다.

Morton int3 → ulong key 3차원 좌표를 비트 인터리브 정수 키로 변환

Chunk world pos → int3 월드 좌표 기반 청크 키 생성 · 지연 초기화

⚙️

VolumeOctreeHost

Unity 컴포넌트

옥트리의 원점·청크 크기·최대 깊이를 인스펙터에서 설정하고, 씬 뷰 에디터 인터페이스를 제공하는 Unity MonoBehaviour 래퍼입니다.

float3origin

floatchunkSize

intmaxDepth

HOW IT WORKS

상세 동작 원리

01 공간 분할 (Set)

루트 바운드 포함 여부 확인

↓

깊이만큼 8방향 자식 노드 탐색

↓

필요한 자식 노드만 동적 생성

↓

리프 노드에 T 값 저장

02 효율적 조회 (TryGet)

루트 노드에서 탐색 시작

↓

존재하는 자식 경로만 따라 하강

↓

경로 부재 시 즉시 false 반환

↓

리프 도달 시 값 반환 · true

03 Morton Key 청크

World Pos
(x, y, z)

→

int3
Chunk Key

↓

Morton
Encode

→

ulong
Hash Key

지연 초기화: 청크가 존재하지 않으면 접근 시점에 생성하여 메모리를 절약합니다.

EDITOR FEATURES

에디터 기능

🛠️ OctreeTool Scene View

씬 뷰에서 핸들(Handle)을 드래그하여 옥트리의 원점(origin)을 직관적으로 편집할 수 있는 씬 뷰 툴입니다. 인스펙터 수치 입력 없이 공간 상에서 직접 배치 위치를 조정합니다.

Handle Drag Origin 편집 Gizmo 연동

👁️ OctreeView Overlay

씬 뷰 오버레이를 통해 현재 옥트리 상태를 실시간으로 시각화합니다. 청크 경계·루트 바운드·현재 설정값을 와이어프레임으로 표시하여 공간 분할 상태를 즉시 확인할 수 있습니다.

Chunks 시각화 Roots 표시 실시간 설정값

DEPTH VISUALIZATION

분할 깊이 구조

루트(depth 0)부터 maxDepth까지 각 레벨에서 최대 8개의 자식 노드로 분기됩니다.

depth 0

Root

depth 1

0

1

2

3

4

5

6

7

depth 2

0

1

2

3

4

5

6

7

maxDepth

Leaf
T value

Leaf
T value

Leaf
T value

💡 자식 노드는 필요 시에만 동적 생성 — 빈 공간은 메모리를 점유하지 않습니다.

⚡ Morton 인코딩으로 캐시 친화적인 공간 지역성(Spatial Locality)을 확보합니다.