NRF SDK 0.9Référence
ModServices
Déclarer un outil ou une action disponible lorsqu’un autre mod est chargé.
Contexte d’utilisation
| Module | Package | Source SDK |
|---|---|---|
| Kotlin/Native | nimby | kotlin/src/nimby/ModServices.kt |
API publique du SDK 0.9.0-alpha.2. Chaque entrée donne la signature Kotlin et son contrat : sens de la valeur, conditions d’utilisation et effets à connaître. Choisissez les imports du module indiqué ci-dessus.
import nimby.SignalAction
import nimby.SignalActionRequest
import nimby.GameMod
import nimby.ToolMod
import nimby.ToolModBuilder
import nimby.toolModSignalAction
data class SignalAction(val id: String, val label: String, val whenMod: String, val service: String)Bouton facultatif d’un signal, relié à un service de mod outil. Le fournisseur absent masque le bouton sans supprimer le signal ni changer ses règles.
SignalAction.id
val id: StringIdentifiant stable de l’action, unique parmi les actions du modèle. Transmis au service lors du clic.
SignalAction.label
val label: StringTexte du bouton dans le panneau de signal ; accepte tr et reste distinct de id.
SignalAction.whenMod
val whenMod: StringIdentifiant technique du mod fournisseur. Sert à la disponibilité du bouton, sans imposer son installation.
SignalAction.service
val service: StringIdentifiant exact du service déclaré par le fournisseur avec service(...). Il ne s’agit pas d’un nom de fonction Kotlin.
SignalActionRequest
data class SignalActionRequest(
val sequence: Long, val signalId: Long, val action: String, val service: String,
val worldId: String, val generation: Long,
val panelToken: Long = 0, val originAction: String = action,
val value: Int? = null,
)Événement fourni au service après une action sur un signal. Conservez ses informations de session et de panneau pour répondre ; un clic ne valide pas à lui seul un plan de construction.
SignalActionRequest.sequence
val sequence: LongNuméro de l’événement reçu. Utilisez la requête fournie pour rattacher votre réponse à cette action, sans fabriquer une nouvelle séquence.
SignalActionRequest.signalId
val signalId: LongSignal source sélectionné. Il peut être supprimé ou modifié ensuite ; revalidez avant une mutation.
SignalActionRequest.action
val action: StringIdentifiant du bouton ou du champ modifié dans le panneau. Le service doit sélectionner explicitement le traitement correspondant.
SignalActionRequest.service
val service: StringService destinataire déclaré par le mod outil. Les événements suivants du même panneau reviennent à ce service.
SignalActionRequest.worldId
val worldId: StringIdentité de la partie ayant produit l’événement. Une requête d’un autre monde ne peut pas présenter ou confirmer le plan courant.
SignalActionRequest.generation
val generation: LongGénération de session à comparer avec le contexte actuel. Invalidez plan et aperçu lors d’un changement.
SignalActionRequest.panelToken
val panelToken: Long = 0Identité opaque du panneau d’origine. Transmettez la requête reçue aux méthodes de présentation plutôt que de reconstruire ce jeton.
SignalActionRequest.originAction
val originAction: String = actionAction initiale qui a ouvert le panneau, conservée lorsque action devient un bouton ou un champ de ce panneau.
SignalActionRequest.value
val value: Int? = nullNouvel entier validé d’un champ numérique ; null pour un bouton. Une saisie vide ou invalide n’est pas remplacée par zéro.
GameMod
abstract class GameModBase commune des mods de signalisation et d’outils. createMod renvoie une implémentation déclarée par le DSL ; un outil n’a pas besoin de modèle de signal.
GameMod.id
abstract val id: StringIdentifiant stable du mod, utilisé par whenMod pour joindre ses services. Réutilisez modInfo.id plutôt qu’un libellé traduit.
GameMod.title
abstract val title: StringTitre déclaré du mod, utilisé pour regrouper ses préférences et raccourcis dans Options → NRF Hub. Vient de modInfo.title avec la surcharge modInfo ; metadata(name=...) ne remplace pas ce titre. L’identité reste id.
GameMod.metadata
open val metadata: ModMetadata?Informations de présentation déclarées avec metadata ; null si aucune n’est fournie. Ne décrit pas les règles de l’outil.
GameMod.options
open val options: List<ModOption<*>>Options explicites du mod, vides par défaut. Gardez leurs objets pour lire value. La limite de 64 inclut les raccourcis des fenêtres ajoutés automatiquement par le SDK.
GameMod.windows
open val windows: List<ToolWindow>Fenêtres déclarées par le mod. Liste vide si aucune ; leur création n’exige pas de signal sélectionné.
GameMod.onWindowEvent
open fun onWindowEvent(request: ToolWindowEvent, context: ToolContext): UnitTraite un événement de fenêtre avec un contexte valable uniquement pendant cet appel. Le DSL dirige l’événement vers le handler de request.window.
GameMod.services
open val services: List<String>Identifiants des services enregistrés par le mod. Les actions externes doivent utiliser exactement ces identifiants.
GameMod.onSignalAction
open fun onSignalAction(request: SignalActionRequest, context: ToolContext): UnitTraite une action de signal dans le service destinataire. Gardez le callback court, validez la session et ne conservez pas ToolContext après le retour.
GameMod.onTick
open fun onTick(context: ToolContext): UnitCallback périodique pour avancer un travail borné, renouveler une présentation ou suivre un ticket. Il ne garantit pas une fréquence exacte ; retournez sans attendre.
GameMod.onStop
open fun onStop(): UnitLibère l’état local et les ressources lors d’un arrêt normal du mod. Aucun ToolContext n’est fourni ; ne comptez pas sur ce callback après un arrêt brutal.
ToolMod
class ToolMod : GameModMod outil construit par toolMod. Ses services et fenêtres reçoivent des événements sans définir d’aspect ni de consigne de signalisation ; constructeur réservé au SDK.
ToolMod.id
override val id: StringIdentifiant stable du mod, utilisé par whenMod pour joindre ses services. Réutilisez modInfo.id plutôt qu’un libellé traduit.
ToolMod.title
override val title: StringTitre déclaré du mod, utilisé pour regrouper ses préférences et raccourcis dans Options → NRF Hub. Vient de modInfo.title avec la surcharge modInfo ; metadata(name=...) ne remplace pas ce titre. L’identité reste id.
ToolMod.metadata
override val metadata: ModMetadata?Informations de présentation déclarées avec metadata ; null si aucune n’est fournie. Ne décrit pas les règles de l’outil.
ToolMod.windows
override val windows: List<ToolWindow>Fenêtres déclarées par le mod. Liste vide si aucune ; leur création n’exige pas de signal sélectionné.
ToolMod.options
override val options: List<ModOption<*>>Options explicites du mod, vides par défaut. Gardez leurs objets pour lire value. La limite de 64 inclut les raccourcis des fenêtres ajoutés automatiquement par le SDK.
ToolMod.services
override val services: List<String>Identifiants des services enregistrés par le mod. Les actions externes doivent utiliser exactement ces identifiants.
ToolMod.onSignalAction
override fun onSignalAction(request: SignalActionRequest, context: ToolContext): UnitTraite une action de signal dans le service destinataire. Gardez le callback court, validez la session et ne conservez pas ToolContext après le retour.
ToolMod.onTick
override fun onTick(context: ToolContext): UnitCallback périodique pour avancer un travail borné, renouveler une présentation ou suivre un ticket. Il ne garantit pas une fréquence exacte ; retournez sans attendre.
ToolMod.onStop
override fun onStop(): UnitLibère l’état local et les ressources lors d’un arrêt normal du mod. Aucun ToolContext n’est fourni ; ne comptez pas sur ce callback après un arrêt brutal.
ToolMod.onWindowEvent
override fun onWindowEvent(request: ToolWindowEvent, context: ToolContext): UnitTraite un événement de fenêtre avec un contexte valable uniquement pendant cet appel. Le DSL dirige l’événement vers le handler de request.window.
ToolModBuilder
class ToolModBuilderConfiguration reçue dans toolMod : services, fenêtres, métadonnées et callbacks de cycle de vie. Le SDK crée ce builder ; ne l’instanciez pas directement.
ToolModBuilder.options
fun options(vararg values: ModOption<*>): UnitEnregistre une ou plusieurs préférences globales ; plusieurs appels ajoutent des options. Refuse les identifiants dupliqués et plus de 64 options, raccourcis de fenêtres compris. Conservez les objets déclarés pour lire leur value.
ToolModBuilder.window
fun window(id: String, title: String, shortcut: String = "F8", handler: ToolContext.(ToolWindowEvent) -> Unit): UnitEnregistre une fenêtre autonome et son handler, jusqu’à 8 identifiants distincts. Le SDK crée son option de raccourci, modifiable par le joueur : F8 par défaut, vide pour désactiver. Format : Ctrl+, Alt+, Shift+ facultatifs dans cet ordre puis A–Z, 0–9, F1–F24 ou une touche nommée du guide. Les raccourcis non vides du mod doivent être distincts. showWindow fournit le contenu.
ToolModBuilder.metadata
fun metadata(author: String, description: String, name: String? = null): UnitDéclare auteur, description et nom optionnel pour les listes et fiches de mods du jeu. name et description acceptent tr. Ne remplace ni le titre du groupe dans Options → NRF Hub, ni les titres de fenêtres ; l’identité vient de mod.json.
ToolModBuilder.service
fun service(id: String, handler: ToolContext.(SignalActionRequest) -> Unit): UnitEnregistre un service avec identifiant unique, jusqu’à 32 par mod. Les callbacks d’un mod sont sérialisés ; un handler bloquant retarde les autres tâches de ce même mod.
ToolModBuilder.onTick
fun onTick(block: ToolContext.() -> Unit): UnitDéclare le travail périodique de l’outil. Traitez seulement les tâches en attente et rendez la main ; évitez lecture complète du réseau et attente à chaque tick.
ToolModBuilder.onStop
fun onStop(block: () -> Unit): UnitDéclare le nettoyage local à l’arrêt normal. Ne conserve ni n’utilise un contexte d’un callback précédent.
toolMod
fun toolMod(id: String, title: String, block: ToolModBuilder.() -> Unit): ToolModConstruit un outil avec identité explicite et au moins un service ou une fenêtre. Dans un projet Gradle, préférez toolMod(modInfo) pour utiliser l’identité générée.