LittleKt Documentation

To use LittleKt in your Kotlin Multiplatform project, add mavenCentral() to your repositories and include the com.littlekt:core dependency. You must also include org.jetbrains.kotlinx:kotlinx-coroutines-core as LittleKt requires coroutines on the classpath.

Important Requirements:

• JDK 22+ is required because LittleKt uses the Java Foreign Function & Memory (FFM) API.
• Set your jvmTarget to JvmTarget.JVM_25 (or the appropriate version for your setup) in your build.gradle.kts.

repositories {
    mavenCentral()
}

kotlin {
    jvm {
        compilerOptions {
            jvmTarget = JvmTarget.JVM_25
        }
    }
}

val littleKtVersion = "0.11.0"
val kotlinCoroutinesVersion = "1.9.0"

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("com.littlekt:core:$littleKtVersion")
            implementation("com.littlekt:scene-graph:$littleKtVersion") // optional scene-graph module
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$kotlinCoroutinesVersion")
        }
    }
}

The Particle class includes several lifecycle hooks and user-defined data fields to facilitate complex particle behaviors.

Lifecycle Hooks:

• onStart: (() -> Unit)?: Invoked when the particle is first initialized.
• onUpdate: ((Particle) -> Unit)?: Invoked every frame while the particle is alive.
• onKill: (() -> Unit)?: Invoked when the particle is killed.

User Data Fields: data0 through data7 are Float fields used to mark or denote events within the lifecycle hooks. These fields are reset to 0f whenever the particle is reallocated.

Example of using onUpdate and data0 to trigger an event once a condition is met:

particle.onUpdate = {
    if (particle.data0 == 1f) {
        // do something once
    } else if (particle.x >= 50f) {
        particle.data0 = 1f
    }
}

particle.onUpdate = {
   if(particle.data0 == 1f) {
      // do something
   } else if(particle.x >= 50f) {
      particle.data0 = 1f
   }
}

You can extend the GLTF loading process by providing custom implementations of GltfModelMaterialStrategy or GltfModelFallbackMaterialStrategy.

GltfModelMaterialStrategy

Used to create a Material when a GLTF primitive contains material data. The createMaterial method provides access to the Device (GPU context), the preferredFormat for textures, the GltfMaterial data, and the full GltfData file.

Available built-in strategies:

• PBRMaterialStrategy: Creates a PBRMaterial using metallic-roughness data from the GLTF file.
• UnlitMaterialStrategy: Creates an UnlitMaterial using base color data.

GltfModelFallbackMaterialStrategy

Used to create a Material when a GLTF primitive does not have material data. The createMaterial method provides the GltfModelConfig and the Device.

Available built-in strategy:

• UnlitMaterialFallbackStrategy: Creates an UnlitMaterial that defaults to a white texture.

To load GLTF models, you must provide a GltfLoaderConfig. This configuration determines how the model's physical properties (like shadows and skinning) are handled and defines the strategies used to create materials both when GLTF material data is present and when it is missing.

GltfLoaderConfig is composed of:

• modelConfig: A GltfModelConfig defining castShadows and skinned properties.
• materialStrategy: A GltfModelMaterialStrategy used when a primitive has GLTF material data.
• fallbackMaterialStrategy: A GltfModelFallbackMaterialStrategy used when a primitive lacks GLTF material data.

Convenience functions are provided for common use cases:

• GltfLoaderPbrConfig(): Configures the loader for Physically Based Rendering (PBR) using PBRMaterialStrategy and an UnlitMaterialFallbackStrategy.
• GltfLoaderUnlitConfig(): Configures the loader for unlit materials using UnlitMaterialStrategy and an UnlitMaterialFallbackStrategy.

// Example: Creating a PBR configuration for a skinned model that casts shadows
val config = GltfLoaderPbrConfig(
    modelConfig = GltfModelConfig(castShadows = true, skinned = true)
)

The Scaler class and its implementations provide different strategies for calculating how a source dimension (e.g., game resolution) should be scaled to fit a target dimension (e.g., screen size).

To use a scaler, call the apply method with the source and target dimensions. The method returns a Vec2f representing the new calculated size.

Available scaling strategies:

• Fit: Maintains aspect ratio while fitting as much content as possible onto the screen.
• Fill: Maintains aspect ratio while ensuring the entire target area is covered (may crop content).
• FillX: Stretches to fit the target width while maintaining the source aspect ratio.
• FillY: Stretches to fit the target height while maintaining the source aspect ratio.
• Stretch: Stretches the content to match the target width and height exactly (ignores aspect ratio).
• StretchX: Stretches to the target width but keeps the source height.
• StretchY: Stretches to the target height but keeps the source width.
• None: Performs no scaling and returns the original source dimensions.

import com.littlekt.util.Scaler

val scaler = Scaler.Fit()
val newSize = scaler.apply(
    sourceWidth = 1920,
    sourceHeight = 1080,
    targetWidth = 1280,
    targetHeight = 720
)

println("New Width: ${newSize.x}, New Height: ${newSize.y}")