NRF SDK 0.9Référence
ModControl
Baux de recette, commandes temporaires et réponses du mod.
Contexte d’utilisation
| Module | Package | Source SDK |
|---|---|---|
| Kotlin/JVM | fr.nimby.sdk | kotlin-client/src/main/kotlin/fr/nimby/sdk/ModControl.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 fr.nimby.sdk.ControlOperation
import fr.nimby.sdk.TrainControlMode
import fr.nimby.sdk.TrainControlState
import fr.nimby.sdk.ControlRequest
import fr.nimby.sdk.ControlResponse
import fr.nimby.sdk.ModControlSessionControlOperation
enum class ControlOperation(val code: Int) {
Status(0),
Acquire(1),
Renew(2),
Release(3),
ForceSignal(4),
RestoreSignal(5),
Train(6),
RestoreTrain(7),
Setting(8),
RestoreSetting(9),
Clear(10),
ReadSignal(11),
ReadTrain(12)
}Opérations de contrôle temporaire. Préférer les méthodes de ModControlSession ; les codes d’aspect et indices de case sont définis par le mod ciblé.
ControlOperation.code
val code: IntCode de l’opération transmis par le client ; utiliser l’enum, sans fabriquer une valeur numérique.
ControlOperation.Status
Status(0)Lire le statut et les compteurs de forçages du mod.
ControlOperation.Acquire
Acquire(1)Acquérir le bail temporaire de contrôle.
ControlOperation.Renew
Renew(2)Renouveler explicitement le bail existant.
ControlOperation.Release
Release(3)Libérer le bail et ses forçages.
ControlOperation.ForceSignal
ForceSignal(4)Demander un aspect temporaire accepté par le mod.
ControlOperation.RestoreSignal
RestoreSignal(5)Retirer le forçage d’un signal.
ControlOperation.Train
Train(6)Demander une contrainte temporaire sur un train.
ControlOperation.RestoreTrain
RestoreTrain(7)Retirer la contrainte temporaire du train.
ControlOperation.Setting
Setting(8)Forcer temporairement une case de réglage.
ControlOperation.RestoreSetting
RestoreSetting(9)Retirer le forçage de cette case.
ControlOperation.Clear
Clear(10)Retirer tous les forçages du bail, sans renouvellement automatique.
ControlOperation.ReadSignal
ReadSignal(11)Lire la dernière décision évaluée du signal.
ControlOperation.ReadTrain
ReadTrain(12)Lire l’état de la contrainte du train ; pas une permission.
TrainControlMode
enum class TrainControlMode(val code: Int) {
SpeedLimit(0),
PhysicalClearance(1),
Stop(2)
}Mode d’une contrainte de recette temporaire. La vitesse doit être finie et positive sauf Stop, qui exige zéro. Les protections du jeu restent applicables.
TrainControlMode.code
val code: IntCode du mode utilisé par le client ; choisir une valeur nommée de l’enum.
TrainControlMode.SpeedLimit
SpeedLimit(0)Plafond numérique de vitesse, sans demande de marche avec dégagement physique.
TrainControlMode.PhysicalClearance
PhysicalClearance(1)Plafond de vitesse avec contrôle de dégagement physique ; ne promet pas un passage contre toute autre protection.
TrainControlMode.Stop
Stop(2)Contrainte d’arrêt, avec speedMps égal à zéro.
TrainControlState
enum class TrainControlState {
Absent,
AwaitingExit,
Active,
Completed,
Cancelled
}État observé d’une contrainte de train. La valeur renvoyée par readTrain.active correspond à cette enum ; aucun état n’est une permission native de mouvement.
TrainControlState.Absent
AbsentAucune contrainte rapportée.
TrainControlState.AwaitingExit
AwaitingExitContrainte en attente de rattachement à sa sortie ; peut aussi signaler une demande pas encore observée comme appliquée.
TrainControlState.Active
ActiveContrainte observée active.
TrainControlState.Completed
CompletedContrainte observée terminée.
TrainControlState.Cancelled
CancelledContrainte annulée après réinitialisation du trajet.
ControlRequest
data class ControlRequest(
val operation: ControlOperation, val owner: Long = 0, val generation: Long = 0,
val leaseMillis: Int = 0, val objectId: Long = 0, val exitSignal: Long = 0,
val speedMps: Double = 0.0, val mode: TrainControlMode = TrainControlMode.SpeedLimit,
val releaseByRear: Boolean = false, val value: Int = 0, val settingIndex: Int = 0
)Demande détaillée de contrôle. Pour les recettes ordinaires, ModControlSession renseigne owner et generation et fournit les méthodes nommées. Ne pas fabriquer une identité de bail.
ControlRequest.operation
val operation: ControlOperationAction demandée ; détermine les champs utiles.
ControlRequest.owner
val owner: Long = 0Identité opaque non nulle du bail pour une mutation ; fournie par la session de contrôle.
ControlRequest.generation
val generation: Long = 0Génération du monde observée par le mod ; doit correspondre au bail.
ControlRequest.leaseMillis
val leaseMillis: Int = 0Durée de bail demandée pour Acquire/Renew, de 1 000 à 60 000 ms.
ControlRequest.objectId
val objectId: Long = 0Identité observée du signal ou train ciblé, selon l’opération.
ControlRequest.exitSignal
val exitSignal: Long = 0Signal de sortie associé à la contrainte, ou zéro si aucune sortie explicite n’est fournie.
ControlRequest.speedMps
val speedMps: Double = 0.0Plafond demandé en m/s : zéro pour Stop, strictement positif pour les autres modes.
ControlRequest.mode
val mode: TrainControlMode = TrainControlMode.SpeedLimitMode explicite de la contrainte de train.
ControlRequest.releaseByRear
val releaseByRear: Boolean = falsetrue : libération après passage de la queue à la sortie ; false : après la tête.
ControlRequest.value
val value: Int = 0Code d’aspect pour ForceSignal ; 0/1 pour Setting. Sa signification dépend de l’opération et du mod.
ControlRequest.settingIndex
val settingIndex: Int = 0Indice de case du modèle de signal ciblé ; pas un identifiant universel de réglage.
ControlResponse
data class ControlResponse(
val capabilities: Int, val generation: Long, val remainingMillis: Long,
val signalCount: Int, val trainCount: Int, val settingCount: Int,
val active: Int, val aspect: Int, val reason: Int,
val speedMps: Double, val exitSignal: Long, val detail: String
)Réponse du mod à une demande. Les compteurs concernent les forçages temporaires. Les champs active/aspect/reason dépendent de l’opération ; interpréter avec le contrat du mod.
ControlResponse.capabilities
val capabilities: IntCapacités annoncées par le mod ; ne prouve pas qu’une mutation particulière sera acceptée.
ControlResponse.generation
val generation: LongGénération du monde actuellement observée par le mod.
ControlResponse.remainingMillis
val remainingMillis: LongDurée restante du bail en millisecondes ; ne se met pas à jour dans cette copie.
ControlResponse.signalCount
val signalCount: IntNombre de forçages de signaux demandés, pas nombre de signaux gérés.
ControlResponse.trainCount
val trainCount: IntNombre de contraintes temporaires demandées sur les trains.
ControlResponse.settingCount
val settingCount: IntNombre de cases temporairement forcées.
ControlResponse.active
val active: IntPour ReadTrain : état TrainControlState. Pour ReadSignal : 0 non forcé, 1 forçage demandé, 2 décision observée conforme au forçage. Ne décrit pas une permission.
ControlResponse.aspect
val aspect: IntCode d’aspect de la dernière décision lue ; sa signification appartient au modèle du mod.
ControlResponse.reason
val reason: IntCode de raison de la dernière décision lue ; à interpréter avec le mod ciblé.
ControlResponse.speedMps
val speedMps: DoublePlafond associé à la contrainte lue, en mètres par seconde ; pas vitesse mesurée du train.
ControlResponse.exitSignal
val exitSignal: LongIdentité de sortie associée à la contrainte rapportée.
ControlResponse.detail
val detail: StringDétail textuel renvoyé par le mod ; utile au journal, sans remplacer les champs structurés.
ModControlSession
class ModControlSession : AutoCloseableBail temporaire obtenu avec game.mods.control. Les forçages ne réécrivent pas les réglages sauvegardés. Expiration et fermeture libèrent les surcharges ; aucun renouvellement ni essai automatique.
ModControlSession.modId
val modId: StringIdentifiant du mod effectivement ciblé par cette session.
ModControlSession.owner
val owner: LongIdentité opaque du propriétaire du bail, fournie à l’acquisition.
ModControlSession.generation
val generation: LongGénération observée lors de l’acquisition ; une autre partie invalide la session.
ModControlSession.renew
fun renew(leaseMillis: Int = 5000): ControlResponseRenouvelle explicitement ce bail pour 1 000 à 60 000 ms ; ne recrée pas un bail expiré silencieusement.
ModControlSession.forceSignal
fun forceSignal(signal: Long, aspect: Int): ControlResponseDemande une indication temporaire sur un signal connu du mod. L’aspect doit être accepté par son modèle ; relire la décision pour constater son application.
ModControlSession.restoreSignal
fun restoreSignal(signal: Long): ControlResponseRetire le forçage du signal pour laisser le modèle recalculer sa décision.
ModControlSession.setSetting
fun setSetting(signal: Long, index: Int, value: Boolean): ControlResponseForce une case par son indice dans le modèle du signal, sans modifier sa valeur sauvegardée.
ModControlSession.restoreSetting
fun restoreSetting(signal: Long, index: Int): ControlResponseRetire la surcharge temporaire de cette case ; le réglage sauvegardé redevient la source.
ModControlSession.constrainTrain
fun constrainTrain(train: Long, speedMps: Double, mode: TrainControlMode,
exitSignal: Long = 0, releaseByRear: Boolean = false): ControlResponseDemande une contrainte temporaire : vitesse finie en m/s, zéro pour Stop et positive sinon. Le train et toute sortie explicite doivent être connus du mod. Relire l’état ; l’acceptation ne prouve pas un mouvement.
ModControlSession.restoreTrain
fun restoreTrain(train: Long): ControlResponseRetire la contrainte temporaire demandée pour ce train.
ModControlSession.readSignal
fun readSignal(signal: Long): ControlResponseLit la dernière décision évaluée du signal ; ne force aucune nouvelle évaluation et ne renouvelle pas le bail.
ModControlSession.readTrain
fun readTrain(train: Long): ControlResponseLit l’état de contrainte du train ; active correspond à TrainControlState, pas à une permission.
ModControlSession.clear
fun clear(): ControlResponseRetire toutes les surcharges de cette session ; ne remplace pas close pour libérer le bail.
ModControlSession.close
override fun close(): UnitDemande la libération une seule fois puis ferme la session locale, même si la libération échoue. Aucun appel ensuite ; l’expiration reste le filet de récupération des surcharges.