Table of Contents

Class ModelComponent

Namespace
Stride.Engine
Assembly
Stride.Engine.dll

Add a Model to an Entity, that will be used during rendering.

[DataContract("ModelComponent")]
[Display("Model", null, Expand = ExpandRule.Once)]
[DefaultEntityComponentProcessor(typeof(ModelTransformProcessor))]
[DefaultEntityComponentRenderer(typeof(ModelRenderProcessor))]
[ComponentOrder(11000)]
[ComponentCategory("Model")]
public sealed class ModelComponent : ActivableEntityComponent, IIdentifiable, IModelInstance
Inheritance
object
ModelComponent
Implements
Inherited Members
Extension Methods

Constructors

ModelComponent()

Initializes a new instance of the ModelComponent class.

public ModelComponent()

ModelComponent(Model)

Initializes a new instance of the ModelComponent class.

public ModelComponent(Model model)

Parameters

model Model

The model.

Fields

BoundingBox

Gets the bounding box in world space.

public BoundingBox BoundingBox

Field Value

BoundingBox

The bounding box.

BoundingSphere

Gets the bounding sphere in world space.

public BoundingSphere BoundingSphere

Field Value

BoundingSphere

The bounding sphere.

Properties

HasMorphTargets

Whether any mesh of the Model has morph targets.

public bool HasMorphTargets { get; }

Property Value

bool

IsShadowCaster

Gets or sets a boolean indicating if this model component is casting shadows.

[DataMember(30)]
[Display("Cast shadows", null)]
public bool IsShadowCaster { get; set; }

Property Value

bool

A boolean indicating if this model component is casting shadows.

Materials

Gets the materials; non-null ones will override materials from Materials (same slots should be used).

[DataMember(40)]
public IndexingDictionary<Material> Materials { get; }

Property Value

IndexingDictionary<Material>

The materials overriding Materials ones.

MeshInfos

Gets the current per-entity state for each mesh in the associated model.

public IReadOnlyList<ModelComponent.MeshInfo> MeshInfos { get; }

Property Value

IReadOnlyList<ModelComponent.MeshInfo>

Model

Gets or sets the model.

[DataMember(10)]
public Model Model { get; set; }

Property Value

Model

The model.

MorphTargetNames

The distinct morph target names of the Model, empty when it has none. A name's index is its slot.

public IReadOnlyList<string> MorphTargetNames { get; }

Property Value

IReadOnlyList<string>

Remarks

A slot stands for one target name across the whole model: meshes with a target of the same name share its slot and its weight. Slots are the same for every component using the model, and stay valid until the model changes. The list is shared by every instance of the model, so reading it doesn't allocate.

Morphs

The authored morph settings, saved with the component: whether morphs apply, and the weight of each target by name.

[DataMember(60)]
[Display("Morphs", null, Expand = ExpandRule.Once)]
public ModelMorphSettings Morphs { get; }

Property Value

ModelMorphSettings

Examples

Find a target's slot once, then set its weight every frame without allocating:

int smile = model.FindMorphTarget("Smile");
// Each frame:
if (smile >= 0)
    model.SetMorphWeight(smile, 0.5f + 0.5f * MathF.Sin(time));

Remarks

A morph target (blend shape) is an alternative shape of a mesh, imported with the model. Its weight scales how far the vertices move towards that shape: 0 is the base shape, 1 the full target shape. Weights are not clamped: any finite value is allowed, including negative values and values above 1, which exaggerate or invert the shape.

The component holds two sets of weights. Weights are the authored weights, saved in the scene and edited in the editor. The runtime weights are what is rendered: they start from the authored weights, and SetMorphWeight(int, float), SetAllMorphWeights(float) and animation clips change them without changing the authored ones. Any change to the authored weights (an item added, changed or removed, or the dictionary replaced) replaces all runtime weights with the authored ones on the next frame.

Animation clips drive weights with the curve path [ModelComponent.Key].MorphWeights[TargetName]. A model without that target ignores the curve, so one clip can play on different models.

RenderGroup

The render group for this component.

[DataMember(20)]
[Display("Render group", null)]
public RenderGroup RenderGroup { get; set; }

Property Value

RenderGroup

Skeleton

[DataMember]
public SkeletonUpdater Skeleton { get; }

Property Value

SkeletonUpdater

Methods

FindMorphTarget(ReadOnlySpan<char>)

Finds the slot of a morph target by name, without allocating.

public int FindMorphTarget(ReadOnlySpan<char> name)

Parameters

name ReadOnlySpan<char>

The target name, compared case-sensitively.

Returns

int

The slot of the target, or -1 when the model has no target with that name.

Exceptions

ArgumentException

name is empty or white space.

FindMorphTarget(string)

Finds the slot of a morph target by name.

public int FindMorphTarget(string name)

Parameters

name string

The target name, compared case-sensitively.

Returns

int

The slot of the target, or -1 when the model has no target with that name.

Remarks

Look the slot up once and keep it: setting weights by slot skips the name lookup.

Exceptions

ArgumentException

name is null, empty or white space.

GetMaterial(int)

Gets the material at the specified index. If the material is not overriden by this component, it will try to get it from Materials

public Material GetMaterial(int index)

Parameters

index int

The index of the material

Returns

Material

The material at the specified index or null if not found

GetMaterialCount()

Gets the number of materials (computed from Materials)

public int GetMaterialCount()

Returns

int

GetMorphWeight(int)

Gets the runtime weight of a morph target.

public float GetMorphWeight(int slot)

Parameters

slot int

The slot of the target, from FindMorphTarget(string).

Returns

float

The weight that is rendered, which may differ from the authored weight in Morphs.

Exceptions

ArgumentOutOfRangeException

slot is out of range.

SetAllMorphWeights(float)

Sets the runtime weight of every morph target, for example 0 to return to the base shape.

public void SetAllMorphWeights(float value)

Parameters

value float

The weight: 0 is the base shape and 1 the full target, but any finite value is allowed.

Exceptions

ArgumentOutOfRangeException

value is NaN or infinite.

SetMorphWeight(int, float)

Sets the runtime weight of a morph target. This is the fastest way to drive a weight every frame.

public void SetMorphWeight(int slot, float value)

Parameters

slot int

The slot of the target, from FindMorphTarget(string).

value float

The weight: 0 is the base shape and 1 the full target, but any finite value is allowed.

Remarks

The authored weights in Morphs are unchanged, and replace this weight when they change. The new weight is rendered from the next frame.

Exceptions

ArgumentOutOfRangeException

slot is out of range, or value is NaN or infinite.

SetMorphWeight(ReadOnlySpan<char>, float)

Sets the runtime weight of a morph target by name, without allocating.

public void SetMorphWeight(ReadOnlySpan<char> name, float value)

Parameters

name ReadOnlySpan<char>

The target name, compared case-sensitively.

value float

The weight: 0 is the base shape and 1 the full target, but any finite value is allowed.

Exceptions

ArgumentException

name is empty or white space, or the model has no target with that name.

ArgumentOutOfRangeException

value is NaN or infinite.

SetMorphWeight(string, float)

Sets the runtime weight of a morph target by name.

public void SetMorphWeight(string name, float value)

Parameters

name string

The target name, compared case-sensitively.

value float

The weight: 0 is the base shape and 1 the full target, but any finite value is allowed.

Remarks

Looks the name up on every call: to set a weight every frame, use SetMorphWeight(int, float).

Exceptions

ArgumentException

name is null, empty or white space, or the model has no target with that name.

ArgumentOutOfRangeException

value is NaN or infinite.