linkOverview

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’s Color page (https://minecraft.wiki/w/Color).

linkColor 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.

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

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)

linkRandom 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

linkExample 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()

These helpers were added to make it easy to generate example content, tests, or procedurally-generated visuals.

linkSerialization formats by context

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

• Chat components (color, shadow_color): string

  • Named colors emit lowercase names (e.g. "red").
  • RGB emits "#rrggbb"; ARGB emits "#aarrggbb".

• 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

    Copy
  • mapColor(..): decimal See on GitHub

    InlineSerializer<MapColorComponent, RGB>(RGB.Companion.ColorAsDecimalSerializer, MapColorComponent::color)
    

    Kotlin

    Copy
  • potionContents(customColor=..): decimal See on GitHub

    @Serializable(RGB.Companion.ColorAsDecimalSerializer::class)
    var customColor: RGB? = null,
    

    Kotlin

    Copy
  • 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

    Copy

• Worldgen Biomes (decimal ints): See on GitHub

  @Serializable(ColorAsDecimalSerializer::class) var skyColor: Color = color(7907327)
  @Serializable(ColorAsDecimalSerializer::class) var fogColor: Color = color(12638463)
  @Serializable(ColorAsDecimalSerializer::class) var waterColor: Color = color(4159204)
  @Serializable(ColorAsDecimalSerializer::class) var waterFogColor: Color = color(329011)
  @Serializable(ColorAsDecimalSerializer::class) var grassColor: Color? = null
  @Serializable(ColorAsDecimalSerializer::class) var foliageColor: Color? = null
  

  Kotlin

  Copy

• Particles:

  • Command particles (decimal ints): Dust, DustColorTransition, Trail See on GitHub

    var color: @Serializable(ColorAsDecimalSerializer::class) Color,
    

    Kotlin

    Copy
    See on GitHub

    var fromColor: @Serializable(ColorAsDecimalSerializer::class) Color,
    var toColor: @Serializable(ColorAsDecimalSerializer::class) Color,
    

    Kotlin

    Copy
    See on GitHub

    var color: @Serializable(ColorAsDecimalSerializer::class) Color,
    

    Kotlin

    Copy
  • Enchantment effect particles (double arrays [r, g, b] in 0..1): See on GitHub

    var color: @Serializable(ColorAsDoubleArraySerializer::class) Color,
    

    Kotlin

    Copy
    See on GitHub

    var fromColor: @Serializable(ColorAsDoubleArraySerializer::class) Color,
    var toColor: @Serializable(ColorAsDoubleArraySerializer::class) Color,
    

    Kotlin

    Copy
    See on GitHub

    var color: @Serializable(ColorAsDoubleArraySerializer::class) Color,
    

    Kotlin

    Copy

• 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

    Copy
    See on GitHub

    fun setColor(color: BossBarColor) = fn.addLine(..., literal("color"), color)
    

    Kotlin

    Copy

linkDye 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)
  // ... existing code ...
  fun ComponentsScope.catCollar(color: DyeColors)
  

  Kotlin

  Copy
  See on GitHub

  data class WolfCollar(var color: DyeColors)
  // ... existing code ...
  fun ComponentsScope.wolfCollar(color: DyeColors)
  

  Kotlin

  Copy
  See on GitHub

  data class SheepColor(var color: DyeColors)
  // ... existing code ...
  fun ComponentsScope.sheepColor(color: DyeColors)
  

  Kotlin

  Copy
  See on GitHub

  data class ShulkerColor(var color: DyeColors)
  // ... existing code ...
  fun ComponentsScope.shulkerColor(color: DyeColors)
  

  Kotlin

  Copy

linkPractical 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)

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)
}

Map color (decimal serialization):

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

val withMapColor = Items.STONE {
    mapColor(rgb(85, 255, 255))
}

Fireworks (decimal lists):

import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.generated.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
            hasFlicker = true
        }
    }
}

Biome effects (decimal):

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

val effects = BiomeEffects(
    skyColor = color(7907327),
    waterColor = color(4159204)
)

Particles

• Command dust (decimal):

  import io.github.ayfri.kore.commands.particle.types.Dust
  import io.github.ayfri.kore.arguments.colors.Color
  
  val p = Dust(color = Color.RED, scale = 1.0)
  

  Kotlin

  Copy

• Enchantment dust (double array):

  import io.github.ayfri.kore.features.enchantments.effects.entity.spawnparticles.types.DustParticleType
  import io.github.ayfri.kore.generated.arguments.types.ParticleTypeArgument
  import io.github.ayfri.kore.arguments.colors.rgb
  
  val enchantDust = DustParticleType(
      type = ParticleTypeArgument('minecraft:dust'),
      color = rgb(255, 0, 0)
  )
  

  Kotlin

  Copy

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)
}

linkNotes

• 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.

linkFurther reading

• Minecraft Wiki — Color: https://minecraft.wiki/w/Color