# khronosgroup/gltf-csharp-loader architecture

> Architecture diagram of the GitHub repository khronosgroup/gltf-csharp-loader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khronosgroup/gltf-csharp-loader
- Repository: https://github.com/khronosgroup/gltf-csharp-loader

## Overview

1. **Repository purpose**
   - This is a C# reference implementation of a glTF loader.
   - The public entry point is the `glTFLoader` library, which exposes a simple API such as `Interface.LoadModel("PathToModel.gltf")`.

2. **Top-level architecture**
   - The repo is split into three main concerns:
     - **Code generation tooling**: `Generator`, `GeneratorLib`, `GeneratorSchema`
     - **Runtime loader library**: `glTFLoader`
     - **Validation/tests**: `GeneratorUnitTests`, `glTFLoaderUnitTests`
   - This separation is important: the schema model is generated, while the loader logic is handwritten.

3. **Schema generation pipeline**
   - `GeneratorSchema` contains the machinery for reading glTF schema/spec input and turning it into an internal representation.
   - `GeneratorLib` converts that representation into C# type definitions.
   - `Generator` is the executable that drives the generation process during the build.
   - The README indicates the generator consumes `.spec` files from the glTF repository and produces the schema classes used by the loader.

4. **Generated schema layer**
   - The `glTFLoader/Schema` folder contains the generated C# model types for the glTF format.
   - These types mirror the glTF domain model: `Gltf`, `Node`, `Mesh`, `Material`, `Accessor`, `Buffer`, `Scene`, `Texture`, `Animation`, `Skin`, and related child objects.
   - This layer is the primary data model boundary between parsed JSON and the loader API.

5. **Runtime loader responsibilities**
   - `glTFLoader` is the runtime assembly that consumers reference.
   - It contains the public interface (`Interface.cs`) and helper utilities for reading model files and converting them into the generated schema objects.
   - `ArrayConverter.cs` and `StreamExtensions.cs` suggest custom handling for JSON array shapes and stream-based file reading, which are key pieces of the parsing pipeline.

6. **Data flow from file to object graph**
   - A glTF file is loaded through the public API.
   - The loader reads the file stream, parses JSON into the generated schema classes, and builds the in-memory representation of the model.
   - The result is a strongly typed object graph rooted at `Gltf`, with references across nodes, meshes, materials, buffers, and textures resolved through the schema structure.

7. **Modeling strategy**
   - The schema types are organized around glTF inheritance and composition:
     - base/shared primitives like `GltfProperty`, `GltfChildOfRootProperty`, `Extension`, `Extras`
     - domain objects like `Accessor`, `MeshPrimitive`, `AnimationSampler`, `CameraPerspective`
   - This indicates the loader is oriented around faithfully representing the standard rather than abstracting it into a higher-level engine-specific API.

8. **Generator architecture**
   - `GeneratorLib` includes factories such as `ArrayValueCodegenTypeFactory` and `SingleValueCodegenTypeFactory`, implying the generator handles different schema field shapes differently.
   - `CodeGenerator`, `CodegenType`, and `CodegenTypeFactory` form the internal generation model.
   - The generator likely translates schema metadata into C# class declarations, properties, and converters.

9. **Testing boundaries**
   - `GeneratorUnitTests` validate the generation and schema parsing logic, protecting the codegen pipeline.
   - `glTFLoaderUnitTests` validate loader behavior against real sample models.
   - The README references the separate `glTF-Sample-Models` repository, so test coverage depends on external canonical test assets.

10. **External dependencies and build assumptions**
   - The solution depends on the glTF schema source repository and the glTF sample models repository being checked out alongside this repo.
   - This matters architecturally because the generated schema is not fully self-contained; it is derived from upstream glTF spec inputs.
   - The resulting package is published as a NuGet library (`glTF2Loader` per the README), making the loader consumable from other C# projects.

11. **How to think about the boundary for a diagram**
   - Draw one boundary for **schema generation inputs** coming from upstream glTF spec files.
   - Draw a second boundary for **generated schema types** in `glTFLoader/Schema`.
   - Draw a third boundary for the **runtime loader API** that reads `.gltf`/model data and returns typed objects.
   - Tests sit beside these boundaries and verify both code generation and runtime parsing.

Main entry points: [`glTFLoader/Schema/Gltf.cs`](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Gltf.cs) (Gltf root), [`GeneratorLib/CodeGenerator.cs`](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorLib/CodeGenerator.cs) (Codegen core), [`glTFLoader/Interface.cs`](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Interface.cs) (Loader API), [`GeneratorSchema/SchemaLoader.cs`](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorSchema/SchemaLoader.cs) (Schema loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External inputs"]
  node_spec_source["glTF spec<br/>upstream input"]
  node_sample_models["Sample models<br/>test assets"]
end

subgraph group_generation["Generation"]
  node_generator_app["Generator<br/>build tool<br/>[Program.cs]"]
  node_schema_loader["Schema loader<br/>schema ingest<br/>[SchemaLoader.cs]"]
  node_schema_parser["Schema parser<br/>[SchemaParser.cs]"]
  node_schema_model["Schema model<br/>schema IR<br/>[Schema.cs]"]
  node_codegen_core["Codegen core<br/>code generator<br/>[CodeGenerator.cs]"]
  node_codegen_types["Type model<br/>codegen model<br/>[CodegenType.cs]"]
  node_type_factories["Type factories<br/>codegen rules"]
end

subgraph group_runtime["Runtime loader"]
  node_runtime_api["Loader API<br/>public entrypoint<br/>[Interface.cs]"]
  node_stream_helpers["Stream helpers<br/>io helpers"]
  node_array_converter["Array converter<br/>json helper<br/>[ArrayConverter.cs]"]
  node_gltf_root["Gltf root<br/>generated schema<br/>[Gltf.cs]"]
  node_schema_base["Schema base<br/>generated schema<br/>[GltfProperty.cs]"]
  node_scene_models["Scene graph<br/>generated schema<br/>[Node.cs]"]
  node_material_models["Materials<br/>generated schema<br/>[Material.cs]"]
  node_resource_models["Resources<br/>generated schema<br/>[Buffer.cs]"]
  node_animation_models["Animation<br/>generated schema<br/>[Animation.cs]"]
end

subgraph group_tests["Tests"]
  node_generator_tests["Gen tests<br/>unit tests"]
  node_loader_tests["Loader tests<br/>unit tests"]
end

node_spec_source -->|"feeds"| node_schema_loader
node_generator_app -->|"drives"| node_schema_loader
node_schema_loader -->|"parses with"| node_schema_parser
node_schema_parser -->|"builds"| node_schema_model
node_schema_model -->|"inputs"| node_codegen_core
node_codegen_types -->|"shapes"| node_codegen_core
node_type_factories -->|"produces"| node_codegen_types
node_codegen_core -->|"emits"| node_gltf_root
node_generator_app -->|"invokes"| node_codegen_core
node_runtime_api -->|"uses"| node_stream_helpers
node_runtime_api -->|"uses"| node_array_converter
node_runtime_api -->|"returns"| node_gltf_root
node_gltf_root -->|"inherits"| node_schema_base
node_gltf_root -->|"contains"| node_scene_models
node_gltf_root -->|"contains"| node_material_models
node_gltf_root -->|"contains"| node_resource_models
node_gltf_root -->|"contains"| node_animation_models
node_generator_tests -->|"validates"| node_schema_model
node_generator_tests -->|"validates"| node_codegen_core
node_loader_tests -->|"validates"| node_runtime_api
node_loader_tests -->|"uses"| node_sample_models

click node_generator_app "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/Generator/Program.cs"
click node_schema_loader "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorSchema/SchemaLoader.cs"
click node_schema_parser "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorSchema/SchemaParser.cs"
click node_schema_model "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorSchema/Schema.cs"
click node_codegen_core "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorLib/CodeGenerator.cs"
click node_codegen_types "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorLib/CodegenType.cs"
click node_type_factories "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorLib/ArrayValueCodegenTypeFactory.cs"
click node_runtime_api "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Interface.cs"
click node_stream_helpers "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/StreamExtensions.cs"
click node_array_converter "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/ArrayConverter.cs"
click node_gltf_root "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Gltf.cs"
click node_schema_base "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/GltfProperty.cs"
click node_scene_models "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Node.cs"
click node_material_models "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Material.cs"
click node_resource_models "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Buffer.cs"
click node_animation_models "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Animation.cs"
click node_generator_tests "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorUnitTests/CodeGeneratorTest.cs"
click node_loader_tests "https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoaderUnitTests/SampleModelsTest.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spec_source,node_sample_models toneBlue
class node_generator_app,node_schema_loader,node_schema_parser,node_schema_model,node_codegen_core,node_codegen_types,node_type_factories toneAmber
class node_runtime_api,node_stream_helpers,node_array_converter,node_gltf_root,node_schema_base,node_scene_models,node_material_models,node_resource_models,node_animation_models toneMint
class node_generator_tests,node_loader_tests toneRose
```

## Components

### External inputs

Upstream glTF spec files and sample assets consumed by tooling and tests.

- **glTF spec**: upstream input · External .spec/schema inputs from the glTF source repository.
- **Sample models**: test assets · External glTF sample files used to validate loader behavior.

### Generation

Schema parsing and C# code generation pipeline.

- [Generator](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/Generator/Program.cs): build tool · Executable that drives schema generation during the build. · `Generator/Program.cs`
- [Schema loader](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorSchema/SchemaLoader.cs): schema ingest · Loads schema input into the generator's internal representation. · `GeneratorSchema/SchemaLoader.cs`
- [Schema parser](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorSchema/SchemaParser.cs): schema parse · Parses schema/spec structure into generator-friendly objects. · `GeneratorSchema/SchemaParser.cs`
- [Schema model](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorSchema/Schema.cs): schema IR · Internal representation of the glTF schema used by code generation. · `GeneratorSchema/Schema.cs`
- [Codegen core](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorLib/CodeGenerator.cs): code generator · Transforms generator IR into C# declarations and properties. · `GeneratorLib/CodeGenerator.cs`
- [Type model](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorLib/CodegenType.cs): codegen model · Codegen type abstractions shared by the generation pipeline. · `GeneratorLib/CodegenType.cs`
- [Type factories](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorLib/ArrayValueCodegenTypeFactory.cs): codegen rules · Factories that map schema field shapes to codegen types. · `GeneratorLib/ArrayValueCodegenTypeFactory.cs`

### Runtime loader

Public loader API and handwritten parsing helpers used by consumers.

- [Loader API](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Interface.cs): public entrypoint · Public consumer-facing API for loading glTF models. · `glTFLoader/Interface.cs`
- [Stream helpers](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/StreamExtensions.cs): io helpers · Helpers for stream-based file reading during model loading. · `glTFLoader/StreamExtensions.cs`
- [Array converter](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/ArrayConverter.cs): json helper · Custom handling for array-shaped JSON data in the loader. · `glTFLoader/ArrayConverter.cs`
- [Gltf root](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Gltf.cs): generated schema · Root object of the typed glTF model graph. · `glTFLoader/Schema/Gltf.cs`
- [Schema base](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/GltfProperty.cs): generated schema · Shared base types for glTF properties and root children. · `glTFLoader/Schema/GltfProperty.cs`
- [Scene graph](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Node.cs): generated schema · Core node/mesh/scene types that form the structural model. · `glTFLoader/Schema/Node.cs`
- [Materials](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Material.cs): generated schema · Material and PBR-related schema types. · `glTFLoader/Schema/Material.cs`
- [Resources](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Buffer.cs): generated schema · Buffer, image, sampler, and texture schema types. · `glTFLoader/Schema/Buffer.cs`
- [Animation](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoader/Schema/Animation.cs): generated schema · Animation and skinning schema types. · `glTFLoader/Schema/Animation.cs`

### Tests

Validation of generation logic and runtime loading behavior.

- [Gen tests](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/GeneratorUnitTests/CodeGeneratorTest.cs): unit tests · Validates schema parsing and code generation behavior. · `GeneratorUnitTests/CodeGeneratorTest.cs`
- [Loader tests](https://github.com/khronosgroup/gltf-csharp-loader/blob/main/glTFLoaderUnitTests/SampleModelsTest.cs): unit tests · Validates runtime loading against sample glTF assets. · `glTFLoaderUnitTests/SampleModelsTest.cs`

## Connections

- glTF spec → Schema loader: feeds · Schema/spec inputs are consumed by the generation pipeline.
- Generator → Schema loader: drives · The executable orchestrates schema ingestion.
- Schema loader → Schema parser: parses with · Loader delegates structured interpretation to the parser.
- Schema parser → Schema model: builds · Parsed schema data is normalized into the internal IR.
- Schema model → Codegen core: inputs · The code generator consumes the schema IR.
- Type model → Codegen core: shapes · Shared codegen type abstractions guide generation output.
- Type factories → Type model: produces · Factories create codegen type variants for different schema field shapes.
- Codegen core → Gltf root: emits · Generated C# schema classes are written into the runtime schema layer.
- Generator → Codegen core: invokes · The build tool runs the generator library.
- Loader API → Stream helpers: uses · The public API relies on stream utilities when loading files.
- Loader API → Array converter: uses · The public API uses custom JSON conversion helpers.
- Loader API → Gltf root: returns · Loaded models are materialized as typed glTF objects.
- Gltf root → Schema base: inherits · Generated root and child types share common schema base classes.
- Gltf root → Scene graph: contains · The root model references scene graph structures.
- Gltf root → Materials: contains · The root model references material structures.
- Gltf root → Resources: contains · The root model references resource and texture structures.
- Gltf root → Animation: contains · The root model references animation and skin structures.
- Gen tests → Schema model: validates · Unit tests protect schema parsing and generation inputs.
- Gen tests → Codegen core: validates · Unit tests cover the code generation pipeline.
- Loader tests → Loader API: validates · Tests exercise the public loading surface.
- Loader tests → Sample models: uses · Runtime tests depend on canonical sample assets.