Documentation/content/world/portals/_index.en.md

title, type, weight

title	type	weight
Portals	docs	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:

// 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:

// 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:

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:

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:

// Uncurse items when returning
CursedItems.uncurseAll(inventory.getCombinedEverything());

Plugin Access

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:

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 >}}