Connect a Kotlin/JVM application

Choose the right environment #

This path is for external Kotlin/JVM applications: dashboards, diagnostics and test recipes. You need the SDK JVM client, its compatible library and a running NIMBY Rails game. A mod loaded inside the game uses nimby callbacks and their ToolContext; it does not open this connection.

Select and close explicitly #

Nimby.runningGames() returns GameProcess values containing a pid and executable name. If several games exist, let the user choose and pass that PID to Nimby.connect. Without a PID, connect requires exactly one discovered game; it does not pick the first. Discovery does not guarantee that opening will still succeed a moment later.

Keep Game open for the lifetime of your screen or service. use closes a one-off connection even when an exception occurs. A long-running application closes its connection on shutdown or when switching games. Game.advanced exposes detailed operations on that same connection: do not close it separately.

First complete reading example #

package wiki.connection

import fr.nimby.sdk.Nimby
import fr.nimby.sdk.TrainQuery
import java.nio.file.Path

fun printTrainSpeeds(sdk: Path, processId: Int) {
    Nimby.connect(sdk, processId).use { game ->
        val snapshot = game.trains.snapshot(query = TrainQuery(
            includeService = false,
            includeLocations = false,
        ))
        snapshot.trains.forEach { train ->
            // A presentation zero does not prove the train is stopped.
            val speed = train.speedKmh.takeUnless { train.speedDefaulted }
            println("${train.name} : ${speed ?: "unknown"} km/h")
        }
        println(game.clock.read()?.toInstant())
    }
}

Call printTrainSpeeds with the SDK library path and chosen PID. The function prints a name and speed for each train, or “unknown” when the game did not provide a reliable measurement. The clock is read separately; use snapshot.clock when you need the time associated with the batch.