# Cobble Metadata Files
Cobble writes metadata under `.cobble/` in every non-dry-run build output.
These files are intended for inspection, validation diagnostics, and future
editor tooling. Schema `version` values are per-file schema versions, not 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`:
| `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 `101.1`. |
| `namespace` | string | Generated data pack namespace. |
| `description` | string | Pack description written to `pack.mcmeta`. |
| `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. |
`input` fields:
| `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:
| `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. |
Each `resources` entry has:
| `kind` | string | Resource kind such as `function_tag` or `predicate`. |
| `namespace` | string | Resource namespace. |
| `path` | string | Resource path without namespace or file extension. |
When validation runs, `validation` has:
| `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 back to Cobble source locations.
It is written when generated command metadata exists.
Stable top-level fields for schema version `1`:
| `version` | number | Source-map schema version. Currently `1`. |
| `entries` | array | Generated command mappings. |
Each entry has:
| `generated_path` | string | Generated `.mcfunction` 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. |
| `source` | object or null | Cobble source location when known. |
| `kind` | string | Command origin: `UserCommand`, `StdLib`, `RuntimeSetup`, `ControlFlow`, or `JsonGenerated`. |
`source` has:
| `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. |
## Compatibility
- Schema version `1` fields 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.