Set up your project

Prepare the tools and kit #

• Use Windows x64, IntelliJ IDEA and JDK 21. Select that JDK as the Gradle JVM in IntelliJ.
• In the Hub, prepare the game SDK and select a matching Kotlin kit. The kit builds your mods; the installed SDK runs them.
• In developer settings, use “Download a Kotlin kit”, then “Download and use”. Keep the path to the directory containing sdk.json.

Create a project with the Hub #

• Select the “Develop” profile. In Settings, choose “Local mod projects” and the matching “Kotlin SDK kit for builds”. An IntelliJ path is optional when creating the project.
• In Mods, click “Create a project”, then choose “Signal” for a signal model or “In-game tool” for a tool available inside NIMBY Rails.
• Enter the ID, name, author, description and initial version. An ID such as my-first-mod uses lowercase letters, digits and hyphens, starting with a letter. Check the displayed destination directory and kit version.
• Click “Create project”. The Hub prepares mod.json, Gradle and its wrapper, Entry.kt and tests. The Signal template also includes textures in assets. Choose a new ID and directory: an existing project is not replaced.
• On the project card, use “Build”, then “Open in IntelliJ” to customize the sources. Creation prepares the project; building prepares its local package. Keep the build kit and installed SDK compatible before testing in the game.

The generated project can then be edited like any Kotlin project. The following sections explain how to create the same basic files manually; they help explain each file and should not be copied over a project you already created.

Create the Gradle project manually #

In IntelliJ, create a Kotlin project with Gradle and the Kotlin DSL. Keep its Gradle wrapper. Before replacing generated files, run the following command in its terminal, then remove the demonstration Main.kt.

.\gradlew.bat wrapper --gradle-version 8.14.3

Create gradle.properties with the actual path to your kit. Then replace settings.gradle.kts and build.gradle.kts with these contents and reload the Gradle projects.

nrfSdkDir=C:/NRF/kotlin-sdk

pluginManagement {
    val sdk = providers.gradleProperty("nrfSdkDir")
        .orElse(providers.environmentVariable("NRF_KOTLIN_SDK"))
        .orNull ?: error("Configure nrfSdkDir with the Kotlin kit directory.")
    repositories {
        maven { url = uri(file(sdk).resolve("gradle-repository")) }
        gradlePluginPortal()
        mavenCentral()
    }
    val metadata = groovy.json.JsonSlurper()
        .parseText(file(sdk).resolve("sdk.json").readText().removePrefix("\uFEFF")) as Map<*, *>
    plugins {
        id("fr.nimbyrails.mod") version (metadata["gradlePluginVersion"] as String)
    }
}
dependencyResolutionManagement { repositories { mavenCentral() } }
rootProject.name = "mon-premier-mod"

plugins { id("fr.nimbyrails.mod") }

The plugin version comes from sdk.json and its repository is included in the kit. You do not need to choose a separate Kotlin version or write a native adapter. nrfSdkDir takes precedence over the NRF_KOTLIN_SDK environment variable.

Declare identity and compatibility #

Create this manifest at the project root. The identifiers describe your mod; gameSha256 describes the game executables against which you validate it. This example value matches the game supported by the documented kit; it cannot be used to declare a different executable compatible.

{
  "id": "mon-premier-mod",
  "name": "Mon premier mod",
  "modId": "MonPremierMod",
  "module": "MonPremierMod",
  "version": "0.1.0",
  "language": "kotlin-native",
  "sdkMin": "0.9.0-alpha.1",
  "sdkMaxExclusive": "0.10.0",
  "gameSha256": ["fff49ac21720abfc824c2b4f68b862727630eb0db71cfe1f9ea8f685d0db10ae"]
}

Build, verify, then activate #