148 lines
4.0 KiB
Markdown
148 lines
4.0 KiB
Markdown
---
|
|
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 >}}
|