Documentation/content/getting-started/creating-a-plugin.fr.md

title, type, weight

title	type	weight
Créer un Plugin	docs	3

Ce guide vous accompagne dans la création de votre premier plugin Hytale.

Structure du Projet

Un projet de plugin Hytale typique a cette structure :

my-plugin/
├── app/
│   ├── build.gradle.kts
│   └── src/
│       ├── main/
│       │   ├── java/
│       │   │   └── com/example/myplugin/
│       │   │       └── MyPlugin.java
│       │   └── resources/
│       │       └── manifest.json
│       └── test/
│           └── java/
├── gradle/
│   ├── libs.versions.toml
│   └── wrapper/
├── build.gradle.kts
├── settings.gradle.kts
└── gradlew

Le manifest.json

Chaque plugin nécessite un fichier manifest.json dans src/main/resources/ :

{
  "Group": "com.example",
  "Name": "MyPlugin",
  "Version": "1.0.0",
  "Description": "Mon premier plugin Hytale",
  "Authors": [
    {
      "Name": "Votre Nom"
    }
  ],
  "Main": "com.example.myplugin.MyPlugin",
  "ServerVersion": "*",
  "Dependencies": {},
  "OptionalDependencies": {},
  "DisabledByDefault": false,
  "IncludesAssetPack": false,
  "SubPlugins": []
}

Champs du Manifest

Champ	Requis	Description
Group	Oui	Groupe de package (ex: "com.example")
Name	Oui	Nom du plugin (utilisé pour l'identification)
Version	Oui	Version sémantique (ex: "1.0.0")
Description	Non	Brève description du plugin
Authors	Non	Liste des auteurs avec champ Name
Main	Oui	Nom complet de la classe principale
ServerVersion	Oui	Compatibilité version serveur ("*" pour toutes)
Dependencies	Non	Dépendances de plugins requises
OptionalDependencies	Non	Dépendances de plugins optionnelles
DisabledByDefault	Non	Si le plugin est désactivé par défaut
IncludesAssetPack	Non	Si le plugin inclut des assets
SubPlugins	Non	Liste des sous-plugins

{{< callout type="warning" >}} Tous les noms de champs du manifest utilisent le PascalCase (ex: ServerVersion, pas serverVersion). {{< /callout >}}

Classe Principale du Plugin

Créez votre classe principale en étendant JavaPlugin :

package com.example.myplugin;

import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import java.util.logging.Level;

public class MyPlugin extends JavaPlugin {

    public MyPlugin(JavaPluginInit init) {
        super(init);
    }

    @Override
    public void setup() {
        // Appelé pendant l'initialisation du plugin
        // Enregistrer les configs, préparer les ressources
        getLogger().at(Level.INFO).log("MyPlugin s'initialise !");
    }

    @Override
    public void start() {
        // Appelé quand le plugin démarre
        // Enregistrer les commandes, événements, entités
        getLogger().at(Level.INFO).log("MyPlugin a démarré !");
    }

    @Override
    public void shutdown() {
        // Appelé quand le plugin s'arrête
        // Nettoyer les ressources
        getLogger().at(Level.INFO).log("MyPlugin s'arrête !");
    }
}

{{< callout type="info" >}} Le constructeur avec le paramètre JavaPluginInit est obligatoire. Appelez toujours super(init). {{< /callout >}}

API de Logging

Hytale utilise une API de logging basée sur Flogger :

import java.util.logging.Level;

// Logging basique
getLogger().at(Level.INFO).log("Message d'information");
getLogger().at(Level.WARNING).log("Message d'avertissement");
getLogger().at(Level.SEVERE).log("Message d'erreur");

// Avec formatage
getLogger().at(Level.INFO).log("Le joueur %s a rejoint la partie", playerName);

build.gradle.kts

Configurez votre fichier de build Gradle (DSL Kotlin) :

plugins {
    java
}

group = "com.example"
version = "1.0.0"

repositories {
    mavenCentral()
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

dependencies {
    // API Serveur Hytale - compile only car fournie à l'exécution
    compileOnly(files("../../../HytaleServer.jar"))

    // Tests
    testImplementation(libs.junit)
}

tasks.jar {
    archiveBaseName.set("MyPlugin")
}

{{< callout type="info" >}} Le chemin vers HytaleServer.jar dépend de l'emplacement de votre source de plugin par rapport au répertoire du jeu. {{< /callout >}}

Registres Disponibles

Votre plugin a accès à plusieurs registres via la classe de base :

Méthode	Type de Registre	Utilité
getEventRegistry()	EventRegistry	Enregistrer des écouteurs d'événements
getCommandRegistry()	CommandRegistry	Enregistrer des commandes
getEntityRegistry()	EntityRegistry	Enregistrer des entités personnalisées
getBlockStateRegistry()	BlockStateRegistry	Enregistrer des états de blocs
getTaskRegistry()	TaskRegistry	Planifier des tâches
getAssetRegistry()	AssetRegistry	Enregistrer des assets
getEntityStoreRegistry()	EntityStoreRegistry	Enregistrer des composants d'entité
getChunkStoreRegistry()	ChunkStoreRegistry	Enregistrer des composants de chunk

Étapes Suivantes

Découvrez le Cycle de Vie du Plugin pour comprendre quand chaque méthode est appelée.