Minecraft Item Gallery

Documentation

How the site works, how to add new Minecraft versions, and how to use the public CDN in your own projects.

How the gallery works

The site loads a base version ZIP containing every item image, then applies incremental changes.json files for each newer version (additions, modifications, removals). This reconstructs the correct texture set for any selected Minecraft version while preserving full history.

In the browser, version ZIPs are cached locally so revisiting a version is fast. Each item card opens a detail view with version history, a compare slider, color palettes, and downloads. Dedicated pages at /items/diamond-sword provide a focused view for sharing and SEO.

Legacy vs enhanced images

The gallery ships two parallel image sets. Use the Images selector in the UI (or ?images=v2 in the URL) to switch.

  • Legacy captures (v1) — original screenshot-based images in /images/. Covers every version today.
  • Enhanced (mod) (v2) — re-rendered icons from the Fabric export mod in /images-v2/. Sharper, with correct transparency. Rolled out per version as you package new exports with --set v2.

The item catalog and version list come from the active set only. Enhanced mode does not mix in legacy images — package each version under images-v2/ as you re-export it.

Exporting a new version (mod)

Images are captured in-game with the standalone Fabric mod in generation/standalone-mod/ (MC 1.21.1). See generation/README.md for build instructions. 

/itemgallery export 1.21.1 64
/itemgallery export 1.21.1 64 all   # include modded namespaces
/itemgallery variants 1.21.1 64    # all potions, light levels, etc.
/itemgallery dumptextures 1.21.1 particle

Output is written to <minecraft>/gallery-export/<version>/ with manifest.json, hashes.json, and auto-generated changes.json when older exports are kept nearby.

Packaging for the website

From the repository root:

# Enhanced v2 (recommended for mod exports)
npm run package-version -- --source "path/to/gallery-export" --mc-version 1.21.1 --set v2

# Legacy v1 (default — original image tree)
npm run package-version -- --source "path/to/gallery-export" --mc-version 1.21.7

This creates:

  • public/images/<version>.zip or public/images-v2/<version>.zip
  • Loose PNGs/WebP and manifest copies for direct URLs and palette generation
  • Updated versions.json in that tree and SEO metadata via enrich-metadata

Particle textures

Particles are not part of the item gallery ZIPs. Export them separately, then package for the /particles page. 

/itemgallery dumptextures 1.21.1 particle

This copies raw PNGs (and .png.mcmeta animation files) to gallery-export/<version>/dumped/. Multi-frame textures are vertical strips in the resource pack. 

npm run package-particles -- --source "path/to/gallery-export" --mc-version 1.21.1

The packaging script:

  • Builds an animated GIF when a texture has multiple frames (from mcmeta or a vertical strip)
  • Keeps a single-frame PNG when there is only one frame
  • Writes public/particles/<version>/manifest.json and updates versions.json

Share a selection

Select items in the gallery and click Share Selection to copy a link. Small selections use readable slugs in ?sel=. Larger ones use a compact ?selc= bitset (~240 characters max). Add ?images=v2 to open in enhanced mode.

Per-item pages & SEO

Each item has a static page at /items/diamond-sword with ImageObject schema markup. Category browse pages live under /items/category/combat and similar paths.

Public API & CDN

Phase 1 (current): stable public URLs on mcitemgallery.com — no API key required. Use these directly in Discord bots, wikis, or any HTTP client.

CDN endpoints

GET https://mcitemgallery.com/images/versions.json
GET https://mcitemgallery.com/images-v2/versions.json
GET https://mcitemgallery.com/images/{version}.zip
GET https://mcitemgallery.com/images-v2/{version}.zip
GET https://mcitemgallery.com/images/{version}/{item}.png
GET https://mcitemgallery.com/images-v2/{version}/{item}.png
GET https://mcitemgallery.com/images/{version}/{item}.webp
GET https://mcitemgallery.com/metadata/items-index.json
GET https://mcitemgallery.com/metadata/categories.json
GET https://mcitemgallery.com/metadata/palettes.json
GET https://mcitemgallery.com/metadata/selection-index.json

Examples

# Diamond sword PNG for a specific version
curl -O https://mcitemgallery.com/images/1.21.6/diamond_sword.png

# Full version archive (base = all PNGs, incremental = changes only)
curl -O https://mcitemgallery.com/images/1.13.2.zip

# Resolve display names and categories
curl -O https://mcitemgallery.com/metadata/items-index.json

Discord bots & integrations

Fetch /images/{version}/{item}.png and attach the PNG directly. Use items-index.json to map filenames to display names and categories. selection-index.json backs compact share links (?selc=).

Phase 2 (planned)

A dedicated API at api.mcitemgallery.com with optional keys and rate limits: 

GET https://api.mcitemgallery.com/v1/items/diamond_sword?version=1.21.6
GET https://api.mcitemgallery.com/v1/versions

Will redirect or stream from the CDN with an optional X-API-Key header.

OpenAPI spec (YAML)

Back to gallery