KMP integration guide

Step 1

Add the dependency

Rentile has one coordinate for common code. Your project also needs JetBrains' public Compose repository for the Skiko platform artifacts used by the renderer. The content filter keeps that repository limited to Skiko.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://maven.pkg.jetbrains.space/public/p/compose/dev") {
            content { includeGroup("org.jetbrains.skiko") }
        }
    }
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.rohittp.rentile:kmp:<version>")
        }
    }
}

Step 2

Give Rentile transport and storage

Rentile does not force an HTTP client or database on your app. You provide a ResourceTransport for fetching bytes and a RawResourceStore for storing complete, validated responses. Both interfaces live in common Kotlin.

val configuration = RentileConfiguration(
    transport = AppResourceTransport(httpClient),
    rawResourceStore = AppRawResourceStore(cacheDirectory),
)

val rasterizer: BasemapRasterizer =
    Rentile.create(configuration)

Optional configuration

The defaults are enough to start. Add a CredentialProvider or MapSessionProvider when your map provider needs them. You can also tune concurrency and safety limits, or attach redacted diagnostic and metrics sinks.

Step 3

Prepare a style, then render a batch

Preparation is deliberately split in two. First Rentile validates and compiles the style. Then it gathers everything required for a caller-defined tile batch. Once a batch is prepared, rendering performs no network or store access.

val style = rasterizer.prepare(
    StyleInput.Remote("https://example.com/style.json")
)

val requestedTiles = listOf(
    TileId(z = 12, x = 2203, y = 1345),
    TileId(z = 12, x = 2204, y = 1345),
)

rasterizer.prepareBatch(style, requestedTiles).use { batch ->
    // Content keys are available before drawing.
    batch.contentKeys.forEach { (tile, key) ->
        println("$tile will render as $key")
    }

    val result: RenderBatch = rasterizer.render(batch)
    result.tiles.forEach { tile ->
        savePng(tile.id, tile.pngBytes)
    }
}

Choose a style input

Output contract

A successful tile contains its TileId, encoded pngBytes, the same contentKey exposed before drawing, and any sanitized diagnostics. A render call is all-or-error: Rentile does not return a partial batch.

Host boundary

Keep your existing network stack

ResourceTransport is one bounded request/response exchange. Map its request onto Ktor, OkHttp, URLSession, Curl, or another client already used by your host. Return the decompressed body and the allowlisted response metadata.

fun interface ResourceTransport {
    suspend fun execute(
        request: TransportRequest
    ): TransportResponse
}

Requests include the URL, resource class, response-size limit, and a small set of cache-validation headers. Arbitrary headers do not cross the public boundary.

Credentials

If a style URL already contains provider credentials, Rentile uses them. Otherwise, it asks your CredentialProvider only for the exact HTTPS origin and query parameter it needs. Credentials and session values are kept out of logs, content keys, cache paths, exception text, and diagnostics.

Caching

Two caches, two owners

Rentile stores reusable source material. Your app stores finished PNGs. Keeping those concerns separate lets your product choose the output lifetime and eviction policy that make sense for its workflows.

Use PreparedBatch.contentKeys to look up rendered outputs before you call render. A failed tile does not undo valid raw-resource entries acquired for other work, and incomplete entries are never committed.

Failures

Handle facts, not exception messages

Every RentileException has a stable machine-readable code, a pipeline stage, sanitized diagnostics, and affected tile identities. Human-readable messages explain the problem but are not a stable API.

Rentile does not retry or fall back on its own. Use the typed fields to decide whether your app should retry, refetch, choose another renderer, or stop. CancellationException is propagated unchanged.

Lifecycle

Close quickly, await when cleanup matters

BasemapRasterizer and PreparedBatch are common Kotlin AutoCloseables. Calling close() is idempotent, non-blocking, and non-throwing. It prevents new work and starts cancellation of owned jobs.

val rasterizer = Rentile.create(configuration)

try {
    renderNeededTiles(rasterizer)
} finally {
    rasterizer.close()
    rasterizer.awaitClosed()
}

awaitClosed() suspends until workers, native objects, leases, and secret state are released. Use it when teardown must be observed—for example, before a test ends or a long-lived service replaces its renderer.

Renderer coverage

Check your style before committing

Rentile follows a versioned rentile-v1 compatibility profile validated against an owner-controlled rolling style corpus. It does not promise support for every current or future MapLibre Style Specification feature. A retained unsupported construct fails during style preparation instead of producing a quietly incomplete map.

Targets

Supported platforms