Documentation/content/core-concepts/codecs.fr.md

title, type, weight

title	type	weight
Codecs	docs	3

Les codecs dans Hytale fournissent un moyen puissant de sérialiser et désérialiser des données. Ils sont utilisés pour les fichiers de configuration, la communication réseau et la persistance des données.

Package: com.hypixel.hytale.codec

BuilderCodec

Le BuilderCodec est le type de codec principal pour les objets complexes. Il utilise un pattern builder pour la construction.

Définir un Codec

import com.hypixel.hytale.codec.Codec;
import com.hypixel.hytale.codec.KeyedCodec;
import com.hypixel.hytale.codec.builder.BuilderCodec;

public class MyConfig {
    private String serverName;
    private int maxPlayers = 20;  // Valeur par défaut
    private boolean debugMode = false;

    public static final BuilderCodec<MyConfig> CODEC = BuilderCodec.builder(MyConfig.class, MyConfig::new)
        .append(new KeyedCodec<>("ServerName", Codec.STRING),
            (config, val) -> config.serverName = val,
            config -> config.serverName)
        .add()
        .append(new KeyedCodec<>("MaxPlayers", Codec.INTEGER),
            (config, val) -> config.maxPlayers = val,
            config -> config.maxPlayers)
        .add()
        .append(new KeyedCodec<>("DebugMode", Codec.BOOLEAN),
            (config, val) -> config.debugMode = val,
            config -> config.debugMode)
        .add()
        .build();

    // Getters...
    public String getServerName() { return serverName; }
    public int getMaxPlayers() { return maxPlayers; }
    public boolean isDebugMode() { return debugMode; }
}

{{< callout type="warning" >}} Les clés KeyedCodec doivent commencer par une majuscule (PascalCase). Les clés comme "serverName" lanceront une IllegalArgumentException. {{< /callout >}}

Structure JSON

Le codec ci-dessus correspond à ce JSON :

{
  "ServerName": "Mon Serveur",
  "MaxPlayers": 100,
  "DebugMode": true
}

Codecs de Base

Hytale fournit des codecs pour les types primitifs :

Codec	Type
Codec.STRING	String
Codec.INTEGER	Integer
Codec.LONG	Long
Codec.FLOAT	Float
Codec.DOUBLE	Double
Codec.BOOLEAN	Boolean
Codec.BYTE	Byte
Codec.SHORT	Short

Utilisation des Fichiers de Config

Enregistrez les fichiers de configuration dans setup() :

import com.hypixel.hytale.server.core.util.Config;
import java.util.logging.Level;

private Config<MyConfig> config;

@Override
public void setup() {
    config = withConfig(MyConfig.CODEC);
}

@Override
public void start() {
    MyConfig cfg = config.get();
    getLogger().at(Level.INFO).log("Nom du serveur : " + cfg.getServerName());
}

Emplacement du Fichier Config

Les fichiers de config sont automatiquement stockés dans le répertoire de données de votre plugin :

Plugins/
└── your-plugin/
    └── config.json

Configs Nommées

Vous pouvez avoir plusieurs fichiers de configuration :

Config<MyConfig> mainConfig = withConfig("main", MyConfig.CODEC);
Config<DatabaseConfig> dbConfig = withConfig("database", DatabaseConfig.CODEC);

Champs Requis vs Optionnels

Par défaut, tous les champs sont optionnels. Pour rendre un champ requis, ajoutez un validateur :

import com.hypixel.hytale.codec.validation.Validators;

BuilderCodec.builder(MyConfig.class, MyConfig::new)
    .append(new KeyedCodec<>("ServerName", Codec.STRING),
        (config, val) -> config.serverName = val,
        config -> config.serverName)
    .addValidator(Validators.nonNull())  // Rend le champ requis
    .add()
    .append(new KeyedCodec<>("MaxPlayers", Codec.INTEGER),
        (config, val) -> config.maxPlayers = val,
        config -> config.maxPlayers)
    .add()  // Optionnel - utilise la valeur par défaut de la classe
    .build();

Codecs List et Map

Pour les collections :

import com.hypixel.hytale.codec.codecs.array.ArrayCodec;
import com.hypixel.hytale.codec.codecs.map.ObjectMapCodec;

// Tableau de strings
Codec<String[]> stringArray = new ArrayCodec<>(Codec.STRING, String[]::new);

// Map avec clés string
Codec<Map<String, Integer>> stringIntMap = new ObjectMapCodec<>(
    Codec.INTEGER,
    LinkedHashMap::new,
    key -> key,           // Clé vers string
    str -> str            // String vers clé
);

Codecs Enum

Pour les types enum :

import com.hypixel.hytale.codec.codecs.EnumCodec;

public enum GameMode {
    SURVIVAL, CREATIVE, ADVENTURE
}

Codec<GameMode> gameModeCodec = new EnumCodec<>(GameMode.class);

Codecs Imbriqués

Les codecs peuvent être imbriqués pour des structures complexes :

public class ServerSettings {
    private GeneralSettings general;
    private DatabaseSettings database;

    public static final BuilderCodec<ServerSettings> CODEC = BuilderCodec.builder(ServerSettings.class, ServerSettings::new)
        .append(new KeyedCodec<>("General", GeneralSettings.CODEC),
            (s, val) -> s.general = val,
            s -> s.general)
        .add()
        .append(new KeyedCodec<>("Database", DatabaseSettings.CODEC),
            (s, val) -> s.database = val,
            s -> s.database)
        .add()
        .build();
}

Héritage

Utilisez des codecs parents pour les hiérarchies de classes :

// Codec classe de base
public static final BuilderCodec<BaseEntity> BASE_CODEC = BuilderCodec.builder(BaseEntity.class, BaseEntity::new)
    .append(new KeyedCodec<>("Id", Codec.STRING),
        (e, val) -> e.id = val,
        e -> e.id)
    .add()
    .build();

// Le codec classe enfant hérite du parent
public static final BuilderCodec<PlayerEntity> CODEC = BuilderCodec.builder(PlayerEntity.class, PlayerEntity::new, BASE_CODEC)
    .append(new KeyedCodec<>("Username", Codec.STRING),
        (e, val) -> e.username = val,
        e -> e.username)
    .add()
    .build();

Bonnes Pratiques

{{< callout type="tip" >}}

• Définissez les codecs comme champs public static final
• Utilisez PascalCase pour les clés JSON (ex : "ServerName", pas "serverName")
• Définissez les valeurs par défaut dans les déclarations de champs de classe
• Utilisez Validators.nonNull() pour les champs requis
• Gardez les classes de configuration avec des setters simples pour la compatibilité codec {{< /callout >}}