Init

2026-01-20 20:33:59 +01:00
commit b16a40e431
583 changed files with 87339 additions and 0 deletions
--- a/content/world/portals/_index.en.md
+++ b/content/world/portals/_index.en.md
@@ -0,0 +1,147 @@
+---
+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 >}}