Trainz/containers/mesh-table container
|
|||
|
KIND Hierarchy
editThe "mesh-table" container is a top-level config.txt file entry used by almost every Asset Type that presents a visible digital shape when rendered, which also means any place-able asset. Even sound effects assets have a minimal 2 triangle mesh or rectangle (asset creator's option) and only those assets which are always dependencies, such as HTML files or Ground Textures will not.
The mesh-table is a list of mesh subcontainers with no standalone tags. Tags are parsed in a standardised format, but not all content types (i.e. KINDs) support the full range of tags listed below. Each mesh derives its name from the subcontainer's tag name, a reserved enumerated data keyword or identifier. These identifier names are used to refer to specific meshes from within the mesh-table and also from scripts in interactive or animated assets, providing the commonality of definition and reference necessary to interface the static code of an asset definition with the interactive flexibility of dynamic operation states detectable by suitable software.
- Each mesh subcontainer uses the following format.
Known Dependent Parent Types
edit- Main article, see: kind mesh
The Content Types listed here use the mesh-table container as part of their definition.
Be advised this new Trainz Wikibooks topic page is rough and incomplete. It was last edited on 8 August 2015, and is still under heavy construction. This Page UNDERCONSTRUCTION: Content here is likely to be changed significantly in a short amount of time. All Trainzer's and Wikibookians with knowledge in this subject are welcome to help out. You can remove this tag and replace it with {{Trainz-stub}} or with section stub templates ({{Trainz-sect-stub}}) on unfinished sections when the 'page' has become more mature. |
The following config containers also reference back to their Asset's mesh-table container in some fashion:
See also:
• Modeling Guidelines
• Modeling Scenery
Level of Detail (LOD)
editFor discussions of LOD see Level_of_Detail, LOD_Example and LM.txt_file (or see Level_of_Detail, LOD_Example and LM.txt_file unaugmented originals)
Simple mesh-table container
edit- This simple configuration will be seen in many pre-TS09 assets using IM meshes:
mesh-table { default { mesh "traincar-body.im" auto-create 1 } shadow { mesh "shadow.im" } }
Pre-TRS2006 (v2.5) assets originated using older Progressive Meshes (PM meshes) tech (v1.0--v2.6 era, depreciated by v2.5) most often use the (older & original) Trainz convention of 'suffixed' subfolder names matching the config file's asset-name definition
and the convention of naming subfolders using that string concatenated with the appended suffixes '_body', '_art', and '_shadow' to define both subfolders in an asset root, and the main mesh, texture, or texture.txt files in such subfolders. In addition to these standardized 'named by suffixes' subfolders, the nightmode tag tag was an early upgrade that, like today's mesh-table containers component tags, provided a pathspec to a night folder which had widely varying names (though many content creator's used simple 'night' and 'nightmode' subfolder names, while others followed the suffixed convention and concatenated asset-filename+_night
.
This convention has been replaced by direct definitions of paths using the mesh-table container entries and thumbnails container entries, freeing the content creator from using said suffixes for asset component groups. Hence often newer assets use a single root folder and may have no subfolders.
|
In any case, the nightmode tag signified and was assigned both the folder name and the mesh name within for the night display. The post-UTC equivalent is a 'night' mesh container within the mesh table:
mesh-table { default { mesh "Shop_Ralph's_Discount_DES.IM" auto-create 1 } night { mesh "night/night.IM" night-mesh-base "default" } }
e.g. a v1.3 locomotive asset <kuid:86105:6225>, in config.txt file's asset-filename "KansasCitySouthernSD40-2" has subfolders kansascitysouthernsd40-2_art and kansascitysouthernsd40-2_body, and if shadows had been installed should have had a kansascitysouthernsd40-2_shadow sub-folder.
- The Content Manager of Post-TC3 versions will not always find and interpret either PM or IM meshes in the sub-folder schema/standard for older content, and will generate the fault message "Error: Unable to load mesh file: 'filename_shadow.pm'" even if present, or worse, are converted to IM.
- In both cases, the fix needed is to add a properly configured mesh-table container.
Mesh subcontainer
editEach mesh subcontainer supports the following tags. Each tag is shown here with its default value. ∅
mesh-asset <NULLKUID> mesh "" anim "" lod-level 255 mesh-season 255 att "" att-parent "" opacity 1.0 position 0,0,0 orientation 0,0,0 auto-create 0 use-parent-bounds 0 should-respond-to-clicks 1 animation-loop-speed 0 critical-animation 1 effects { } night-mesh-base ""
* The att-parent defaults to "default" which is the parent mesh. The att-parent tag can include a path.
Supported Tags
editEach mesh subcontainer supports the following tags.
anim
edit- Type: File
- Default: ""
- Compulsory: No
- Desc: The animation file (.kin) exported from the 3D modelling tool and/or TrainzMeshImporter. This may include a sub-path.
animation-loop-speed
edit- Type: Float
- Default: 0
- Compulsory: No
- Desc: This tag must be present if the asset is to animate when placed. If this tag is not present when placed the animation will not play by default, but may play if controlled by script. A different value (e.g. 0.5, 2.0) may be used in the tag to play the animation at a different speed from that created in the 3D modelling tool.
att
edit- Type: Attachment point
- Default: ""
- Compulsory: No
- Desc: The mesh (and animation if present) is inserted at a mesh attachment point rather than the origin (without this line the mesh is placed relative to the origin of the parent model).
att-parent
edit- Type: Mesh name
- Default: Defaults to "default" which is the parent mesh
- Compulsory: No
- Desc: The tag tells Trainz in which mesh the attachment point is located. The insertion attachment point is located within the mesh ‘name’ , as listed in the config.txt.
auto-create
edit- Type: Bool
- Default: 0
- Compulsory No
- Desc: The model is generated automatically when placed, or when you load a map which includes the model. In some instances you don’t want the mesh visible (as this may be controlled through script). If auto-create is 0 the mesh will not be visible when placed.
critical-animation
edit- Type: Bool
- Default: 1 (TBD: surely this should be false (0))
- Compulsory: No
- Desc: "critical-animation" indicates that this mesh's animation generates events which are critical to the script system's behavior. If your asset is not scripted, does not use scripted animation events, or only uses the events for display purposes and will not break if the occasional event is missed, this tag should be set to false (0). Leaving this flag set to true (1) is a significant performance penalty.
custom-render-plugin
edit- Type: KUID
- Default: ""
- Compulsory: No
- Desc: TBD
effects subcontainers
edit- Type: Corona Effect | Name Effect | Attachment Effect | Animation Effect | Texture-Replacement Effect
- Default {}
- Compulsory: No
- Desc: The effects container can contain a list of effect subcontainers. The effect subcontainers support the following generic tags.
- kind ""
- name ""
- Each effects subcontainer supports additional tags depending on the effect kind. The following effect kinds are supported:
light
edit- Type: Bool
- Default: True(1)
- Compulsory: No
- Desc: If true, this tag causes the non-stitched mesh to be linked into the Trainz lighting model. This causes the mesh to respond to directional lighting changes, such as the angle of the sun or train headlights. This is also necessary for normal maps to work correctly. Zeroing this tag will remove the mesh from the Trainz lighting model. Generally speaking, you should never zero this tag- almost every effect that can be achieved through this approach can be better served by using an appropriate normal map or appropriate geometry detail.
- This tag has no effect on stitched meshes, which are always affected by the Trainz lighting. Since the content creator has no direct influence over which meshes are subject to Mesh Stitching, and all indirect influences are subject to change between Trainz editions, it is strongly recommended that this tag is avoided to ensure that results are consistent.
lod-level
edit- Type: Int (0-8)
- Default: 255
- Compulsory: No
- Desc: The object LOD level at which this mesh is displayed. The default value (255) indicates that this mesh is visible at all detail levels. See also kind mesh for the 'mesh-detail-level' tag.
mesh
edit- Type: Mesh name
- Default: "" (will raise error if null)
- Compulsory: Yes (3.4)
- Desc: The ‘main’ mesh name. This may include a sub-path. ie: mesh nightwindows/nightwindows.im, where the file nightwindows.im has been placed in the subdirectory nightwindows. Use .im files or reference an LM.txt_file file if you wish your asset to have ‘Level of Detail’ mesh reduction.
- The mesh name can also refer to an IM file in a mesh asset library if the mesh-asset tag is specified.
mesh-asset
edit- Type: KUID
- Default: <NULLKUID>
- Compulsory: No
- Desc: Specifies a mesh asset library to be used in conjunction with the 'mesh' tag. The mesh name specified in the 'mesh' tag must be located in this asset as Content Manager not check for the existence of the mesh. If the mesh is not located in the root folder of the mesh asset then include the path as part of the mesh name in the 'mesh' tag.
mesh-scale
edit- Type: Floatlist
- Default: 0,0,0
- Compulsory: No
- Desc: This tag defines a minimum and maximum scaling value for the mesh, where 1.0 is the size as modelled. Each instance of the mesh that exists in the world will randomise within this range. Randomisation will not change between runs or between Trainz editions, but may change based on factors such as the position of the mesh in the world. This tag is currently only supported on SpeedTree assets; attempts to use this tag on other assets results in undefined behaviour.
mesh-season
edit- Type: Int (0-250)
- Default: 255
- Compulsory: No
- Desc: The season index for which this mesh is displayed. The default value (255) indicates that this mesh is visible in all seasons. See also Season-selector container.
night-mesh-base
edit- Type: Mesh name
- Default: ""
- Compulsory: No
- Desc: This night mesh is linked to the specified mesh and is visible only at night. It is invisible if the specified mesh is invisible, (if the auto-create 0 line were used so the specified mesh can be controlled by script).
opacity
edit- Type: Float (0.0 - 1.0)(See below)
- Default: 1.0
- Compulsory: No
- Desc: Specifies the overall transparency of the mesh. Values other than 0.0 or 1.0 employ alpha blending and a value of 0.0 has the same effect as hiding the mesh. Note that this tag is buggy in TS2009 prior to SP4.
orientation
edit- Type: Floatlist (radians)
- Default: 0,0,0
- Compulsory: No
- Desc: Orientation of X,Y,Z axes. Allows a submesh to be rotated relative to its insertion point. To reverse a mesh by 180 degrees about the Z axis, add the tag: orientation 0,0,3.14159
position
edit- Type: Floatlist (metres)
- Default: 0,0,0
- Compulsory: No
- Desc: Position of the mesh using X,Y,Z axes relative to its insertion point.
radius
edit- Type: Float
- Default: TBD
- Compulsory: No
- Desc: TBD (should this be in mesh-table_container_(interior_version)?)
should-respond-to-clicks
edit- Type: Bool
- Default: True(1)
- Compulsory: No
- Desc: If set to false (0) on a mesh that is part of an asset, it will remove that mesh from the calculation of the 'bounding box' that will be used to check whether the user clicked on that particular asset. This is useful for light ray effects or animations which are significantly outside the normal bounding volume, and may cause movement to focus on the wrong asset. For instance, a traincar may need a mesh marked with should-respond-to-clicks set to false in order to ensure that the click is detected for the correct traincar when it is part of a consist. First introduced with TS12 SP1 HF4 (build 61388). Default value (True) is the prior behavior (the mesh will be considered part of the bounding box for the purpose of registering clicks).
test-collisions
edit- Type: Bool
- Default: TBD
- Compulsory: No
- Desc: TBD (should this be in mesh-table_container_(interior_version)Ø)
use-parent-bounds
edit- Type: Bool
- Default: False(0)
- Compulsory: No
- Desc: When enabled, this tag indicates that render culling should occur using the whole object's bounding box rather than this mesh's bounding box. Bounding boxes on individual meshes may not update correctly when animation moves the object's geometry any significant distance from the bind position. This flag can help mitigate such effects, at a tiny performance penalty.
Mesh-Table Example
edit This Trainz/Containers/mesh-table container section is a stub placeholder, an outline or marker that this section of the book is otherwise incomplete. You can help the Wikibooks Trainz project by expanding it with fuller discussion of the topic. Work needed: Need clearer explanation of when to switch, citations, and various types of examples. |
The following is an example of a simple mesh-table which implements two levels of detail. Generally, asset designers should be attempting mesh reductions of upto four lod levels LOD0, LOD1, LOD2 and LOD4∅.
mesh-table { default-lod0 { mesh "example-lod0.im" auto-create 1 lod-level 0 } default-lod1 { mesh "example-lod1.im" auto-create 1 lod-level 1 } }
Notes and references
editThis reference page is adapted from the TrainzOnline Wiki under the CC-BY-SA 3.0 License. This page will likely include more textual explanations, exposition, history, and/or examples than the source page on the same topic. The TrainzOnline Wiki is for the most part maintained by the programmers or knowledgeable content creators and may have newer more up-to-date information on the current trainz-build code standards, which have some tendency to change as features are added to the software. |