Comprendre le comportement
Cette page précise le cycle de vie des catégories, la façon dont les valeurs circulent et ce que l’API v1 ne prend pas encore en charge.
Quand enregistrer une catégorie ?
Enregistrez-la une fois dans votre entrypoint Fabric client, au démarrage du client, après avoir chargé la configuration qui fournit les valeurs initiales. L’enregistrement est conservé en mémoire pour la session. Il ne dépend pas du monde actuellement chargé, ce qui permet à l’écran d’être ouvert depuis le menu principal.
Ne l’enregistrez pas à chaque entrée dans un monde, à chaque ouverture de l’écran ou à chaque tick. Les identifiants de catégorie sont globaux et un deuxième enregistrement de la même catégorie déclenche une erreur.
Comment les valeurs sont-elles lues et modifiées ?
- Votre mod charge sa configuration.
- Votre mod enregistre la catégorie avec des fonctions qui lisent et modifient cette configuration.
- Quand l’écran ElytraF5 est construit, le contrôle lit la valeur courante.
- Quand le joueur modifie le contrôle, l’API appelle votre fonction
onChanged. - Votre mod met à jour puis sauvegarde sa configuration.
Les callbacks sont exécutés depuis l’interface client. Ils doivent rester rapides et ne pas faire d’accès réseau ou de chargement coûteux. Si la configuration change par un autre chemin pendant que l’écran est ouvert, fermez puis rouvrez l’écran pour reconstruire les widgets.
Qu’est-ce qui est copié à l’inscription ?
L’API copie la liste des options de la catégorie, mais les objets d’options et leurs callbacks restent ceux fournis par votre mod. Les changements ultérieurs à la liste d’origine ne mettent pas à jour la catégorie enregistrée. Il n’existe pas encore de méthode pour modifier ou retirer une catégorie.
Intégration optionnelle ou obligatoire ?
Dépendance obligatoire
Déclarez ef5am dans depends si le fonctionnement de votre mod nécessite cette intégration. Vous pouvez alors référencer directement l’API dans l’entrypoint client.
Intégration facultative
Déclarez plutôt suggests. Testez la présence du mod avec Fabric Loader et gardez les références directes aux classes ElytraF5 dans une classe passerelle dédiée que vous n’appelez que si ef5am est chargé. Cela évite qu’un mod absent soit résolu trop tôt. Testez les deux configurations : avec et sans ElytraF5.
L’API est dans le source set client. Ne l’appelez jamais depuis un entrypoint ou une classe partagée avec un serveur dédié.
Compatibilité
ElytraF5SettingsApi.API_VERSION vaut actuellement 1. C’est une constante informative pour vérifier la génération de l’API lorsqu’ElytraF5 est déjà présent ; elle ne remplace pas la vérification Fabric de la dépendance. Compilez contre la version de l’API que vous utilisez et vérifiez les signatures après une mise à jour majeure.
Ce que l’API v1 ne fait pas
- Elle ne sauvegarde pas les valeurs à votre place.
- Elle ne fournit pas de curseur numérique, champ texte, liste multi-sélection ou groupe imbriqué.
- Elle ne donne pas accès aux options privées d’un autre mod.
- Elle ne met pas à jour l’écran déjà ouvert si les catégories enregistrées changent.
- Elle ne fournit pas de méthode de désinscription ou de remplacement d’une catégorie.
- Elle n’ajoute pas automatiquement vos traductions au mod hôte : elles appartiennent à votre namespace.
Dépannage détaillé
| Erreur / symptôme | Cause probable | Correction |
|---|---|---|
| « id must be namespaced » | ID de catégorie sans namespace ou avec majuscule/caractère interdit. | Utilisez par exemple examplemod:visuals en minuscules. |
| Catégorie déjà enregistrée | La fonction d’enregistrement est appelée deux fois. | Déplacez l’appel dans l’initialisation client et retirez les appels liés au monde ou à l’écran. |
| « Current choice is not registered » | La configuration contient une valeur inconnue ou lue avant son initialisation. | Chargez la config avant l’enregistrement et migrez les anciennes valeurs vers un choix pris en charge. |
| Le changement n’est pas sauvegardé | Le callback a modifié une variable temporaire seulement. | Modifiez la source de vérité de votre configuration puis appelez sa fonction de sauvegarde. |
| Erreur de classe absente | L’intégration est facultative mais une classe charge directement l’API sans vérifier la présence d’ElytraF5. | Isoler les références à l’API dans une passerelle et ne l’appeler qu’après le test Fabric Loader. |
| Icône invisible | Namespace, chemin ou casse différents du vrai chemin dans resources. | Comparez exactement l’Identifier à assets/<namespace>/textures/gui/... et vérifiez le PNG 16 × 16. |