Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SparkUniverse/Essential-Mod/llms.txt

Use this file to discover all available pages before exploring further.

The MojangAPI interface provides utilities for interacting with the Mojang API, allowing you to fetch player information, profiles, and manage skins.

​
Accessing MojangAPI

import gg.essential.api.EssentialAPI

val mojangAPI = EssentialAPI.getMojangAPI()

​
Player Lookups

​
getUUID

Retrieve a player’s UUID from their username. 
import java.util.UUID

val future = mojangAPI.getUUID("Notch")
future?.thenAccept { uuid: UUID ->
    println("UUID for Notch: $uuid")
}
Parameters:
  • name: String - The player’s username
Returns: CompletableFuture<UUID>? - A future that resolves to the player’s UUID, or null if the request fails Reference: Mojang API - Username to UUID

​
getName

Retrieve a player’s username from their UUID. 
import java.util.UUID

val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val future = mojangAPI.getName(uuid)

future?.thenAccept { name: String ->
    println("Username: $name")
}
Parameters:
  • uuid: UUID - The player’s UUID
Returns: CompletableFuture<String>? - A future that resolves to the player’s username, or null if the request fails Reference: Mojang API - Usernames to UUIDs

​
Player Profiles

​
getProfile

Retrieve the complete player profile including skin and cape information. 
val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val profile = mojangAPI.getProfile(uuid)

if (profile != null) {
    println("Player: ${profile.name}")
    println("UUID: ${profile.id}")
    
    // Access textures
    val textures = profile.textures
    val skinUrl = textures.textures?.skin?.url
    val capeUrl = textures.textures?.cape?.url
    
    println("Skin URL: $skinUrl")
    println("Cape URL: $capeUrl")
}
Parameters:
  • uuid: UUID - The player’s UUID
Returns: Profile? - The player’s profile object, or null if the request fails Reference: Mojang API - UUID to Profile and Skin/Cape

​
Skin Management

​
changeSkin

Send a skin change request to Mojang. The player must rejoin the server to see the new skin. 
import gg.essential.api.utils.mojang.Model
import java.util.UUID

val accessToken = "player_session_token"
val uuid = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5")
val skinUrl = "https://example.com/skin.png"

val response = mojangAPI.changeSkin(
    accessToken = accessToken,
    uuid = uuid,
    model = Model.STEVE,
    url = skinUrl
)

if (response != null) {
    println("Skin changed successfully: ${response.name}")
}
Parameters:
  • accessToken: String - Session token for authentication with Mojang
  • uuid: UUID - Player UUID (must match the session token)
  • model: Model - Skin model type (STEVE or ALEX)
  • url: String - Image URL of the new skin
Returns: SkinResponse? - Response from Mojang, or null if the request fails Reference: Mojang API - Change Skin

​
Data Types

​
Profile

data class Profile(
    val id: String?,           // Player UUID (no dashes)
    val name: String?,         // Player username
    val properties: List<Property>?
) {
    val textures: ProfileTextures  // Decoded skin and cape data
}

​
ProfileTextures

data class ProfileTextures(
    val timestamp: Long?,
    val profileId: String?,
    val profileName: String?,
    val textures: Textures?
)

data class Textures(
    val skin: TextureURL?,
    val cape: TextureURL?
)

data class TextureURL(val url: String?)

​
Model

Skin model enumeration: 
enum class Model(
    val type: String,      // Internal Minecraft name
    val variant: String    // Mojang service name
) {
    STEVE("default", "classic"),
    ALEX("slim", "slim");
    
    companion object {
        fun byType(str: String): Model?
        fun byTypeOrDefault(str: String): Model
        fun byVariant(str: String): Model?
        fun byVariantOrDefault(str: String): Model
    }
}

​
SkinResponse

data class SkinResponse(
    val id: String,
    val name: String,
    val skins: List<Skin>?,
    val capes: List<Skin>
)

data class Skin(
    val id: String,
    val state: String,
    val url: String,
    val variant: String
)

​
Name (Deprecated)

@Deprecated("Name history has been removed from the Mojang API")
data class Name(
    val name: String?,
    val changedToAt: Long?
)

​
Method Reference

interface MojangAPI {
    fun getUUID(name: String): CompletableFuture<UUID>?
    fun getName(uuid: UUID): CompletableFuture<String>?
    fun getProfile(uuid: UUID): Profile?
    fun changeSkin(
        accessToken: String,
        uuid: UUID,
        model: Model,
        url: String
    ): SkinResponse?
    
    @Deprecated("Name history has been removed from the Mojang API")
    fun getNameHistory(uuid: UUID?): List<Name?>?
}

​
Common Use Cases

​
Looking Up Player Information

import gg.essential.api.EssentialAPI

fun lookupPlayer(username: String) {
    val api = EssentialAPI.getMojangAPI()
    
    api.getUUID(username)?.thenAccept { uuid ->
        println("Found UUID: $uuid")
        
        // Now fetch the full profile
        val profile = api.getProfile(uuid)
        if (profile != null) {
            println("Player name: ${profile.name}")
            println("Skin URL: ${profile.textures.textures?.skin?.url}")
        }
    }
}

​
Displaying Player Skins

fun getPlayerSkinUrl(uuid: UUID): String? {
    val api = EssentialAPI.getMojangAPI()
    val profile = api.getProfile(uuid) ?: return null
    
    return profile.textures.textures?.skin?.url
}

fun getPlayerCapeUrl(uuid: UUID): String? {
    val api = EssentialAPI.getMojangAPI()
    val profile = api.getProfile(uuid) ?: return null
    
    return profile.textures.textures?.cape?.url
}

​
Async Player Lookup

import gg.essential.api.utils.Multithreading

fun asyncPlayerLookup(username: String, callback: (UUID?) -> Unit) {
    val api = EssentialAPI.getMojangAPI()
    
    Multithreading.runAsync {
        val future = api.getUUID(username)
        future?.thenAccept { uuid ->
            callback(uuid)
        } ?: callback(null)
    }
}

​
Checking Skin Model

import gg.essential.api.utils.mojang.Model

fun getPlayerSkinModel(uuid: UUID): Model {
    val api = EssentialAPI.getMojangAPI()
    val profile = api.getProfile(uuid)
    
    // Check if player uses slim (Alex) or classic (Steve) model
    val variant = profile?.textures?.textures?.skin?.variant ?: "classic"
    return Model.byVariantOrDefault(variant)
}

​
Notes

  • All network operations return futures or nullable types - always handle failure cases
  • The Mojang API has rate limits - cache responses when possible
  • Name history endpoint has been deprecated by Mojang and is no longer functional
  • Skin changes require valid authentication tokens
  • Players must rejoin servers to see skin changes take effect

Build docs developers (and LLMs) love

Get started for freeTalk to us