Configuration

Detailed explanation of every setting in config.yml

1 min readUpdated Nov 12, 2026

Configuration Guide

This page covers every setting available in the config.yml file. SamsHead offers deep customization for caching, rendering, and resource pack delivery.

Update Checker

update-checker.enabled: Checks for new versions on startup.
update-checker.notify-on-join: Alerts admins in chat if an update is available.

Skin Cache

SamsHead uses a high-performance LRU (Least Recently Used) memory cache backed by a persistent SQLite database.

Option	Description	Default
cache.duration	Seconds before a skin is re-fetched (86400 = 24h).	`86400` (24h)
cache.max-size	Max skins held in memory before the oldest are evicted.	500
cache.auto-cache-on-join	Fetches the skin immediately when a player joins.	true

Persistence

Skins are saved in skins.db. This means that even after a server restart, player heads will load instantly without hitting Mojang's API limits.

Rendering Options

`render.default-layer`

Sets the default look if not specified in the placeholder.

face: Base skin layer only.
head: Base skin + hat/overlay layer (Recommended).

`render.sizes`

Defines the pixel height for avatar presets.

Scaling

These values determine the size in the Minecraft font system. A size of 8 matches standard character height.

sizes:
  small: 4
  medium: 8
  normal: 12
  large: 16
  giant: 32

ResourcePack Server

Only active in Vanilla Mode (when ItemsAdder/Nexo are not detected).

Firewall

Ensure port 8765 (or your custom port) is open in your firewall for the internal HTTP server to function.

serve.port: The port for the internal web server.
serve.url: A direct link to your pack if hosted externally (e.g., Dropbox/GitHub).
serve.send-on-join: Automatically prompts players to download the pack.
serve.required: Forces players to accept the pack to play.

Startup Preload

You can specify player names to be cached immediately on startup. This is perfect for NPC heads or staff members to avoid "Loading..." text when players first see them.

preload:
  players:
    - Notch
    - Sam1qk_