@carbonenginejs/format-carbon

CarbonEngineJS schema emitter and build tool. It turns Carbon Blue scan-report JSON into the current versioned schema tree used by downstream readers, generators, and build steps.

This package looks forward only. The current schema version is 1; older or future schema documents are rejected instead of migrated in place.

Public API

The package root exports one public class: CjsFormatCarbon. The Cjs prefix marks this as a CarbonEngineJS format/construction boundary, not an engine runtime class.

import CjsFormatCarbon from "@carbonenginejs/format-carbon";

const bundle = CjsFormatCarbon.read("build-tools/carbon-blue/reports/full-latest.json");
const summary = CjsFormatCarbon.inspect(bundle);
const manifest = CjsFormatCarbon.write(bundle, "src/schema");
const blackManifest = CjsFormatCarbon.writeBlackDefinitions("src/schema", "../format-black/schema");

Named import is also available:

import { CjsFormatCarbon } from "@carbonenginejs/format-carbon";

read, inspect, and write accept a plain object, JSON text, UTF-8 bytes, a JSON file path, or an emitted schema directory. Inputs may be a Carbon Blue scan report, an emitted schema bundle, a root index, a family index, an enum document, or a class schema.

Schema Imports

Published packages include the latest generated schema JSON under @carbonenginejs/format-carbon/schema. Consumers can import only the schema documents they need:

import schemaIndex from "@carbonenginejs/format-carbon/schema" with { type: "json" };
import effectSchema from "@carbonenginejs/format-carbon/schema/shader/Tr2Effect" with { type: "json" };

Node ESM requires JSON import attributes. Bundlers may allow equivalent JSON imports without the with clause.

Each class schema keeps the source-facing data together: C++ fields, Blue exposure metadata, inferred black wire fields, source hashes, and review notes. Smaller black/red/public projections should be derived from these v1 schemas so there is one canonical source of truth.

readBlackDefinitions and writeBlackDefinitions project only the Black/public-facing surface. The generated Black bundle contains a class map: each classes key is a Black class name and the value is that class's compact field map. Ordinary fields are emitted as property-name to reader-type pairs:

{
  "EveSOFDataHull": {
    "name": "string",
    "geometryResFilePath": "path",
    "hull": "array"
  }
}

Fields that need more context use tiny objects, for example enum fields or ordered chooser/index properties:

{ "Primary": { "type": "color", "field": "colors", "index": "primary" } }

The projection writes one named JSON bundle such as black-schema-v1-2026-07-01.json, containing schema/version/date metadata, enums, and classes. Classes with no exposed Black properties are omitted from the projection because the Black reader only needs a class definition when it has fields to resolve. Source refs, hashes, Blue decorators, methods, defaults, and review notes stay in the canonical format-carbon schema tree.

Class schemas keep source paths in a per-document sourceRefs table. Nested locations use compact ids such as { "file": "#ref2", "line": 29 }; resolve the id through sourceRefs when a full source path is needed.

Black field schemas compact repeated naming aliases into a field-local names map:

{ "name": "name fieldName", "m_name": "cppName member memberPath memberRoot" }

That means the black/public field name and the normalized field name are both name, while the C++ member aliases are m_name.

The emitter filters scanner artifacts that have no header, no fields, no Blue metadata, no parent data, and no review notes. This removes pseudo-types such as std, Entry, and CurrentValues from the importable schema tree. Header backed data structs such as lights/LightData remain even when they are not Blue-exposed.

Enums are emitted in schema/enums. Standalone constants are not part of the v1 schema surface yet; adding them should be a deliberate schema-versioned extension.

CLI

The package provides carbon-schema and format-carbon binaries.

carbon-schema build-tools/carbon-blue/reports/full-latest.json --inspect
carbon-schema build-tools/carbon-blue/reports/full-latest.json --out src/schema --clean --quiet
carbon-schema src/schema --black-out ../format-black/schema --clean --quiet

--clean removes the output directory before writing, which keeps generated schema folders from retaining stale JSON files.

Reader Rules

• Instance methods are PascalCase because reader instances can hydrate and extend CarbonClasses without colliding with camelCase Carbon data fields or future instance methods.
• Static one-shot methods are camelCase because they live on CjsFormatCarbon itself.
• Use reader.SetClass(type, Class), reader.SetClasses(classes), or classes in the options object for class hydration.
• Accepted class keys are exposed as CjsFormatCarbon.CLASS_KEYS.
• Shared schema, decorators, registries, and hydration utilities belong in the future @carbonenginejs/core-types package.

Baseline Checks

npm test
npm run lint