261 lines
7.7 KiB
Markdown
261 lines
7.7 KiB
Markdown
---
|
|
title: TaskRegistry
|
|
type: docs
|
|
weight: 1
|
|
---
|
|
|
|
Le TaskRegistry permet aux plugins d'enregistrer et de suivre les tâches asynchrones. Hytale utilise les APIs de concurrence standard de Java pour la planification des tâches.
|
|
|
|
## Comprendre TaskRegistry
|
|
|
|
{{< callout type="warning" >}}
|
|
**Important :** TaskRegistry n'a PAS de méthodes `runAsync()`, `runLater()`, ou `runRepeating()`. Ce sont des idées fausses courantes venant d'autres plateformes. Hytale utilise les APIs standard Java `CompletableFuture` et `ScheduledExecutorService`.
|
|
{{< /callout >}}
|
|
|
|
## API TaskRegistry
|
|
|
|
```java
|
|
public class TaskRegistry extends Registry<TaskRegistration> {
|
|
// Enregistrer une tâche CompletableFuture
|
|
public TaskRegistration registerTask(CompletableFuture<Void> task);
|
|
|
|
// Enregistrer une tâche ScheduledFuture
|
|
public TaskRegistration registerTask(ScheduledFuture<Void> task);
|
|
}
|
|
```
|
|
|
|
Le TaskRegistry suit les tâches pour un nettoyage correct lors de l'arrêt du plugin.
|
|
|
|
## Tâches Asynchrones
|
|
|
|
Utilisez `CompletableFuture` pour les opérations async :
|
|
|
|
```java
|
|
// Exécuter une opération async
|
|
CompletableFuture<Void> task = CompletableFuture.runAsync(() -> {
|
|
// Calcul lourd, I/O, requêtes réseau
|
|
String data = fetchFromDatabase(playerId);
|
|
});
|
|
|
|
// Enregistrer avec TaskRegistry pour le suivi
|
|
getTaskRegistry().registerTask(task);
|
|
|
|
// Gérer l'achèvement
|
|
task.thenAccept(result -> {
|
|
// Traiter le résultat - NOTE : Ceci s'exécute sur un pool de threads, pas le thread du monde
|
|
// Utilisez world.execute() pour exécuter du code sur le thread du monde
|
|
});
|
|
```
|
|
|
|
### Retourner au Thread du Monde
|
|
|
|
Après les opérations async, utilisez `world.execute()` pour retourner au thread du monde :
|
|
|
|
```java
|
|
PlayerRef playerRef = player.getPlayerRef();
|
|
World world = player.getWorld();
|
|
|
|
CompletableFuture<Void> task = CompletableFuture.runAsync(() -> {
|
|
// Charger depuis la base de données (I/O bloquant est OK ici)
|
|
PlayerData data = database.load(playerRef.getUuid());
|
|
|
|
// Retourner au thread du monde pour les changements d'état du jeu
|
|
world.execute(() -> {
|
|
Ref<EntityStore> ref = playerRef.getReference();
|
|
if (ref != null) {
|
|
Player p = ref.getStore().getComponent(ref, Player.getComponentType());
|
|
if (p != null) {
|
|
applyData(p, data);
|
|
playerRef.sendMessage(Message.raw("Données chargées !"));
|
|
}
|
|
}
|
|
});
|
|
});
|
|
|
|
getTaskRegistry().registerTask(task);
|
|
```
|
|
|
|
## Tâches Différées
|
|
|
|
Utilisez `CompletableFuture.delayedExecutor()` pour les délais :
|
|
|
|
```java
|
|
import java.util.concurrent.TimeUnit;
|
|
|
|
// Exécuter après 3 secondes
|
|
CompletableFuture.delayedExecutor(3, TimeUnit.SECONDS)
|
|
.execute(() -> {
|
|
world.execute(() -> {
|
|
playerRef.sendMessage(Message.raw("3 secondes se sont écoulées !"));
|
|
});
|
|
});
|
|
```
|
|
|
|
## Tâches Répétitives
|
|
|
|
Utilisez `ScheduledExecutorService` pour les tâches répétitives :
|
|
|
|
```java
|
|
import java.util.concurrent.Executors;
|
|
import java.util.concurrent.ScheduledExecutorService;
|
|
import java.util.concurrent.TimeUnit;
|
|
|
|
public class MyPlugin extends JavaPlugin {
|
|
private ScheduledExecutorService scheduler;
|
|
|
|
@Override
|
|
public void start() {
|
|
scheduler = Executors.newSingleThreadScheduledExecutor();
|
|
|
|
// Exécuter toutes les 5 minutes
|
|
ScheduledFuture<?> saveTask = scheduler.scheduleAtFixedRate(
|
|
() -> {
|
|
saveAllData();
|
|
getLogger().at(Level.INFO).log("Auto-sauvegarde terminée");
|
|
},
|
|
5, // Délai initial
|
|
5, // Période
|
|
TimeUnit.MINUTES
|
|
);
|
|
|
|
// Enregistrer pour le suivi
|
|
getTaskRegistry().registerTask((ScheduledFuture<Void>) saveTask);
|
|
}
|
|
|
|
@Override
|
|
public void shutdown() {
|
|
if (scheduler != null) {
|
|
scheduler.shutdown();
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Timing Basé sur les Ticks
|
|
|
|
Pour un timing basé sur les ticks, suivez les ticks manuellement dans un gestionnaire de tick du monde :
|
|
|
|
```java
|
|
public class TickTimerPlugin extends JavaPlugin {
|
|
private final Map<String, TickTimer> timers = new ConcurrentHashMap<>();
|
|
|
|
public void scheduleAfterTicks(String id, int ticks, Runnable action) {
|
|
timers.put(id, new TickTimer(ticks, action));
|
|
}
|
|
|
|
// Appeler depuis votre gestionnaire de tick
|
|
public void onWorldTick() {
|
|
timers.entrySet().removeIf(entry -> {
|
|
TickTimer timer = entry.getValue();
|
|
timer.ticksRemaining--;
|
|
if (timer.ticksRemaining <= 0) {
|
|
timer.action.run();
|
|
return true; // Supprimer
|
|
}
|
|
return false;
|
|
});
|
|
}
|
|
|
|
private static class TickTimer {
|
|
int ticksRemaining;
|
|
Runnable action;
|
|
|
|
TickTimer(int ticks, Runnable action) {
|
|
this.ticksRemaining = ticks;
|
|
this.action = action;
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Patterns Courants
|
|
|
|
### Compte à Rebours
|
|
|
|
```java
|
|
public void startCountdown(PlayerRef playerRef, int seconds) {
|
|
AtomicInteger remaining = new AtomicInteger(seconds);
|
|
World world = Universe.get().getWorld(playerRef.getWorldUuid());
|
|
|
|
ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
|
|
ScheduledFuture<?> countdown = scheduler.scheduleAtFixedRate(() -> {
|
|
int count = remaining.decrementAndGet();
|
|
|
|
world.execute(() -> {
|
|
if (count > 0) {
|
|
playerRef.sendMessage(Message.raw("Démarrage dans : " + count));
|
|
} else {
|
|
playerRef.sendMessage(Message.raw("Go !"));
|
|
scheduler.shutdown();
|
|
}
|
|
});
|
|
}, 0, 1, TimeUnit.SECONDS);
|
|
}
|
|
```
|
|
|
|
### Chargement de Données Async
|
|
|
|
```java
|
|
public void loadPlayerData(PlayerRef playerRef, World world) {
|
|
CompletableFuture.runAsync(() -> {
|
|
// Charger depuis la base de données (I/O bloquant est OK ici)
|
|
PlayerData data = database.load(playerRef.getUuid());
|
|
|
|
// Retourner au thread du monde
|
|
world.execute(() -> {
|
|
Ref<EntityStore> ref = playerRef.getReference();
|
|
if (ref != null) {
|
|
applyData(ref, data);
|
|
playerRef.sendMessage(Message.raw("Données chargées !"));
|
|
}
|
|
});
|
|
});
|
|
}
|
|
```
|
|
|
|
## Conversion de Temps
|
|
|
|
Hytale tourne à **30 TPS** (ticks par seconde) :
|
|
|
|
| Temps | Ticks (à 30 TPS) | Millisecondes |
|
|
|-------|------------------|---------------|
|
|
| 1 tick | 1 | ~33ms |
|
|
| 1 seconde | 30 | 1 000ms |
|
|
| 5 secondes | 150 | 5 000ms |
|
|
| 1 minute | 1 800 | 60 000ms |
|
|
| 5 minutes | 9 000 | 300 000ms |
|
|
|
|
## Bonnes Pratiques
|
|
|
|
{{< callout type="info" >}}
|
|
**Directives pour les Tâches :**
|
|
- Utilisez `CompletableFuture.runAsync()` pour les opérations I/O, base de données et réseau
|
|
- Utilisez `world.execute()` pour retourner au thread du monde pour les changements d'état du jeu
|
|
- Utilisez `PlayerRef` dans les tâches async, pas `Player` ou `Ref<EntityStore>`
|
|
- Enregistrez les tâches longue durée avec `getTaskRegistry()` pour le nettoyage
|
|
- Arrêtez les instances `ScheduledExecutorService` personnalisées dans `shutdown()`
|
|
{{< /callout >}}
|
|
|
|
{{< callout type="warning" >}}
|
|
**Thread Safety :** Chaque World s'exécute sur son propre thread. Utilisez toujours `world.execute()` ou vérifiez `world.isInThread()` avant de modifier l'état du jeu depuis du code async.
|
|
{{< /callout >}}
|
|
|
|
```java
|
|
// Bien : Pattern async correct avec PlayerRef
|
|
PlayerRef ref = player.getPlayerRef();
|
|
World world = player.getWorld();
|
|
|
|
CompletableFuture.runAsync(() -> {
|
|
String result = heavyComputation();
|
|
|
|
world.execute(() -> {
|
|
ref.sendMessage(Message.raw(result));
|
|
});
|
|
});
|
|
|
|
// Mauvais : Utiliser Player directement en async
|
|
// CompletableFuture.runAsync(() -> {
|
|
// player.sendMessage("Pas sûr !"); // NE FAITES PAS ÇA
|
|
// });
|
|
```
|