Understanding Models¶

Models for v1.5.x¶

TODO: Add directory diagrams

What is a .model file?

A model file is essentially a ZIP file containing the resources needed for the source of an IMML model element. Primitive elements also use *.model files which are embedded in the VastPark Player and cannot be modified externally.
If you rename a *.model file to .zip, you will be able to look at the contents.

• *.scene.xml – the scene graph of the model that references all needed resources
• geometry/*.geo – geometry resource
• materials/*.material.xml – material resource
• shaders/*.shader – shader resource
• textures/*.textureExtension – texture resource

Using the default shader

Primitves by default use the default shader. To use the default shader on a model, in the *.model file simply specify "shaders/model.shader" in the material file, and make sure there is no corresponding file "shaders/model.shader". Using the default shader will allow you to leverage IMML MaterialGroup elements’ children.

Embedding a custom shader

This can currently only be done on models, not primitives. To use a custom shader, simply add it to the shader directory and reference it from the *.material.xml.

Embedding custom textures

Embedding textures in the *.model file, rather than putting them in IMML, can often be handy. They are zipped, so are smaller to download, and IMML doesn’t need to be written each time they are used. They can also be overridden in IMML material groups (if using the default shader) later if you decide you need to change the textures.

Embedding textures for use with default shader

To embed a texture, simply place it in the textures folder. To use it on a material, open the desired material in "materials/". You need to add a map so the material knows which texture to reference. Add the following line for each texture:

<Sampler name="MapName" map="textures/textureName.extension" />

Where MapName is one of the following:

• "AmbientMap"
• "DiffuseMap"
• "EmissiveMap"
• "SpecularMap"
• "NormalMap"
• "AmbientOcclusionMap"

And "textureName.extension" is the file name and extension of the texture that you placed in the textures folder.

If you want to add texture tiling or offsets, add the following line for each texture:

<Uniform name="MapNameUVParams" a="tileU" b="tileV" c="offsetU" d="offsetV" />

Where MapNameUVParams is one of the following:

• "AmbientMapUVParams"
• "DiffuseMapUVParams"
• "EmissiveMapUVParams"
• "SpecularMapUVParams"
• "NormalMapUVParams"
• "AmbientOcclusionMapUVParams"

And where:

• tileU is a float, being the amount to tile the texture in U
• tileV is a float, being the amount to tile the texture in V
• offsetU is a float, being the amount to offset the texture in U (after scaling)
• offsetV is a float, being the amount to offset the texture in V (after scaling)

Alpha Mapping

If including a diffuse texture with alpha mapping, you must change the class of the material to alpha mapped. i.e. change the first line of the *.material.xml to

<Material class="alphaMapped">

Skinning

If a material is on an object that is skinned for animation, you must change the class of the material to skinned. i.e. change the first line of the *.material.xml to

<Material class="skinned">

Embedding textures for use with custom shaders

Feel free to do whatever you want!