H073.HxGLTF.MonoGame 1.3.0

HxGLTF.MonoGame

Load glTF/GLB models into MonoGame — with PBR materials, skeletal animation, and a clean scene graph powered by ModelKit.

HxGLTF.MonoGame bridges HxGLTF (a pure .NET GLTF 2.0 parser) and ModelKit (a model abstraction layer). One line loads a model into a fully usable ModelScene.

var scene = ModelLoader.LoadScene(GraphicsDevice, "character.glb");

Note: This README was generated with the help of AI. The library code itself was written entirely by hand.

Table of Contents

• Installation
• Quick Start
• Loading Models
• Deferred Loading (Parse / Upload)
• Animation
• Materials
• Load Options
• Architecture
• Migration from 1.2.x
• Limitations
• Contact

Installation

dotnet add package H073.HxGLTF.MonoGame

Or add to your .csproj:

<PackageReference Include="H073.HxGLTF.MonoGame" Version="1.3.0" />

This pulls in H073.HxGLTF (core parser) and H073.ModelKit (scene graph & animation) as dependencies.

Quick Start

using ModelKit;

ModelScene scene;

protected override void LoadContent()
{
    // ModelKit auto-discovers GlbModelLoader via assembly attribute
    scene = ModelLoader.LoadScene(GraphicsDevice, "Content/Models/character.glb");
}

protected override void Update(GameTime gameTime)
{
    // Update animations, skeletons, etc.
    scene.Update(gameTime);
}

protected override void Draw(GameTime gameTime)
{
    // Collect render commands and draw with your own renderer
    var commands = scene.CollectRenderCommands();
    foreach (var cmd in commands)
    {
        // cmd.Primitive, cmd.Material, cmd.WorldTransform, etc.
        DrawMesh(cmd);
    }
}

protected override void UnloadContent()
{
    scene.Dispose();
}

Note: ModelKit does not include a built-in renderer — you build your own using the RenderCommand data (vertex buffers, materials, transforms).

Loading Models

Via ModelKit (recommended)

ModelLoader auto-discovers GlbModelLoader at runtime via the [assembly: ModelKitLoader] attribute. No manual registration needed.

// Synchronous
var scene = ModelLoader.LoadScene(GraphicsDevice, "model.glb");

// Asynchronous
var scene = await ModelLoader.LoadSceneAsync(GraphicsDevice, "model.glb");

// Check support
bool canLoad = ModelLoader.CanLoad(".glb"); // true

Direct

using HxGLTF.Monogame;

var loader = new GlbModelLoader();
var scene = (ModelScene)loader.Load(GraphicsDevice, "model.glb");

Deferred Loading (Parse / Upload)

Separate CPU parsing from GPU upload — useful for background loading or build pipelines.

using HxGLTF.Monogame;

// Step 1: Parse on any thread (CPU only, no GraphicsDevice needed)
var parsed = GlbModelLoader.Parse("model.glb");

// Step 2: Upload on the graphics thread
var scene = GlbModelLoader.Upload(GraphicsDevice, parsed);

Animation

ModelKit provides a full animation system that works with glTF animations loaded through this bridge.

// Find and play an animation
var clip = scene.FindAnimation("Walk");

var player = new AnimationPlayer();
player.Clip = clip;
player.Loop = true;
player.Play();

// In Update
player.Update((float)gameTime.ElapsedGameTime.TotalSeconds);

// Apply to skeleton
if (scene.Skeletons.Length > 0)
{
    var skeleton = scene.Skeletons[0];
    skeleton.ComputeJointMatrices();
}

Supported Interpolation

• Linear — standard interpolation
• Step — instant transitions
• CubicSpline — smooth curves with tangents

Channel Targets

• Translation, Rotation, Scale (bone/node transforms)
• Morph weights

Materials

glTF materials are converted to GameMaterial with full PBR support:

foreach (var mat in scene.Materials)
{
    // Material type: Pbr, Phong, or Unlit
    var type = mat.Type;

    // Common properties
    var color = mat.MainColor;
    var texture = mat.MainTexture;
    var alpha = mat.AlphaMode; // Opaque, Mask, Blend

    // PBR-specific
    var metallic = mat.MetallicFactor;
    var roughness = mat.RoughnessFactor;
    var normalMap = mat.NormalMap;
    var emissive = mat.EmissiveTexture;
}

Supported Vertex Formats

• VertexPositionNormalTexture — standard meshes
• VertexPositionNormalTextureSkin — skinned meshes (bone indices + weights)
• VertexPositionNormalTextureTangent — meshes with tangent data
• VertexPositionNormalTextureColor — meshes with vertex colors

Load Options

// Default
var scene = ModelLoader.LoadScene(GraphicsDevice, "model.glb");

// With options
var options = new LoadOptions
{
    SkipAnimations = false,
    SkipSkins = false,
    SkipTextures = false,
    KeepCpuData = true,        // retain CPU-side vertex data (for raycasting, etc.)
    CalculateBounds = true,    // compute bounding boxes
    MaxTextureSize = 2048,     // limit texture resolution
};
var scene = ModelLoader.LoadScene(GraphicsDevice, "model.glb", options);

// Presets
var scene = ModelLoader.LoadScene(GraphicsDevice, "model.glb", LoadOptions.ForRendering);
var scene = ModelLoader.LoadScene(GraphicsDevice, "model.glb", LoadOptions.ForCollision);
var scene = ModelLoader.LoadScene(GraphicsDevice, "model.glb", LoadOptions.ForPreview);

Architecture

model.glb
  │
  ▼
HxGLTF (pure parser)
  │  GLTFLoader.Load() → GLTFFile
  ▼
HxGLTF.MonoGame (bridge)
  │  GlbModelLoader → converts to ModelKit types
  ▼
ModelKit (scene graph)
  │  ModelScene
  ├── SceneNode[]        (scene graph with TRS transforms)
  ├── Mesh[]             (MeshPrimitive[] with GPU buffers)
  ├── GameMaterial[]     (PBR / Phong / Unlit)
  ├── Skeleton[]         (bones + inverse bind matrices)
  ├── AnimationClip[]    (keyframe channels)
  ├── SceneCamera[]      (perspective / orthographic)
  └── RenderCommand[]    (collected draw calls)

Auto-Discovery

HxGLTF.MonoGame registers itself via:

[assembly: ModelKitLoader(typeof(GlbModelLoader))]

ModelKit scans loaded assemblies for this attribute. Just reference the package — no manual setup needed.

Migration from 1.2.x

Version 1.3.0 is a major rework. HxGLTF.MonoGame no longer provides its own GameModel, renderer, LOD, instancing, or streaming. Instead, it bridges to ModelKit, which provides the scene graph and animation system.

Why the change?

ModelKit is a format-agnostic model abstraction. HxGLTF.MonoGame is now a thin loader plugin — all scene graph, animation, and material logic lives in ModelKit, making it reusable across formats (glTF, OBJ, STL, KBIN, ...).

Limitations

• No built-in renderer — ModelKit provides data, you provide the rendering.
• GPU thread requirement — VertexBuffer, IndexBuffer, and Texture2D creation must happen on the main/graphics thread. Use Parse()/Upload() for background loading.
• Maximum bone count depends on your shader's constant buffer size.

Related Packages

• H073.HxGLTF — Pure .NET GLTF 2.0 parser (no MonoGame dependency)
• H073.ModelKit — Model abstraction layer with animation, materials, and scene graph

License

MIT

Contact

Discord: sameplayer