---
title: Portals
type: docs
weight: 6
---

The portals system provides mechanics for inter-dimensional travel between worlds, including portal devices, void events, and fragment instances.

**Package:** `com.hypixel.hytale.builtin.portals`

## Architecture

```
Portals System
├── Components
│   ├── PortalDevice - Portal block component
│   ├── VoidEvent - Void invasion event
│   └── VoidSpawner - Void spawner entity
├── Resources
│   └── PortalWorld - Portal world data
├── Interactions
│   ├── EnterPortalInteraction - Enter portal
│   └── ReturnPortalInteraction - Return from portal
├── Systems
│   ├── PortalTrackerSystems - UI tracking
│   ├── PortalInvalidDestinationSystem - Destination validation
│   ├── VoidEventStagesSystem - Void event progression
│   └── VoidSpawnerSystems - Spawner management
└── Commands
    ├── FragmentCommands - Fragment management
    ├── LeaveCommand - Leave portal world
    └── VoidEventCommands - Void event control
```

## Core Concepts

### Portal Device

A portal device is a block-based entity that can transport players to fragment worlds:

```java
// PortalDevice is a ChunkStore component
PortalDevice portal = BlockModule.get().getComponent(
    PortalDevice.getComponentType(),
    world, x, y, z
);

// Get destination world
World targetWorld = portal.getDestinationWorld();
```

### Portal World

A portal world is a temporary instance created when players activate a portal:

```java
// PortalWorld is an EntityStore resource
PortalWorld portalWorld = store.getResource(PortalWorld.getResourceType());

// Check if this is a portal world
if (portalWorld.exists()) {
    Transform spawn = portalWorld.getSpawnPoint();
    double remaining = portalWorld.getRemainingSeconds(world);
}
```

### Fragment Instances

Fragments are temporary worlds with:
- Time limit before auto-closure
- Spawn point for returning players
- Death tracking (players who died cannot re-enter)
- Optional void invasion events

## Key Features

### Portal States

Portals have three visual states:
- **Off** - Portal is inactive
- **Spawning** - Instance is being created
- **On/Active** - Portal is ready for travel

### Time Limits

Portal worlds have configurable time limits:
```java
int totalTime = portalWorld.getTimeLimitSeconds();
double elapsed = portalWorld.getElapsedSeconds(world);
double remaining = portalWorld.getRemainingSeconds(world);
```

### Death Tracking

Players who die in a portal world cannot re-enter:
```java
Set<UUID> deaths = portalWorld.getDiedInWorld();
if (deaths.contains(playerUuid)) {
    // Player died here - show "DIED_IN_WORLD" state
}
```

### Cursed Items

Items can become "cursed" in portal worlds and are removed on death:
```java
// Uncurse items when returning
CursedItems.uncurseAll(inventory.getCombinedEverything());
```

## Plugin Access

```java
PortalsPlugin portals = PortalsPlugin.getInstance();

// Component types
ComponentType<ChunkStore, PortalDevice> portalDeviceType =
    portals.getPortalDeviceComponentType();
ComponentType<EntityStore, VoidEvent> voidEventType =
    portals.getVoidEventComponentType();
ComponentType<EntityStore, VoidSpawner> voidSpawnerType =
    portals.getVoidPortalComponentType();

// Resource type
ResourceType<EntityStore, PortalWorld> portalWorldType =
    portals.getPortalResourceType();
```

## Concurrent Fragments Limit

The system limits concurrent portal fragments:
```java
public static final int MAX_CONCURRENT_FRAGMENTS = 4;

int active = portals.countActiveFragments();
if (active >= MAX_CONCURRENT_FRAGMENTS) {
    // Cannot create new fragments
}
```

## Related Topics

{{< cards >}}
  {{< card link="portal-components" title="Portal Components" subtitle="PortalDevice, VoidEvent components" >}}
  {{< card link="portal-systems" title="Portal Systems" subtitle="ECS systems for portal logic" >}}
  {{< card link="portal-commands" title="Portal Commands" subtitle="Admin and player commands" >}}
{{< /cards >}}