@carbonenginejs/format-gltf

Pure-JavaScript CarbonEngineJS-facing package for the glTF 2.0 / GLB format. No native tooling, no build step; it runs in Node and modern browsers.

The package currently exposes a read path. glTF is only the import source; it emits the shared CarbonEngineJS JSON geometry schema: deinterleaved vertex channels, triangle-index groups, optional skin skeletons, and explicit uncompressed transform animation curves.

CarbonEngine and Fenris Creations (CCP Games) are named in this package for interoperability and target-ecosystem context only. glTF itself is not a CCP format, and this package contains no CarbonEngine or Fenris Creations (CCP Games) source code.

Package

• npm: https://www.npmjs.com/package/@carbonenginejs/format-gltf
• package: @carbonenginejs/format-gltf
• version: 0.1.0
• license: MIT
• runtime: Node >=18, modern browsers
• module: ESM, package root exports CjsFormatGltf

Install

npm install @carbonenginejs/format-gltf

Public API

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

import CjsFormatGltf from "@carbonenginejs/format-gltf";

const gltf = new CjsFormatGltf({
    emit: "json",                  // "json" only for now
    source: "mesh.glb",            // name written to grannyFileSource
    buffers: null,                  // optional external .bin buffers for .gltf object input
    packTangents: false,            // opt-in: pack basis for GR2-style shader inputs
    uvHandedness: "right",          // "right" (default) | "left"
    rebuildMissingNormals: false,
    rebuildMissingTangents: false,
    rebuildMissingBiNormals: false,
    classes: {
        Root: CjsGeometryRoot,
        Mesh: CjsGeometryMesh,
        Model: CjsGeometryModel,
        Animation: CjsGeometryAnimation
    }
});

const json = gltf.Read(glbBytes);
const summary = gltf.Inspect(glbBytes);
const text = JSON.stringify(gltf.ToJSON(json));

The named export is the same class for callers that prefer named imports:

import { CjsFormatGltf } from "@carbonenginejs/format-gltf";

Format Rules

• The package root currently exports one public format class: CjsFormatGltf.
• Instance methods are PascalCase because format instances can hydrate or sit beside CarbonClasses without colliding with camelCase data fields.
• Static one-shot methods are camelCase because they live on CjsFormatGltf itself, not on hydrated CarbonClass instances.
• src/CjsFormatGltf.js is the public format boundary. Parser and geometry helpers live under src/core.
• Read / static read return the shared JSON schema. emit: "raw" is not exposed yet because parser state is intentionally internal.
• ToJSON / static toJSON converts format output to JSON-compatible data. It is not a glTF, GLB, OBJ, or GR2 writer.
• Shared schema, registries, hydration utilities, decorators, math helpers, and animation-curve helpers are expected to move into future shared core packages once those packages exist.

JSON Graph

emit: "json" is the only public output mode. Square-bracketed fields are conditional in the broader shared schema:

Root
|-- grannyFileFormatRevision, grannyFileSource
|-- meshes: Mesh[]
|   |-- name, minBounds, maxBounds
|   |-- boneBindings: BoneBinding[]
|   |-- morphTargets: MorphTarget[]
|   |-- vertex: VertexChannels
|   |   |-- position, normal, tangent, binormal
|   |   |-- texcoord0, texcoord1
|   |   |-- blendIndice, blendWeight
|   |   `-- all channels are flat numeric arrays
|   `-- indices: IndexGroup[]
|       `-- name, bytesPerIndex, faces
|-- models: Model[]
|   `-- name, skeleton, meshBindings
`-- animations: Animation[]
    `-- trackGroups: TrackGroup[]
        `-- transformTracks: TransformTrack[]
            |-- orientation: Curve
            |-- position: Curve
            `-- scaleShear: Curve

glTF animation samplers are emitted as explicit uncompressed curves:

{
    source: {
        format: 1,
        degree: 1,
        interpolation: "LINEAR",
        path: "orientation"
    },
    uncompressed: {
        dimension: 4,
        knots: [ 0, 1 ],
        controls: [ 0, 0, 0, 1, 0, 0, 0.707, 0.707 ]
    }
}

This is deliberate. glTF animation data is already explicit sampler data, so it should not pretend to be a compressed Granny curve. STEP samplers use degree 0; LINEAR and CUBICSPLINE currently emit key values with degree 1 while preserving the original interpolation name in source.interpolation.

glTF Coverage

This first version handles the practical geometry path:

• glTF 2.0 JSON objects
• UTF-8 .gltf JSON text/bytes
• .glb version 2 binary containers
• embedded data: buffers
• caller-provided external buffers via buffers
• Node-only readFile(path) for .gltf/.glb
• accessors, bufferViews, byte strides, normalized integer attributes
• sparse accessors
• triangle, triangle-strip, and triangle-fan primitives
• POSITION, NORMAL, TANGENT, TEXCOORD_0, TEXCOORD_1
• JOINTS_0 -> blendIndice
• WEIGHTS_0 -> blendWeight
• skins as shared-schema models/skeletons
• transform animation channels for translation, rotation, and scale
• morph target delta channels for position, normal, and tangent

Unsupported glTF primitive modes throw. Materials, textures, cameras, lights, scene transforms, mesh instancing, and extensions are not yet converted into CarbonEngineJS runtime objects.

Options

• emit: "json" default. Other values currently throw.
• source: default "memory". Written to grannyFileSource and used in error messages.
• buffers: optional external buffer source for object/JSON .gltf input. Accepts an array, map, or object keyed by buffer index or URI.
• packTangents: default false. true converts explicit normal/tangent/ binormal data into a packed four-component tangent channel for GR2-style shader inputs. glTF TANGENT.w is used when generating binormals.
• uvHandedness: "right" default. Used when tangents/binormals are generated rather than authored.
• rebuildMissingNormals: default false.
• rebuildMissingTangents: default false.
• rebuildMissingBiNormals: default false.
• Missing-channel rebuild options and packTangents also accept rule functions. They receive { format, options, raw, json, mesh, meshIndex, feature, channel } and must return true or false.
• classes: optional for new CjsFormatGltf(options), Read, and static read. Accepted keys are exposed as CjsFormatGltf.CLASS_KEYS.

Tests

npm test

Tests are fully self-contained and build glTF/GLB fixtures in memory. They do not require local asset folders, network access, or game files.

License

MIT (see LICENSE and NOTICE).

This package contains no CarbonEngine or Fenris Creations (CCP Games) code. Its output shape targets the shared CarbonEngineJS JSON geometry schema used for CarbonEngine interoperability.