Developer API

Integrate SamsHead into your own plugins!

1 min readUpdated Nov 12, 2026

SamsHead provides several utility classes to render player skins into colored text strings.

Rendering an Avatar

To get the raw String containing colored PUA characters for an 8x8 head:

// Get colors from cache (returns int[128] where 0-63 is face, 64-127 is head+hat)
int[] colors = samsHead.getSkinCache().getColors("PlayerName");
 
if (colors != null) {
    // Render to colored text using a specific size preset
    String avatar = AvatarRenderer.render(colors, RenderSize.NORMAL, RenderMode.HEAD);
}

Rendering a Player Bust

For the full 32x32 player bust:

int[] bustColors = samsHead.getSkinCache().getBustColors("PlayerName");
 
if (bustColors != null) {
    // Renders the full 32x32 grid
    String bust = BustRenderer.render(bustColors, BustSize.BUST_NORMAL);
}

Fetching Skin Async

If a skin isn't in the cache, you should fetch it asynchronously. The SkinFetcher handles the Mojang API and SkinsRestorer lookups automatically.

samsHead.getSkinFetcher().fetchAsync("PlayerName", 
    () -> {
        // Success callback: Skin is now in cache and DB
        plugin.getLogger().info("Skin is now ready!");
    }, 
    () -> {
        // Failure callback
        plugin.getLogger().warning("Could not fetch skin.");
    }
);

Cache Managment

You can interact with the SkinCache directly to check status or evict players.

SkinCache cache = samsHead.getSkinCache();
 
boolean isStale = cache.isStale("PlayerName", 86400);
boolean isFetching = cache.isFetching("PlayerName");
 
// Manually evict from memory (does not delete from SQLite DB)
cache.evict("PlayerName");