#moonbit-gltf-tools

#Project positioning

• glTF 2.0 JSON documents and GLB containers;
• structural validation and actionable diagnostics;
• scene graph, transform, resource, accessor, and mesh analysis;
• binary accessor decoding, GLB writing, semantic validation, and extension audits;
• topology quality, meshlet planning, vertex-cache analysis, spatial queries, instancing, and progressive resource streaming;
• machine-readable reports for automation;
• a native CLI for local inspection and CI integration.

#Core capabilities

#Parsing

• Parse glTF 2.0 JSON into strongly typed MoonBit data structures.
• Unpack GLB headers, JSON chunks, and optional BIN chunks.
• Decode the core scene, mesh, material, texture, image, animation, skin, accessor, buffer, and buffer view structures.

#Validation and diagnostics

• Validate reference bounds across scenes, nodes, meshes, materials, buffers, accessors, animations, and skins.
• Detect scene graph cycles and invalid child references.
• Check accessor element sizes, byte strides, alignment, buffer view windows, and normalization constraints.
• Produce configurable diagnostic summaries with severity, code, path, message, and remediation hints.

#Analysis and optimization

• Traverse scene graphs and evaluate inherited TRS transforms.
• Estimate vertices, indices, triangles, draw calls, attribute slots, and vertex memory.
• Report indexed geometry ratios, missing vertex attributes, material usage, animation channels, and skinning information.
• Audit embedded and external resource dependencies.
• Apply configurable quality gates for general and mobile-oriented pipelines.
• Build deterministic optimization plans for geometry, materials, resources, animation, skinning, and runtime budgets.

#Reporting

• Build a single AssetReport from the parser, validator, scene, resource, geometry, and quality-analysis passes.
• Export stable debug representations for CLI and automation consumers.
• Inspect URI safety, media types, data URIs, and common asset extensions.

#Quick start

#Prerequisites

#Build and test the repository

moon update
moon check --target all --deny-warn
moon test --target native --deny-warn
moon test --target wasm-gc --deny-warn
moon build --target native --deny-warn

#Run the sample asset

moon run --target native cmd/main benchmarks/minimal.gltf
moon run --target native cmd/main benchmarks/minimal.gltf --json

#Library usage

moon add hzfhzf89/moonbit-gltf-tools

///|
import {
  "hzfhzf89/moonbit-gltf-tools/gltf",
}

///|
fn inspect_asset(json : String) raise {
  let document = @gltf.parse_gltf_string(json)
  let report = @gltf.build_default_asset_report(document)
  println("triangles=\\{report.geometry.triangles}")
  println("diagnostics=\\{report.diagnostics.errors}")
}

#CLI

moon run --target native cmd/main path/to/asset.gltf
moon run --target native cmd/main path/to/asset.glb
moon run --target native cmd/main path/to/asset.gltf --json

1. structural validation results;
2. scene graph and resource dependency summaries;
3. mesh and animation metadata;
4. optimization suggestions;
5. quality-gate score and violations.

#Architecture

.
├── lib.mbt                  # root facade exports
├── gltf/
│   ├── types.mbt            # glTF 2.0 data model
│   ├── parser.mbt           # JSON document parser
│   ├── glb.mbt              # GLB container handling
│   ├── validator.mbt        # reference and structure validation
│   ├── diagnostics.mbt      # configurable diagnostic engine
│   ├── accessor.mbt         # accessor and buffer layout analysis
│   ├── scene.mbt            # scene graph and resource analysis
│   ├── transform.mbt        # TRS/world-transform evaluation
│   ├── mesh_analysis.mbt    # geometry cost analysis
│   ├── analyzer.mbt         # optimization suggestions
│   ├── report.mbt           # unified asset reports
│   ├── quality.mbt          # quality gates
│   ├── uri.mbt              # URI classification and safety checks
│   ├── binary_reader.mbt    # bounded reads and accessor decoding
│   ├── binary_writer.mbt    # aligned GLB construction and inspection
│   ├── geometry_pipeline.mbt # geometry metrics and budget checks
│   ├── topology_analysis.mbt # manifold, boundary, and component analysis
│   ├── meshlet_pipeline.mbt # bounded meshlet and LOD planning
│   ├── cache_optimizer.mbt  # vertex-cache metrics and reordering
│   ├── spatial_query.mbt    # bounds, ray, frustum, and nearest queries
│   ├── instance_batching.mbt # transform and draw-batch planning
│   ├── streaming_scheduler.mbt # progressive resource scheduling
│   ├── semantic_validation.mbt # policy-driven semantic validation
│   ├── resource_pipeline.mbt # resource manifests and package plans
│   ├── animation_pipeline.mbt # track sampling and clip budgets
│   ├── skin_pipeline.mbt    # joint and weight analysis
│   └── report_formats.mbt   # JSON, Markdown, and CI annotations
├── cmd/main/main.mbt        # native command-line entry point
├── benchmarks/              # deterministic benchmark fixtures
└── .github/workflows/       # cross-platform CI

#Benchmarks

moon run --target native cmd/main benchmarks/minimal.gltf --json

#Testing

moon fmt
moon check --target all --deny-warn
moon test --target all --deny-warn
moon build --target native --deny-warn
moon info

#CI

• moon check --target all --deny-warn;
• native build verification;
• formatting and public-interface drift checks;
• moon test --target all --deny-warn.

#License