Configuration

Mosaikin's configuration file is located at plugins/Mosaikin/config.yml. Edit this file and run /mosaikin reload to apply most changes without restarting the server.

---

metrics

metrics:
  enabled: true

Key	Default	Description
enabled	true	Send anonymous usage statistics to bStats. No personally identifiable information is collected. Set to false to opt out.

---

mineskin

mineskin:
  apiKey: ""

Key	Default	Description
apiKey	""	Your MineSkin API key. Get one at account.mineskin.org/keys. Can also be set at runtime with /mosaikin apikey <key>.

---

display

Controls how wall entities are rendered in the world.

display:
  defaultViewRangeBlocks: 128
  interpolationTicksOnRescale: 5
  interpolationTicksOnPlayback: 0

Key	Default	Description
defaultViewRangeBlocks	128	Distance in blocks at which clients render wall entities. Increase for walls that need to be visible from further away.
interpolationTicksOnRescale	5	Number of ticks over which the smooth transition animation runs when a wall is moved, rotated, or rescaled at runtime.
interpolationTicksOnPlayback	0	Ticks of smooth transition between animation frames during playback. Keep this at 0 — non-zero values cause visible texture smearing between frames.

---

playback

Controls animation playback behavior.

playback:
  defaultFps: 12
  maxFps: 20
  pauseWhenNoNearbyPlayers: true
  proximityDistanceBlocks: 128
  proximityCheckIntervalTicks: 20

Key	Default	Description
defaultFps	12	Fallback FPS used when a source GIF has missing or unreliable frame delay data.
maxFps	20	Maximum playback frame rate. Minecraft's server tick rate caps effective rendering at 20 FPS, so higher values have no effect.
pauseWhenNoNearbyPlayers	true	When enabled, animation ticks are skipped for walls with no players within proximityDistanceBlocks. Reduces CPU load for walls that nobody is watching.
proximityDistanceBlocks	128	Radius for the "any player nearby" check. Should match display.defaultViewRangeBlocks so walls never freeze while still visible to someone.
proximityCheckIntervalTicks	20	How often (in server ticks) the nearby-player check runs. 20 = once per second. Lower values react faster to players approaching/leaving; higher values are cheaper.

---

limits

Guards against accidentally creating oversized walls or downloading excessively large files.

limits:
  maxCellsPerWall: 10000
  defaultMaxAxisCells: 64
  maxSourceBytes: 50000000

Key	Default	Description
maxCellsPerWall	10000	Warn when a wall's total grid cell count exceeds this value. High entity counts can exceed Minecraft's per-player entity cap. 1 cell = 1 head entity in the worst case (before merging/dedup).
defaultMaxAxisCells	64	Default cap on the longest wall axis, in grid cells (1 cell = 8 pixels). Source images larger than this are proportionally downscaled before processing. 0 disables the default cap. Can be overridden per-wall with /mosaikin <name> maxsize.
maxSourceBytes	50000000	Maximum size of a source image or archive download in bytes (default: 50 MB). Converter-exported ZIP archives for long animations may be larger — increase this if you plan to import them.

---

cache

Controls how processed image data is stored on disk.

cache:
  directory: cache
  retainAfterReady: true

Key	Default	Description
directory	cache	Path to the cache directory, relative to plugins/Mosaikin/.
retainAfterReady	true	Keep cached frames and packed head data after a wall reaches READY status. Useful if you need to regenerate later. Set to false to save disk space.

---

walls

Controls wall data storage and restart behavior.

walls:
  directory: walls
  autoResumeOnStart: true
  despawnOnShutdown: false
  respawnOnStart: true

Key	Default	Description
directory	walls	Path to the wall data directory, relative to plugins/Mosaikin/.
autoResumeOnStart	true	Resume any in-progress generation jobs when the plugin loads. Useful after an unexpected server shutdown mid-generation.
despawnOnShutdown	false	Remove all wall entities when the plugin unloads. If false, Paper preserves the entities across restarts and respawnOnStart reconnects them. Set to true if you prefer a clean slate on every load.
respawnOnStart	true	On plugin load, reuse stored entity UUIDs if the entities still exist in the world; respawn fresh entities for any that are missing. This is the main mechanism that keeps walls visible across restarts.

---

walls.regionMerge

Advanced optimization that automatically merges large uniform areas of a wall into single, larger entities. See How It Works for a detailed explanation.

walls:
  regionMerge:
    enabled: true
    maxSize: 8
    similarityThreshold: 12
    coverageThreshold: 1.0
    minMergeRunFrames: 12
    alphaTolerance: 16
    rectangular: true

Key	Default	Description
enabled	true	Enable or disable region merging entirely.
maxSize	8	Largest region size to consider, in grid cells. Must be a power of 2: 1, 2, 4, or 8. Setting 1 disables merging.
similarityThreshold	12	Maximum RGB color distance (0–255) between a pixel and its region's average color for the pixel to count as "similar". Higher values allow more aggressive merging at the cost of detail. The default of 12 preserves most visible gradients.
coverageThreshold	1.0	Fraction of pixels in a region that must survive downsampling within the similarity threshold. 1.0 requires all pixels to match (pixel-perfect). Lower values allow some blurring; 0.95 tolerates 5% outliers.
minMergeRunFrames	12	For animated walls: minimum number of consecutive frames a region must stay uniform before it's worth merging. Shorter uniform runs fall back to per-cell entities. Default is approximately 1 second at the default FPS.
alphaTolerance	16	Maximum allowed transparency variation (0–255) across a region before it is rejected. Prevents visible fringing when downsampling near transparency edges.
rectangular	true	Allow non-square merges (2×4, 4×2, etc.). Disable this for a strict pixel-grid look, at the cost of fewer merges on non-square uniform areas.