Documentation/content/world/portals/portal-components.en.md

title, type, weight

title	type	weight
Portal Components	docs	1

Portal components define the data structures for portal devices, portal worlds, and void events.

Package: com.hypixel.hytale.builtin.portals.components

PortalDevice

A chunk-level component representing a portal block device.

public class PortalDevice implements Component<ChunkStore> {
    // Configuration for portal states
    private PortalDeviceConfig config;

    // Block type key for the portal device
    private String baseBlockTypeKey;

    // UUID of the destination world (if active)
    private UUID destinationWorldUuid;
}

Accessing Portal Devices

// Get portal device at block position
PortalDevice portal = BlockModule.get().getComponent(
    PortalDevice.getComponentType(),
    world, x, y, z
);

if (portal != null) {
    // Portal exists at this location
    BlockType blockType = portal.getBaseBlockType();
    World destination = portal.getDestinationWorld();
}

Destination World

// Set destination when activating portal
portal.setDestinationWorld(targetWorld);

// Get destination (null if inactive or world closed)
World destination = portal.getDestinationWorld();
if (destination == null || !destination.isAlive()) {
    // Portal destination invalid
}

PortalDeviceConfig

Configuration for portal device visual states.

public class PortalDeviceConfig {
    // State when instance is being created
    private String spawningState = "Spawning";

    // State when portal is active
    private String onState = "Active";

    // State when portal is inactive
    private String offState = "default";

    // Block placed at spawn point in portal world
    private String returnBlock;
}

State Validation

// Verify all states exist on block type
PortalDeviceConfig config = portal.getConfig();
if (config.areBlockStatesValid(baseBlockType)) {
    // All states (on, off, spawning) are valid
}

State Names

State	Description	Default
spawningState	Transition from off to on	"Spawning"
onState	Portal is active	"Active"
offState	Portal is inactive	"default"

PortalWorld

A resource attached to worlds created by portals.

public class PortalWorld implements Resource<EntityStore> {
    // Portal type configuration ID
    private String portalTypeId;

    // Time limit in seconds
    private int timeLimitSeconds;

    // Removal condition handler
    private PortalRemovalCondition worldRemovalCondition;

    // Players who died in this world
    private Set<UUID> diedInWorld;

    // Players currently seeing the UI
    private Set<UUID> seesUi;

    // Spawn point transform
    private Transform spawnPoint;

    // Reference to active void event
    private Ref<EntityStore> voidEventRef;
}

Checking Portal World

// Get portal world resource
PortalWorld portalWorld = store.getResource(PortalWorld.getResourceType());

// Check if this is a valid portal world
if (portalWorld.exists()) {
    PortalType type = portalWorld.getPortalType();
    int timeLimit = portalWorld.getTimeLimitSeconds();
}

Time Management

// Get elapsed and remaining time
double elapsed = portalWorld.getElapsedSeconds(world);
double remaining = portalWorld.getRemainingSeconds(world);

// Modify remaining time (e.g., extend timer)
portalWorld.setRemainingSeconds(world, 300.0); // 5 minutes

Death Tracking

// Check if player died in this world
if (portalWorld.getDiedInWorld().contains(playerUuid)) {
    // Cannot re-enter - died here
}

// Track a death
portalWorld.getDiedInWorld().add(playerUuid);

UI State

// Track players seeing the portal UI
portalWorld.getSeesUi().add(playerUuid);
portalWorld.getSeesUi().remove(playerUuid);

VoidEvent

Component for void invasion events in portal worlds.

public class VoidEvent implements Component<EntityStore> {
    // Minimum distance between spawners
    public static final double MIN_BLOCKS_BETWEEN_SPAWNERS = 62.0;

    // Spatial grid of void spawners
    private SpatialHashGrid<Ref<EntityStore>> voidSpawners;

    // Current active stage
    private VoidEventStage activeStage;
}

Void Event Access

// Check if void event is active
Ref<EntityStore> voidRef = portalWorld.getVoidEventRef();
if (portalWorld.isVoidEventActive()) {
    VoidEvent voidEvent = store.getComponent(voidRef, VoidEvent.getComponentType());
    VoidEventStage stage = voidEvent.getActiveStage();
}

Void Spawner Grid

// Get spawner grid
SpatialHashGrid<Ref<EntityStore>> spawners = voidEvent.getVoidSpawners();

// Spawners maintain minimum distance of 62 blocks

VoidEventConfig

Configuration for void events.

public class VoidEventConfig {
    // Duration of void event in seconds
    private int durationSeconds;

    // Stages of the void event
    private List<VoidEventStage> stages;
}

VoidEventStage

Single stage in a void event progression.

public class VoidEventStage {
    // When this stage starts (seconds from event start)
    private int startTime;

    // Spawners to activate
    private List<VoidSpawnerConfig> spawners;
}

VoidSpawner

Entity component for void invasion spawners.

public class VoidSpawner implements Component<EntityStore> {
    // Spawner configuration
    // Tracks active spawning state
}

Component Registration

Components are registered in PortalsPlugin setup:

// In PortalsPlugin.setup()
this.portalDeviceComponentType = this.getChunkStoreRegistry()
    .registerComponent(PortalDevice.class, "Portal", PortalDevice.CODEC);

this.voidEventComponentType = this.getEntityStoreRegistry()
    .registerComponent(VoidEvent.class, VoidEvent::new);

this.voidPortalComponentType = this.getEntityStoreRegistry()
    .registerComponent(VoidSpawner.class, VoidSpawner::new);

Serialization

PortalDevice uses BuilderCodec for persistence:

public static final BuilderCodec<PortalDevice> CODEC = BuilderCodec.builder(...)
    .append(new KeyedCodec<>("Config", PortalDeviceConfig.CODEC), ...)
    .append(new KeyedCodec<>("BaseBlockType", Codec.STRING), ...)
    .append(new KeyedCodec<>("DestinationWorld", Codec.UUID_BINARY), ...)
    .build();