ModServices — SDK 0.9 — Wiki NimbyRails France

Usage context

Module	Package	SDK source
Kotlin/Native	nimby	kotlin/src/nimby/ModServices.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.

Imports on this page

import nimby.SignalAction
import nimby.SignalActionRequest
import nimby.GameMod
import nimby.ToolMod
import nimby.ToolModBuilder
import nimby.toolMod

SignalAction

nimby · class

data class SignalAction(val id: String, val label: String, val whenMod: String, val service: String)

Optional signal button connected to a tool-mod service. An absent provider hides the button without removing the signal or changing its rules.

SignalAction.id

nimby · val

val id: String

Stable action identifier, unique among the model’s actions. Sent to the service on click.

SignalAction.label

nimby · val

val label: String

Button text in the signal panel; accepts tr and remains separate from id.

SignalAction.whenMod

nimby · val

val whenMod: String

Technical identifier of the provider mod. Controls button availability without requiring its installation.

SignalAction.service

nimby · val

val service: String

Exact service identifier declared by the provider through service(...). It is not a Kotlin function name.

SignalActionRequest

nimby · class

data class SignalActionRequest(
    val sequence: Long, val signalId: Long, val action: String, val service: String,
    val worldId: String, val generation: Long,
    val panelToken: Long = 0, val originAction: String = action,
    
    val value: Int? = null,
)

Event supplied to the service after a signal action. Retain its session and panel information when responding; a click alone does not validate a construction plan.

SignalActionRequest.sequence

nimby · val

val sequence: Long

Number of the received event. Use the supplied request to associate your response with this action; do not fabricate a sequence.

SignalActionRequest.signalId

nimby · val

val signalId: Long

Selected source signal. It can later be deleted or changed; revalidate before a mutation.

SignalActionRequest.action

nimby · val

val action: String

Identifier of the activated button or edited field in the panel. The service must explicitly select the corresponding action.

SignalActionRequest.service

nimby · val

val service: String

Target service declared by the tool mod. Subsequent events from the same panel return to this service.

SignalActionRequest.worldId

nimby · val

val worldId: String

Identity of the game world that produced the event. A request from another world cannot present or confirm the current plan.

SignalActionRequest.generation

nimby · val

val generation: Long

Session generation to compare with the current context. Invalidate plan and preview when it changes.

SignalActionRequest.panelToken

nimby · val

val panelToken: Long = 0

Opaque identity of the originating panel. Pass the received request to presentation methods instead of reconstructing this token.

SignalActionRequest.originAction

nimby · val

val originAction: String = action

Initial action that opened the panel, preserved when action becomes one of that panel’s buttons or fields.

SignalActionRequest.value

nimby · val

val value: Int? = null

New validated integer from a numeric field; null for a button. Empty or invalid input is not replaced with zero.

GameMod

nimby · class

abstract class GameMod

Common base for signalling and tool mods. createMod returns a DSL-declared implementation; a tool does not need a signal model.

GameMod.id

nimby · val

abstract val id: String

Stable mod identifier, used by whenMod to reach its services. Reuse modInfo.id rather than a translated label.

GameMod.title

nimby · val

abstract val title: String

Declared mod title, used to group its preferences and shortcuts in Options → NRF Hub. Comes from modInfo.title with the modInfo overload; metadata(name=...) does not replace it. Identity remains id.

GameMod.metadata

nimby · val

open val metadata: ModMetadata?

Presentation information declared through metadata; null when none is supplied. Does not describe tool rules.

GameMod.options

nimby · val

open val options: List<ModOption<*>>

Explicit mod options, empty by default. Retain their objects to read value. The limit of 64 includes window shortcuts added automatically by the SDK.

GameMod.windows

nimby · val

open val windows: List<ToolWindow>

Windows declared by the mod. Empty when none are declared; opening them requires no selected signal.

GameMod.onWindowEvent

nimby · fun

open fun onWindowEvent(request: ToolWindowEvent, context: ToolContext): Unit

Handles a window event with a context valid only during this call. The DSL routes the event to the handler for request.window.

GameMod.services

nimby · val

open val services: List<String>

Identifiers of services registered by the mod. External actions must use these exact identifiers.

GameMod.onSignalAction

nimby · fun

open fun onSignalAction(request: SignalActionRequest, context: ToolContext): Unit

Handles a signal action in its target service. Keep the callback short, validate the session and do not retain ToolContext after returning.

GameMod.onTick

nimby · fun

open fun onTick(context: ToolContext): Unit

Periodic callback to advance bounded work, renew presentation or poll a ticket. It does not guarantee an exact frequency; return without waiting.

GameMod.onStop

nimby · fun

open fun onStop(): Unit

Releases local state and resources during a normal mod shutdown. No ToolContext is supplied; do not rely on this callback after an abrupt termination.

ToolMod

nimby · class

class ToolMod : GameMod

Tool mod constructed through toolMod. Its services and windows receive events without defining signalling aspects or rules; construction is reserved for the SDK.

ToolMod.id

nimby · val

override val id: String

Stable mod identifier, used by whenMod to reach its services. Reuse modInfo.id rather than a translated label.

ToolMod.title

nimby · val

override val title: String

Declared mod title, used to group its preferences and shortcuts in Options → NRF Hub. Comes from modInfo.title with the modInfo overload; metadata(name=...) does not replace it. Identity remains id.

ToolMod.metadata

nimby · val

override val metadata: ModMetadata?

Presentation information declared through metadata; null when none is supplied. Does not describe tool rules.

ToolMod.windows

nimby · val

override val windows: List<ToolWindow>

Windows declared by the mod. Empty when none are declared; opening them requires no selected signal.

ToolMod.options

nimby · val

override val options: List<ModOption<*>>

Explicit mod options, empty by default. Retain their objects to read value. The limit of 64 includes window shortcuts added automatically by the SDK.

ToolMod.services

nimby · val

override val services: List<String>

Identifiers of services registered by the mod. External actions must use these exact identifiers.

ToolMod.onSignalAction

nimby · fun

override fun onSignalAction(request: SignalActionRequest, context: ToolContext): Unit

Handles a signal action in its target service. Keep the callback short, validate the session and do not retain ToolContext after returning.

ToolMod.onTick

nimby · fun

override fun onTick(context: ToolContext): Unit

Periodic callback to advance bounded work, renew presentation or poll a ticket. It does not guarantee an exact frequency; return without waiting.

ToolMod.onStop

nimby · fun

override fun onStop(): Unit

Releases local state and resources during a normal mod shutdown. No ToolContext is supplied; do not rely on this callback after an abrupt termination.

ToolMod.onWindowEvent

nimby · fun

override fun onWindowEvent(request: ToolWindowEvent, context: ToolContext): Unit

Handles a window event with a context valid only during this call. The DSL routes the event to the handler for request.window.

ToolModBuilder

nimby · class

class ToolModBuilder

Configuration received inside toolMod: services, windows, metadata and lifecycle callbacks. The SDK creates this builder; do not instantiate it directly.

ToolModBuilder.options

nimby · fun

fun options(vararg values: ModOption<*>): Unit

Registers one or more global preferences; multiple calls append options. Rejects duplicate IDs and more than 64 options including window shortcuts. Keep the declared objects to read their value.

ToolModBuilder.window

nimby · fun

fun window(id: String, title: String, shortcut: String = "F8", handler: ToolContext.(ToolWindowEvent) -> Unit): Unit

Registers a standalone window and handler, up to 8 distinct IDs. The SDK creates its player-configurable shortcut option: F8 by default, empty to disable. Format: optional Ctrl+, Alt+, Shift+ in that order followed by A–Z, 0–9, F1–F24 or a named key from the guide. Nonempty shortcuts within the mod must be distinct. showWindow supplies the content.

ToolModBuilder.metadata

nimby · fun

fun metadata(author: String, description: String, name: String? = null): Unit

Declares the author, description and optional name for the game’s mod lists and details. name and description accept tr. Replaces neither the group heading in Options → NRF Hub nor window titles; identity comes from mod.json.

ToolModBuilder.service

nimby · fun

fun service(id: String, handler: ToolContext.(SignalActionRequest) -> Unit): Unit

Registers a service with a unique identifier, up to 32 per mod. A mod’s callbacks are serialized; a blocking handler delays that same mod’s other tasks.

ToolModBuilder.onTick

nimby · fun

fun onTick(block: ToolContext.() -> Unit): Unit

Declares periodic tool work. Process only pending tasks and return; avoid a full network read and waiting on every tick.

ToolModBuilder.onStop

nimby · fun

fun onStop(block: () -> Unit): Unit

Declares local cleanup during normal shutdown. Must not retain or use a context from an earlier callback.

toolMod

nimby · fun

fun toolMod(id: String, title: String, block: ToolModBuilder.() -> Unit): ToolMod

Builds a tool with an explicit identity and at least one service or window. In a Gradle project, prefer toolMod(modInfo) to use the generated identity.