Init

2026-01-20 20:33:59 +01:00
commit b16a40e431
583 changed files with 87339 additions and 0 deletions
--- a/content/reference/buildertools/snapshots.fr.md
+++ b/content/reference/buildertools/snapshots.fr.md
@@ -0,0 +1,284 @@
+---
+title: Snapshots
+type: docs
+weight: 5
+---
+
+Le systeme de snapshots fournit la fonctionnalite annuler/refaire pour les outils de construction en capturant et restaurant l'etat.
+
+**Package:** `com.hypixel.hytale.builtin.buildertools.snapshot`
+
+## Architecture
+
+```
+Snapshots
+├── Base
+│   └── SelectionSnapshot - Interface snapshot
+├── Snapshots Blocs
+│   └── BlockSelectionSnapshot - Etat selection blocs
+├── Snapshots Presse-papiers
+│   ├── ClipboardSnapshot - Interface presse-papiers
+│   ├── ClipboardContentsSnapshot - Contenu presse-papiers
+│   └── ClipboardBoundsSnapshot - Limites selection
+└── Snapshots Entites
+    ├── EntitySnapshot - Interface entite
+    ├── EntityAddSnapshot - Suivi ajout entite
+    ├── EntityRemoveSnapshot - Suivi suppression entite
+    └── EntityTransformSnapshot - Suivi changements transform
+```
+
+## Interface SelectionSnapshot
+
+Interface de base pour tous les snapshots:
+
+```java
+public interface SelectionSnapshot<T extends SelectionSnapshot<?>> {
+    // Restaurer etat precedent
+    // Retourne snapshot inverse pour refaire
+    T restore(Ref<EntityStore> ref, Player player, World world,
+              ComponentAccessor<EntityStore> accessor);
+}
+```
+
+### Fonctionnement Annuler/Refaire
+
+Le pattern snapshot cree des operations inverses:
+1. Le snapshot capture l'etat actuel avant l'operation
+2. L'operation modifie l'etat
+3. Appeler `restore()` annule les changements
+4. `restore()` retourne nouveau snapshot pour refaire
+
+## Snapshots Selection Blocs
+
+### BlockSelectionSnapshot
+
+Capture l'etat de selection de blocs:
+
+```java
+public class BlockSelectionSnapshot implements SelectionSnapshot<BlockSelectionSnapshot> {
+    private final BlockSelection selection;
+
+    public BlockSelection getBlockSelection();
+
+    // Creer copie de selection
+    public static BlockSelectionSnapshot copyOf(BlockSelection selection);
+}
+```
+
+### Utilisation
+
+```java
+// Avant modification selection
+BlockSelectionSnapshot snapshot = BlockSelectionSnapshot.copyOf(selection);
+
+// Effectuer modifications...
+
+// Pour annuler - restore retourne snapshot refaire
+BlockSelectionSnapshot redoSnapshot = snapshot.restore(ref, player, world, accessor);
+```
+
+## Snapshots Presse-papiers
+
+### Interface ClipboardSnapshot
+
+Interface etendue pour operations presse-papiers:
+
+```java
+public interface ClipboardSnapshot<T extends SelectionSnapshot<?>>
+        extends SelectionSnapshot<T> {
+
+    T restoreClipboard(Ref<EntityStore> ref, Player player, World world,
+                       BuilderToolsPlugin.BuilderState state,
+                       ComponentAccessor<EntityStore> accessor);
+}
+```
+
+### ClipboardContentsSnapshot
+
+Capture le contenu du presse-papiers:
+
+```java
+public class ClipboardContentsSnapshot implements ClipboardSnapshot<ClipboardContentsSnapshot> {
+    private final BlockSelection selection;
+
+    // Creer copie du contenu presse-papiers
+    public static ClipboardContentsSnapshot copyOf(BlockSelection selection);
+}
+```
+
+### ClipboardBoundsSnapshot
+
+Capture uniquement les limites de selection:
+
+```java
+public class ClipboardBoundsSnapshot implements ClipboardSnapshot<ClipboardBoundsSnapshot> {
+    public static final ClipboardBoundsSnapshot EMPTY;
+
+    private final Vector3i min;
+    private final Vector3i max;
+
+    public ClipboardBoundsSnapshot(BlockSelection selection);
+    public ClipboardBoundsSnapshot(Vector3i min, Vector3i max);
+
+    public Vector3i getMin();
+    public Vector3i getMax();
+}
+```
+
+## Snapshots Entites
+
+### Interface EntitySnapshot
+
+Interface pour snapshots lies aux entites:
+
+```java
+public interface EntitySnapshot<T extends SelectionSnapshot<?>>
+        extends SelectionSnapshot<T> {
+
+    T restoreEntity(Player player, World world,
+                    ComponentAccessor<EntityStore> accessor);
+}
+```
+
+Les snapshots d'entites gerent automatiquement la securite des threads, assurant que la restauration s'execute sur le thread de tick du monde.
+
+### EntityAddSnapshot
+
+Suit la creation d'entite (annuler supprime l'entite):
+
+```java
+public class EntityAddSnapshot implements EntitySnapshot<EntityRemoveSnapshot> {
+    private final Ref<EntityStore> entityRef;
+
+    public Ref<EntityStore> getEntityRef();
+
+    // Restore supprime l'entite
+    // Retourne EntityRemoveSnapshot pour refaire (re-ajouter)
+}
+```
+
+### EntityRemoveSnapshot
+
+Suit la suppression d'entite (annuler ajoute l'entite):
+
+```java
+public class EntityRemoveSnapshot implements EntitySnapshot<EntityAddSnapshot> {
+    private final Holder<EntityStore> holder;
+
+    public Holder<EntityStore> getHolder();
+
+    // Restore ajoute l'entite
+    // Retourne EntityAddSnapshot pour refaire (supprimer a nouveau)
+}
+```
+
+Le `Holder<EntityStore>` stocke une copie complete de l'entite et ses composants.
+
+### EntityTransformSnapshot
+
+Suit la position et rotation d'entite:
+
+```java
+public class EntityTransformSnapshot implements EntitySnapshot<EntityTransformSnapshot> {
+    private final Ref<EntityStore> ref;
+    private final Transform transform;      // Position et rotation
+    private final Vector3f headRotation;    // Direction tete
+
+    // Stocke l'etat transform actuel
+    public EntityTransformSnapshot(Ref<EntityStore> ref,
+                                   ComponentAccessor<EntityStore> accessor);
+
+    // Restore retourne snapshot de l'etat actuel avant restauration
+}
+```
+
+## Paires de Snapshots
+
+Les snapshots viennent en paires complementaires:
+
+| Operation Ajout | Annuler (Supprimer) | Refaire (Ajouter) |
+|-----------------|---------------------|-------------------|
+| `EntityAddSnapshot` | Supprime entite | `EntityRemoveSnapshot` |
+| `EntityRemoveSnapshot` | Ajoute entite | `EntityAddSnapshot` |
+
+| Modification | Annuler | Refaire |
+|--------------|---------|---------|
+| `EntityTransformSnapshot` | Restaure transform precedent | Retourne nouveau snapshot |
+| `BlockSelectionSnapshot` | Restaure blocs precedents | Retourne nouveau snapshot |
+| `ClipboardContentsSnapshot` | Restaure contenu precedent | Retourne nouveau snapshot |
+| `ClipboardBoundsSnapshot` | Restaure limites precedentes | Retourne nouveau snapshot |
+
+## Integration Historique Edition
+
+Les snapshots s'integrent avec le systeme d'historique:
+
+```java
+// L'historique stocke les snapshots pour chaque operation
+// Commande /undo restaure depuis l'historique
+// Commande /redo utilise les snapshots inverses
+
+// Commandes liees a l'historique:
+// /undo [nombre]
+// /redo [nombre]
+// /clearedithistory
+// /settoolhistorysize <taille>
+```
+
+## Securite des Threads
+
+Les snapshots d'entites gerent automatiquement les exigences de thread du monde:
+
+```java
+// Implementation EntitySnapshot.restore()
+default T restore(...) {
+    if (!world.isInThread()) {
+        // Executer sur thread tick du monde
+        return CompletableFuture.supplyAsync(
+            () -> this.restoreEntity(player, world, store),
+            world
+        ).join();
+    }
+    return this.restoreEntity(player, world, store);
+}
+```
+
+## Utilisation de l'API
+
+### Travailler avec Snapshots Blocs
+
+```java
+// Avant operation
+BlockSelectionSnapshot before = BlockSelectionSnapshot.copyOf(selection);
+
+// Effectuer operation qui modifie les blocs
+// ...
+
+// Stocker snapshot dans historique pour annuler
+```
+
+### Travailler avec Snapshots Entites
+
+```java
+// Avant ajout entite
+Ref<EntityStore> newEntity = world.spawnEntity(...);
+EntityAddSnapshot snapshot = new EntityAddSnapshot(newEntity);
+
+// Pour annuler (supprimer l'entite)
+EntityRemoveSnapshot inverse = snapshot.restore(ref, player, world, accessor);
+
+// Pour refaire (ajouter entite a nouveau)
+EntityAddSnapshot restored = inverse.restore(ref, player, world, accessor);
+```
+
+### Travailler avec Snapshots Transform
+
+```java
+// Avant deplacement entite
+EntityTransformSnapshot before = new EntityTransformSnapshot(entityRef, accessor);
+
+// Deplacer entite
+transformComponent.setPosition(newPosition);
+
+// Pour annuler (restaurer position originale)
+EntityTransformSnapshot after = before.restore(player, world, accessor);
+```