NRF SDK 0.9Reference
Gradle project and Native package
Public contract of the fr.nimbyrails.mod plugin: kit, identity, manifest, resources, tasks and outputs.
Kit and plugin selection
This page is for Kotlin/Native signal mods and in-game tools. For a Kotlin/JVM application, follow the connection guide. The fr.nimbyrails.mod plugin is supplied by gradle-repository in the kit; settings.gradle.kts selects the gradlePluginVersion from sdk.json.
| Input | Contract |
|---|---|
| nrfSdkDir | Preferred Gradle property: path to the extracted directory containing sdk.json. A relative path is resolved from the project. |
| NRF_KOTLIN_SDK | Environment variable used when nrfSdkDir is absent. |
| sdk.json | Describes the selected kit. The plugin checks required files, format, Kotlin, its own version, the SDK range and declared game executables. |
| fr.nimbyrails.mod | Applies Kotlin configuration and supplies compilation dependencies. The Windows kit creates the windows target and windowsTest tasks. |
mod.json fields
| Field | Type and accepted value | Meaning |
|---|---|---|
| id | String: initial lowercase letter, followed by lowercase letters, digits or hyphens; 1–64 characters. | Project identity for the Hub. |
| name | String that is non-empty after trimming. | Readable name and modInfo title. |
| modId | String of 1–70 letters, digits, hyphens or underscores. | Directory identity and package prefix. |
| module | String of 1–100 characters; initial letter, then letters, digits, hyphens or underscores. No extension. | Base name of mod files. |
| version | X.Y.Z, X.Y.Z-alpha.N or X.Y.Z-beta.N; no leading zeroes, X/Y/Z from 0 to 9999, N from 1 to 999999999. | The mod’s own version; alpha, beta or stable also determines its channel. |
| language | "kotlin-native" | Language expected by this plugin. |
| sdkMin · sdkMaxExclusive | Versions in the same format, with sdkMin strictly below sdkMaxExclusive. | Accepted range: inclusive lower bound, exclusive upper bound. |
| gameSha256 | Non-empty list of 64-character hexadecimal SHA-256 strings. | Every declared game executable must be supported by the kit. |
For equal X.Y.Z numbers, alpha precedes beta, then the stable version; prerelease numbers are compared numerically. Declare compatibility you have verified. These build checks do not replace an in-game test.
createMod and generated identity
package nimby.mod
// createMod() assembles your signalMod or toolMod declaration.
// modInfo is supplied by the plugin from mod.json.Provide createMod() in package nimby.mod. For a signal, the result is a SignallingMod built with signalMod(modInfo); a tool uses toolMod and its dedicated contract. The plugin generates modInfo from id and name: keep that single source of identity.
Catalogue generation evaluates the declaration outside the game. createMod and its initialisers must therefore describe the mod without accessing a game or printing to standard output. Put game interactions in the designated callbacks and diagnostics in logging functions.
Files included in the package
| Source | Destination or role |
|---|---|
| src/main/kotlin/ | Compiled sources; they are not copied into the distribution as source files. |
| src/test/kotlin/ | Tests run by test tasks, not included in the package. |
| assets/ | Contents at the package root, except generated mod.txt and nrf-mod.ini. |
| imgs/ · config/ · docs/ | Optional directories retained under the same name. |
| README.md · LICENSE · LICENSE.txt | Optional files copied to the root. |
| licenses/ | Mod notices in licenses/mod; SDK notices are added in licenses/sdk. |
On Windows, the package contains <module>.dll and <module>Kotlin.dll. Distribute the complete directory with its resources and licences. SDK components used to verify the package are not files to add manually to your mod.
Choose a Gradle task
| Task | Windows result |
|---|---|
| windowsTest | Runs Kotlin tests; reports in build/gradle/reports/tests/. |
| generateModIdentity | Generates modInfo from mod.json; called automatically by dependent compilations. |
| generateDebugGameManifest · generateReleaseGameManifest | Evaluates the compiled declaration and generates mod.txt and nrf-metadata.json for the selected variant. |
| generateModManifest | Generates nrf-mod.ini for the package. |
| assembleDebugMod · assembleReleaseMod | Assembles in build/gradle/mod/debug or release. This step alone does not run the full acceptance suite. |
| verifyNativeMod | Assembles the Release variant and checks its lifecycle without the game. |
| modArchive | Assembles Release, depends on tests and verifyNativeMod, then produces the ZIP. |
| hubManifest | Builds the ZIP and generates both descriptors with actual size and hash. |
| packageMod | Distribution entry point: depends on hubManifest. |
| build | Assembly, verification, tests and distribution. |
| clean | Removes build outputs in build/gradle; does not uninstall the game profile. |
.\gradlew.bat windowsTest assembleReleaseMod verifyNativeMod
.\gradlew.bat packageModDependent tasks may be UP-TO-DATE when inputs have not changed. The ZIP is in build/gradle/distributions, is named <modId>-<version>-windows-x64.zip and contains a <modId>-<version> root directory.
Local descriptor and publication URL
hubManifest writes project.json and project-windows-x64.json. By default their url names the local ZIP. Size and SHA-256 are calculated from the produced file, not entered in mod.json.
The releaseBaseUrl Gradle option serves the official repository publication workflow. In this plugin version it accepts only https://github.com/NimbyRails-France/<id>/releases/download/v<version>, using mod.json id and version, and appends the ZIP name. It prepares a URL; it does not publish anything. For other hosting, retain the local descriptor and use your project’s distribution process.