NRF SDK 0.9Reference
ModControl
Scenario leases, temporary commands and mod responses.
Usage context
| Module | Package | SDK source |
|---|---|---|
| Kotlin/JVM | fr.nimby.sdk | kotlin-client/src/main/kotlin/fr/nimby/sdk/ModControl.kt |
Public API for SDK 0.9.0-alpha.2. Each entry provides the Kotlin signature and its contract: what the value means, conditions of use and effects to understand. Choose imports from the module shown above.
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)
}Temporary control operations. Prefer ModControlSession methods; aspect codes and checkbox indices are defined by the target mod.
ControlOperation.code
val code: IntOperation code sent by the client; use the enum without inventing a numeric value.
ControlOperation.Status
Status(0)Read mod status and override counts.
ControlOperation.Acquire
Acquire(1)Acquire the temporary control lease.
ControlOperation.Renew
Renew(2)Explicitly renew the existing lease.
ControlOperation.Release
Release(3)Release the lease and its overrides.
ControlOperation.ForceSignal
ForceSignal(4)Request a temporary aspect accepted by the mod.
ControlOperation.RestoreSignal
RestoreSignal(5)Remove a signal override.
ControlOperation.Train
Train(6)Request a temporary train constraint.
ControlOperation.RestoreTrain
RestoreTrain(7)Remove the temporary train constraint.
ControlOperation.Setting
Setting(8)Temporarily override a checkbox setting.
ControlOperation.RestoreSetting
RestoreSetting(9)Remove that checkbox override.
ControlOperation.Clear
Clear(10)Remove all lease overrides, without automatic renewal.
ControlOperation.ReadSignal
ReadSignal(11)Read the signal’s latest evaluated decision.
ControlOperation.ReadTrain
ReadTrain(12)Read train-constraint state; not a permission.
TrainControlMode
enum class TrainControlMode(val code: Int) {
SpeedLimit(0),
PhysicalClearance(1),
Stop(2)
}Mode of a temporary test constraint. Speed must be finite and positive except for Stop, which requires zero. Game protections still apply.
TrainControlMode.code
val code: IntMode code used by the client; choose a named enum value.
TrainControlMode.SpeedLimit
SpeedLimit(0)Numeric speed ceiling without requesting physical-clearance running.
TrainControlMode.PhysicalClearance
PhysicalClearance(1)Speed ceiling with physical-clearance checks; does not promise passage against every other protection.
TrainControlMode.Stop
Stop(2)Stop constraint, with speedMps equal to zero.
TrainControlState
enum class TrainControlState {
Absent,
AwaitingExit,
Active,
Completed,
Cancelled
}Observed train-constraint state. readTrain.active corresponds to this enum; no state is a native movement permission.
TrainControlState.Absent
AbsentNo reported constraint.
TrainControlState.AwaitingExit
AwaitingExitConstraint awaiting its exit binding; can also indicate a request not yet observed as applied.
TrainControlState.Active
ActiveConstraint observed as active.
TrainControlState.Completed
CompletedConstraint observed as completed.
TrainControlState.Cancelled
CancelledConstraint cancelled after a route reset.
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
)Detailed control request. For ordinary test scenarios, ModControlSession supplies owner and generation and provides named methods. Do not invent a lease identity.
ControlRequest.operation
val operation: ControlOperationRequested action; determines relevant fields.
ControlRequest.owner
val owner: Long = 0Nonzero opaque lease identity for mutations; supplied by the control session.
ControlRequest.generation
val generation: Long = 0World generation observed by the mod; must match the lease.
ControlRequest.leaseMillis
val leaseMillis: Int = 0Requested lease duration for Acquire/Renew, from 1,000 to 60,000 ms.
ControlRequest.objectId
val objectId: Long = 0Observed identity of the target signal or train, according to the operation.
ControlRequest.exitSignal
val exitSignal: Long = 0Constraint-associated exit signal, or zero if no explicit exit is supplied.
ControlRequest.speedMps
val speedMps: Double = 0.0Requested ceiling in m/s: zero for Stop, strictly positive for other modes.
ControlRequest.mode
val mode: TrainControlMode = TrainControlMode.SpeedLimitExplicit train-constraint mode.
ControlRequest.releaseByRear
val releaseByRear: Boolean = falsetrue: release after the rear passes the exit; false: after the head.
ControlRequest.value
val value: Int = 0Aspect code for ForceSignal; 0/1 for Setting. Meaning depends on operation and mod.
ControlRequest.settingIndex
val settingIndex: Int = 0Checkbox index in the target signal model; not a universal setting identity.
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
)Mod response to a request. Counts concern temporary overrides. active/aspect/reason depend on the operation; interpret them using the mod contract.
ControlResponse.capabilities
val capabilities: IntCapabilities advertised by the mod; does not prove a particular mutation will be accepted.
ControlResponse.generation
val generation: LongWorld generation currently observed by the mod.
ControlResponse.remainingMillis
val remainingMillis: LongRemaining lease duration in milliseconds; does not update within this copy.
ControlResponse.signalCount
val signalCount: IntNumber of requested signal overrides, not managed signal count.
ControlResponse.trainCount
val trainCount: IntNumber of requested temporary train constraints.
ControlResponse.settingCount
val settingCount: IntNumber of temporarily overridden checkboxes.
ControlResponse.active
val active: IntFor ReadTrain: TrainControlState. For ReadSignal: 0 not overridden, 1 override requested, 2 observed decision matches the override. Does not describe permission.
ControlResponse.aspect
val aspect: IntAspect code of the latest read decision; meaning belongs to the mod model.
ControlResponse.reason
val reason: IntReason code of the latest read decision; interpret using the target mod.
ControlResponse.speedMps
val speedMps: DoubleCeiling associated with the read constraint in metres per second; not measured train speed.
ControlResponse.exitSignal
val exitSignal: LongExit identity associated with the reported constraint.
ControlResponse.detail
val detail: StringText detail returned by the mod; useful in logs without replacing structured fields.
ModControlSession
class ModControlSession : AutoCloseableTemporary lease obtained through game.mods.control. Overrides do not rewrite saved settings. Expiration and closing release overlays; no automatic renewal or retries.
ModControlSession.modId
val modId: StringIdentity of the mod actually targeted by this session.
ModControlSession.owner
val owner: LongOpaque lease-owner identity supplied on acquisition.
ModControlSession.generation
val generation: LongGeneration observed at acquisition; another game invalidates the session.
ModControlSession.renew
fun renew(leaseMillis: Int = 5000): ControlResponseExplicitly renews this lease for 1,000 to 60,000 ms; does not silently recreate an expired lease.
ModControlSession.forceSignal
fun forceSignal(signal: Long, aspect: Int): ControlResponseRequests a temporary indication on a signal known to the mod. Its model must accept the aspect; read the decision again to observe application.
ModControlSession.restoreSignal
fun restoreSignal(signal: Long): ControlResponseRemoves the signal override so the model can recalculate its decision.
ModControlSession.setSetting
fun setSetting(signal: Long, index: Int, value: Boolean): ControlResponseOverrides a checkbox by its index in the signal model, without modifying its saved value.
ModControlSession.restoreSetting
fun restoreSetting(signal: Long, index: Int): ControlResponseRemoves this checkbox’s temporary override; the saved setting becomes the source again.
ModControlSession.constrainTrain
fun constrainTrain(train: Long, speedMps: Double, mode: TrainControlMode,
exitSignal: Long = 0, releaseByRear: Boolean = false): ControlResponseRequests a temporary constraint: finite speed in m/s, zero for Stop and positive otherwise. The train and any explicit exit must be known to the mod. Read state again; acceptance does not prove movement.
ModControlSession.restoreTrain
fun restoreTrain(train: Long): ControlResponseRemoves the temporary constraint requested for this train.
ModControlSession.readSignal
fun readSignal(signal: Long): ControlResponseReads the signal’s latest evaluated decision; neither forces a new evaluation nor renews the lease.
ModControlSession.readTrain
fun readTrain(train: Long): ControlResponseReads train-constraint state; active corresponds to TrainControlState, not permission.
ModControlSession.clear
fun clear(): ControlResponseRemoves all overlays from this session; does not replace close for releasing the lease.
ModControlSession.close
override fun close(): UnitRequests release once, then closes the local session even if release fails. No further calls; expiry remains the override-recovery fallback.