Colors

Kore provides a unified Color API that covers three families of colors used by Minecraft:

  • FormattingColor and BossBarColor (named colors for chat, UI, teams, etc.)
  • RGB and ARGB (numeric colors)
  • DyeColors (the 16 dye colors used by entities and items)

For the vanilla reference on color behavior, see the Minecraft Wiki - Color.

Color types in Kore

  • Color (sealed interface): umbrella type accepted by most helpers.
  • FormattingColor: named chat/formatting colors (e.g. Color.RED, Color.AQUA).
  • BossBarColor: bossbar's named colors.
  • RGB / ARGB: numeric colors. RGB is #rrggbb, ARGB is #aarrggbb.
  • DyeColors: 16 dye colors (white, orange, magenta, …, black) for collars, shulkers, sheep, tropical fish, etc.

Every named chat color as the game draws it, click one to copy its Kotlin name.

In game: the 16 chat colors. Color.PINK and Color.PURPLE are boss bar colors, so they aren't in this list.

Helpers to create numeric colors:

import io.github.ayfri.kore.arguments.colors.*

val c1 = color(85, 255, 255) // RGB
val c2 = color("#55ffff") // RGB from hex string
val c3 = color(0x55ffff) // RGB from decimal
val c4 = argb(255, 85, 255, 255) // ARGB
val c5 = argb("#ff55ffff") // ARGB from hex string
Kotlin

Conversions and utils:

val rgb = Color.AQUA.toRGB() // Named/Bossbar/ARGB → RGB
val argb = rgb.toARGB(alpha = 200)
val mixed = mix(rgb(255, 0, 0), 0.25, rgb(0, 0, 255), 0.75)
Kotlin

Random colors

Kore provides static random() helpers on the color classes to simplify testing and procedural generation. You can also use a Random instance to generate random colors with a specific seed.

These helpers are available on:

  • RGB: RGB.random(random: Random = Random): returns a random RGB
  • ARGB: ARGB.random(random: Random = Random, alpha: Boolean = false): returns a random ARGB; set alpha = true to randomize the alpha channel
  • FormattingColor: FormattingColor.random(random: Random = Random): returns a random named formatting color
  • BossBarColor: BossBarColor.random(random: Random = Random): returns a random named bossbar color

Example usage:

import kotlin.random.Random
import io.github.ayfri.kore.arguments.colors.*
import io.github.ayfri.kore.arguments.enums.DyeColors

val randomRgb = RGB.random()
val randomArgb = ARGB.random(random = Random(12345))
val randomArgbWithAlpha = ARGB.random(alpha = true)
val randomFormatting = FormattingColor.random()
Kotlin

They make it easy to generate example content, tests, or procedurally-generated visuals.

Serialization formats by context

Different Minecraft systems expect colors in different formats. Kore picks the right format automatically via serializers.

  • Chat components color: string

    • Named colors emit lowercase names (e.g. "red").
    • RGB emits "#rrggbb"; ARGB emits "#aarrggbb".
  • Chat components shadow_color: signed ARGB int (ColorAsARGBDecimalSerializer), colors without alpha being fully opaque

    • Color.BLUE emits -11184641 (0xFF5555FF), argb(0, 0, 0, 0) emits 0.
  • Item components (decimal ints):

    • dyedColor(..): decimal (or object with rgb decimal when tooltip flag is present) See on GitHub
      @Serializable(RGB.Companion.ColorAsDecimalSerializer::class) var rgb: RGB,
      
      Kotlin
    • potionContents(customColor=..): decimal See on GitHub
      @Serializable(RGB.Companion.ColorAsDecimalSerializer::class)
      var customColor: RGB? = null,
      
      Kotlin
    • Firework explosion colors / fade_colors: decimal list See on GitHub
      var colors: List<@Serializable(RGB.Companion.ColorAsDecimalSerializer::class) RGB>? = null,
      @SerialName("fade_colors")
      var fadeColors: List<@Serializable(RGB.Companion.ColorAsDecimalSerializer::class) RGB>? = null,
      
      Kotlin
  • Worldgen Biomes (decimal ints):

    • effects.waterColor, effects.grassColor, effects.foliageColor, etc. use decimal ints.
    • Sky/fog/water fog colors are set via environment attributes (attributes). See on GitHub
    // BiomeEffects (decimal ints in JSON)
    @Serializable(ColorAsDecimalSerializer::class) var waterColor: Color = color(4159204)
    @Serializable(ColorAsDecimalSerializer::class) var grassColor: Color? = null
    @Serializable(ColorAsDecimalSerializer::class) var foliageColor: Color? = null
    @Serializable(ColorAsDecimalSerializer::class) var dryFoliageColor: Color? = null
    
    // Environment attributes (also typically decimal ints for worldgen colors)
    attributes {
    	skyColor(0x78A7FF)
    	fogColor(0xC0D8FF)
    	waterFogColor(0x050533)
    }
    
    Kotlin
  • Particles:

    • Particle options, in the /particle command, enchantment effects and environment attributes (packed ints): RGB for dust, dust_color_transition, effect, instant_effect and trail, ARGB for entity_effect, flash and tinted_leaves. A color without alpha is fully opaque, so colorParticle(Color.GREEN) gives particle minecraft:entity_effect{color:-11141291}. See on GitHub
      // RGB: dust, dust_color_transition, effect, instant_effect, trail
      @Serializable(ColorAsDecimalSerializer::class) var color: Color,
      
      // ARGB: entity_effect, flash, tinted_leaves
      @Serializable(ColorAsARGBDecimalSerializer::class) var color: Color,
      
      Kotlin
  • UI and commands using named colors (strings):

    • Teams, Scoreboards, Bossbar: FormattingColor / BossBarColor See on GitHub
      fun color(color: FormattingColor) = fn.addLine(..., literal("color"), color)
      
      Kotlin
      See on GitHub
      fun setColor(color: BossBarColor) = fn.addLine(..., literal("color"), color)
      
      Kotlin

Dye colors and where they're used

DyeColors are used for entity variants and certain item/entity data components:

  • catCollar(..), wolfCollar(..), sheepColor(..), shulkerColor(..) See on GitHub
    data class CatCollar(var color: DyeColors)
    fun ComponentsScope.catCollar(color: DyeColors)
    
    Kotlin
    See on GitHub
    data class WolfCollar(var color: DyeColors)
    fun ComponentsScope.wolfCollar(color: DyeColors)
    
    Kotlin
    See on GitHub
    data class SheepColor(var color: DyeColors)
    fun ComponentsScope.sheepColor(color: DyeColors)
    
    Kotlin
    See on GitHub
    data class ShulkerColor(var color: DyeColors)
    fun ComponentsScope.shulkerColor(color: DyeColors)
    
    Kotlin

Practical examples

Chat components (string serialization):

import io.github.ayfri.kore.arguments.chatcomponents.textComponent
import io.github.ayfri.kore.arguments.colors.Color

val title = textComponent("Legendary Sword", Color.AQUA)
Kotlin

Dyed leather color (decimal serialization):

import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.arguments.colors.Color

val dyedHelmet = Items.LEATHER_HELMET {
	dyedColor(Color.AQUA)
}
Kotlin

Fireworks (decimal lists):

import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.arguments.components.item.FireworkExplosionShape
import io.github.ayfri.kore.arguments.colors.Color

val rocket = Items.FIREWORK_ROCKET {
	fireworks(flightDuration = 1) {
		explosion(FireworkExplosionShape.BURST) {
			colors(Color.AQUA)
			fadeColors(Color.BLACK, Color.WHITE)
			hasTrail = true
			hasTwinkle = true
		}
	}
}
Kotlin

Biome effects (decimal):

import io.github.ayfri.kore.features.worldgen.biome.types.BiomeEffects
import io.github.ayfri.kore.arguments.colors.color

val effects = BiomeEffects(
	waterColor = color(4159204),
	grassColor = color(0x79C05A)
)
Kotlin

Particles

  • Dust, in the command (particle minecraft:dust{color:16711680,scale:1.0f}), an enchantment or an environment attribute ("color": 16711680):
    import io.github.ayfri.kore.arguments.colors.rgb
    import io.github.ayfri.kore.data.particle.dustParticle
    
    val dust = dustParticle(rgb(255, 0, 0), scale = 1f)
    
    Kotlin

Entity variant dye usage:

import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.arguments.enums.DyeColors

val cat = Items.CAT_SPAWN_EGG {
	catCollar(DyeColors.RED)
}
Kotlin

Notes

  • Passing Color to component helpers that use decimal or double-array formats is safe: Kore converts automatically via toRGB().
  • Use DyeColors when the game mechanic expects a dye color (collars, sheep, shulkers, tropical fish), and FormattingColor/ BossBarColor for chat/UI tints.

Further reading