Cobble Metadata Files
Cobble writes generated-pack metadata under .cobble/ in every non-dry-run
build output. These files are intended for inspection, validation diagnostics,
and future editor tooling. Cobble also writes project-local workflow metadata
under the project’s .cobble/ directory for commands such as link.
Each file’s version field is a per-file schema version that changes
independently of the Cobble package version.
.cobble/build_manifest.json
The build manifest summarizes the build inputs, target version, generated outputs, generated resources, and optional validation result.
Stable top-level fields for schema version 1:
| Field | Type | Meaning |
|---|---|---|
version | number | Build manifest schema version. Currently 1. |
cobble_version | string | Cobble package version that produced the build. |
minecraft_version | string | Supported Minecraft Java Edition target. |
pack_format | number or object | Serialized pack-format value. |
pack_format_text | string | Human-readable pack-format value such as 121.0. |
namespace | string | Generated data pack namespace. |
description | string | Pack description written to pack.mcmeta. |
project_root | string | Canonical project/source root used for ownership diagnostics. |
project_id | string | Stable SHA-1 identity derived from project_root. |
generated_at_unix_epoch_ms | number | Generation timestamp in Unix epoch milliseconds. |
input | object or null | Source input summary. |
generated_namespaces | array | Namespaces generated in data/. |
generated | object | Generated output counts. |
resources | array | Generated JSON resource entries. |
validation | object or null | Validation summary when validation ran. |
0.8.0 Additive Fields
The following optional top-level fields are added in 0.8.0. They are omitted when not applicable and do not require a schema version bump.
| Field | Type | Meaning |
|---|---|---|
stdlib_version | number | Stdlib version declared in cobble.toml. 1 or 2. Omitted when no stdlib helpers are used. |
active_stdlib_modules | array | Stdlib modules activated by imports. Empty when import stdlib is used (all modules active). |
unrolled_loops | number | Number of for loops expanded at compile time. Omitted when zero. |
0.9.0 Additive Top-Level Fields
The following optional top-level fields are added in 0.9.0. They are omitted when not applicable and do not require a schema version bump.
| Field | Type | Meaning |
|---|---|---|
experimental_features | array | Experimental features enabled for this build, e.g. ["resource_pack"]. Omitted when empty. |
Native CLI builds set project_root to the canonical project/source root and
project_id to the SHA-1 identity derived from that path. Browser/WASM
compilation has no local project root, so its manifest leaves project_root and
project_id empty. Browser/WASM output also uses 0 for
generated_at_unix_epoch_ms; native CLI builds use the current system time.
Only local CLI link, watch, doctor, and clean workflows use project_id for
ownership checks.
input fields:
| Field | Type | Meaning |
|---|---|---|
source | string | Source file or source directory. |
entry_points | array | Configured entry points used for the build. |
compiled_files | array | Cobble files compiled as entry points. |
generated fields:
| Field | Meaning |
|---|---|
functions | Number of generated .mcfunction files. |
commands | Number of generated command lines. |
source_map_entries | Number of source-map entries written. |
function_tags | Total generated function tag JSON files. |
stdlib_function_tags | Function tags generated by stdlib event registration. |
custom_function_tags | Function tags generated by user declarations. |
json_function_tags | Function tags declared through datapack.function_tag. |
advancements | Generated advancement JSON count. |
loot_tables | Generated loot table JSON count. |
recipes | Generated recipe JSON count. |
predicates | Generated predicate JSON count. |
item_modifiers | Generated item modifier JSON count. |
json_resources | Generic datapack.* JSON resources. |
total_json_resources | Legacy typed resources plus generic JSON resources. |
0.9.0 Additive generated Fields
| Field | Meaning |
|---|---|
resource_pack_models | Generated resource-pack model JSON count. Omitted when zero. |
resource_pack_langs | Generated resource-pack lang JSON count. Omitted when zero. |
resource_pack_static_assets | Static resource-pack assets copied from project assets/. Omitted when zero. |
Each resources entry has:
| Field | Type | Meaning |
|---|---|---|
kind | string | Resource kind such as function_tag, predicate, resource_pack_model, resource_pack_lang, or resource_pack_static_asset. |
namespace | string | Resource namespace. |
path | string | Resource path without namespace or file extension. |
resource_pack_model, resource_pack_lang, and
resource_pack_static_asset are emitted under the resource-pack opt-in. See
Resource Packs.
When validation runs, validation has:
| Field | Type | Meaning |
|---|---|---|
enabled | boolean | Always true when the object is present. |
commands_json | string | Command-tree file used for validation. |
files_checked | number | .mcfunction files checked. |
commands_checked | number | Regular commands checked. |
macro_commands_checked | number | Macro commands checked. |
commands_skipped | number | Commands skipped by validator rules. |
errors | number | Command validation errors. |
source_map_errors | number | Source-map consistency errors. |
.cobble/source_map.json
The source map links generated command lines and generated JSON resource files back to Cobble source locations when available. It is written when generated metadata exists.
Stable top-level fields for schema version 1:
| Field | Type | Meaning |
|---|---|---|
version | number | Source-map schema version. Currently 1. |
entries | array | Generated file mappings. |
Each entry has:
| Field | Type | Meaning |
|---|---|---|
generated_path | string | Generated file path relative to the data pack root. |
generated_line | number | 1-based line number in the generated file. |
command | string | Generated command text without a leading slash, or the mapped generated JSON line text. |
source | object or null | Cobble source location when known. |
kind | string | Command origin: UserCommand, StdLib, RuntimeSetup, ControlFlow, JsonGenerated, or Unrolled. |
JsonGenerated entries are added in 0.9.0 for generated data-pack and
resource-pack JSON files. Static resource-pack passthrough assets are listed in
the build manifest, but they are not source-mapped because Cobble copies them
without generating their contents.
Unrolled is added in 0.8.0 for commands generated by compile-time
unrolling of literal for loops. See
For Loops.
source has:
| Field | Type | Meaning |
|---|---|---|
file | string | Source path, usually relative to the project/source root. |
line | number | 1-based Cobble source line. |
column | number | 1-based Cobble source column. |
Experimental Doctor Output Status
doctor --json reports configured build output status under
experimental_output. This field is not part of the stable metadata contract
yet; it lets CI and editor tooling distinguish an unbuilt project from an
existing Cobble-generated output directory without running a build.
The report includes the resolved configured output path, whether that path
exists, and marker information for .cobble/build_manifest.json. A missing
configured output is reported as not_present and does not make the top-level
doctor status a warning. Existing output with no Cobble marker, a stale marker,
a mismatched namespace, or a mismatched project_id is reported as warning.
Symlink traversal, symlink descendants, non-directory output paths, or
unreadable marker state are reported as error.
Project-local .cobble/link_state.json
cobble link writes this file in the project directory. It records the
explicit local target used by watch --link, clean --linked, and
doctor --json.
Stable fields for schema version 1:
| Field | Type | Meaning |
|---|---|---|
version | number | Link-state schema version. Currently 1. |
target_kind | string | One of datapacks, world, or minecraft. |
target_path | string | Resolved target datapacks/ directory. |
pack_name | string | Directory name of the linked data pack. |
pack_path | string | Final linked data pack directory. |
doctor --json reports link state under experimental_link. That field is not
part of the stable metadata contract yet; it is labeled experimental so editor
and CI tooling can try it before 1.0 schema commitments.
Commands that consume link state validate that pack_path remains under
target_path, still ends with pack_name, and does not rely on an existing
target symlink. Link state reads, writes, and clears also refuse symlink
components in the project-local .cobble/link_state.json path. Tampered link
state is reported as an error by doctor --json, shown as invalid by
link --status, and refused by watch --link and clean --linked.
The linked pack is considered Cobble-owned only when its output directory
contains a valid .cobble/build_manifest.json alongside normal data pack files
such as pack.mcmeta and data/. For linked workflows, the manifest
namespace must match the current project namespace and project_id must match
the current project root identity. Copied, stale, or namespace-only forged
manifests are reported as invalid and are not cleaned or replaced by
watch --link.
Compatibility
- Schema version
1fields above are treated as stable for 0.x tooling. - New optional fields may be added without a schema version bump.
- Removing or renaming a stable field requires a schema version bump and a changelog note.
- Tests assert the object shapes for these stable fields to catch accidental field removal.