Documentation/content/reference/buildertools/snapshots.fr.md

title, type, weight

title	type	weight
Snapshots	docs	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:

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:

public class BlockSelectionSnapshot implements SelectionSnapshot<BlockSelectionSnapshot> {
    private final BlockSelection selection;

    public BlockSelection getBlockSelection();

    // Creer copie de selection
    public static BlockSelectionSnapshot copyOf(BlockSelection selection);
}

Utilisation

// 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:

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:

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:

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:

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):

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):

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:

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:

// 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:

// 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

// Avant operation
BlockSelectionSnapshot before = BlockSelectionSnapshot.copyOf(selection);

// Effectuer operation qui modifie les blocs
// ...

// Stocker snapshot dans historique pour annuler

Travailler avec Snapshots Entites

// 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

// 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);