@carbonenginejs/format-red

CarbonEngineJS-facing reader for Red data — a type-discriminated, self-referential YAML object graph (type: per node, YAML anchors/aliases for shared references). It emits a compact public payload by default, a cleaned raw graph, or caller-supplied runtime classes through the @carbonenginejs/core-types hydration adapter.

YAML syntax parsing is provided by @carbonenginejs/format-yaml. This package sits on top of that generic, safe syntax/data layer and owns only Red semantics: authoring-key stripping, typed-table decoding, graph references, and runtime hydration. It does not load yaml or js-yaml directly.

Any red or blue meta data should be stripped when publishing.

The package imports the current compact Carbon class definitions from @carbonenginejs/format-carbon/definitions/black and re-exports the class map through @carbonenginejs/format-red/schema. It stores no generated schema folder. Red parsing remains driven by YAML values and does not use Black wire descriptors to interpret source text.

Provenance

CarbonEngine and Fenris Creations (CCP Games) are named in this package for interoperability and schema-provenance context only. This package contains CarbonEngineJS original code unless NOTICE is expanded; it is not affiliated with or endorsed by CCP Games.

Public API

The package root exports one public class: CjsFormatRED.

import CjsFormatRED from "@carbonenginejs/format-red";

const red = new CjsFormatRED({
  emit: "json",            // "json"/"payload" (default) | "runtime" | "raw"
  classes: { EveChildContainer, Tr2Effect, Tr2PointLight /* … by Red type */ },
});

const payload = red.Read(source);            // compact public payload
const text = JSON.stringify(red.ToJSON(payload));

source is either an already-parsed Red object graph, or a YAML string read through CjsFormatYAML.readRaw. For compatibility, options.parse(text) still takes precedence and must return the parsed JS graph. Red YAML strings preserve anchor/alias identity and reject custom tags before semantic hydration.

Static one-shot methods are also available:

const payload = CjsFormatRED.readPayload(source);
const runtime = CjsFormatRED.readRuntime(source, { classes });
const raw     = CjsFormatRED.readRaw(source);
const summary = CjsFormatRED.inspect(source);

Schema-aware tools can use the canonical definitions through Red:

import redClasses from "@carbonenginejs/format-red/schema";

console.log(redClasses.Tr2SkinnedModel.geometryResPath); // "path"

Read modes

• Read / readPayload — compact public payload: each node carries _type, repeated (aliased) nodes emit { _reference: id } after the first full emission (which gains _id lazily), so the result is a JSON-safe tree.
• ReadRuntime / readRuntime — constructs caller classes (by Red type) via the core-types hydration adapter: construct → applyValues → finalize, with shared nodes resolving to one instance. Provide classes and/or a registry; pass adapter: createLifecycleAdapter() for SetValues/Initialize-style classes.
• ReadRaw / readRaw — the cleaned parsed graph (metadata stripped, typed tables decoded), shared references preserved by identity.
• Inspect / inspect — root type and a type histogram, without building the object graph.

Typed tables

Red's compact columnar encoding ({ structure, items }, used by curve keys, effect options, and samplerOverrides) decodes to an array of row objects keyed by column name — e.g. curve keys become [{ time, value, leftTangent, rightTangent, id, interpolation, tangentType }, …].

Options

• emit, schema, classes, registry, family
• adapter / adapters — hydration adapter(s) (see @carbonenginejs/core-types)
• parse — (text) => object YAML parser override
• payloadTypeField / payloadIdField / payloadReferenceField — default _type / _id / _reference; set to false to omit.

Baseline Checks

npm test
npm run lint