Init

content/world/portals/portal-components.fr.md

@@ -0,0 +1,270 @@
+---
+title: Composants Portail
+type: docs
+weight: 1
+---
+
+Les composants portail definissent les structures de donnees pour les dispositifs portail, les mondes portail et les evenements du vide.
+
+**Package:** `com.hypixel.hytale.builtin.portals.components`
+
+## PortalDevice
+
+Un composant au niveau chunk representant un bloc dispositif portail.
+
+```java
+public class PortalDevice implements Component<ChunkStore> {
+    // Configuration pour etats du portail
+    private PortalDeviceConfig config;
+
+    // Cle type de bloc pour le dispositif portail
+    private String baseBlockTypeKey;
+
+    // UUID du monde de destination (si actif)
+    private UUID destinationWorldUuid;
+}
+```
+
+### Acceder aux Dispositifs Portail
+
+```java
+// Obtenir dispositif portail a position bloc
+PortalDevice portal = BlockModule.get().getComponent(
+    PortalDevice.getComponentType(),
+    world, x, y, z
+);
+
+if (portal != null) {
+    // Portail existe a cet emplacement
+    BlockType blockType = portal.getBaseBlockType();
+    World destination = portal.getDestinationWorld();
+}
+```
+
+### Monde de Destination
+
+```java
+// Definir destination lors activation portail
+portal.setDestinationWorld(targetWorld);
+
+// Obtenir destination (null si inactif ou monde ferme)
+World destination = portal.getDestinationWorld();
+if (destination == null || !destination.isAlive()) {
+    // Destination portail invalide
+}
+```
+
+## PortalDeviceConfig
+
+Configuration pour les etats visuels du dispositif portail.
+
+```java
+public class PortalDeviceConfig {
+    // Etat quand instance en creation
+    private String spawningState = "Spawning";
+
+    // Etat quand portail actif
+    private String onState = "Active";
+
+    // Etat quand portail inactif
+    private String offState = "default";
+
+    // Bloc place au point de spawn dans monde portail
+    private String returnBlock;
+}
+```
+
+### Validation des Etats
+
+```java
+// Verifier que tous les etats existent sur type de bloc
+PortalDeviceConfig config = portal.getConfig();
+if (config.areBlockStatesValid(baseBlockType)) {
+    // Tous les etats (on, off, spawning) sont valides
+}
+```
+
+### Noms des Etats
+
+| Etat | Description | Defaut |
+|------|-------------|--------|
+| `spawningState` | Transition de eteint a actif | "Spawning" |
+| `onState` | Portail actif | "Active" |
+| `offState` | Portail inactif | "default" |
+
+## PortalWorld
+
+Une ressource attachee aux mondes crees par les portails.
+
+```java
+public class PortalWorld implements Resource<EntityStore> {
+    // ID configuration type portail
+    private String portalTypeId;
+
+    // Limite temps en secondes
+    private int timeLimitSeconds;
+
+    // Handler condition de suppression
+    private PortalRemovalCondition worldRemovalCondition;
+
+    // Joueurs morts dans ce monde
+    private Set<UUID> diedInWorld;
+
+    // Joueurs voyant actuellement l'UI
+    private Set<UUID> seesUi;
+
+    // Transform point de spawn
+    private Transform spawnPoint;
+
+    // Reference vers evenement vide actif
+    private Ref<EntityStore> voidEventRef;
+}
+```
+
+### Verifier Monde Portail
+
+```java
+// Obtenir ressource monde portail
+PortalWorld portalWorld = store.getResource(PortalWorld.getResourceType());
+
+// Verifier si c'est un monde portail valide
+if (portalWorld.exists()) {
+    PortalType type = portalWorld.getPortalType();
+    int timeLimit = portalWorld.getTimeLimitSeconds();
+}
+```
+
+### Gestion du Temps
+
+```java
+// Obtenir temps ecoule et restant
+double elapsed = portalWorld.getElapsedSeconds(world);
+double remaining = portalWorld.getRemainingSeconds(world);
+
+// Modifier temps restant (ex: etendre timer)
+portalWorld.setRemainingSeconds(world, 300.0); // 5 minutes
+```
+
+### Suivi des Morts
+
+```java
+// Verifier si joueur mort dans ce monde
+if (portalWorld.getDiedInWorld().contains(playerUuid)) {
+    // Ne peut pas re-entrer - mort ici
+}
+
+// Enregistrer une mort
+portalWorld.getDiedInWorld().add(playerUuid);
+```
+
+### Etat UI
+
+```java
+// Suivre joueurs voyant l'UI portail
+portalWorld.getSeesUi().add(playerUuid);
+portalWorld.getSeesUi().remove(playerUuid);
+```
+
+## VoidEvent
+
+Composant pour evenements invasion du vide dans mondes portail.
+
+```java
+public class VoidEvent implements Component<EntityStore> {
+    // Distance minimum entre spawners
+    public static final double MIN_BLOCKS_BETWEEN_SPAWNERS = 62.0;
+
+    // Grille spatiale des spawners du vide
+    private SpatialHashGrid<Ref<EntityStore>> voidSpawners;
+
+    // Etape active actuelle
+    private VoidEventStage activeStage;
+}
+```
+
+### Acces Evenement Vide
+
+```java
+// Verifier si evenement vide actif
+Ref<EntityStore> voidRef = portalWorld.getVoidEventRef();
+if (portalWorld.isVoidEventActive()) {
+    VoidEvent voidEvent = store.getComponent(voidRef, VoidEvent.getComponentType());
+    VoidEventStage stage = voidEvent.getActiveStage();
+}
+```
+
+### Grille Spawners Vide
+
+```java
+// Obtenir grille spawners
+SpatialHashGrid<Ref<EntityStore>> spawners = voidEvent.getVoidSpawners();
+
+// Spawners maintiennent distance minimum de 62 blocs
+```
+
+## VoidEventConfig
+
+Configuration pour evenements du vide.
+
+```java
+public class VoidEventConfig {
+    // Duree evenement vide en secondes
+    private int durationSeconds;
+
+    // Etapes de l'evenement vide
+    private List<VoidEventStage> stages;
+}
+```
+
+## VoidEventStage
+
+Etape unique dans progression evenement vide.
+
+```java
+public class VoidEventStage {
+    // Quand cette etape demarre (secondes depuis debut evenement)
+    private int startTime;
+
+    // Spawners a activer
+    private List<VoidSpawnerConfig> spawners;
+}
+```
+
+## VoidSpawner
+
+Composant entite pour spawners invasion du vide.
+
+```java
+public class VoidSpawner implements Component<EntityStore> {
+    // Configuration spawner
+    // Suit etat de spawn actif
+}
+```
+
+## Enregistrement Composants
+
+Les composants sont enregistres dans setup PortalsPlugin:
+
+```java
+// Dans 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);
+```
+
+## Serialisation
+
+PortalDevice utilise BuilderCodec pour persistance:
+
+```java
+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();
+```