H073.ModelKit 0.1.0

ModelKit — 3D Model Abstraction Layer for MonoGame

ModelKit is a format-agnostic 3D model framework for MonoGame. It provides a unified scene graph, PBR materials, skeletal animation, and an auto-discovery loader system that supports multiple file formats through plugins.

// Load any supported format — the right loader is found automatically
var scene = ModelLoader.LoadScene(GraphicsDevice, "character.glb");
var obj = ModelLoader.LoadScene(GraphicsDevice, "building.obj");

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
• Scene Graph
• Loading Models
• Loader Plugins
• Animation
• Materials
• Skeletons
• Rendering
• Load Options
• Binary Format (KBIN)
• Architecture
• Contact

Installation

dotnet add package H073.ModelKit

Or in .csproj:

<PackageReference Include="H073.ModelKit" Version="0.1.0" />

Format-Specific Loaders

ModelKit itself doesn't parse any file format. Add loader plugins for the formats you need:

dotnet add package H073.HxGLTF.MonoGame   # glTF / GLB support

Quick Start

using ModelKit;
using ModelKit.Animation;

ModelScene scene;
AnimationPlayer player;

protected override void LoadContent()
{
    scene = ModelLoader.LoadScene(GraphicsDevice, "character.glb");

    // Set up animation
    var clip = scene.FindAnimation("Idle");
    if (clip != null)
    {
        player = new AnimationPlayer { Clip = clip, Loop = true };
        player.Play();
    }
}

protected override void Update(GameTime gameTime)
{
    float dt = (float)gameTime.ElapsedGameTime.TotalSeconds;
    player?.Update(dt);

    // Recompute skeleton joint matrices
    foreach (var skeleton in scene.Skeletons)
        skeleton.ComputeJointMatrices();
}

protected override void Draw(GameTime gameTime)
{
    var commands = scene.CollectRenderCommands();
    foreach (var cmd in commands)
    {
        // Use cmd.Primitive, cmd.Material, cmd.WorldTransform
        // to draw with your own shader/effect
    }
}

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

Scene Graph

ModelScene is the root container for all 3D data:

ModelScene
├── SceneNode[]       — Hierarchical scene graph (TRS transforms)
├── Mesh[]            — Geometry (MeshPrimitive[] with GPU buffers)
├── GameMaterial[]    — PBR / Phong / Unlit materials
├── Skeleton[]        — Bone hierarchies + inverse bind matrices
├── AnimationClip[]   — Keyframe animations
├── SceneCamera[]     — Perspective / Orthographic cameras
├── Light[]           — Light sources
├── SceneBounds       — Axis-aligned bounding box (lazy)
└── SceneSphere       — Bounding sphere (lazy)

Nodes

foreach (var rootIdx in scene.RootNodeIndices)
{
    var node = scene.Nodes[rootIdx];
    // node.Name, node.LocalTransform (Matrix)
    // node.MeshIndex, node.CameraIndex, node.LightIndex, node.SkinIndex
    // node.ChildIndices[]
}

Instances

// Create per-instance data (transforms, bone matrices)
var instance = scene.CreateInstance();

Loading Models

Auto-Discovery

ModelKit scans loaded assemblies for [assembly: ModelKitLoader(typeof(...))] attributes. Just reference a loader package — no manual registration needed.

// Works if H073.HxGLTF.MonoGame is referenced
var scene = ModelLoader.LoadScene(GraphicsDevice, "model.glb");

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

// Check what formats are available
bool canLoad = ModelLoader.CanLoad(".glb");
var extensions = ModelLoader.SupportedExtensions;

Manual Registration

ModelLoader.Register(new MyCustomLoader());

Loader Plugins

To create a loader for a new format, implement IModelLoader:

public class MyFormatLoader : IModelLoader
{
    public string[] SupportedExtensions => [".myf"];

    public IModelAsset Load(GraphicsDevice device, string path, LoadOptions? options = null)
    {
        // Parse file → build ModelScene
        var scene = new ModelScene { Name = Path.GetFileName(path) };
        // ... populate nodes, meshes, materials ...
        return scene;
    }

    public Task<IModelAsset> LoadAsync(GraphicsDevice device, string path,
        LoadOptions? options = null, IProgress<float>? progress = null,
        CancellationToken ct = default)
    {
        return Task.FromResult(Load(device, path, options));
    }
}

// Register via assembly attribute:
[assembly: ModelKitLoader(typeof(MyFormatLoader))]

Animation

AnimationClip & AnimationPlayer

// Find a clip
var walkClip = scene.FindAnimation("Walk");
var runClip = scene.GetAnimation("Run"); // throws if not found

// Create a player
var player = new AnimationPlayer
{
    Clip = walkClip,
    Speed = 1.0f,
    Loop = true,
};

player.Play();
player.Update(deltaTime);

// Query state
bool isPlaying = player.State == PlaybackState.Playing;
float time = player.Time;
float normalized = player.NormalizedTime; // 0..1

// Events
player.Completed += () => Console.WriteLine("Done");

Channels & Targets

Animations consist of typed channels that target specific properties:

// AnimationTarget specifies what is animated
// Kind: Bone, Node, Material, Mesh, UV, Custom
// Property: Translation, Rotation, Scale, Opacity, MorphWeights, ...

Interpolation Modes

• Linear — standard interpolation
• Step — instant value changes
• CubicSpline — smooth curves with in/out tangents

Materials

GameMaterial supports PBR, Phong, and Unlit workflows:

var mat = scene.Materials[0];

// Type
mat.Type // MaterialType.Pbr, Phong, or Unlit

// Common
mat.MainColor       // Color (base/diffuse color)
mat.MainTexture     // GameTexture
mat.AlphaMode       // Opaque, Mask, Blend
mat.AlphaCutoff     // for Mask mode
mat.DoubleSided     // backface culling

// PBR
mat.MetallicFactor
mat.RoughnessFactor
mat.NormalMap
mat.MetallicRoughnessTexture
mat.EmissiveTexture
mat.OcclusionTexture
mat.EmissiveColor

// Phong
mat.AmbientColor
mat.SpecularColor
mat.Shininess

// Extensions
mat.ClearcoatFactor
mat.TransmissionFactor
mat.IOR

// Custom shader
mat.CustomEffect = myEffect;
mat.ApplyParameters = (effect, material) => { /* set uniforms */ };

// Extensible
mat.ExtendedProperties["myKey"] = myValue;

Skeletons

var skeleton = scene.Skeletons[0];

// Bones
foreach (var bone in skeleton.Bones)
{
    // bone.Name, bone.ParentIndex, bone.ChildIndices[], bone.LocalTransform
}

// Find a bone by name
var headBone = skeleton.FindBone("Head");

// Compute final joint matrices (call after animation update)
skeleton.ComputeJointMatrices();
var matrices = skeleton.JointMatrices; // Matrix[] ready for your shader

Rendering

ModelKit provides the data — you build the renderer.

// Collect all draw calls
var commands = scene.CollectRenderCommands();

// Sort (e.g., opaque first, then transparent back-to-front)
RenderSorter.Sort(commands, cameraPosition);

foreach (var cmd in commands)
{
    // cmd.Primitive      — MeshPrimitive (VertexBuffer, IndexBuffer, Topology)
    // cmd.Material       — GameMaterial (textures, colors, PBR factors)
    // cmd.WorldTransform — Matrix

    // Draw
    cmd.Primitive.Draw(GraphicsDevice);
}

MeshPrimitive

var prim = scene.Meshes[0].Primitives[0];

prim.VertexBuffer    // VertexBuffer (GPU)
prim.IndexBuffer     // IndexBuffer? (GPU, nullable)
prim.Topology        // PrimitiveTopology (Triangles, Lines, Points, ...)
prim.Material        // GameMaterial
prim.BoundingBox     // BoundingBox
prim.BoundingSphere  // BoundingSphere

// Optional CPU data (if LoadOptions.KeepCpuData = true)
prim.CpuPositions    // Vector3[]?
prim.CpuIndices      // int[]?

// Draw
prim.Draw(GraphicsDevice);

// Instancing
var bindings = prim.GetBindings(); // for instanced draw calls

Load Options

// Presets
LoadOptions.Default        // balanced defaults
LoadOptions.ForRendering   // skip CPU data, compute bounds
LoadOptions.ForCollision   // keep CPU data, skip textures
LoadOptions.ForPreview     // fast, minimal

// Custom
var options = new LoadOptions
{
    KeepCpuData = true,
    CalculateBounds = true,
    SkipTextures = false,
    SkipAnimations = false,
    SkipSkins = false,
    MaxTextureSize = 2048,
};

Binary Format (KBIN)

ModelKit includes KaiserBinary (.kbin), a universal binary asset format for fast serialization:

using ModelKit.Data;

// Save a scene to binary
KaiserBinary.Save("scene.kbin", scene);

// Load from binary
var scene = KaiserBinary.Load(GraphicsDevice, "scene.kbin");

KBIN stores GPU-ready data with LZ4 compression and DXT/BC texture encoding for minimal file size and fast loading.

Architecture

ModelKit
├── Core
│   ├── ModelScene         — Root scene container
│   ├── SceneNode          — Scene graph node (TRS transform + hierarchy)
│   ├── Mesh               — Collection of MeshPrimitive[]
│   ├── MeshPrimitive      — Single draw call (VertexBuffer + IndexBuffer)
│   ├── GameMaterial       — PBR / Phong / Unlit material
│   ├── Skeleton           — Bone hierarchy + inverse bind matrices
│   ├── SceneCamera        — Camera data
│   └── GameModelInstance  — Per-instance state
│
├── Animation
│   ├── AnimationClip      — Keyframe animation definition
│   ├── AnimationPlayer    — Playback control (play/pause/stop/loop)
│   ├── AnimationChannel   — Typed keyframe channel
│   └── AnimationSampler   — Keyframe storage + interpolation
│
├── Loading
│   ├── ModelLoader        — Static registry with auto-discovery
│   ├── IModelLoader       — Plugin interface for format loaders
│   ├── LoadOptions        — Configuration presets
│   └── ModelKitLoaderAttribute — Assembly attribute for auto-registration
│
├── Rendering
│   ├── RenderCommand      — Draw call data
│   ├── RenderSorter       — Command sorting
│   └── BoundsHelper       — Bounding volume computation
│
├── Data
│   ├── KaiserBinary       — Save / Load API for .kbin
│   ├── KbinWriter         — Streaming binary writer
│   └── KbinReader         — Streaming binary reader
│
└── Vertices
    ├── VertexPositionNormalTexture
    ├── VertexPositionNormalTextureSkin
    ├── VertexPositionNormalTextureTangent
    └── VertexPositionNormalTextureColor

Loader Auto-Discovery Flow

App references H073.HxGLTF.MonoGame (NuGet)
  └── Assembly has [assembly: ModelKitLoader(typeof(GlbModelLoader))]
        └── ModelLoader scans assemblies at first use
              └── GlbModelLoader registered for .glb / .gltf
                    └── ModelLoader.LoadScene("model.glb") dispatches to GlbModelLoader

Available Loader Plugins

License

MIT

Contact

Discord: sameplayer