### Fabric Dependency Setup (Gradle)

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Configure your Gradle build for Fabric to include the Sable Companion Maven repository and add the Fabric-specific dependency, which bundles the companion into your mod JAR.

```groovy
// build.gradle (Fabric)
repositories {
    exclusiveContent {
        forRepository {
            maven { url = "https://maven.ryanhcode.dev/releases" }
        }
        filter {
            includeGroup("dev.ryanhcode.sable-companion")
        }
    }
}

dependencies {
    // include: bundles companion inside your Fabric mod JAR
    include(modApi("dev.ryanhcode.sable-companion:sable-companion-fabric:${project.sable_companion_version}"))
}
```

--------------------------------

### NeoForge Dependency Setup (Gradle)

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Configure your Gradle build to include the Sable Companion Maven repository and add the common dependency, ensuring it's bundled into your mod JAR. The version range ensures compatibility with Sable.

```groovy
// build.gradle
repositories {
    exclusiveContent {
        forRepository {
            maven { url = "https://maven.ryanhcode.dev/releases" }
        }
        filter {
            includeGroup("dev.ryanhcode.sable-companion")
        }
    }
}

dependencies {
    // JiJ: bundles companion into your mod, version range ensures Sable can replace it
    jarJar(api("dev.ryanhcode.sable-companion:sable-companion-common:[${project.sable_companion_version},)")) {
        version {
            prefer(project.sable_companion_version) // e.g. "1.6.0"
        }
    }
}
```

--------------------------------

### Add Sable Companion Fabric to Fabric Build

Source: https://github.com/ryanhcode/sable-companion/blob/main/README.md

Configure your build.gradle for Fabric projects to include the Sable Companion Fabric module. This requires the correct repository setup.

```groovy
repositories {
    exclusiveContent {
        forRepository {
            maven { url = "https://maven.ryanhcode.dev/releases" }
        }
        filter {
            includeGroup("dev.ryanhcode.sable-companion")
        }
    }
}

dependencies {
    include(modApi("dev.ryanhcode.sable-companion:sable-companion-fabric:${project.sable_companion_version}"))
}
```

--------------------------------

### Manipulate Bounding Boxes with BoundingBox3dc

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Illustrates how to get dimensions, check for containment and intersection, expand, move, and transform bounding boxes using `BoundingBox3dc`. Includes conversion to Mojang AABB format.

```java
SubLevelAccess sub = SableCompanion.INSTANCE.getContaining(level, pos);
BoundingBox3dc bb = sub.boundingBox();

// --- Dimensions ---
System.out.println("Width : " + bb.width());  // maxX - minX + 1
System.out.println("Height: " + bb.height()); // maxY - minY + 1
System.out.println("Length: " + bb.length()); // maxZ - minZ + 1
System.out.println("Volume: " + bb.volume());
Vector3d center = bb.center(); // midpoint

// --- Containment / intersection ---
Vector3d point = new Vector3d(12345.5, 65.0, -98765.5);
boolean inside = bb.contains(point);

AABB mojangBox = new AABB(-5, 60, -5, 5, 80, 5);
boolean overlaps = bb.intersects(mojangBox);

// --- Expand / move (destination pattern — does not mutate source) ---
BoundingBox3d expanded = new BoundingBox3d();
bb.expand(1.0, expanded); // 1-block outset on all sides

BoundingBox3d moved = new BoundingBox3d();
bb.move(10.0, 0.0, 0.0, moved); // shift +10 on X

// --- Transform by sub-level pose (local AABB → global AABB) ---
BoundingBox3d globalBB = new BoundingBox3d();
bb.transform(sub.logicalPose(), globalBB);

// --- Inverse transform (global AABB → local AABB) ---
BoundingBox3d localBB = new BoundingBox3d();
globalBB.transformInverse(sub.logicalPose(), localBB);

// --- Chunk-section range for iteration ---
BoundingBox3i chunkBounds = bb.chunkBoundsFrom();

// --- Convert to Mojang AABB ---
AABB aabb = bb.toMojang();
```

--------------------------------

### Get Velocity of a Point Inside a Sub-Level

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Retrieves the velocity of a sub-level at a given world position. Use this to impart momentum to projectiles. Returns Vec3.ZERO if Sable is absent. Option A auto-detects the sub-level and overwrites the position vector. Option B is more efficient if the SubLevelAccess is already known.

```java
Level level = /* ... */;
Vector3d pos = new Vector3d(entity.getX(), entity.getY(), entity.getZ());

// Option A: auto-detect sub-level from position (mutating)
SableCompanion.INSTANCE.getVelocity(level, pos); // pos is overwritten with velocity
Vec3 velocity = new Vec3(pos.x, pos.y, pos.z);
```

```java
// Option B: supply the known SubLevelAccess (more efficient if already known)
SubLevelAccess subLevel = SableCompanion.INSTANCE.getContaining(level, entity);
if (subLevel != null) {
    Vector3d dest = new Vector3d();
    SableCompanion.INSTANCE.getVelocity(level, subLevel,
            new Vector3d(entity.getX(), entity.getY(), entity.getZ()), dest);
    // Add sub-level velocity to a projectile's motion
    entity.setDeltaMovement(
            entity.getDeltaMovement().add(dest.x, dest.y, dest.z));
}
```

--------------------------------

### Get Containing Sub-Level Access

Source: https://github.com/ryanhcode/sable-companion/blob/main/README.md

Find the loaded sub-level that contains a given position within a level. Returns null if no sub-level contains the position.

```java
Level level = ...;

// To find the loaded sub-level containing a given position in its plot, if present:
SubLevelAccess subLevelAccess = SableCompanion.INSTANCE.getContaining(level, pos);

// To check if a given position is contained in the plot grid:
boolean isInPlotGrid = SableCompanion.INSTANCE.isInPlotGrid(level, pos);
```

--------------------------------

### SableCompanion.INSTANCE - Singleton Access

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Provides access to the global singleton instance of SableCompanion, loaded via ServiceLoader. This is the primary way to interact with the Sable Companion API. The reference is stable for the lifetime of the JVM.

```APIDOC
## SableCompanion.INSTANCE

### Description
Obtain the global singleton instance of `SableCompanion`. This instance is loaded via Java's `ServiceLoader` mechanism. A default implementation is provided, which Sable replaces at runtime with a higher-priority implementation if installed.

### Usage
```java
// Obtaining the singleton — never construct directly
SableCompanion api = SableCompanion.INSTANCE;
// Returns the highest-priority registered SableCompanion implementation.
// Safe to store as a field; the reference is stable for the lifetime of the JVM.
```
```

--------------------------------

### Transform Positions with Pose3dc

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Demonstrates transforming local positions to global space and vice-versa using `Pose3dc`. Also shows normal transformation and interpolation for smooth rendering.

```java
SubLevelAccess sub = SableCompanion.INSTANCE.getContaining(level, pos);
if (sub == null) return;

Pose3dc pose = sub.logicalPose();

// --- Transform a LOCAL position to GLOBAL space ---
Vec3 localPos = new Vec3(5.0, 1.0, 3.0); // local to sub-level
Vec3 globalPos = pose.transformPosition(localPos);

// JOML mutable variant (avoids allocation)
Vector3d mutablePos = new Vector3d(5.0, 1.0, 3.0);
pose.transformPosition(mutablePos); // mutates in place

// --- Transform a GLOBAL position to LOCAL space ---
Vec3 backToLocal = pose.transformPositionInverse(globalPos);

// --- Transform normals ---
Vec3 localNormal = new Vec3(0, 1, 0); // up in local space
Vec3 globalNormal = pose.transformNormal(localNormal);

// --- Lerp between last and current pose for smooth rendering ---
Pose3dc last = sub.lastPose();
Pose3d interpolated = new Pose3d();
last.lerp(pose, partialTick, interpolated);

// --- Bake into a Matrix4d for use with JOML/rendering pipelines ---
Matrix4d matrix = pose.bakeIntoMatrix(new Matrix4d());

// --- Tolerance check (e.g., skip update if pose hasn't moved much) ---
boolean moved = !last.withinTolerance((Pose3d) pose, 0.001, 0.0001);
```

--------------------------------

### Accessing SableCompanion Singleton

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Obtain the global singleton instance of SableCompanion. This is the primary way to interact with the API. Do not construct it directly; it's loaded via ServiceLoader.

```java
// Obtaining the singleton — never construct directly
SableCompanion api = SableCompanion.INSTANCE;
// Returns the highest-priority registered SableCompanion implementation.
// Safe to store as a field; the reference is stable for the lifetime of the JVM.
```

--------------------------------

### Add Sable Companion Common to NeoForge Build

Source: https://github.com/ryanhcode/sable-companion/blob/main/README.md

Include this configuration in your build.gradle for NeoForge projects to add the Sable Companion common library. Ensure the repository is correctly configured.

```groovy
repositories {
    exclusiveContent {
        forRepository {
            maven { url = "https://maven.ryanhcode.dev/releases" }
        }
        filter {
            includeGroup("dev.ryanhcode.sable-companion")
        }
    }
}

dependencies {
    jarJar(api("dev.ryanhcode.sable-companion:sable-companion-common:[${project.sable_companion_version},)")) {
        version {
            prefer(project.sable_companion_version)
        }
    }
}
```

--------------------------------

### Add Sable Companion Common to Common Build

Source: https://github.com/ryanhcode/sable-companion/blob/main/README.md

Use this Gradle configuration to add the Sable Companion common library to your project. It ensures the correct Maven repository is used.

```groovy
repositories {
    exclusiveContent {
        forRepository {
            maven { url = "https://maven.ryanhcode.dev/releases" }
        }
        filter {
            includeGroup("dev.ryanhcode.sable-companion")
        }
    }
}

dependencies {
    api("dev.ryanhcode.sable-companion:sable-companion-common:${project.sable_companion_version}")
}
```

--------------------------------

### Sub-Level-Aware Entity Position Utilities

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Compute interpolated eye and feet positions of an entity, accounting for sub-level movement for smooth rendering. Use these instead of Entity#getEyePosition(float) when the entity may be on a moving sub-level.

```java
Entity entity = /* ... */;
float partialTick = /* render partial tick */;

// Eye position smoothed with partial-tick and sub-level motion
Vec3 eyePos = SableCompanion.INSTANCE.getEyePositionInterpolated(entity, partialTick);

// Feet position at a given distance below the entity (e.g., for shadow rendering)
Vector3d feetPos = SableCompanion.INSTANCE.getFeetPos(entity, /* distanceDown= */ 0.0f);
```

```java
// Feet position with a custom orientation quaternion (for rotated entities)
Quaterniondc orientation = /* entity orientation */;
Vector3d feetPosOriented = SableCompanion.INSTANCE.getFeetPos(entity, 0.0f, orientation);
```

--------------------------------

### Block Lookup Across Sub-Level Boundaries

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Checks a position in the world for a non-null (or `true`) result from a converter function, transparently searching across sub-level coordinate frames. Priority order: `World→World`, `Sub-level→World`, `World→Sub-level`. Useful for block interaction (e.g., chute outputs, cable connections) that must work whether the block is in global space or a sub-level.

```APIDOC
## `runIncludingSubLevels` / `findIncludingSubLevels` — Block Lookup Across Sub-Level Boundaries

Checks a position in the world for a non-null (or `true`) result from a converter function, transparently searching across sub-level coordinate frames. Priority order: `World→World`, `Sub-level→World`, `World→Sub-level`. Useful for block interaction (e.g., chute outputs, cable connections) that must work whether the block is in global space or a sub-level.

```java
Level level = /* ... */;
Vec3 origin = /* position of the interacting block */;
SubLevelAccess currentSubLevel = SableCompanion.INSTANCE.getContaining(level, origin);

// runIncludingSubLevels: find the first BlockState that is air, searching across boundaries
BlockState result = SableCompanion.INSTANCE.runIncludingSubLevels(
        level,
        origin,               // origin position
        true,                 // check the origin chunk itself
        currentSubLevel,      // assumed sub-level for origin (may be null)
        (subLevel, blockPos) -> {
            BlockState state = level.getBlockState(blockPos);
            return state.isAir() ? state : null; // return non-null to "match"
        }
);

if (result != null) {
    System.out.println("Found air block across sub-level boundary.");
}

// findIncludingSubLevels: boolean variant
boolean found = SableCompanion.INSTANCE.findIncludingSubLevels(
        level,
        origin,
        true,
        currentSubLevel,
        (subLevel, blockPos) -> level.getBlockState(blockPos).is(Blocks.IRON_BLOCK)
);
```
```

--------------------------------

### Sub-Level-Aware Entity Position Utilities

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Compute the interpolated eye and feet positions of an entity, taking sub-level movement into account for smooth rendering. Use these instead of `Entity#getEyePosition(float)` when the entity may be on a moving sub-level.

```APIDOC
## `getEyePositionInterpolated` / `getFeetPos` — Sub-Level-Aware Entity Position Utilities (since 1.5.0)

Compute the interpolated eye and feet positions of an entity, taking sub-level movement into account for smooth rendering. Use these instead of `Entity#getEyePosition(float)` when the entity may be on a moving sub-level.

```java
Entity entity = /* ... */;
float partialTick = /* render partial tick */;

// Eye position smoothed with partial-tick and sub-level motion
Vec3 eyePos = SableCompanion.INSTANCE.getEyePositionInterpolated(entity, partialTick);

// Feet position at a given distance below the entity (e.g., for shadow rendering)
Vector3d feetPos = SableCompanion.INSTANCE.getFeetPos(entity, /* distanceDown= */ 0.0f);

// Feet position with a custom orientation quaternion (for rotated entities)
Quaterniondc orientation = /* entity orientation */;
Vector3d feetPosOriented = SableCompanion.INSTANCE.getFeetPos(entity, 0.0f, orientation);
```
```

--------------------------------

### Block Lookup Across Sub-Level Boundaries

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Checks a position in the world for a non-null result from a converter function, transparently searching across sub-level coordinate frames. Priority order: World→World, Sub-level→World, World→Sub-level. Useful for block interaction that must work whether the block is in global space or a sub-level.

```java
Level level = /* ... */;
Vec3 origin = /* position of the interacting block */;
SubLevelAccess currentSubLevel = SableCompanion.INSTANCE.getContaining(level, origin);

// runIncludingSubLevels: find the first BlockState that is air, searching across boundaries
BlockState result = SableCompanion.INSTANCE.runIncludingSubLevels(
        level,
        origin,               // origin position
        true,                 // check the origin chunk itself
        currentSubLevel,      // assumed sub-level for origin (may be null)
        (subLevel, blockPos) -> {
            BlockState state = level.getBlockState(blockPos);
            return state.isAir() ? state : null; // return non-null to "match"
        }
);

if (result != null) {
    System.out.println("Found air block across sub-level boundary.");
}
```

```java
// findIncludingSubLevels: boolean variant
boolean found = SableCompanion.INSTANCE.findIncludingSubLevels(
        level,
        origin,
        true,
        currentSubLevel,
        (subLevel, blockPos) -> level.getBlockState(blockPos).is(Blocks.IRON_BLOCK)
);
```

--------------------------------

### getAllIntersecting

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Returns all `SubLevelAccess` objects whose bounding boxes overlap with the provided `BoundingBox3dc`. This is efficient for broad-phase queries like determining entities within an explosion radius or ability area of effect.

```APIDOC
## `getAllIntersecting` — Query All Sub-Levels Touching a Bounding Box

Returns every `SubLevelAccess` whose bounding box overlaps the given `BoundingBox3dc`. Useful for broad-phase queries (e.g., explosion radius, ability AoE).

```java
// Build a 10-block query box centred on an entity
Vec3 center = entity.position();
BoundingBox3d query = new BoundingBox3d(
        center.x - 5, center.y - 5, center.z - 5,
        center.x + 5, center.y + 5, center.z + 5);

// NOTE: do NOT mutate `query` while iterating
Iterable<? extends SubLevelAccess> hits = 
        SableCompanion.INSTANCE.getAllIntersecting(entity.level(), query);

for (SubLevelAccess hit : hits) {
    System.out.println("Intersecting sub-level: " + hit.getUniqueId());
    BoundingBox3dc bb = hit.boundingBox();
    System.out.printf("  Bounds: [%.1f,%.1f,%.1f] -> [%.1f,%.1f,%.1f]%n",
            bb.minX(), bb.minY(), bb.minZ(),
            bb.maxX(), bb.maxY(), bb.maxZ());
}
```
```

--------------------------------

### Query All Sub-Levels Intersecting a Bounding Box

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Use this to find all sub-levels that overlap with a given 3D bounding box. Useful for broad-phase queries like explosion radii or ability area-of-effect.

```java
Vec3 center = entity.position();
BoundingBox3d query = new BoundingBox3d(
        center.x - 5, center.y - 5, center.z - 5,
        center.x + 5, center.y + 5, center.z + 5);

// NOTE: do NOT mutate `query` while iterating
Iterable<? extends SubLevelAccess> hits =
        SableCompanion.INSTANCE.getAllIntersecting(entity.level(), query);

for (SubLevelAccess hit : hits) {
    System.out.println("Intersecting sub-level: " + hit.getUniqueId());
    BoundingBox3dc bb = hit.boundingBox();
    System.out.printf("  Bounds: [%.1f,%.1f,%.1f] -> [%.1f,%.1f,%.1f]%n",
            bb.minX(), bb.minY(), bb.minZ(),
            bb.maxX(), bb.maxY(), bb.maxZ());
}
```

--------------------------------

### projectOutOfSubLevel

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Transforms a position from a sub-level's local coordinate space into the equivalent global world position. If the position is not within any sub-level, it is returned unchanged.

```APIDOC
## `projectOutOfSubLevel` — Transform a Position to Global Space

Converts a position that may be inside a sub-level's local (extreme-value) coordinate space into the equivalent global world position. If the position is not in any sub-level, it is returned unchanged.

```java
Level level = /* ... */;

// --- JOML Vector3d (mutating, preferred) ---
Vector3d pos = new Vector3d(12345.5, 64.0, -98765.5);
SableCompanion.INSTANCE.projectOutOfSubLevel(level, pos); // mutates pos in place
System.out.println("Global position: " + pos);

// --- JOML Vector3dc → Vector3d (non-mutating src) ---
Vector3dc src = new Vector3d(12345.5, 64.0, -98765.5);
Vector3d dest = new Vector3d();
SableCompanion.INSTANCE.projectOutOfSubLevel(level, src, dest);

// --- Minecraft Position / Vec3 ---
Vec3 mcPos = new Vec3(12345.5, 64.0, -98765.5);
Vec3 globalPos = SableCompanion.INSTANCE.projectOutOfSubLevel(level, (Position) mcPos);
System.out.println("Global (Mojang Vec3): " + globalPos);
```
```

--------------------------------

### Locating Sub-Level at a Position

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Use `getContaining` to find the `SubLevelAccess` for a given position. This method has overloads for various position types including `BlockPos`, `Entity`, and client-side access.

```java
Level level = /* server or client level */;
BlockPos blockPos = new BlockPos(12345, 64, -98765); // position inside a plot grid

// By BlockPos (delegates via SectionPos bit-shift)
SubLevelAccess sub = SableCompanion.INSTANCE.getContaining(level, blockPos);

if (sub != null) {
    System.out.println("Sub-level UUID : " + sub.getUniqueId());
    System.out.println("Sub-level name : " + sub.getName()); // nullable
    // Pose of the sub-level this tick
    Pose3dc pose = sub.logicalPose();
    System.out.println("Position       : " + pose.position());
    System.out.println("Orientation    : " + pose.orientation());
} else {
    System.out.println("No sub-level at this position (or Sable not installed).");
}

// By Entity (convenience overload)
Entity entity = /* some entity */;
SubLevelAccess entitySub = SableCompanion.INSTANCE.getContaining(entity);

// Client-side variant — uses the client level automatically
ClientSubLevelAccess clientSub = SableCompanion.INSTANCE.getContainingClient(blockPos);
if (clientSub != null) {
    // renderPose() uses the current frame's partial-tick
    Pose3dc renderPose = clientSub.renderPose();
    // renderPose(float) accepts an explicit partial-tick
    Pose3dc smoothPose = clientSub.renderPose(0.5f);
}
```

--------------------------------

### Entity Sub-Level Tracking

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Queries which sub-level an entity is currently "tracking" (moving with). Entities track a sub-level when they are within its plot, and their network position/logout point is expressed in that sub-level's local frame.

```APIDOC
## `getTrackingSubLevel` / `getLastTrackingSubLevel` / `getTrackingOrVehicleSubLevel` / `getVehicleSubLevel` — Entity Sub-Level Tracking (since 1.5.0)

Queries which sub-level an entity is currently "tracking" (moving with). Entities track a sub-level when they are within its plot, and their network position/logout point is expressed in that sub-level's local frame.

```java
Entity entity = /* ... */;

// Current tracking sub-level (this tick)
SubLevelAccess tracking = SableCompanion.INSTANCE.getTrackingSubLevel(entity);

// Previous tick's tracking sub-level (useful for interpolation)
SubLevelAccess lastTracking = SableCompanion.INSTANCE.getLastTrackingSubLevel(entity);

// Returns tracking sub-level OR the vehicle's sub-level (for passengers)
SubLevelAccess effective = SableCompanion.INSTANCE.getTrackingOrVehicleSubLevel(entity);

// Only the vehicle's sub-level (null if entity is not a passenger)
SubLevelAccess vehicleSub = SableCompanion.INSTANCE.getVehicleSubLevel(entity);

if (tracking != null) {
    System.out.println("Entity is tracking sub-level: " + tracking.getUniqueId());
}
```
```

--------------------------------

### Transform a Position to Global Space

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Converts a position that might be in a sub-level's local coordinate space to its equivalent global world position. If the position is not in a sub-level, it remains unchanged. Overloads are provided for JOML Vector3d (mutating), JOML Vector3dc (non-mutating source), and Minecraft's Position/Vec3 types.

```java
Level level = /* ... */;

// --- JOML Vector3d (mutating, preferred) ---
Vector3d pos = new Vector3d(12345.5, 64.0, -98765.5);
SableCompanion.INSTANCE.projectOutOfSubLevel(level, pos); // mutates pos in place
System.out.println("Global position: " + pos);

// --- JOML Vector3dc → Vector3d (non-mutating src) ---
Vector3dc src = new Vector3d(12345.5, 64.0, -98765.5);
Vector3d dest = new Vector3d();
SableCompanion.INSTANCE.projectOutOfSubLevel(level, src, dest);

// --- Minecraft Position / Vec3 ---
Vec3 mcPos = new Vec3(12345.5, 64.0, -98765.5);
Vec3 globalPos = SableCompanion.INSTANCE.projectOutOfSubLevel(level, (Position) mcPos);
System.out.println("Global (Mojang Vec3): " + globalPos);
```

--------------------------------

### Entity Sub-Level Tracking

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Queries which sub-level an entity is currently tracking. Entities track a sub-level when they are within its plot and their network position is expressed in that sub-level's local frame. Useful for interpolation and determining effective tracking.

```java
Entity entity = /* ... */;

// Current tracking sub-level (this tick)
SubLevelAccess tracking = SableCompanion.INSTANCE.getTrackingSubLevel(entity);

// Previous tick's tracking sub-level (useful for interpolation)
SubLevelAccess lastTracking = SableCompanion.INSTANCE.getLastTrackingSubLevel(entity);

// Returns tracking sub-level OR the vehicle's sub-level (for passengers)
SubLevelAccess effective = SableCompanion.INSTANCE.getTrackingOrVehicleSubLevel(entity);

// Only the vehicle's sub-level (null if entity is not a passenger)
SubLevelAccess vehicleSub = SableCompanion.INSTANCE.getVehicleSubLevel(entity);

if (tracking != null) {
    System.out.println("Entity is tracking sub-level: " + tracking.getUniqueId());
}
```

--------------------------------

### Transform Position Out of Sub-Level

Source: https://github.com/ryanhcode/sable-companion/blob/main/README.md

Transforms a position from a sub-level's local space into global space using its logical pose. A utility function is provided for a compact transformation.

```java
// Example: Transform a position out of a sub-level into "global" space
Vec3 position = ...;
SubLevelAccess subLevelAccess = SableCompanion.INSTANCE.getContaining(level, pos);

if (subLevelAccess != null) {
    Pose3dc pose = subLevelAccess.logicalPose();

    // Transform the position to global space
    position = pose.transformPosition(position);
}

// Companion has a compact utility for the above that projects a position out of a sub-level (if it is one)
position = SableCompanion.INSTANCE.projectOutOfSubLevel(level, position);
```

--------------------------------

### getVelocity

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Returns the velocity (m/tick) of the sub-level at a given world position. Useful for imparting momentum to projectiles launched from a moving sub-level. Returns Vec3.ZERO when Sable is absent.

```APIDOC
## `getVelocity` — Global Velocity of a Point Inside a Sub-Level

Returns the velocity (m/tick) of the sub-level at a given world position. Useful for imparting momentum to projectiles launched from a moving sub-level. Returns `Vec3.ZERO` when Sable is absent.

```java
Level level = /* ... */;
Vector3d pos = new Vector3d(entity.getX(), entity.getY(), entity.getZ());

// Option A: auto-detect sub-level from position (mutating)
SableCompanion.INSTANCE.getVelocity(level, pos); // pos is overwritten with velocity
Vec3 velocity = new Vec3(pos.x, pos.y, pos.z);

// Option B: supply the known SubLevelAccess (more efficient if already known)
SubLevelAccess subLevel = SableCompanion.INSTANCE.getContaining(level, entity);
if (subLevel != null) {
    Vector3d dest = new Vector3d();
    SableCompanion.INSTANCE.getVelocity(level, subLevel,
            new Vector3d(entity.getX(), entity.getY(), entity.getZ()), dest);
    // Add sub-level velocity to a projectile's motion
    entity.setDeltaMovement(
            entity.getDeltaMovement().add(dest.x, dest.y, dest.z));
}
```
```

--------------------------------

### Calculate Global Distance Squared

Source: https://github.com/ryanhcode/sable-companion/blob/main/README.md

Computes the squared distance between two points in global space, correctly handling cases where one or both points are within a sub-level. Avoids incorrect extreme values.

```java
Level level = ...;
Vec3 a = ...;
Vec3 b = ...;

// INCORRECT - distance will be extreme if one or both of the positions are in the plot
double incorrectDistanceSquared = a.distanceToSqr(b);

// CORRECT - distance will be computed in global space
double distanceSquared = SableCompanion.INSTANCE.distanceSquaredWithSubLevels(level, a, b);
```

--------------------------------

### rectilinearDistanceWithSubLevels

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Calculates the rectilinear (Chebyshev) distance between two global-space points after applying sub-level projection. This is useful for block-grid range checks.

```APIDOC
## `rectilinearDistanceWithSubLevels` — Sub-Level-Aware Chebyshev Distance

Returns the rectilinear (Chebyshev / max-component) distance between two global-space points, with sub-level projection applied. Added in 1.6.0. Useful for block-grid range checks.

```java
Level level = /* ... */;
Vector3dc a = new Vector3d(0, 64, 0);
Vector3dc b = new Vector3d(10, 70, 5);

double chebyshev = SableCompanion.INSTANCE.rectilinearDistanceWithSubLevels(level, a, b);
// max(|10-0|, |70-64|, |5-0|) = max(10, 6, 5) = 10
System.out.println("Chebyshev distance: " + chebyshev); // 10.0
```
```

--------------------------------

### Sub-Level-Aware Chebyshev Distance Calculation

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Calculates the rectilinear (Chebyshev / max-component) distance between two global-space points, applying sub-level projection. This is useful for block-grid range checks. Added in version 1.6.0.

```java
Level level = /* ... */;
Vector3dc a = new Vector3d(0, 64, 0);
Vector3dc b = new Vector3d(10, 70, 5);

double chebyshev = SableCompanion.INSTANCE.rectilinearDistanceWithSubLevels(level, a, b);
// max(|10-0|, |70-64|, |5-0|) = max(10, 6, 5) = 10
System.out.println("Chebyshev distance: " + chebyshev); // 10.0
```

--------------------------------

### getContaining - Locate Sub-Level

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Determines which sub-level's plot grid contains a given position. It returns a `SubLevelAccess` object for the containing sub-level, or `null` if no sub-level is present at that location. Overloads support various position types including `ChunkPos`, `BlockPos`, `SectionPos`, JOML `Vector3dc`, Minecraft `Position`, raw chunk coordinates, and entities.

```APIDOC
## getContaining

### Description
Locates the `SubLevelAccess` for the sub-level whose plot grid contains the specified coordinates. Returns `null` if no sub-level is found at the given position or if Sable is not installed.

### Method
`SableCompanion.INSTANCE.getContaining(Level level, BlockPos blockPos)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (Overloads)
- `ChunkPos`
- `BlockPos` (`Vec3i`)
- `SectionPos`
- JOML `Vector3dc`
- Minecraft `Position`
- Raw chunk XZ integers
- `Entity` or `BlockEntity`

### Request Example
```java
Level level = /* server or client level */;
BlockPos blockPos = new BlockPos(12345, 64, -98765); // position inside a plot grid

// By BlockPos (delegates via SectionPos bit-shift)
SubLevelAccess sub = SableCompanion.INSTANCE.getContaining(level, blockPos);

if (sub != null) {
    System.out.println("Sub-level UUID : " + sub.getUniqueId());
    System.out.println("Sub-level name : " + sub.getName()); // nullable
    // Pose of the sub-level this tick
    Pose3dc pose = sub.logicalPose();
    System.out.println("Position       : " + pose.position());
    System.out.println("Orientation    : " + pose.orientation());
} else {
    System.out.println("No sub-level at this position (or Sable not installed).");
}

// By Entity (convenience overload)
Entity entity = /* some entity */;
SubLevelAccess entitySub = SableCompanion.INSTANCE.getContaining(entity);
```

### Response
#### Success Response (SubLevelAccess or null)
- `SubLevelAccess` (object) - An object providing read-only data about the loaded sub-level, including its unique ID, name (nullable), and logical pose.
- `null` - If no sub-level contains the given position.

#### Response Example
```java
// Example when a sub-level is found:
{
  "uniqueId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "My Awesome Sub-Level",
  "logicalPose": {
    "position": [10.5, 20.0, -5.2],
    "orientation": [0.0, 0.0, 0.0, 1.0] // Quaternion
  }
}

// Example when no sub-level is found:
null
```
```

```APIDOC
## getContainingClient

### Description
Client-side variant of `getContaining` that automatically uses the client `Level`. It returns `ClientSubLevelAccess` which extends `SubLevelAccess` with client-specific rendering information.

### Method
`SableCompanion.INSTANCE.getContainingClient(BlockPos blockPos)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (Overloads)
- `ChunkPos`
- `BlockPos` (`Vec3i`)
- `SectionPos`
- JOML `Vector3dc`
- Minecraft `Position`
- Raw chunk XZ integers
- `Entity` or `BlockEntity`

### Request Example
```java
ClientSubLevelAccess clientSub = SableCompanion.INSTANCE.getContainingClient(blockPos);
if (clientSub != null) {
    // renderPose() uses the current frame's partial-tick
    Pose3dc renderPose = clientSub.renderPose();
    // renderPose(float) accepts an explicit partial-tick
    Pose3dc smoothPose = clientSub.renderPose(0.5f);
}
```

### Response
#### Success Response (ClientSubLevelAccess or null)
- `ClientSubLevelAccess` (object) - An object providing read-only data about the loaded sub-level, including client-side rendering poses.
- `null` - If no sub-level contains the given position.

#### Response Example
```java
// Example when a sub-level is found:
{
  "uniqueId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "My Awesome Sub-Level",
  "logicalPose": {
    "position": [10.5, 20.0, -5.2],
    "orientation": [0.0, 0.0, 0.0, 1.0] // Quaternion
  },
  "renderPose": {
    "position": [10.51, 20.00, -5.21],
    "orientation": [0.01, 0.00, 0.00, 0.99] // Quaternion
  }
}

// Example when no sub-level is found:
null
```
```

--------------------------------

### Sub-Level-Aware Squared Distance Calculation

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Computes the squared Euclidean distance between two points, projecting them out of any sub-level they occupy before measurement. Always use this method instead of `Vec3.distanceToSqr` when points might be within a plot. Overloads are available for JOML Vector3d and raw coordinate values.

```java
Level level = /* ... */;

Vec3 playerPos = player.position();     // could be in the main world
Vec3 turretPos = turret.getBlockPos().getCenter(); // could be inside a sub-level

// WRONG — will produce extreme values if either point is in a plot
double bad = playerPos.distanceToSqr(turretPos);

// CORRECT
double distSq = SableCompanion.INSTANCE.distanceSquaredWithSubLevels(
        level,
        new Vector3d(playerPos.x, playerPos.y, playerPos.z),
        new Vector3d(turretPos.x, turretPos.y, turretPos.z));

if (distSq < 64.0 * 64.0) {
    System.out.println("Turret is within 64 blocks of the player (global).");
}

// Raw coordinate overload (avoids allocation)
double distSq2 = SableCompanion.INSTANCE.distanceSquaredWithSubLevels(
        level,
        playerPos.x, playerPos.y, playerPos.z,
        turretPos.x, turretPos.y, turretPos.z);
```

--------------------------------

### distanceSquaredWithSubLevels

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Computes the squared Euclidean distance between two points, ensuring both points are projected out of any sub-level they occupy before the distance is measured. This method should be used instead of `Vec3.distanceToSqr` when either point might be within a sub-level.

```APIDOC
## `distanceSquaredWithSubLevels` — Sub-Level-Aware Squared Distance

Computes the squared Euclidean distance between two points, projecting each out of any sub-level they occupy before measuring. Always use this instead of `Vec3.distanceToSqr` when either point may be inside a plot.

```java
Level level = /* ... */;

Vec3 playerPos = player.position();     // could be in the main world
Vec3 turretPos = turret.getBlockPos().getCenter(); // could be inside a sub-level

// WRONG — will produce extreme values if either point is in a plot
double bad = playerPos.distanceToSqr(turretPos);

// CORRECT
double distSq = SableCompanion.INSTANCE.distanceSquaredWithSubLevels(
        level,
        new Vector3d(playerPos.x, playerPos.y, playerPos.z),
        new Vector3d(turretPos.x, turretPos.y, turretPos.z));

if (distSq < 64.0 * 64.0) {
    System.out.println("Turret is within 64 blocks of the player (global).");
}

// Raw coordinate overload (avoids allocation)
double distSq2 = SableCompanion.INSTANCE.distanceSquaredWithSubLevels(
        level,
        playerPos.x, playerPos.y, playerPos.z,
        turretPos.x, turretPos.y, turretPos.z);
```
```

--------------------------------

### isInPlotGrid

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Checks if a given position or chunk falls within any sub-level plot grid. This method supports various position types including `BlockPos`, `ChunkPos`, `SectionPos`, `Vec3i`, `Position`, `Vector3dc`, `Entity`, and `BlockEntity`.

```APIDOC
## `isInPlotGrid` — Check Whether a Position Is Inside the Plot Grid

Returns `true` if the given position/chunk falls within any sub-level plot grid. Works for `BlockPos`, `ChunkPos`, `SectionPos`, `Vec3i`, `Position`, `Vector3dc`, `Entity`, and `BlockEntity`.

```java
Level level = /* ... */;
BlockPos pos = new BlockPos(12345, 64, -98765);

if (SableCompanion.INSTANCE.isInPlotGrid(level, pos)) {
    // Position is inside a sub-level plot — raw coordinates are extreme values
    System.out.println("Inside plot grid");
} else {
    System.out.println("Regular world space");
}

// Entity convenience
Entity entity = /* ... */;
boolean entityInPlot = SableCompanion.INSTANCE.isInPlotGrid(entity);
```
```

--------------------------------

### Check if a Position is Inside the Plot Grid

Source: https://context7.com/ryanhcode/sable-companion/llms.txt

Determines if a given position or chunk falls within any sub-level plot grid. This method accepts various position types including BlockPos, ChunkPos, SectionPos, Vec3i, Position, Vector3dc, Entity, and BlockEntity.

```java
Level level = /* ... */;
BlockPos pos = new BlockPos(12345, 64, -98765);

if (SableCompanion.INSTANCE.isInPlotGrid(level, pos)) {
    // Position is inside a sub-level plot — raw coordinates are extreme values
    System.out.println("Inside plot grid");
} else {
    System.out.println("Regular world space");
}

// Entity convenience
Entity entity = /* ... */;
boolean entityInPlot = SableCompanion.INSTANCE.isInPlotGrid(entity);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.