Creating Your First Wall

This guide walks through creating a basic still-image wall from start to finish. For animated walls, see Animated Walls after completing this guide.

Before You Start

Image size matters

The size of your image directly determines how many player heads are generated, which affects both generation time and in-world performance:

• Smaller images generate faster. A 128×128 image generates far fewer heads than a 512×512 image.
• Walls with more than 2,000 unique player heads can take up to an hour or more to generate via MineSkin, depending on your subscription.
• Many player heads in the world can cause significant frame rate drops for players viewing the wall, especially on lower-end hardware.

Start small and scale up once you understand the costs involved.

The Mosaikin Converter at mosaikin.eu can resize your image and let you preview roughly how many heads it will require before you commit to generating it. Use it to scale down images that are too large.

Step 1: Prepare Your Image

You have two options for providing a source image:

Option A — Use the converter website (recommended):

Visit mosaikin.eu, upload your image, resize it if needed, and click Export. This downloads a .zip file. Upload that file somewhere publicly accessible (e.g. a file host or your server files) and use its URL in Step 3 below. Alternatively, if the file is on your server, use a file:// path.

Converter-exported files include your density and playback settings automatically, so the plugin will pick them up without extra configuration.

Option B — Use a direct URL:

For simple images, you can point the plugin directly at a public URL. Supported formats are: PNG, JPEG, GIF, WebP, BMP, TIFF.

https://example.com/my-image.png

Video files and animated PNGs/WebPs must go through the converter website first — the plugin does not decode video files directly.

Step 2: Create the Wall

Choose a name for your wall. Names must be 1–32 characters, using only letters, numbers, underscores, and hyphens (A-Z a-z 0-9 _ -).

/mosaikin create <name>

Example:

/mosaikin create lobby-banner

The wall is now in DRAFT status and ready to configure.

Step 3: Set the Image Source

/mosaikin <name> image <url>

Examples:

/mosaikin lobby-banner image https://example.com/banner.png
/mosaikin lobby-banner image file:///path/to/banner.zip

Step 4: Adjust Settings (Optional)

These settings can be changed before generating. After generation, changing density, fit, or maxsize requires resetting and regenerating the wall.

Density — how many source pixels fit in one block of wall width. Higher values = sharper image, smaller physical wall, more heads.

/mosaikin <name> density <1-256>

Default: 16. If you used the converter, the density from your export is applied automatically.

Fit mode — how to handle source images that don't match the target aspect ratio.

/mosaikin <name> fit <crop|fit|stretch>

• crop — center-crop the excess (default)
• fit — letterbox/pillarbox with transparent padding
• stretch — stretch to fill, ignoring aspect ratio

Maximum size — cap the longest wall axis in grid cells (1 cell = 8 pixels). Prevents accidentally generating enormous walls.

/mosaikin <name> maxsize <cells>

Use 0 to apply the server default (64 cells). Larger values generate more heads and take longer.

Scale — physical size multiplier in the world. Does not affect the number of heads.

/mosaikin <name> scale <factor>

Example: scale 2 makes the wall twice as large in-world.

Step 5: Prepare the Image

Once your settings look good, run confirm to process the image locally. This step does not hit MineSkin yet — it just downloads, resizes, chunks, and packs your image so you can see exactly how many unique player heads it will require.

/mosaikin <name> confirm

The plugin will:

1. Download and decode the image
2. Break it into 8×8 pixel grid cells
3. Pack cells into player head textures (up to 6 cells per head)
4. Deduplicate identical cells to minimize MineSkin submissions

The wall moves to PACKED status and a summary is printed with the final pixel dimensions, grid dimensions, and unique-head count, followed by a clickable [Generate] chip.

Review the numbers before starting the slow MineSkin upload — especially the unique-head count, since that's what determines how long generation will take:

/mosaikin <name> info

If the result isn't what you want (image was cropped differently than expected, too many heads, etc.) you can adjust settings and start over:

/mosaikin <name> reset confirm

Reset wipes the packed data back to DRAFT while keeping your settings.

Step 6: Submit to MineSkin

When you're happy with the packed result, kick off the MineSkin upload:

/mosaikin <name> generate

The plugin will:

1. Submit each unique head texture to MineSkin for generation
2. Move the wall to GENERATING while uploads are in flight
3. Move to READY once every head completes

Generation time

Generation time depends heavily on the number of unique player heads and your MineSkin subscription tier. A simple still image may take a few minutes; large or complex images can take much longer.

Walls with more than 2,000 unique heads should be expected to take up to an hour or more. Check progress with /mosaikin <name> info.

You can check progress at any time:

/mosaikin <name> info

If some heads fail, use /mosaikin <name> retry to resubmit them without starting over.

Step 7: Spawn the Wall

Once the wall reaches READY status, spawn it in the world. Stand where you want the wall to appear, then:

/mosaikin <name> spawn

The wall spawns at your location, facing the direction you're looking. You can also provide explicit coordinates:

/mosaikin <name> spawn <x> <y> <z>

Relative coordinates are supported:

/mosaikin <name> spawn ~ ~ ~

Adjusting the Wall After Spawning

These commands work on a spawned wall without regenerating it:

/mosaikin <name> move <x> <y> <z>
/mosaikin <name> rotate <yaw> [pitch] [roll]
/mosaikin <name> rescale <factor>

Performance Disclaimer

In-world performance

Each grid cell on a wall is rendered as a separate player head entity. A 128×128 image at default settings produces 256 head entities. At larger sizes or higher density settings, this count grows quickly.

Large numbers of head entities in a small area can cause significant frame rate drops for players viewing the wall, especially on lower-end hardware. Keep walls reasonably sized and avoid placing multiple large walls in the same area.