menu
info Documentation

Linking Custom Models to Meshes

Introduction

A satellite component in D2S2 is drawn by a render object, which is linked to the component by a binder. This page explains how to create a component in user code that is drawn with your own mesh. The mesh must first be built as an .xnb file, as described in the Content Creation Guide. In this example, we will be linking a custom model "customModel" which inherits from SatellitePhysicalComponent to a render we made. The code required to create and link the visuals of the component is found at the end of the page.

Setup

Open Settings > Develop and select the active profile (see Developer User Settings):

  • Add the folder that contains your .cs files under Source Directories.
  • Add the folder that contains your .xnb files under Content Directories.
  • Tick Include visualisation reference assemblies. Without it, the render object does not compile.

D2S2 looks up content by name: the file name without the .xnb extension. It searches the application's Content folder first, then each content directory in the order listed. A file in a subfolder is named with its relative path, for example Antennas\customModel.

Creating the Model

A model with a render consists of three classes.

Component

The component (customModel.cs) derives from SatellitePhysicalComponent. This class contains all the logic of the component.

Render Object

The render object (customModelRenderObject.cs) derives from SatelliteComponentMeshModelRenderObject. It only has to return the content name of the mesh from ModelName. The base class loads, draws and selects the mesh. Textures linked from the model's material are loaded automatically. If the model has no texture linked, apply one in Initialise, as shown in the commented-out code of the example.

Binder

The binder (customModelViewElementBinder.cs) links the component to the render object. It derives from SatellitePhysicalComponentViewElementBinder<TComponent, TRenderObject>. That base class keeps the position and orientation of the mesh in sync with the component. Return null from ComponentBoundProperties when no other properties have to be passed to the render object.

Troubleshooting

D2S2 reports "Content '...' could not be found"

The name returned by ModelName does not match an .xnb file in the Content folder or a content directory. Check the name and the Content Directories list. The message lists every folder that was searched.

Compile errors about Microsoft.Xna.Framework

Include visualisation reference assemblies is not ticked in the active profile.

The component does not appear in the component list

The user code did not compile; check the Coding Errors list. Also check that the component class is public and has a ModelInfo attribute.

The mesh is not visible, or fills the view

The mesh is not in metres. Export it again at the correct scale. A model drawn in millimetres is 1000 times too large.

Appendix: Example Source

customModel.cs

using D2S2.Model;
using D2S2.Model.Satellite;
using D2S2.Shared;

namespace UserCode
{
    [DisplayName("customModel Component")]
    [ModelInfo("Satellite Components/UserCode", "UserCode", @"customModel component, drawn with the customModel mesh.")]
    public class customModel : SatellitePhysicalComponent
    {
        // does something
    }
}

customModelRenderObject.cs

using Microsoft.Xna.Framework.Content;
using Microsoft.Xna.Framework.Graphics;
using D2S2.Ui.Satellite;

namespace UserCode
{
    public class customModelRenderObject : SatelliteComponentMeshModelRenderObject
    {
        protected override string ModelName { get { return "customModel"; } }

        // If the model has no texture linked from its material, apply the texture during initialisation:

        //public override void Initialise(GraphicsDevice device, ContentManager contentManager)
        //{
        //    base.Initialise(device, contentManager);

        //    // the model has no texture reference, so apply the texture to its effects.
        //    // Load returns the same cached model instance that the base class draws.
        //    try
        //    {
        //        Texture2D texture = contentManager.Load<Texture2D>("customModeltexture");
        //        foreach (ModelMesh mesh in contentManager.Load<Microsoft.Xna.Framework.Graphics.Model>(ModelName).Meshes)
        //        {
        //            foreach (BasicEffect effect in mesh.Effects)
        //            {
        //                effect.Texture = texture;
        //                effect.TextureEnabled = true;
        //            }
        //        }
        //    }
        //    catch { }
        //}
    }
}

customModelViewElementBinder.cs

using D2S2.Binding;

namespace UserCode
{
    public class customModelViewElementBinder : SatellitePhysicalComponentViewElementBinder<customModel, customModelRenderObject>
    {
        protected override ModelViewPropertyBinding[] ComponentBoundProperties
        {
            get { return null; }
        }
    }
}