Create signals with a construction ticket

Prepare, submit once, then inspect #

JVM construction is experimental and requires the SDK construction feature. Your application calculates and displays its plan, then receives explicit confirmation before creating anything. Unlike the Native tool API, Game.Construction does not provide a preview method: it exposes prepare, create, poll and undo.

• Obtain the source signal and tracks from the current game. After a game or plan change, abandon the ticket and have a new plan confirmed.
• A batch contains 1 to 64 distinct positions. Each fraction is finite and strictly between 0 and 1; each direction is +1 or −1.
• prepare supplies a ticket tied to that game and editor. Retain every nonzero token before submitting create; wait for READY.
• After submission, poll observes the outcome. Do not call create again to wait for completion.

package wiki.constructiontickets

import fr.nimby.sdk.ConstructionResult
import fr.nimby.sdk.ConstructionState
import fr.nimby.sdk.Game
import fr.nimby.sdk.Position

class ConfirmedPlacement(
    private val game: Game,
    private val sourceSignal: Long,
    confirmedPositions: List<Position>,
) {
    private val positions = confirmedPositions.toList()
    var ticket: Long? = null
        private set
    private var prepareSubmitted = false
    private var submitted = false
    private var undoSubmitted = false

    fun prepare(): ConstructionResult {
        check(!prepareSubmitted)
        prepareSubmitted = true
        val result = game.construction.prepare(sourceSignal)
        if (result.token != 0L) ticket = result.token
        return result
    }

    fun createOnce(): ConstructionResult {
        val token = checkNotNull(ticket)
        check(!submitted)
        val current = game.construction.poll(token)
        if (current.state != ConstructionState.READY) return current
        submitted = true
        return game.construction.create(token, sourceSignal, positions)
    }

    fun inspect(): ConstructionResult = game.construction.poll(checkNotNull(ticket))

    fun undoIfAvailable(): ConstructionResult {
        val token = checkNotNull(ticket)
        check(!undoSubmitted)
        val current = game.construction.poll(token)
        if (!current.canUndo) return current
        undoSubmitted = true
        return game.construction.undo(token)
    }
}

Call prepare once; your interface may then inspect the ticket at a moderate cadence. Once the state becomes READY, createOnce submits the batch once. The submitted marker is set before writing: if the write throws, inspect remains available and another creation is refused locally. The object remains attached to the Game that created it.

Respect undo availability #

canUndo describes the ticket’s observed state. A subsequent editor command may invalidate undo; reread the result before offering undo and check its response too. Do not infer undo availability merely from createdIds being present. The example sets undoSubmitted before writing and refuses a second call, even after an exception: the ticket can still be inspected without repeating undo.