### Default Portal Animation (Java)

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Start the default portal animation with a specified duration. The start method takes the initial frame and the total duration in ticks.

```java
DefaultPortalAnimation anim = portal.getDefaultAnimation();
anim.start(0, 100);  // Start animation, 100 ticks duration
```

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

### Storing Chunk Loader References Example

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Demonstrates the correct approach of storing a reference to the ChunkLoader instance for proper addition and removal.

```java
// GOOD: Keep reference to original
ChunkLoader loader = new ChunkLoader(dim, 0, 0, 5);
PortalAPI.addGlobalChunkLoader(server, loader);
// ... later ...
PortalAPI.removeGlobalChunkLoader(server, loader); // Same instance
```

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

### Example: Setting Teleportation Commands

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Demonstrates how to set a list of commands to be executed upon entity teleportation. Ensure commands do not have a leading '/'.

```java
List<String> commands = Arrays.asList(
    "say entity teleported",
    "playsound block.portal.trigger"
);
portal.setCommandsOnTeleported(commands);
```

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

### ChunkPosConsumer Usage Example

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Example of implementing and using the ChunkPosConsumer interface with `foreachChunkPosFromInnerToOuter()`.

```java
ChunkPosConsumer callback = (dim, x, z, dist) -> {
    System.out.println("Processing chunk " + x + "," + z + " at distance " + dist);
};

loader.foreachChunkPosFromInnerToOuter(callback);
```

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

### Creating a Simple Portal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

This example demonstrates how to create a basic portal entity, set its properties like position, size, orientation, and destination, and then spawn it into the world.

```APIDOC
## Creating a Simple Portal

### Description
This example demonstrates how to create a basic portal entity, set its properties like position, size, orientation, and destination, and then spawn it into the world.

### Method
```java
// Create a portal entity
Portal portal = new Portal(Portal.ENTITY_TYPE, serverLevel);

// Set position (center of portal)
portal.setOriginPos(new Vec3(100, 64, 200));

// Set size (width x height in blocks)
portal.setWidth(4.0);
portal.setHeight(5.0);

// Set orientation (facing direction)
Vec3 axisW = new Vec3(1, 0, 0);  // Left-right
Vec3 axisH = new Vec3(0, 1, 0);  // Up-down
portal.setOrientation(axisW, axisH);

// Set destination
portal.setDestinationDimension(Level.NETHER);
portal.setDestination(new Vec3(50, 64, 50));

// Spawn in world
serverLevel.addFreshEntity(portal);
```
```

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

### Add Global Chunk Loader Example

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Demonstrates adding a global chunk loader. Ensure proper cleanup by removing the loader when it's no longer needed.

```java
// BAD: Loader never removed, chunks stay loaded forever
ChunkLoader loader = new ChunkLoader(...);
PortalAPI.addGlobalChunkLoader(server, loader);
```

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

### Default Portal Animation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Start the default portal animation with a specified duration in ticks.

```APIDOC
## Default Animation

Start the default portal animation with a specified duration in ticks.

```java
DefaultPortalAnimation anim = portal.getDefaultAnimation();
anim.start(0, 100);  // Start animation, 100 ticks duration
```
```

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

### Proper Chunk Loader Cleanup Example

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Shows the correct way to add and remove a global chunk loader to prevent memory leaks and ensure chunks are unloaded.

```java
// GOOD: Remove when done
ChunkLoader loader = new ChunkLoader(...);
PortalAPI.addGlobalChunkLoader(server, loader);
// ... later ...
PortalAPI.removeGlobalChunkLoader(server, loader);
```

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

### Mixing Chunk Loader Instance References Example

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Illustrates a common mistake where different instances of ChunkLoader are used for adding and removing, leading to removal failure.

```java
// BAD: Different instance, won't remove
ChunkLoader loader1 = new ChunkLoader(dim, 0, 0, 5);
PortalAPI.addGlobalChunkLoader(server, loader1);
ChunkLoader loader2 = new ChunkLoader(dim, 0, 0, 5);
PortalAPI.removeGlobalChunkLoader(server, loader2); // Won't find it!
```

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

### Set Portal to Half Size

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Example of setting the portal's scaling to 0.5, making teleported entities half their original size.

```java
portal.setScaling(0.5); // Half size
```

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

### Axis-Aligned Portal (Facing Direction)

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

This example demonstrates how to create an axis-aligned portal by defining a region and using helper methods to automatically configure its shape based on a cardinal direction.

```APIDOC
## Axis-Aligned Portal (Facing Direction)

### Description
This example demonstrates how to create an axis-aligned portal by defining a region and using helper methods to automatically configure its shape based on a cardinal direction.

### Method
```java
Portal portal = new Portal(Portal.ENTITY_TYPE, level);

// Define region
AABB region = new AABB(100, 64, 200, 104, 69, 200);

// Auto-configure for cardinal direction
PortalAPI.setPortalOrthodoxShape(portal, Direction.NORTH, region);

PortalAPI.setPortalTransformation(
    portal,
    Level.NETHER,
    new Vec3(50, 64, 50),
    null, 1.0
);

level.addFreshEntity(portal);
```
```

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

### Attaching a RotatingPortalDriver

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Example of how to instantiate and attach a `RotatingPortalDriver` to a portal. This code assumes a `portal` object is already available.

```java
RotatingPortalDriver driver = new RotatingPortalDriver(portal, 2.0, 100);
portal.addThisSideAnimationDriver(driver);
```

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

### Apply 90 Degree Rotation to Portal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Example of setting a 90-degree rotation around the Y axis for a portal's transformation.

```java
// 90 degree rotation around Y axis
DQuaternion rot = DQuaternion.rotationByDegrees(new Vec3(0, 1, 0), 90);
portal.setRotation(rot);
```

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

### Portal Dimensions

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Methods for getting and setting the width, height, and thickness of a portal.

```APIDOC
## getWidth

### Description
Gets the portal width in blocks (horizontal extent along axis W).

### Method
GET

### Endpoint
/portal/width

### Response
#### Success Response (200)
- **width** (double) - The width of the portal.
```

```APIDOC
## setWidth

### Description
Sets the portal width.

### Method
POST

### Endpoint
/portal/width

### Parameters
#### Request Body
- **newWidth** (double) - Required - Width in blocks (e.g., 4.0)

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

```APIDOC
## getHeight

### Description
Gets the portal height in blocks (vertical extent along axis H).

### Method
GET

### Endpoint
/portal/height

### Response
#### Success Response (200)
- **height** (double) - The height of the portal.
```

```APIDOC
## setHeight

### Description
Sets the portal height.

### Method
POST

### Endpoint
/portal/height

### Parameters
#### Request Body
- **newHeight** (double) - Required - Height in blocks

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

```APIDOC
## getThickness

### Description
Gets the portal thickness (visual/collision depth perpendicular to plane).

### Method
GET

### Endpoint
/portal/thickness

### Response
#### Success Response (200)
- **thickness** (double) - The thickness of the portal.
```

```APIDOC
## setThickness

### Description
Sets the portal thickness.

### Method
POST

### Endpoint
/portal/thickness

### Parameters
#### Request Body
- **newThickness** (double) - Required - Thickness in blocks

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

```APIDOC
## setPortalSize

### Description
Sets all three dimensions (width, height, and thickness) in a single call.

### Method
POST

### Endpoint
/portal/size

### Parameters
#### Request Body
- **newWidth** (double) - Required - Width
- **newHeight** (double) - Required - Height
- **newThickness** (double) - Required - Thickness

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

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

### Portal Class State and Shape Management

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-api.md

Methods for getting and setting the current state and shape of the portal.

```java
public PortalState getPortalState()
public void setPortalState(PortalState state)
public PortalShape getPortalShape()
public void setPortalShape(PortalShape shape)
```

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

### Portal Orientation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Methods for getting and setting the orientation axes (W and H) of a portal.

```APIDOC
## getAxisW

### Description
Gets the horizontal orientation axis (normalized). Points in the "width" direction.

### Method
GET

### Endpoint
/portal/axisW

### Response
#### Success Response (200)
- **axisW** (Vec3) - Normalized direction vector representing the horizontal axis.
```

```APIDOC
## setAxisW

### Description
Sets the horizontal axis of the portal.

### Method
POST

### Endpoint
/portal/axisW

### Parameters
#### Request Body
- **axisW** (Vec3) - Required - Normalized direction vector for the horizontal axis.

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

```APIDOC
## getAxisH

### Description
Gets the vertical orientation axis (normalized). Points in the "height" direction.

### Method
GET

### Endpoint
/portal/axisH

### Response
#### Success Response (200)
- **axisH** (Vec3) - Normalized direction vector representing the vertical axis.
```

```APIDOC
## setAxisH

### Description
Sets the vertical axis of the portal.

### Method
POST

### Endpoint
/portal/axisH

### Parameters
#### Request Body
- **axisH** (Vec3) - Required - Normalized direction vector for the vertical axis.

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

```APIDOC
## setOrientation

### Description
Sets both orientation axes (horizontal and vertical) in a single call.

### Method
POST

### Endpoint
/portal/orientation

### Parameters
#### Request Body
- **newAxisW** (Vec3) - Required - The new horizontal axis.
- **newAxisH** (Vec3) - Required - The new vertical axis.

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

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

### Portal Orientation Rotation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Methods for getting and setting the portal's orientation using a quaternion.

```APIDOC
## getOrientationRotation

### Description
Retrieves the portal's orientation as a quaternion, representing the direction it is facing.

### Method
GET

### Endpoint
/portal/orientationRotation

### Response
#### Success Response (200)
- **orientationRotation** (DQuaternion) - The portal's orientation as a quaternion.
```

```APIDOC
## setOrientationRotation

### Description
Sets the portal's orientation using a quaternion.

### Method
POST

### Endpoint
/portal/orientationRotation

### Parameters
#### Request Body
- **quaternion** (DQuaternion) - Required - The new orientation quaternion.

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

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

### Converting Block Coordinates to Chunk Coordinates Example

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Shows the correct method for converting block coordinates to chunk coordinates by dividing by 16 (right shift by 4).

```java
// Block coordinate 100 → Chunk coordinate 6
int blockX = 100;
int chunkX = blockX >> 4; // Divide by 16
new ChunkLoader(dim, chunkX, chunkX >> 4, 5)
```

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

### Set Portal Rotation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Apply a rotation transformation to a portal using `setRotation`. This example shows a 90-degree rotation around the Y axis.

```java
// 90 degree rotation around Y axis (vertical)
DQuaternion rotation = DQuaternion.rotationByDegrees(new Vec3(0, 1, 0), 90);
portal.setRotation(rotation);
```

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

### Using Block Coordinates Instead of Chunk Coordinates Example

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Highlights the error of using block coordinates directly when chunk coordinates are expected for ChunkLoader.

```java
// BAD: Block coordinate (100) ≠ Chunk coordinate
new ChunkLoader(dim, 100, 100, 5) // This is chunk #100, not blocks x=100
```

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

### Forge Mod Initialization for Event Registration

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Use the Forge EventBusSubscriber to register your mod's event listeners during initialization. This example shows how to call the portal listener registration method.

```java
@Mod.EventBusSubscriber(modid = "mymod", bus = Mod.EventBusSubscriber.Bus.FORGE)
public class MyModSetup {
    public static void init(FMLCommonSetupEvent event) {
        MyPortalListener.register();
    }
}
```

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

### Fabric Mod Initializer for Event Registration

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Implement the ModInitializer interface for Fabric mods to register your event listeners. This example shows the basic structure for calling the portal listener registration.

```java
public class MyModInitializer implements ModInitializer {
    @Override
    public void onInitialize() {
        MyPortalListener.register();
    }
}
```

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

### Get Portal Origin Position

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the portal's center point coordinates in its origin dimension. Use this to get the current location of the portal.

```java
public Vec3 getOriginPos()

```

```java
Vec3 pos = portal.getOriginPos();
double x = pos.x, y = pos.y, z = pos.z;

```

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

### foreachChunkPosFromInnerToOuter

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Iterates over chunk positions starting from the center and moving outwards.

```APIDOC
## foreachChunkPosFromInnerToOuter

### Description
Iterates chunks from center outward (useful for prioritized loading).

### Method
```java
public void foreachChunkPosFromInnerToOuter(ChunkPosConsumer func)
```

### Parameters
#### Path Parameters
- **func** (ChunkPosConsumer) - Required - Callback invoked per chunk

### Order
Center (distance 0), then distance 1 ring, distance 2 ring, etc.

### Example
```java
// Load chunks prioritizing those near center
loader.foreachChunkPosFromInnerToOuter((dim, x, z, dist) -> {
    if (dist <= loader.radius / 2) {
        // High priority area
    }
});
```
```

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

### Get and Set Portal State Snapshot

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Obtain an immutable snapshot of the portal's current state, which can be used for animation interpolation or saving/restoring the portal's configuration. The state can be restored later using `setPortalState`.

```java
// Get immutable state (for animation interpolation)
PortalState state = portal.getPortalState();

// Save and restore
PortalState saved = portal.getPortalState();
// ... modify portal ...
portal.setPortalState(saved);  // Restore
```

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

### getDefaultAnimation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Gets the default animation driver for position, size, and transformation animations.

```APIDOC
## getDefaultAnimation

### Description
Gets the default animation driver (for position/size/transformation animations).

### Return type
`DefaultPortalAnimation`
```

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

### Use Portal API Helpers for Configuration

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

This snippet demonstrates using helper functions from the PortalAPI to set a portal's position, orientation, size, and transformation in a more streamlined manner.

```java
Portal portal = new Portal(Portal.ENTITY_TYPE, level);
DQuaternion orientation = DQuaternion.rotationByDegrees(new Vec3(0, 1, 0), 0);
PortalAPI.setPortalPositionOrientationAndSize(
    portal, 
    new Vec3(100, 64, 200),
    orientation,
    4.0, 5.0
);

PortalAPI.setPortalTransformation(
    portal,
    Level.NETHER,
    new Vec3(50, 64, 50),
    null,  // no rotation
    1.0    // no scaling
);

level.addFreshEntity(portal);
```

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

### Get Destination-Side Portal State

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the state of the portal from the destination side.

```java
public UnilateralPortalState getOtherSideState()
```

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

### PortalAPI - Static Entry Point

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/ANALYSIS.md

The PortalAPI provides static utility methods for interacting with the Immersive Portals system. It includes over 25 public methods for portal manipulation, registration, chunk loading, and entity teleportation.

```APIDOC
## PortalAPI

### Description
Static utility methods for portal manipulation, global registration, chunk loading, entity teleportation, block synchronization, dimension conversion, and network utilities.

### Location
`qouteall.imm_ptl.core.api.PortalAPI`

### Methods (Examples)
- Portal manipulation (position, size, orientation, transformation)
- Global portal registration
- Chunk loading (global and per-player)
- Entity teleportation
- Block synchronization
- Dimension conversion
- Network packet utilities
```

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

### Get Portal Shape

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the current shape of the portal. Defaults to rectangular.

```java
public @NotNull PortalShape getPortalShape()
```

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

### Using Portal API Helpers

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

This section shows how to use helper methods from the PortalAPI to simplify setting portal properties such as position, orientation, size, and transformation.

```APIDOC
## Using Portal API Helpers

### Description
This section shows how to use helper methods from the PortalAPI to simplify setting portal properties such as position, orientation, size, and transformation.

### Method
```java
// Set position, orientation, and size together
Portal portal = new Portal(Portal.ENTITY_TYPE, level);
DQuaternion orientation = DQuaternion.rotationByDegrees(new Vec3(0, 1, 0), 0);
PortalAPI.setPortalPositionOrientationAndSize(
    portal, 
    new Vec3(100, 64, 200),
    orientation,
    4.0, 5.0
);

// Set transformation (destination dimension, position, rotation, scale)
PortalAPI.setPortalTransformation(
    portal,
    Level.NETHER,
    new Vec3(50, 64, 50),
    null,  // no rotation
    1.0    // no scaling
);

// Add to world
level.addFreshEntity(portal);
```
```

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

### Get Player Rendering Status

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Checks if the player should be rendered from the destination side of the portal.

```java
public boolean getDoRenderPlayer()
```

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

### Get Portal Discriminator

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the unique UUID for this portal. This value may be null.

```java
public @Nullable UUID getDiscriminator()
```

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

### Accessing IPConfig Settings

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/architecture.md

Demonstrates how to access various configuration settings within the IPConfig class for per-player server-side adjustments. These settings control portal behavior such as gravity changes, rendering distance, and collision detection.

```java
IPConfig.getConfig().portalsChangeGravityByDefault
IPConfig.getConfig().portalRenderingDistance
IPConfig.getConfig().enableCrossPortalCollision
// ... and more
```

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

### Client World Loading Strategy

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/architecture.md

Describes how client-side worlds are loaded for portal rendering, including synchronized chunk tracking.

```text
Single Player World (local save)
    │
    ├─ Overworld (always loaded)
    │
    ├─ Nether (if chunks visible through portal)
    │
    ├─ The End (if chunks visible through portal)
    │
    └─ [Custom dimensions]

All loaded client-side for portal rendering!
Synchronized via ImmPtlChunkTracking.
```

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

### Get Portal Destination World

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the destination dimension for this portal. Returns a Level object.

```java
public Level getDestWorld()
```

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

### Copy Portal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Create an exact copy of an existing portal using `copyPortal`. You can then set its origin position and add it to the world.

```java
Portal copy = PortalAPI.copyPortal(original, Portal.ENTITY_TYPE);
copy.setOriginPos(new Vec3(200, 64, 300));
world.addFreshEntity(copy);
```

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

### Get Portal Origin World

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the dimension containing this portal. Returns a Level object.

```java
public Level getOriginWorld()
```

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

### Create a Simple Portal Entity

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

This snippet shows how to create a portal entity by directly setting its properties like position, size, orientation, and destination before adding it to the world.

```java
Portal portal = new Portal(Portal.ENTITY_TYPE, serverLevel);

portal.setOriginPos(new Vec3(100, 64, 200));

portal.setWidth(4.0);
portal.setHeight(5.0);

Vec3 axisW = new Vec3(1, 0, 0);
Vec3 axisH = new Vec3(0, 1, 0);
portal.setOrientation(axisW, axisH);

portal.setDestinationDimension(Level.NETHER);
portal.setDestination(new Vec3(50, 64, 50));

serverLevel.addFreshEntity(portal);
```

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

### Fire-and-Forget Chunk Loading with Callback

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Shows how to load chunks and execute a callback function once they are loaded.

```APIDOC
## Fire-and-Forget Chunk Loading with Callback

### Description
This pattern allows you to initiate chunk loading and provide a callback function that will be executed automatically once the chunks are confirmed to be loaded. This is useful for operations that need to happen immediately after chunk readiness, assuming the server remains active.

### Usage
```java
new ChunkLoader(Level.NETHER, 0, 0, 10).loadChunksAndDo(server, () -> {
    // Called when chunks are loaded (if server stays running)
});
```
```

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

### Get Portal Destination Position

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the coordinates where entities will exit the portal in the destination dimension.

```java
public Vec3 getDestPos()

```

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

### Get Source-Side Portal State

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the state of the portal from the source side, excluding destination information.

```java
public UnilateralPortalState getThisSideState()
```

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

### Load and Execute

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

This code snippet shows how to load chunks and then execute a specific task once all the required chunks are loaded. This is useful for operations that depend on a certain area being loaded, such as placing blocks or spawning entities.

```APIDOC
## Load and Execute

```java
ChunkLoader loader = new ChunkLoader(Level.NETHER, 0, 0, 5);
loader.loadChunksAndDo(server, () -> {
    // Called when all chunks are loaded
    System.out.println("Chunks ready, doing something...");
    // Place blocks, spawn entities, etc.
});
```
```

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

### Global Chunk Loader

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

This section demonstrates how to create and manage a global chunk loader to keep distant chunks loaded for portal rendering. It shows how to initialize a ChunkLoader, add it globally, check its status, and remove it when no longer needed.

```APIDOC
## Global Chunk Loader

Keep distant chunks loaded for portal rendering.

### Usage

```java
// Load 10-chunk radius around (0, 0) in Nether
ChunkLoader loader = new ChunkLoader(Level.NETHER, 0, 0, 10);

// Add globally
PortalAPI.addGlobalChunkLoader(server, loader);

// Check status
int loaded = loader.getLoadedChunkNum(server);
int total = loader.getChunkNum();
if (loader.isFullyLoaded(server)) {
    System.out.println("All chunks loaded!");
}

// Remove when done
PortalAPI.removeGlobalChunkLoader(server, loader);
```
```

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

### Get Portal Orientation Rotation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the portal's orientation as a DQuaternion, representing its facing direction.

```java
public DQuaternion getOrientationRotation()
```

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

### Portal Entity Creation Flow

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/architecture.md

Describes the steps involved in creating a new portal entity, including initialization of properties and spawning into the world. The CLIENT_PORTAL_SPAWN_EVENT fires after the entity is added.

```plaintext
1. new Portal(entityType, level)
       ↓
2. set properties:
   - position (setOriginPos)
   - size (setWidth, setHeight)
   - orientation (setAxisW, setAxisH)
   - destination (setDestination)
   - dimension (setDestinationDimension)
       ↓
3. spawn: level.addFreshEntity(portal)
       ↓
4. CLIENT_PORTAL_SPAWN_EVENT fires
   SERVER_PORTAL_TICK_SIGNAL starts firing
```

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

### ChunkLoader Constructor Variants

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Provides details on how to instantiate a ChunkLoader object using different constructor methods.

```APIDOC
### Constructor Variants

#### Primary Constructor (Record)

```java
public ChunkLoader(
    ResourceKey<Level> dimension,
    int x,
    int z,
    int radius
)
```

Direct instantiation with all fields.

**Example**:
```java
ChunkLoader loader = new ChunkLoader(
    Level.NETHER,
    0, 0,  // Chunk coordinates (multiply block coords by 16)
    10     // 10-chunk radius = 21×21 chunks total
);
```

#### Constructor from DimensionalChunkPos

```java
public ChunkLoader(DimensionalChunkPos center, int radius)
```

Creates a loader centered at a specific dimensional chunk position.

| Parameter | Type | Description |
|-----------|------|-------------|
| center | DimensionalChunkPos | Center chunk position |
| radius | int | Radius in chunks |

**Example**:
```java
DimensionalChunkPos center = new DimensionalChunkPos(Level.OVERWORLD, 5, 5);
ChunkLoader loader = new ChunkLoader(center, 3);
```
```

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

### Get Portal Destination World Alias

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

An alias for getDestWorld(), retrieving the destination dimension. Returns a Level object.

```java
public Level getDestinationWorld()
```

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

### Create Bidirectional Portals

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Create a forward portal and then use `createReversePortal` to generate its corresponding return portal.

```java
// Forward portal
Portal gate1 = new Portal(Portal.ENTITY_TYPE, overworld);
PortalAPI.setPortalPositionOrientationAndSize(
    gate1, new Vec3(100, 64, 200), 
    DQuaternion.identity(), 4.0, 5.0
);
PortalAPI.setPortalTransformation(
    gate1, Level.NETHER, new Vec3(50, 64, 50), null, 1.0
);
overworld.addFreshEntity(gate1);

// Return portal
Portal gate2 = PortalAPI.createReversePortal(gate1);
nether.addFreshEntity(gate2);
```

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

### specificPlayerId

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Gets or sets the UUID of the specific player that can use the portal. If set to Util.NIL_UUID, no players can use the portal.

```APIDOC
## specificPlayerId

### Description
If set, only this player (or no players if `Util.NIL_UUID`) can use the portal.

### Type
@Nullable UUID

### Usage
```java
// Single-player portal
portal.specificPlayerId = player.getUUID();

// Entity-only portal
portal.specificPlayerId = Util.NIL_UUID;
```
```

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

### Get Point in Plane (Same as getPointInPlane)

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

This method is an alias for `getPointInPlane()` and performs the same conversion from portal-local coordinates to world position.

```java
public Vec3 getPointInPlaneLocal(double xInPlane, double yInPlane)
```

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

### Per-Player Chunk Loaders

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Illustrates how to manage chunk loaders specifically for individual players.

```APIDOC
## Per-Player Chunk Loaders

### Description
This pattern enables the management of chunk loaders that are associated with a specific player. You can add a loader for a player and later remove it. This is useful for scenarios where chunk loading needs to be tailored to a player's current context or needs.

### Usage
```java
ChunkLoader playerLoader = new ChunkLoader(Level.NETHER, 0, 0, 5);
PortalAPI.addChunkLoaderForPlayer(player, playerLoader);

// Later, remove:
PortalAPI.removeChunkLoaderForPlayer(player, playerLoader);
```
```

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

### Get Portal Content Direction

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the direction vector looking through the portal, opposite to the normal and adjusted for rotation.

```java
public Vec3 getContentDirection()
```

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

### Create Mirrored Portal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Create a mirrored portal using `createFlippedPortal`. Mirrored portals reflect rather than teleport.

```java
Mirror mirror = (Mirror) PortalAPI.createFlippedPortal(portal);
world.addFreshEntity(mirror);
// Mirrors reflect instead of teleport
```

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

### Instantiate ChunkLoader with Fields

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Directly create a ChunkLoader instance by providing all its fields: dimension, chunk coordinates (x, z), and radius. The radius defines the extent of loaded chunks around the center.

```java
ChunkLoader loader = new ChunkLoader(
    Level.NETHER,
    0, 0,  // Chunk coordinates (multiply block coords by 16)
    10     // 10-chunk radius = 21×21 chunks total
);
```

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

### Get Portal Thickness

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the portal's thickness, representing its visual or collision depth. This is a read-only property.

```java
public double getThickness()
```

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

### Manual Chunk Loading with Polling

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Demonstrates how to manually add a chunk loader, poll for its completion, and then remove it.

```APIDOC
## Manual Chunk Loading with Polling

### Description
This pattern shows how to add a global chunk loader and then periodically check if the chunks have finished loading. Once loaded, the loader can be removed.

### Usage
```java
ChunkLoader loader = new ChunkLoader(Level.NETHER, 0, 0, 10);
PortalAPI.addGlobalChunkLoader(server, loader);

// Later, poll for loading:
if (loader.isFullyLoaded(server)) {
    // Chunks are ready
    PortalAPI.removeGlobalChunkLoader(server, loader);
}
```
```

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

### Get Portal Height

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the portal's height in blocks along the H axis. This is a read-only property.

```java
public double getHeight()
```

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

### Get Portal Width

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the portal's width in blocks along the W axis. This is a read-only property.

```java
public double getWidth()
```

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

### Create a Permanent Dimension Gateway

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Set up a portal with specific transformations and register it globally to act as a permanent gateway between dimensions.

```java
// Permanent gateway between dimensions
Portal gateway = new Portal(Portal.ENTITY_TYPE, overworld);
PortalAPI.setPortalPositionOrientationAndSize(
    gateway, new Vec3(0, 128, 0),
    DQuaternion.identity(), 4.0, 5.0
);
PortalAPI.setPortalTransformation(
    gateway, Level.NETHER, new Vec3(0, 128, 0), null, 1.0
);

// Register globally so it's always loaded
PortalAPI.addGlobalPortal(overworld, gateway);
```

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

### Client Portal Accept Sync Event

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Fired when the client receives updated portal data from the server. Useful for updating UI or caches.

```java
public static final Event<Consumer<Portal>> CLIENT_PORTAL_ACCEPT_SYNC_EVENT = 
    Helper.createConsumerEvent();
```

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

### Get Portal Destination (Alias)

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

An alias for getDestPos(), this method also retrieves the destination coordinates in the destination dimension.

```java
public Vec3 getDestination()

```

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

### Iterating Chunks for Operations

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Demonstrates how to iterate through the chunks managed by a ChunkLoader to perform operations.

```APIDOC
## Iterating Chunks for Operations

### Description
This pattern shows how to use a `ChunkLoader` to iterate over its managed chunks. For each chunk, you can retrieve its position and distance from the center, allowing you to perform custom operations on them. This is useful for tasks that require processing individual chunks within a loaded area.

### Usage
```java
ChunkLoader loader = new ChunkLoader(Level.OVERWORLD, 100, 100, 3);
loader.foreachChunkPosFromInnerToOuter((dim, x, z, dist) -> {
    ServerLevel level = server.getLevel(dim);
    ChunkPos pos = new ChunkPos(x, z);
    // Do something with this chunk
});
```
```

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

### Get Teleportation Commands

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the list of commands that are executed when an entity teleports through the portal. Returns null if no commands are set.

```java
public @Nullable List<String> getCommandsOnTeleported()
```

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

### Load Chunks and Execute Callback

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Load a specified area of chunks and then execute a callback function once all chunks are loaded. This is ideal for performing actions that depend on specific chunks being available.

```java
ChunkLoader loader = new ChunkLoader(Level.NETHER, 0, 0, 5);
loader.loadChunksAndDo(server, () -> {
    // Called when all chunks are loaded
    System.out.println("Chunks ready, doing something...");
    // Place blocks, spawn entities, etc.
});
```

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

### Get Default Portal Animation Driver

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the default animation driver used for position, size, and transformation animations.

```java
public DefaultPortalAnimation getDefaultAnimation()
```

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

### Fire-and-Forget Chunk Loading with Callback

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Initiate chunk loading and execute a callback function once loading is complete. This is suitable for operations where immediate feedback on loading status is not critical, assuming the server remains active.

```java
new ChunkLoader(Level.NETHER, 0, 0, 10).loadChunksAndDo(server, () -> {
    // Called when chunks are loaded (if server stays running)
});
```

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

### Get Portal Destination Dimension

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the dimension key for the portal's destination. This indicates which world the portal leads to.

```java
public ResourceKey<Level> getDestDim()

```

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

### GlobalPortalStorage

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/types.md

Registry for globally-loaded portals per dimension. Provides methods to get, add, remove, and list global portals.

```APIDOC
## GlobalPortalStorage

### Description
Registry for globally-loaded portals per dimension.

### Methods
- `get(ServerLevel)`: Get storage for dimension
- `addPortal(Portal)`: Register global portal
- `removePortal(Portal)`: Unregister global portal
- `getGlobalPortals()`: List all global portals

### Location
`qouteall.imm_ptl.core.portal.global_portals.GlobalPortalStorage`
```

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

### Camera Transformation for Portals

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/architecture.md

Explains the steps involved in transforming the camera's position, direction, and clipping planes when rendering through a portal.

```plaintext
1. Calculate camera position in destination dimension
   newPos = portal.transformPoint(cameraPos)

2. Apply rotation to camera direction
   newDir = portal.rotation.rotate(cameraDir)

3. Apply scale (no scaling, but scaling factor affects LOD)
   
4. Set up clipping planes
   frontClip = portal.getInnerClipping()
   backClip = computed from portal depth
```

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

### Combined Orientation and Size

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Methods for setting portal orientation and size together.

```APIDOC
## setOrientationAndSize

### Description
Sets the portal's orientation and size in a single operation.

### Method
POST

### Endpoint
/portal/orientationAndSize

### Parameters
#### Request Body
- **axisW** (Vec3) - Required - The horizontal axis vector.
- **axisH** (Vec3) - Required - The vertical axis vector.
- **width** (double) - Required - The new width of the portal.
- **height** (double) - Required - The new height of the portal.

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.
```

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

### Set Portal Position, Orientation, and Size

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-api.md

Use this method to set the portal's world position, orientation, and size dimensions simultaneously. Ensure `portal`, `position`, `orientation`, `width`, and `height` are correctly provided.

```java
public static void setPortalPositionOrientationAndSize(
    Portal portal,
    Vec3 position,
    DQuaternion orientation,
    double width, double height
)
```

```java
Vec3 portalCenter = new Vec3(100, 64, 200);
DQuaternion facing = DQuaternion.rotationByDegrees(new Vec3(0, 1, 0), 0);
PortalAPI.setPortalPositionOrientationAndSize(
    portal, portalCenter, facing, 4.0, 5.0
);
```

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

### Get Approximate Facing Direction

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Determines the cardinal direction closest to the portal's normal vector. Returns a Direction object.

```java
public Direction getApproximateFacingDirection()
```

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

### Define Portal Destination and Transformation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-api.md

Use this method to define where the portal leads, including the destination dimension, position, rotation, and scale. The `rotation` parameter can be null for no rotation.

```java
public static void setPortalTransformation(
    Portal portal,
    ResourceKey<Level> destinationDimension,
    Vec3 destinationPosition,
    @Nullable DQuaternion rotation,
    double scale
)
```

```java
PortalAPI.setPortalTransformation(
    portal,
    Level.NETHER,
    new Vec3(50, 64, 50),
    null,
    1.0
);
```

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

### Get Vertical Orientation Axis (H)

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the normalized vector representing the portal's vertical orientation (height direction).

```java
public Vec3 getAxisH()
```

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

### Instantiate Portal Entity

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Use this constructor to create a portal entity. Typically, this is handled by the entity type factory.

```java
Portal portal = new Portal(Portal.ENTITY_TYPE, level);
```

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

### Get Horizontal Orientation Axis (W)

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the normalized vector representing the portal's horizontal orientation (width direction).

```java
public Vec3 getAxisW()
```

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

### Get Center Chunk Position

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Retrieves the center chunk position of the loader. Used to determine the central point of the loaded area.

```java
DimensionalChunkPos center = loader.getCenter();
System.out.println(center.dimension + " " + center.x + "," + center.z);
```

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

### Reload and Sync Portal to Client

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Forces an immediate resynchronization of portal data to all tracking clients.

```java
public void reloadAndSyncToClient()
```

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

### createFlippedPortal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-api.md

Creates a mirror-image portal with reversed orientation. Useful for seamless bidirectional travel or creating mirror rooms.

```APIDOC
## createFlippedPortal

### Description
Creates a mirror-image portal with reversed orientation. Useful for seamless bidirectional travel or creating mirror rooms.

### Method Signature
```java
public static <T extends Portal> T createFlippedPortal(T portal)
```

### Parameters
#### Path Parameters
- **portal** (T extends Portal) - Required - The original portal

### Return type
- **T** - A new portal with flipped orientation

### Example
```java
Portal flipped = PortalAPI.createFlippedPortal(portal);
```
```

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

### Create Flipped Portal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-api.md

Creates a mirror-image portal with reversed orientation. Useful for seamless bidirectional travel or creating mirror rooms.

```java
public static <T extends Portal> T createFlippedPortal(T portal)
```

```java
Portal flipped = PortalAPI.createFlippedPortal(portal);
```

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

### Conditional Teleportation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Control teleportation based on specific conditions by overriding `imm_ptl_canTeleportThroughPortal` and adding your logic. For example, prevent teleportation if the entity is in water.

```APIDOC
## Conditional Teleportation

Control teleportation based on specific conditions by overriding `imm_ptl_canTeleportThroughPortal` and adding your logic. For example, prevent teleportation if the entity is in water.

```java
@Override
public boolean imm_ptl_canTeleportThroughPortal(Entity portal) {
    // Only teleport if not in liquid
    return !this.isInWater();
}
```
```

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

### Get New Gravity Direction After Teleportation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Computes the new gravity direction for an entity after it has passed through a portal, given the original gravity direction.

```java
public Direction getTeleportedGravityDirection(Direction oldGravityDir)
```

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

### CLIENT_PORTAL_ACCEPT_SYNC_EVENT

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Fired when the client receives updated portal data from the server. Use this to update UI, refresh caches, or play synchronization effects.

```APIDOC
## CLIENT_PORTAL_ACCEPT_SYNC_EVENT

### Description
Fired when the client receives updated portal data from server.

### Listener Signature
```java
public static final Event<Consumer<Portal>> CLIENT_PORTAL_ACCEPT_SYNC_EVENT = Helper.createConsumerEvent();
```

### Use Cases
- Update UI based on portal properties
- Refresh portal-dependent caches
- Play synchronization effects
```

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

### Get Portal Plane Normal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the normalized vector perpendicular to the portal plane, pointing outwards. Computed as axisW × axisH.

```java
public Vec3 getNormal()
```

```java
Vec3 normal = portal.getNormal();
// Check if entity is approaching from correct side
if (entity.position().subtract(portal.getOriginPos()).dot(normal) > 0) {
    // Entity is on the outside
}
```

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

### Client Portal Spawn Event

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Fired when a portal becomes visible on the client. Use for client-side rendering or sound effects.

```java
public static final Event<Consumer<Portal>> CLIENT_PORTAL_SPAWN_EVENT = 
    Helper.createConsumerEvent();
```

```java
ServerPlayNetworking.registerGlobalReceiver(
    PORTAL_SPAWN_CHANNEL,
    (payload, context) -> {
        Portal.CLIENT_PORTAL_SPAWN_EVENT.invoker().accept(portal);
    }
);
```

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

### Get Portal State Snapshot

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves an immutable snapshot of the portal's current state, including position, destination, dimensions, and visual properties.

```java
public @NotNull PortalState getPortalState()
```

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

### CLIENT_PORTAL_SPAWN_EVENT

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Fired when a portal is spawned or becomes visible on the client. Useful for playing sounds, optimizing rendering, or tracking portal instances.

```APIDOC
## CLIENT_PORTAL_SPAWN_EVENT

### Description
Fired when a portal is spawned/becomes visible on the client.

### Listener Signature
```java
public static final Event<Consumer<Portal>> CLIENT_PORTAL_SPAWN_EVENT = Helper.createConsumerEvent();
```

### Use Cases
- Play spawn sound effects
- Initialize client-side portal rendering optimizations
- Track portal instances for special handling
```

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

### Get Nearest Point in Portal

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Finds the closest point on the portal's surface to a given world position. Returns the coordinates of this nearest point.

```java
public Vec3 getNearestPointInPortal(Vec3 pos)
```

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

### Get Full 3D Bounding Box

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Retrieves the complete 3D bounding box of the portal, including its thickness. Use this for accurate collision detection.

```java
public @NotNull AABB getBoundingBox()
```

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

### Portal Rendering Loop

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/architecture.md

Details the client-side render loop for portals, including visibility checks, render target creation, and compositing.

```plaintext
Render Loop (Client)
    │
    ├─ For each loaded portal:
    │  │
    │  ├─ Check visibility (frustum culling)
    │  │
    │  ├─ Create render target (FBO)
    │  │
    │  ├─ Render destination world
    │  │  └─ Apply camera transformation
    │  │     └─ Apply scaling transformation
    │  │     └─ Apply clipping planes
    │  │
    │  └─ Composite into main framebuffer
    │
    └─ If portal in portal:
       └─ Recursive rendering up to max depth
```

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

### Conditional Entity Teleportation

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/entity-extensions-and-events.md

Allow or deny teleportation based on the entity's current state by implementing ImmPtlEntityExtension. This example prevents bound entities from teleporting.

```java
public class SummonedBeast extends LivingEntity implements ImmPtlEntityExtension {
    private boolean isBound = true;
    
    @Override
    public boolean imm_ptl_canTeleportThroughPortal(Entity portal) {
        // Bound entities cannot teleport
        return !isBound;
    }
}
```

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

### Conditional Teleportation (Java)

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/quick-start.md

Implement conditional teleportation logic by checking specific conditions within the imm_ptl_canTeleportThroughPortal method. This example prevents teleportation if the entity is in water.

```java
@Override
public boolean imm_ptl_canTeleportThroughPortal(Entity portal) {
    // Only teleport if not in liquid
    return !this.isInWater();
}
```

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

### Set Orientation and Size

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Sets the portal's orientation (W and H axes) and dimensions (width, height) in a single call.

```java
public void setOrientationAndSize(Vec3 axisW, Vec3 axisH, double width, double height)
```

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

### Instantiate ChunkLoader from DimensionalChunkPos

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/chunk-loading-api.md

Create a ChunkLoader instance using a DimensionalChunkPos for the center and an integer for the radius. This constructor simplifies creation when the center is already defined as a chunk position.

```java
DimensionalChunkPos center = new DimensionalChunkPos(Level.OVERWORLD, 5, 5);
ChunkLoader loader = new ChunkLoader(center, 3);
```

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

### Get Clamped Point in Plane

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/portal-entity.md

Similar to `getPointInPlane()`, but ensures that the provided local coordinates are clamped within the portal's bounds before conversion to a world position.

```java
public Vec3 getPointInPlaneLocalClamped(double xInPlane, double yInPlane)
```

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

### Implement a Custom Animation Driver

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/architecture.md

Create a custom animation logic for portals by implementing the PortalAnimationDriver interface. This allows for unique visual effects.

```java
public class MyAnimation implements PortalAnimationDriver {
    // Custom animation logic
}
```

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

### PortalLike Interface

Source: https://github.com/iportalteam/immersiveportalsmod/blob/1.21/_autodocs/types.md

A marker interface for objects that exhibit portal-like behavior, such as standard portals and mirrors. It provides methods for transformations, position, dimension, visibility, and rendering.

```APIDOC
## PortalLike

Marker interface for objects that behave like portals (portals, mirrors).

```java
public interface PortalLike
```

### Methods:
- `isConventionalPortal()`: Is this a standard portal
- `getThinBoundingBox()`: Bounding box as plane
- `transformPoint(Vec3)`: Apply portal transformation
- `transformLocalVec(Vec3)`: Transform direction
- `getOriginPos()`: Portal location
- `getDestPos()`: Destination location
- `getOriginWorld()`: Source dimension
- `getDestWorld()`: Destination dimension
- `getDestDim()`: Destination ResourceKey
- `isRoughlyVisibleTo(Vec3)`: Visibility check
- `getInnerClipping()`: Front clipping plane
- `getRotation()`: Rotation transformation
- `getScale()`: Scale factor
- `getIsGlobal()`: Is globally registered
- `isVisible()`: Is visible to clients
- `getOuterFrustumCullingVertices()`: Vertices for advanced culling
- `getAdditionalCameraTransformation()`: Camera adjustment matrix
- `getDiscriminator()`: UUID for uniqueness
- `cannotRenderInMe(Portal)`: Portals that can't render inside this one
- `isFuseView()`: Whether to fuse with nearby portals
- `getDoRenderPlayer()`: Render player from destination
- `getHasCrossPortalCollision()`: Cross-boundary collision

### Location
`qouteall.imm_ptl.core.portal.PortalLike`
```