H073.ModelKit 1.0.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 = FormatRegistry.LoadScene(GraphicsDevice, "character.glb");
var instance = scene.CreateInstance();
instance.Play("Idle");

Installation

dotnet add package H073.ModelKit

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
dotnet add package H073.HxOBJ.MonoGame    # OBJ / MTL
dotnet add package H073.HxSTL.MonoGame    # STL / STLX

Quick Start

using ModelKit;

Scene scene;
SceneInstance instance;

protected override void LoadContent()
{
    scene = FormatRegistry.LoadScene(GraphicsDevice, "character.glb");
    instance = scene.CreateInstance();
    instance.Play("Idle");
}

protected override void Update(GameTime gameTime)
{
    instance.Update((float)gameTime.ElapsedGameTime.TotalSeconds);
}

protected override void Draw(GameTime gameTime)
{
    var commands = new List<RenderCommand>();
    instance.CollectRenderCommands(commands);

    foreach (var cmd in commands)
    {
        // cmd.Material    — Material (color, textures, PBR factors)
        // cmd.WorldTransform — Matrix
        // cmd.BoneMatrices   — Matrix[]? (for skinned meshes)
        // Use your own shader/effect to render
        cmd.Apply(GraphicsDevice);
        cmd.Draw(GraphicsDevice);
    }
}

Scene Graph

Scene is the root container for all 3D data:

Scene
├── SceneNode[]       — Hierarchical transform nodes
├── Mesh[]            — Geometry (MeshPrimitive[] with GPU buffers)
├── Material[]        — PBR / Phong / Unlit materials
├── Skeleton[]        — Bone hierarchies + inverse bind matrices
├── AnimationClip[]   — Keyframe animations
├── SceneCamera[]     — Cameras
├── SceneLight[]      — Light sources
├── SceneBounds       — Axis-aligned bounding box (lazy)
└── SceneSphere       — Bounding sphere (lazy)

Instances

var instance = scene.CreateInstance();
instance.WorldTransform = Matrix.CreateTranslation(5, 0, 0);
instance.Play("Walk", loop: true, blendDuration: 0.2f);
instance.Update(deltaTime);

Multiple instances share GPU resources (meshes, textures) while each has its own animation state and transform.

Materials

Material supports PBR, Phong, and Unlit workflows:

var mat = scene.Materials[0];

mat.Type            // MaterialType.Pbr, Phong, or Unlit
mat.Color           // Base/diffuse color (RGBA)
mat.Texture         // Base color texture
mat.EmissiveFactor  // Emissive color multiplier
mat.EmissiveMap     // Emissive texture

mat.AlphaMode       // Opaque, Mask, Blend
mat.AlphaCutoff     // Threshold for Mask mode
mat.DoubleSided     // Backface culling

// PBR
mat.MetallicFactor, mat.RoughnessFactor
mat.NormalMap, mat.MetallicRoughnessMap
mat.OcclusionMap, mat.OcclusionStrength

// Phong
mat.SpecularColor, mat.Shininess, mat.SpecularMap

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

Animation

// Via SceneInstance (recommended)
instance.Play("Walk");
instance.Play(0);                    // by index
instance.AddLayer("UpperBody", 0.5f); // blending
instance.Stop(blendDuration: 0.3f);

// Low-level
var clip = scene.GetAnimation("Walk");
var player = new AnimationPlayer();
player.Play(clip, loop: true);
player.Update(deltaTime);

Interpolation Modes

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

Loading

Auto-Discovery

ModelKit scans loaded assemblies for [assembly: FormatLoader(typeof(...))] attributes. Just reference a loader package.

var scene = FormatRegistry.LoadScene(GraphicsDevice, "model.glb");
var scene = await FormatRegistry.LoadSceneAsync(GraphicsDevice, "model.glb");

bool canLoad = FormatRegistry.CanLoad(".glb");
string[] exts = FormatRegistry.SupportedExtensions;

Manual Registration

FormatRegistry.Register(new MyCustomLoader());

Creating a Loader Plugin

public class MyLoader : IFormatLoader
{
    public string[] SupportedExtensions => [".myf"];

    public IAsset Load(GraphicsDevice device, string path, LoadOptions? options = null)
    {
        // Parse file → build Scene
        return new Scene { Name = Path.GetFileName(path), ... };
    }

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

[assembly: FormatLoader(typeof(MyLoader))]

Load Options

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

Binary Format (KBIN)

using ModelKit.Data;

KbinFile.Save("scene.kbin", scene);
var scene = KbinFile.Load(GraphicsDevice, "scene.kbin");

Available Loader Plugins

License

MIT

Contact

Discord: sameplayer