Multiavatar KMP

中文文档 | Chinese README

Important

Publishing: currently only the JVM artifact is published. Other targets (Android/JS/iOS/Native) are not yet available in the Maven repository. Amper's publish has limited support for multiplatform/native artifacts. See: https://github.com/JetBrains/amper/blob/main/sources/amper-cli/src/org/jetbrains/amper/tasks/PublishTask.kt#L108

Until Amper supports publishing all artifacts, use Gradle (kotlin-multiplatform + maven-publish) if you need to publish non-JVM artifacts to mavenLocal/GitHub Packages.

If you need this now, please open an Issue and we will consider switching to Gradle-based publishing. Otherwise, we'll wait for Amper to support full publishing before changing the setup.

Kotlin Multiplatform port of Multiavatar — a multicultural avatar generator with up to 12,230,590,464 unique combinations.

This library generates avatar SVG strings from any input text and works across the Kotlin targets defined in module.yaml.

Supported targets

• Android
• iOS: iosArm64, iosSimulatorArm64, iosX64
• JVM
• JS
• Native: mingwX64, macosArm64, macosX64

Installation

Add the dependency from your package repository (e.g., GitHub Packages).

Gradle Kotlin DSL (replace with the actual version):

dependencies {
  implementation("io.github.kingsword09:multiavatar:0.1.5")
}

If you use GitHub Packages, configure repository and credentials accordingly.

Note

Availability: currently only the JVM target is published. Android/JS/iOS/Native targets are not yet in the Maven repository. Temporary options:

• Depend on source (include this module as a composite build/subproject).
• Build locally and use mavenLocal (still JVM-only).
• Wait for a Gradle-based publish or Amper support for full multiplatform publishing.

Basic usage (common)

Generate an SVG string:

import io.github.kingsword09.multiavatar.Multiavatar

val svg: String = Multiavatar.generate("Binx Bond")

// Optional: remove the circular background (Environment)
val svgNoEnv = Multiavatar.generate("Binx Bond", sansEnv = true)

// Optional: force part/theme
// AvatarEngine.Version(part = "00", theme = "A")
val svgForced = Multiavatar.generate("Binx Bond", ver = AvatarEngine.Version("00", "A"))

Android: Jetpack Compose + Coil (SVG)

Render the generated SVG using Coil's SVG decoder.

Dependencies:

dependencies {
  implementation("io.coil-kt:coil-compose:2.6.0")
  implementation("io.coil-kt:coil-svg:2.6.0")
}

Sample composable:

import androidx.compose.runtime.*
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import coil.compose.AsyncImage
import coil.decode.SvgDecoder
import coil.request.ImageRequest
import io.github.kingsword09.multiavatar.Multiavatar

@Composable
fun Avatar(
  name: String,
  modifier: Modifier = Modifier
) {
  // Generate SVG string (lightweight)
  val svg = remember(name) { Multiavatar.generate(name) }

  // Feed the string as bytes to Coil and enable SvgDecoder
  val context = androidx.compose.ui.platform.LocalContext.current
  val request = remember(svg) {
    ImageRequest.Builder(context)
      .data(svg.toByteArray())
      .decoderFactory(SvgDecoder.Factory())
      .build()
  }

  AsyncImage(
    model = request,
    contentDescription = "avatar",
    modifier = modifier.size(64.dp)
  )
}

Notes:

• Passing svg.toByteArray() as the model works well; alternatively create a custom Model/Fetcher to treat String as an SVG source.
• Control theme or sansEnv via Multiavatar.generate(...) args.

Validation and hashing

import io.github.kingsword09.multiavatar.SvgValidator
import io.github.kingsword09.multiavatar.MultiavatarHash

val svg = Multiavatar.generate("demo")
val result = SvgValidator.validate(svg)
check(result.isValid) { "Invalid SVG: ${result.reasons}" }

val hex = MultiavatarHash.sha256Hex("demo")
val digits = MultiavatarHash.sha256Digits("demo") // digits only, length <= 12

Design and rules (brief)

• 16 base characters × 3 themes = 48 base avatar parts.
• Final avatar composes 6 parts: Environment, Clothes, Head, Mouth, Eyes, Top.
• Mix-and-match yields 48^6 ≈ 12.23B combinations.

License

Use under the original project's license. See LICENSE.

Acknowledgements

Based on the original Multiavatar design and algorithm, ported to Kotlin Multiplatform.