Offline, normalized Minecraft Java Edition specifications for the Glow compiler.
Glow needs exact, target-aware Minecraft data without contacting Mojang during
normal builds. mcspec converts official server-generated reports into a
stable schema owned by this project and embeds the generated specs for offline
use.
The public package never exposes Mojang's raw JSON layout.
The root package is the public API consumed by Glow. Generated specifications
are committed under spec/<minecraft-version>/ and loaded offline at runtime.
mcspec/
├── cmd/mcspec-gen/ # Generator CLI
├── internal/ # Extraction, normalization, release, and validation
├── schema/ # Normalized specification model
├── spec/ # Generated, versioned specifications
├── test/ # Integration tests
├── load.go, types.go # Public loading API and query types
└── .github/workflows/ # CI and release tracking automation
Generation follows this pipeline:
official Minecraft data → extraction → normalization → validation → spec/<version>/*.json
Extraction understands upstream reports, normalization owns the stable mcspec schema, and validation rejects malformed or incompatible documents. Runtime Glow builds remain offline; network access is limited to generation and release tracking workflows.
go get github.com/glow-mc/mcspecUse a committed specification from Go:
package main
import (
"fmt"
"github.com/glow-mc/mcspec"
)
func main() {
spec, err := mcspec.Load("1.21.6")
if err != nil {
panic(err)
}
block, ok := spec.Blocks.Lookup("minecraft:stone")
if ok {
fmt.Println(block.ID)
}
fmt.Println(spec.Features.Has("item_components"))
}| Category | Public API | Purpose |
|---|---|---|
| Registries | spec.Blocks, spec.Items, spec.Other |
Typed target-version lookup |
| Commands | spec.Commands |
Command tree and argument parsers |
| Advancements | spec.Advancements |
Trigger vocabulary and criteria |
| Features | spec.Features.Has(...) |
Version-specific capabilities |
| Pack formats | spec.Pack |
Data/resource pack major and minor versions |
spec/<minecraft-version>/
├── metadata.json
├── registries.json
├── commands.json
├── features.json
├── pack.json
└── advancements.json
metadata.json records the Minecraft version, data version, protocol, schema
version, generator version, and deterministic source hash. The current
normalized schema is version 2. Pack formats use major fields
(data_pack/resource_pack) and optional minor fields
(data_pack_minor/resource_pack_minor).
mcspec-gen generate [VERSION] [flags]
mcspec-gen validate VERSION [flags]
mcspec-gen validate --all [flags]
mcspec-gen version
generate VERSION acquires official data by default. Use --offline with
embedded fixtures or --input DIR with previously extracted reports. The
--channel flag accepts release, snapshot, and pre-release; automatic
upstream generation currently supports stable releases.
Example local regeneration:
mcspec-gen generate 1.21.6
mcspec-gen validate 1.21.6 --root .
mcspec-gen generate 1.21.6 --offline --verify --root .The server jar and its temporary libraries are never committed. Only the
normalized output under spec/<version>/ belongs in the repository.
The generator follows the structure reported by the official Minecraft data generator instead of assuming that every version uses the same directory names.
| Version range | Datapack element paths | Common tag paths |
|---|---|---|
| Before 1.21 (for example 1.20.6) | functions, advancements, recipes, loot_tables, predicates, item_modifiers, structures |
tags/blocks, tags/items, tags/fluids, tags/entity_types, tags/game_events, tags/functions |
| 1.21 and later | function, advancement, recipe, loot_table, predicate, item_modifier, structure |
tags/block, tags/item, tags/fluid, tags/entity_type, tags/game_event, tags/function |
The tags directory itself remains plural. The official reports/ directory
also remains the report root across the versions checked. Newer generators
may add nested reports such as reports/minecraft/components/item/*.json;
the extractor preserves and hashes those files instead of copying only the
top-level JSON files.
Resource-pack directories are independent from datapack directories. Official
client jars checked for 1.20.6, 1.21, 1.21.6, and 26.2 keep plural roots such as
models, textures, sounds, atlases, and particles. Newer versions may
add roots such as items, equipment, post_effect, and waypoint_style.
When a local input includes assets/<namespace>/, discovered resource paths
are stored in pack.json; no client jar is committed to this repository.
The path transition was documented by Mojang for Java Edition 1.21: directory renames.
cd_minecraft_spec.yml runs daily and supports workflow_dispatch with
optional version, dry-run, and release-channel inputs. It uses
Mojang's official Java Edition version manifest,
tracks stable entries (type: release) only, and ignores snapshots,
pre-releases, and release candidates.
When a new stable version is detected, the workflow:
- Acquires official server reports.
- Generates and validates the normalized spec.
- Checks deterministic output, formatting,
go vet, and tests. - Creates or reuses
spec/minecraft-<version>. - Commits only
spec/<version>/asfeat(spec): add Minecraft <version>. - Creates or updates a pull request with dynamic metadata and diff summary.
The branch and pull-request head lookup make repeated runs idempotent. Concurrency protection prevents competing scheduled updates. Failures stop the job before a successful update PR is created.
Generated PRs use titles such as:
feat(spec): add Minecraft 26.2
The body includes generated categories, validation checks, Minecraft/data/ protocol/pack/schema metadata, and a concise registry/command/capability diff.
Glow should depend on the module and load the exact compiler target:
spec, err := mcspec.Load(targetVersion)The compiler can then query registries, commands, advancement triggers, features, and pack formats during semantic analysis and Minecraft lowering. Runtime Glow builds should remain completely offline.
gofmt -w .
go vet ./...
go test ./...
go run ./cmd/mcspec-gen validate --all --root .
go run ./cmd/mcspec-gen generate 1.21.6 --offline --verify --root .The normal CI workflow is ci_test.yml. The release tracker is cd_minecraft_spec.yml.
The mcspec source code is licensed under the Apache License 2.0.
Minecraft data contained in generated specifications is derived from Minecraft Java Edition data and remains subject to Mojang/Microsoft terms. This project is not affiliated with Mojang Studios or Microsoft.