Recettes d’intégration

Ces exemples montrent le chemin complet : définir les options, les enregistrer côté client, persister leur valeur, fournir les traductions et ajouter une icône.

Exemple Kotlin : une catégorie entière

Le code ci-dessous suppose un objet de configuration propre au mod. Remplacez ExampleConfig par votre système JSON, TOML ou autre.

package example.mod

import net.fabricmc.api.ClientModInitializer
import net.minecraft.network.chat.Component
import net.minecraft.resources.Identifier
import net.turtle.ef5am.api.client.settings.*

class ExampleClient : ClientModInitializer {
    override fun onInitializeClient() {
        ElytraF5SettingsApi.registerCategory(
            SettingsCategory(
                id = "examplemod:visuals",
                title = Component.translatable("examplemod.settings.category.visuals"),
                icon = Identifier.fromNamespaceAndPath(
                    "examplemod", "textures/gui/settings/visuals.png"
                ),
                options = listOf(
                    BooleanSettingOption(
                        id = "particles",
                        title = Component.translatable("examplemod.settings.particles"),
                        description = Component.translatable("examplemod.settings.particles.hint"),
                        currentValue = { ExampleConfig.particles },
                        onChanged = { value ->
                            ExampleConfig.particles = value
                            ExampleConfig.save()
                        }
                    ),
                    ChoiceSettingOption(
                        id = "quality",
                        title = Component.translatable("examplemod.settings.quality"),
                        description = Component.translatable("examplemod.settings.quality.hint"),
                        choices = listOf(
                            SettingsChoice("fast", Component.translatable("examplemod.quality.fast")),
                            SettingsChoice("balanced", Component.translatable("examplemod.quality.balanced")),
                            SettingsChoice("fancy", Component.translatable("examplemod.quality.fancy"))
                        ),
                        currentChoice = { ExampleConfig.quality },
                        onChanged = { value ->
                            ExampleConfig.quality = value
                            ExampleConfig.save()
                        }
                    ),
                    ActionSettingOption(
                        id = "advanced",
                        title = Component.translatable("examplemod.settings.advanced"),
                        description = Component.translatable("examplemod.settings.advanced.hint"),
                        buttonTitle = Component.translatable("examplemod.settings.open"),
                        action = { parent ->
                            Minecraft.getInstance().gui.setScreen(ExampleAdvancedScreen(parent))
                        }
                    )
                )
            )
        )
    }
}

Ajoutez l’import net.minecraft.client.Minecraft pour l’exemple d’action. Le callback reçoit l’écran de réglages en parent ; l’écran avancé doit le restaurer quand il se ferme.

Exemple Java : option booléenne

L’API est écrite en Kotlin. En Java, ses callbacks utilisent les interfaces Kotlin Function0 et Function1. Le callback de changement renvoie Unit.INSTANCE.

import java.util.List;
import kotlin.Unit;
import kotlin.jvm.functions.Function0;
import kotlin.jvm.functions.Function1;
import net.minecraft.network.chat.Component;
import net.turtle.ef5am.api.client.settings.*;

ElytraF5SettingsApi.registerCategory(new SettingsCategory(
    "examplemod:visuals",
    Component.translatable("examplemod.settings.category.visuals"),
    List.of(new BooleanSettingOption(
        "particles",
        Component.translatable("examplemod.settings.particles"),
        Component.translatable("examplemod.settings.particles.hint"),
        (Function0<Boolean>) () -> ExampleConfig.isParticlesEnabled(),
        (Function1<Boolean, Unit>) value -> {
            ExampleConfig.setParticlesEnabled(value);
            ExampleConfig.save();
            return Unit.INSTANCE;
        }
    )),
    null
));

Java doit compiler avec le jar ElytraF5 et la bibliothèque Kotlin disponibles. Pour une intégration Java, vérifiez les signatures générées par la version d’API ciblée.

Fichiers de ressources attendus

src/main/resources/
└── assets/
    └── examplemod/
        ├── lang/
        │   ├── en_us.json
        │   └── fr_fr.json
        └── textures/
            └── gui/
                └── settings/
                    └── visuals.png  # 16 × 16 pixels

Exemple de traductions

// fr_fr.json
{
  "examplemod.settings.category.visuals": "Visuels",
  "examplemod.settings.particles": "Particules",
  "examplemod.settings.particles.hint": "Affiche les particules décoratives.",
  "examplemod.settings.quality": "Qualité",
  "examplemod.settings.quality.hint": "Choisit le niveau de qualité des effets.",
  "examplemod.quality.fast": "Rapide",
  "examplemod.quality.balanced": "Équilibrée",
  "examplemod.quality.fancy": "Élevée",
  "examplemod.settings.advanced": "Options avancées",
  "examplemod.settings.advanced.hint": "Ouvre les options détaillées.",
  "examplemod.settings.open": "Configurer"
}

Le même jeu de clés doit apparaître dans en_us.json avec des textes anglais. Si une clé n’existe pas, Minecraft affiche généralement son identifiant brut.

Choisir un type d’option

À retenir

• Les callbacks de l’API ne sauvegardent rien automatiquement : appelez votre mécanisme de sauvegarde.
• Fournissez une valeur initiale valide avant d’enregistrer une option à choix.
• Utilisez des clés de traduction dans tous les Component destinés au joueur.
• Les icônes sont facultatives ; vérifiez l’ID de ressource, le namespace et les dimensions.