View source for Art Recommendations

This document seeks to provide guidance for content creators working at the [[TRS18]] modeling standard. This is a living document and will be updated based on our real-world experiences. That said, content creators should avoid the temptation to ignore the recommendations put forward in this document "for this model only" as that type of thinking quickly leads to an inefficient content set and poor overall performance. Performance is a holistic subject which requires an ongoing commitment.

It is also important to understand the intent of each recommendation, rather than to blindly follow each. There are frequently conflicting demands which only the individual creator can balance. Religiously following the rules without understand why is suitable for beginner creators who are building simple variations on a fixed template, but more advanced creators will need to understand the benefits and tradeoffs of each decision that they make.

=Who is this Document for?=
This document is aimed at all Trainz content creators- whether that be a prolific creator of high-quality scenery, an esteemed creator of train models, a route builder on a long-running and large-scale route project, or just somebody who likes to tinker at home (in some cases all of these are one person!)

Trainz lives or dies by the quality of the third-party content. We expect content creators creating payware or engaging in large-scale freeware content release to take this document to heart, as it is the only way that Trainz can continue to evolve as a product. We understand completely that there are many members of our community to whom much of this document is largely theoretical, because they work in isolation on small home projects, however we hope that the guidelines here will also help these users gain the most from their Trainz experience.

This document provides guidelines on how to use well-known techniques; it does not attempt to teach those techniques. Information on the various techniques described in this document can be found elsewhere on this wiki. Information on general modeling techniques can be found all over the internet.

=Terminology=
This document subdivides Trainz assets into various categories, such as "Major Scenery". These are not necessarily terms found outside this document, but are simply the way that this document describes the category. Do not expect to find these terms used in other documents, within the content config files, or within the game.

=Scene Budget=
* TBD

=Modeling Overview=
All TRS18 art should be built with the following principles in mind:
* There are very few items close to the camera at any time, yet paradoxically these items are typically the most important in the scene. It is very important to ensure that every item looks excellent at extreme close range. The highest [[Level of Detail|LODs]] can afford to be fairly excessive, as long as the extra detail is removed quickly in lower LODs.
* "Background-only" low quality scenery should not exist. Trainz is an open-ended game where users can use any scenery for any purpose, so the original intentions of the content creator cannot be enforced. Trainz offers efficient LOD and stitching systems, so there are no performance gains from creating "low LOD only" models. This is simply lazy modeling. Similarly, we discourage serious route creators from using such models - even if the models are used appropriately in their route - because this causes the scenery to be installed on the end-user's computer when we'd prefer to discourage the use of these items.
* All scenery must have LOD. There are exceedingly few exceptions to this requirement. If your scenery is less than a few hundred polygons, please consider whether the above principle applies to you. For everybody else- you need to be using LOD. Well-built LOD does not make individual content look substantially worse, and allows the overall scene to look much better by significantly increasing the number of items which may be displayed simultaneously.
* You should use [[Physically Based Rendering|PBR materials]] at all times. Our older materials are emulated using the PBR code, so there is no benefit at all in using the older materials, and there are significant gains to be had through the PBR materials.
* Use [[parallax mapping]] wherever it makes sense. There is a performance cost, however it is expected that users will switch it on or off as appropriate for their machine. Parallax is not a miracle-cure for low-polygon modeling, but it can substantially improve the visual quality of an already-decent model.

When modeling:
* Don't creating polygons which are not visible. This is pure wastage. An example of this is a cube attached to a wall. A normal cube requires 6 faces (12 polygons). A cube attached to a wall requires 5 faces (10 polygons). This can be a substantial source of wasted performance- not just because of the extra polygons (maybe only a 20% cost), but because of [[overdraw]] (up to 100% cost).
* Avoid creating large polygons where substantial parts of the polygon are not visible. This can introduce expensive overdraw. There is often a tradeoff between overdraw and polygon count which you will need to balance. Adding a small number of extra polygons to halve the overdraw is very worthwhile. Adding thousands of polygons for a small gain in overdraw is probably not.
* Remember that overdraw is paid each time a [[fragment]] is hit. If a given fragment is overlapped by 50 polygons, you are paying up to 5000% cost for that fragment.
* [[Vertex Buffer|Vertices]] are more expensive than fragments, but there is a balance point at which the cost of adding more fragments outweighs the cost of adding more vertices. For example, if you have 100 vertices drawing 100000 fragments, it is substantially cheaper to add 10% more vertices than 10% more fragments.
* Fragments are not [[texel]]s. Both should be optimised, but optimising one does not directly affect the other.
* All polygons are triangles. If your modeling program is working in higher-order polygons, be aware that this is being converted to triangles before it reaches the GPU. Trainz always works in triangles, so there is no separation of these terms in Trainz.
* Vertices are not polygons. A contiguous [[mesh]] gives close to a 1:1 relationship between polygons and vertices. In cases where the meshes are not contiguous (including open edges, or unsmoothed edges) this can move closer to 3 vertices to 1 polygon. There are costs to both vertices and polygons.

When texturing:
* Reduce the number of [[material]]s in your asset. This is true at any detail level, but especially true at lower LOD levels.
* Each separate color [[texture]] usage forces a new material, so the more textures you have, the more materials you have. Reduce the number of textures.
* If you have a large amount of fully-opaque geometry, and a small amount of transparent or masked geometry, this may be a worthwhile reason to split into two separate materials for the higher LODs. In the lower LODs, remember that you're unlikely to have much of either on screen (since the overall screen size is tiny) so it's no longer worth the extra material and you should just go with the transparency-capable one for everything.
* Texture space is reasonably expensive. Don't repeat the same large feature ten times over when you can just texture it once and map the same texture onto several different polygons.
* On the flipside, there is a point at which geometry becomes more expensive. Don't spend thousands of polygons on something that you could implement cheaply in the texture.
* [[Texture tiling]] is a great way to cheaply fill a large polygon with detail, however it has a number of downsides. For starters, it can make it harder (one-way tiling) or impossible (two-way tiling) to share the texture with other geometry. Secondly, each repeat is identical (unless you're using a detail texture) and so the overall result can feel quite unnatural. Be careful about what you choose to tile, to ensure that the gains outweigh the downsides.
* Avoid texture tiling at the lowest LODs. It's typically not a major saving (because even a uniquely-mapped object will only be a handful of texels) and it prevents atlasing (whether by hand, or automated). It is likely to be flagged as an error condition in the future.
* [[Texture Atlas|Atlas]] where it makes sense. All else being equal, if you're going to have three meshes on the screen at the same time, it's better to share a single texture between them rather than use three separate textures.
* Don't atlas where it makes no sense. If you build a library of assets which share an [[Texture Atlas|atlas texture]], the entire atlas must be loaded at full resolution even if only a single of the assets is loaded. If you know that assets are unlikely to be used together in the same scene, don't atlas them.
* Keep the [[texels-to-meters ratio]] roughly constant across your mesh for best visual results. This is especially important within any given material, as the texture LOD algorithms work with a single pre-calculated ratio per [[render chunk]].
* If your model has painted lines, as often happens with train liveries, consider aligning your texture map such that the lines flow vertically or horizontally along the texture. This may help reduce aliasing, causing your texture to look crisper. Where the lines are lightly curved, you may be able to get away with "cutting out" the line in a small number of rectangular segments, each of which holds a nearly straight line. By aligning each to the texture, you not only straighten the line along the grain of the texture but also reduce the area of texture required to map the line. Remember that you can arbitrarily cut the line at the texture edges, in a similar manner to the lines of text on this page. Straighter lines are likely to give far superior visual results when texture compression is in use.

Texture Compression
* By default, Trainz compresses all textures. You can adjust the texture compression algorithm or turn it off entirely.
* Texture compression saves space (boosting performance and load times and reducing VRAM usage) but reduces quality, sometimes substantially. Natural images tend to fare well, whereas two patches of contrasting colours meeting at a sharp edge can distort noticeably.
* One way to look at texture compression is not that it gains you performance, but rather than it lets you raise the texture resolution while maintaining performance. Seen in this light, texture quality improves while space (performance/etc) stays unchanged.
* Regardless of which way you look at it, texture compression is something that needs to be understood and tuned.
* If you can tune the texture compression settings to improve your result, or adjust how your texture is laid out to avoid the worst artifacts, your visual outcomes can be substantially improved.
* For many textures the default is good enough, but if you're struggling with texture quality, then a reasonable place to start is to turn off texture compression and see what happens. If you're suddenly happy with the result, then try turning it back on and tweaking things.
* While one outcome is that texture compression should be switched off for a given texture, this should only be used once all other avenues have been unsuccessfully exhausted:
** Have you tried raising the texture resolution?
** Have you tried applying the texture map differently; for example changing the angle of the texture features with respect to the texture axes?
** Have you tried different texture compression options in your [[texture.txt file]]?
** If you are only having trouble with particular areas on your model, have you considered changing your mapping to dedicate more texels to these areas?
** Finally, if you really must turn off texture compression, are you able to split the texture into two smaller ones- one which avoids compression for those areas which need maximum quality, and one which is compressed and contains the details where compression doesn't hurt.
*** But be careful of [[draw call]] count. Don't add more textures if you're trying to reduce draw call count.

When it comes to building LODs, the following should be kept in mind:
* LOD transitions take CPU time, GPU time, and may distract the user. Avoid unnecessary transitions. Try to time the transitions so that they can occur at reasonable spacing and shave off a significant number of polygons (etc) with each step. Maximise the gain from each amount of pain.
* Texture LOD is automatic. Do not manually introduce lower-detail textures as this will simply lower performance.
* [[Mesh stitching]] can bring massive performance gains when large numbers of low-polygon meshes with identical materials are used in the scene.
** Mesh stitching does not work on LM meshes.
** Mesh stitching does not work on animated meshes.
** Mesh stitching does not operate on regularly-moving objects such as train vehicles.
** Mesh stitching may not work where modifications have been made to the meshes, such as texture replacement or scripted emissive.
** Mesh stitching requires [[material sharing|shared materials]], but does not require identical meshes.
** [[Texture atlas|Low-LOD atlases]] can benefit mesh stitching because they introduce sharing between meshes which are otherwise not using shared materials.
* [[Hardware instancing]] can bring modest performance gains where many identical meshes exist in the scene which are not otherwise eligible for mesh stitching.
** Hardware instancing does not work on animated meshes.
** Hardware instancing does not work where modifications have been made to the meshes, such as texture replacement or scripted emissive.
** Hardware instancing requires identical meshes, not just shared materials.
* Do not use "lower quality" materials at lowest LOD.
** Material cost is in proportion with the number of fragments, meaning that it is typically negligible for low LOD objects.
*** Unless you're talking about an entire city of buildings, or a forest of trees perhaps.
** The heaviest materials often LOD internally with distance, meaning that they are not as expensive on low LOD (distant) objects anyway.
** You can often use the better materials to maintain graphical quality while the polygon count drops. Dropping polygon count at low LOD is much more important than using cheaper materials.
* Do not test your LOD models at close range and then say "well, it doesn't look any good, this isn't working". Use [[Preview Asset]] on "auto" mode, then zoom in and out to see what the various transitions look like, when they occur, and how many polygons, draw calls, and animations are saved. Or just test the asset in-game. The end-user will never see your low-LOD model up close, so being concerned over its look at close range is entirely missing the point.
* Do zoom in to the low-LOD models using [[preview asset]] manual LOD distance control in order to take a close look at how your LOD models are put together. The end-user will never see this, so it's not what you're actually tuning for, but seeing the model zoomed in like this can help identify problems which are present-but-hard-to-identify at the actual view range.
* TBD: polys vs normals.

Normal Maps:
* Providing a correct [[normal map]] is nearly as important as providing the correct [[albedo]] (surface color) texture and is often more important the providing quality geometry. If your normal map is not suitable, you will end up with incorrect lighting conditions, with dark areas where you expect light or vice versa.
* Normal maps and geometry are traditionally created simultaneously by:
** Building an ultra-high-detail source model.
** Creating a LOD0 game model with a suitably reduce polygon count; this process is often partly automated by the modelling tool, but also typically requires hand adjustment to get optimum efficiency.
** Baking the mesh normals from the high-detail source model into a normal map for the LOD0 game model.
** Rinse and repeat for the other LODs, with the process likely getting more manual as the polygon count gets lower.
* Normal maps are NOT simply color textures. Editing them in photoshop or a similar tool is likely to give poor (and often unexpected) results. If you must edit them per-pixel, be sure to use a linear color space. Photoshop color space is NOT linear by default, and working in a linear color space is non-trivial for beginners. [http://therenderblog.com/how-to-linearize-textures-in-photoshop/ Read this page] for more details. If you get this wrong, your normals will be distorted and probably lean to one side. This may or may not be enough to be noticed immediately in-game, but it will be enough to reduce the visual quality of the overall scene. Additionally, normal maps should contain normalised color values only (ie. the RGB channels must add up to 1.0). Trainz will renormalise your normal maps when they are submitted, however if you are supplying non-normalised values then the end result may not match what you are expecting.
* Normal maps cause the lighting model to act as if additional geometry is present. They do not cause self-shadowing, but do affect the intensity of directional light, they do affect the position of specular reflection, they do affect the direction of cube-mapped reflections, and so on. They are essential when performing LOD because each LOD step replaces a number of polygons with a singular polygon, distorting the remaining normals to an average of those removed. This means that lighting becomes "averaged" over the model, rather than having light and dark in the appropriate areas. The normal map serves to exactly reverse this effect- it distorts the normal data to match the original model on a per-texel basis, thus preserving the play of light across your model as if the original shape was still present.
* Normal maps cannot help your model retain its silhouette. It is important when creating LOD that you preserve the silhouette in your geometry (or perhaps consider alpha masking). The normal map can help with everything else.
* Normal maps are stored in [[tangent space]] and are dependent on the actual geometry present in the LOD as well as the simulated geometry that is represented by the map. This means that it is not appropriate to take a normal map created for one LOD and use it for another substantially different LOD, even if the simulated geometry is identical. "Substantially different" in this case is one in which the [[vertex normals]] or [[UV mapping]] are noticeably different.

Animation:
* Care should be taken when exporting animated meshes to ensure that low-LOD variants or non-animated variants do not still contain bones or other animation data. Even if an animation is not actively being played, costs are incurred by the presence of bones.
* [[LM.txt file]]s allow you to switch off playback of animation past a certain distance. This is a separate decision to whether each submesh of the LM contains bones. An animation can be playing even though no bones are present to visualise it. Separately, an animation can be paused even though bones are present and displaying it. You should take care to both pause the animation at an appropriate distance and also to remove bones from the lowest LOD meshes.
* [[Mesh-table]]s apply animation per submesh. Unlike LM files, they do not share animations between submeshes. If the same animation file is applied to multiple submeshes, this will load several animation instances which will then play independently. This means that mesh-table animations are typically only appropriate where the highest LOD is animated but all lower LODs are not animated. This might be useful where the animation is very subtle (so that the user can notice it when extremely close to the object, but doesn't notice it vanish and doesn't miss it while it's some distance away) but should not be used where the animation makes obvious changes to the mesh- for example on a crane. Subtle foliage wind animations, human/animal idle animations, and fan rotation might be reasonable under these limitations.

General guidelines:
* Don't rely on assumptions that you are doing the right things. There are many ways to make mistakes, and many optimisations are affected by the exact construction of your asset, so it's possible to "tick all the right boxes" and still end up with a poor-performing asset because you aren't using the optimisations you were aiming at.
* Do use the [[preview asset]] in-game. If you are seeing "wrong" results from [[preview asset]] then it is very, very likely that the results are correct and that you are making incorrect assumptions. Do not simply assume that [[preview asset]] is feeding you incorrect information and ignore it: it works by measuring the actual results, not by estimating what should happen.
* Do test your asset in a variety of scenarios, to find any weaknesses: unexpectedly high polygon counts or draw calls, animations active past the point where you can actually see them, overly-visible LOD transitions, etc.
* If you're in doubt about using a texture atlas, err in favor of not using it. Future optimisations may be incompatible with manual atlasing. If you have a clear case where the atlas is a significant benefit, use it- you will win now, and the manual atlas can be removed in the future if it becomes unnecessary.
* The guidelines given in this document are intended to allow you to produce excellent visual results while still maintaining solid performance. If you focus on the maximum polygon count guidelines but ignore the efficiency guidelines, it is of course possible to make terrible-looking content that is still quite expensive for what you get. Don't do this. Before, during, and after creating each asset you should be spending some time to review the performance concerns and ensure that you have built the best model that you can reasonably make.
* A good-looking asset which performs poorly is no more useful than a poor-looking asset that performs well. Don't fall into the trap of making a good-looking mesh and thinking your work is done.

=Route-Building Overview=
* Avoid having the route baseboards end suddenly within line-of-sight of the track. Even if you choose not to fully detail the outer baseboards, at least provide basic geometric detail out to the maximum draw distance. Especially avoid any situation where the baseboard wall is visible.
* Build a palette of scenery and ground textures that is appropriate for your route, and work from that. Don't simply select new scenery from the DLS each time you need to place something. Using a restricted set of content has multiple benefits:
** You can ensure that each selection is visually and functionally appropriate for your route.
** You can test the performance and visuals of your selected content and avoid any poor-performing scenery without having to re-test each placement.
** If it later turns out that some of your scenery needs updating, it is much easier to update a small selection of content which is reused than hundreds of items that are used only once each.
** Performance improves when scenery is used multiple times and reduces when each scenery item is different.
** If you wish to redistribute your route, it is easier to secure the necessary rights and the overall download size is smaller.
* Avoid heavily blending ground textures. It performs poorly and doesn't look good. If the textures that you are using don't look appropriate individually, consider selecting better textures instead.
* Avoid using too many ground textures in a small area. Try to keep to 3-4 textures within any given ~240m x 240m area.
* Use PBR ground textures with parallax. While mixing PBR ground textures with legacy ground texture is possible, it doesn't look as good.
* Carefully read the per-asset guidelines, and select assets which follow the guidelines over those which don't.
* Test your route's performance as you go. Achieving a good selection of assets, good object density, and so on up front is far easier than retrofitting performance once you're done.

=Trains=
==LOD Recommendations==
LM is the appropriate technique for all train vehicles. Mesh stitching is never used, so mesh-table LOD does not provide major benefits, and LM offers more control.
===Locomotives===
The following ranges are appropriate for primary locomotives. All numbers here are as per [[preview asset]]- they include any bogeys, effects, and other attachments. Distances indicate the approximate range in which the LOD will be visible. The exact distances will vary per model- if pushing LOD3 back to start at 350m allows you to bake in the bogeys, for example, the tradeoff is likely worthwhile.

* LOD0: Used at extreme close range (0m-20m). Typically there will only be 1-2 vehicles on screen at this range. Primarily used for inspecting the vehicle and fussing over how pretty it looks. Performance is (within reason) a lesser concern here.
** 100k-150k polygons total.
** Consider using attachments for small heavily-repeated features such as lamps, boxes, fans, etc. This is appropriate for 10-20 features, not for thousands of features. The advantages include the ability to individually LOD the attachments (reducing the overall polygon count active in the scene), the reduction in polygon count on disk (reduced file size) and the possibility of hardware instancing accelerating the rendering (not applicable if animated). There is an associated increase in CPU cost and in draw call count, so this technique should not be used for very-low-poly-count meshes.
** The object will be large on the screen, so reducing overdraw is quite important.
** No more than 50 draw calls total.
** Corona attachment, Particle Effects, etc.
** Animated small details (moving fans, swinging hoses or chains, etc.)
** Modelled interior should be present where there are windows. The interior should have reasonable geometric detail (chairs, etc) but is obviously not seen from inside so should be more representative than precise. Texture detail should be low, as the window should hide most details. The interior will typically be darker than the outside world during daylight conditions, and overbright in nighttime conditions.
** Effects such as font replacement for running numbers and emissive strength adjustment for the interior material may be appropriate.
** Scripted control of the various effects may be appropriate.
* LOD1: Used at close range (20m-50m). There will be several vehicles on the screen in this range but the detail must remain high, so performance is a significant concern. Primarily used when the player is actively working with or around the vehicle.
** 50k-100k polygons total. You can typically knock 30-50% of your LOD0 polygons away.
** Consider reducing or removing your attachments, animations, and effects.
** No more than 20 draw calls total.
** Fully modelled interiors are no longer necessary, but the silhouette seen through the window should be maintained (ie. the opposite wall of the interior should still be visible; if a chair was blocking the view then a low-poly version may still be present, etc. Interior floors and roofs are probably unnecessary.
* LOD2: Used at medium range (50m-250m). There will be a lot of vehicles on the screen, and detail is no longer a major concern.
** 10k-30k polygons.
** 3-8 draw calls.
** If you are finding it hard to reduce detail from LOD1 without a visible change, break this into two transitions (eg. a 30k and a 10k).
** Remove all attachments.
** Remove all non-essential animations. This may mean keeping the bogey wheels (or not) but losing all fans etc.
** Switch off most particle effects, coronas, texture replacement, running numbers, names, etc.
* LOD3: Used at long range (250m-1km).
** 1k-5k polygons.
** 1-3 draw calls.
** Remove all attachments, animations, and effects.
** Optionally bake the bogeys into the mesh.
** This LOD still has the basic shape and texture of the full vehicle, but lacks finesse. Fine details that consume significant polygon counts (eg. pipes, tubes, rails) may be removed entirely and/or burned into the texture. Detail which is still visible but no longer clear can be simplified or converted from geometry to an alpha mask.
** At this level, you're aiming at numbers low enough that things which were noise before are now starting to be problematic. Attachments such as bogeys require at least one draw call, even if their polygon count is tiny at this point, so it's time to consider baking them in.
* LOD4: Extreme range (1km-15km).
** 50-200 polygons.
** 1 draw call.
** No effects.
** Fully baked.
** This LOD is very literally a box. The silhouette needs to be accurate enough to represent the vehicle while occupying only a handful of pixels, so details smaller than about 50cm are entirely invisible.
===Rolling Stock===
The process of modeling rolling stock is fundamentally similar to that of locomotives. Polygon counts "per detail" are expected to be similar. Most rolling stock is considerably simpler than most locomotives however, so as a result the typical rolling stock models will be substantially lower polygon at the same distance when compared to a locomotive. When modelling rolling stock which is as heavily detailed as a typical locomotive, it is acceptable to approach the locomotive detail recommendations instead of staying at the typical rolling stock limits.

As always, avoid the temptation to claim that your asset is special and deserves special attention. Most rolling stock does not require super-high detail, and these numbers are generous:

* LOD0: 30k-60k, 5-20 draw calls.
* LOD1: 10k-30k, 5-15 draw calls.
* LOD2: 5k-10k, 3-8 draw calls.
* LOD3: 1k-3k, 1-3 draw calls, no animation.
* LOD4: 50-200, 1 draw call, no animation, fully baked.

==Scripting==
* TBD

=Flagship Scenery=
A flagship scenery item fits the following criteria:
* Highly detailed.
* Visible over a reasonable range.
** A small statue or plaque, no matter how interesting, is not a flagship.
** The Statue of Liberty is a flagship.
* Only one present in the scene at a time.
** This is obviously under the control of the route creator, not the original modeller, however intentions are telling.
** A business or house that can't easily be identified as different from others is not a flagship.
** An overpass is not a flagship.
** A train station may be a flagship. (But an individual platform is not.)

Flagship scenery items are considered a separate class of object simply because there are times when you might want to build at a detail level which exceeds the guidelines for regular scenery objects. This is obviously something that can be considered, but only in the context of "we will only do this once in the scene". If you were to place several flagship objects together in the scene, performance will obviously suffer.

At the end of the day, we can't stop people making poor-performing content. But having guidelines helps conscientious creators to make decisions about when they should play strictly by the rules, and when they have a little leeway. We consider "Flagship Scenery Items" to be that leeway. It's reasonable to build a truly iconic building (one of the seven wonders, for example, or even something that is iconic only in the local sense) at a higher detail than the average apartment building. But if you find yourself building (or using) run-of-the-mill items without sticking to the scenery budgets below, you're just being lazy.

=Large Scenery=
Large Scenery is anything from roughly the size of a house upward. It's going to be visible from quite some distance away. It's large enough that if you're standing right next to it, it's going to tower above you, or stretch out in each direction. It's something that you're going to want at moderate detail.

Scenery should never be unnecessarily large. There are a number of negatives to creating large scenery. Performance can suffer. Usability can suffer. LOD is less effective since you're "close to the object" for a much larger distance.

In normal usage, it is reasonable to model any singular object as one scenery object, but you should not typically bake several unrelated or semi-related objects into one scenery object. If you have performance concerns with using multiple smaller objects, consider material sharing and/or atlasing, however keep in mind that this is pointless for multi-thousand-polygon meshes (it may still be useful at lower LODs).

In the past, creators (including [[Auran]]) have modelled large composites (eg. an airport, including the terminal building, runway, ancillary buildings, planes, and land vehicles) as a single scenery object. This may have been appropriate at the time but is strongly discouraged in recent versions of Trainz.

Some creators have also attempted to "optimise" their scenery by creating "configurable" scenery objects, such as a house which is scripted so that you can configure the number of windows, floors, roof color, etc. This approach is strongly discouraged as it restricts the game's ability to optimise the content. As time goes on, new methods of optimisation are introduced which are inevitably incompatible with these "optimisation tricks", so they fall rapidly behind in terms of both performance and usability.

Mesh-table LOD gives substantially better performance on scenery objects than LM.

* LOD0: Large scenery is expected to be of substantially lower complexity than a train vehicle, and also of somewhat lower importance to the game environment. As such, despite being physically larger than a train vehicle, it will have less polygons, less draw calls, and less effects.
** 10k-30k polygons.
** 1-5 draw calls.
** No animation.
* LOD1:
** 1k-5k polygons.
** 1-3 draw calls
** No animation.
* LOD2:
** 300-1k polygons.
** 1 draw call.
** No animation.
* LOD3:
** 10-300 polygons.
** 1 draw call.
** No animation.

Large scenery should generally not be animated. Where an animation is required, it should be provided by the use of minor scenery items (that users may then use in conjunction with the large scenery or separately as they wish).

In some cases, large scenery simply must be animated. An example of this is a large (building-sized) crane. In this case, a decision must be made as to how much of the scenery object to animate. If the object is high-poly, and only a small amount of the object is to be animated, it may be worth splitting it into two meshes- one static and one animated. Both meshes may be components of the single Large Scenery asset, but reducing the animated footprint in this fashion can help improve performance and robustness. LM may be used for the animated meshes.

You may consider using similar techniques to those describe under the Locomotive LOD recommendations, such as using attached meshes at higher LODs.

==Scripting==
* TBD

=Trees=
Trees are typically handled different from other scenery, so they're given their own category in this document.
==SpeedTree==
Trainz typically uses [[SpeedTree]] for tree rendering. This is not mandatory, however it is currently the simplest way to build an efficient-but-attractive tree. The SpeedTree tools take care of wind animation, LOD (using an attractive fade transition), atlased billboarding (a technique not currently available to other Trainz assets) and a custom form of mesh stitching.

SpeedTree assets may be constructed with an appropriately licensed copy of the SpeedTree Modeler software from IDV. The SRT file format is version-specific and so the appropriate software versions must be used. [[N3V Games]] is typically unable to assist with acquiring the necessary licenses, however if you are a well-established content creator with specific needs, feel free to contact us on this topic.

SpeedTree assets are relatively performant although it is still possible to overload a scene by adding too many trees. The worst-case scenario tends to be when a large number of trees are placed in very close proximity to the camera, as a distance-based LOD is used and leaf overdraw can be expensive. A SpeedTree-specific performance slider is available in the in-game video settings which allows adjusting the LOD distance separately from other scenery.

Other performance gotchas include using too many different types of tree within one scene, and using too many trees in the scene total (ie. stretching a "horizon to horizon" forest at high density).
==Mesh Trees==
It is also possible to create a tree as a regular scenery asset. In this scenario, it will be your responsibility to create the necessary animations, LOD, etc.

* LOD0: The tree should look as attractive as possible up close. It should minimise the use of tricks and billboards, while staying within the overall polygon budget.
** 1k-4k polygons.
** 1-2 draw calls.
** Optionally animated.
* LOD1: The main difficulty with manual tree scenery creation is maintaining the look of the tree over several LODs while shedding polygons. This tends to be much harder than with manmade objects. You will need to combine smaller leaf cards into larger leaf cards without substantially changing the overall look of the tree. Pay special attention to the silhouette of the tree and the normal map.
** 250-500 polygons.
** 1 draw call.
** Not animated.
* LOD2: The lowest LOD needs to be hugely efficient.
** 1-20 polygons.
** 1 draw call.
** Not animated.

You may find that you need to introduce additional LODs between these steps in order to soften the transitions.

For performance reasons, mesh-table LOD should be used, at least for the lowest LOD.
==Scripting==
* TBD

=Minor Scenery=
Minor Scenery is anything larger than a rock or pot-plant or garbage can, but smaller than a house. This includes cars, camper trailers, commercial garbage bins, boulders, large statues, utility poles, street signs, animals and people, etc.

* LOD0:
** 500-4k polygons.
** 1 draw call.
** Optionally animated.
* LOD1:
** 250-500 polygons.
** 1 draw call.
** Not animated.
* LOD2:
** 1-20 polygons.
** 1 draw call.
** Not animated.

You may find that you need to introduce additional LODs between these steps in order to soften the transitions.

For performance reasons, mesh-table LOD should be used.

Scenery objects in Trainz are not expected to move (animate) over large distances. Any animation should typically stay within a few meters of the object origin.
==Scripting==
* TBD

=Detail Scenery=
Detail Scenery is the smallest class of standalone scenery object in Trainz. This includes small rocks, ferns, small plants and tufts of grass, litter and refuse, toolboxes, etc. Where multiple objects are going to be placed over a wide area, clutter should be used rather than Detail Scenery, however there are many cases where individual placement is desired.

* LOD0:
** 20-2k polygons.
** 1 draw call.
** Optionally animated.
* LOD1:
** 20-200 polygons.
** 1 draw call.
** Not animated.
* Abbreviated draw distance.
==Scripting==
* TBD

=Ground Textures=
Ground Textures are an efficient way to provide a base coverage for the Trainz environment, whether that coverage is grass, sand, rock, gravel, shrubs.. the list goes on. Ground textures come with many benefits but also many tradeoffs.

Ground Textures are a fundamental aspect of Trainz rendering; it is not possible to switch them off entirely. There are however various ways that you can influence the performance and quality of the ground rendering.

TRS18 introduces [[KIND Groundtexture|PBR ground textures]]. These are much higher quality than traditional Trainz ground textures and (if properly constructed) don't suffer from regular tiling in the same way that older textures could. This means that you don't need to continuously change texture and cross-blend textures in order to avoid tiling. In fact, it is very strongly recommended that you do not do this as it may severely impact both visual quality and performance.

PBR ground textures support Parallax rendering. This is an expensive but effective technique which introduces a per-texel heightmap and uses it to deform the ground texture. From most perspectives, this is indistinguishable from actual geometry. The heightmap is self-shadowing and self-occluding. The heightmap will intersect correctly with surrounding geometry.

There are a few flaws in the effect, however:
* Shadowcasting (other than self-shadowing) does not use the heightmap. This is typically not a big concern with ground textures, although if you have the sun shining over a rocky ledge, you may see a hard edged shadow where you expected to see a slightly bumpy shadow.
* As with any fragment shading effect, the geometry is not truly deformed. While you can't tell it at all when looking near 90° to the ground, if you manage to get side-on with a parallax polygon you will see that it is completely flat. What's worse, as you approach close to that state, the geometry (which up to that point seemed solid 3D) will start to deform towards the flat state. Again, this isn't typically a massive concern with ground textures, but it can be visible with certain sharp edges, or on hills some distance away.
* Heightmaps don't allow overlapped geometry, only an upper surface like a shrinkwrap. While some shapes (pebbles, for example) lend themselves to heightmap techniques, other shapes are not possible to accurately represent. This doesn't mean that heightmaps can't be used to give the impression of that shape, but the end result will be representative rather than an exact match.
* Subtlety is the name of the game. This technique is a simulation of depth, and the more that you try to pronounce this, the more the user will notice any flaws. Parallax is best used to give an extra hint of depth rather than trying to replace geometry altogether. Small sticks, roughness, pebbles and flat grass are fine. Large rocks and upright tufts of grass won't work well.

One of the techniques that PBR Ground Textures use to avoid tiling is a "detail map". Instead of applying a single color map repeatedly, the ground textures use two different color maps at different scales. The primary map can also control (per texel) how much it is affected by the detail map. This allows a number of different effects:

* The primary map can be used as a normal ground (eg. grass) texture, repeating every 10m, while the detail map can provide very low resolution noise over 111.1m. The end result tiles once every 11km meters.
* The primary map can be used to display a tiled path. The detail texture can provide a very high resolution cracking and roughness texture. The primary map masks this to apply to the tile areas only, not the gaps or grout. The end result appears to have nearly infinite resolution- even fully zoomed in, the texture still has plenty of detail.

Users may switch off the parallax effect in order to save performance, in which case the PBR ground texture will still look similar but without the effect of the height map. The ground height collapses to a "mid level" without any raising or lowering. The detail map still operates.
==Ground Texture Blending==
Trainz allows multiple textures to be applied to each ground vertex. Since rendering is triangle-based, three vertices worth of textures must be applied to each triangle that is rendered. If we assume that Trainz allows three textures per vertex, then this means that there are up to 9 possible textures applied to any ground triangle simultaneously. Each texture is drawn in a separate pass, so this has the potential to cause a massive amount of [[overdraw]]. Even in older versions of Trainz the performance of ground rendering could vary substantially depending on the route creator's choices. With PBR Ground Textures, this problem would become substantially worse as the materials are much heavier to start with. This is one reason to avoid blending multiple textures. Trainz performance will be substantially improved if single textures are used over wide areas, with blending only occurring at the changeover point (and only between two textures rather than 9 or so).

Because Trainz ground uses a multipass rendering technique, it's not possible to simply take heightmap data from each texture and add them up to determine an overall height. Instead, each parallax texture is processed separately, and only the final color values are added. This can lead to blends between parallax textures having "floating" elements, or ghostly transparencies. The effect isn't a dealbreaker, but nor is it something that we want to have occur too frequently. So this is another reason to avoid blending.

Finally, because of [[z-fighting]] concerns, and also to benefit performance, we only apply parallax on a single texture pass on any given ground triangle. Any secondary texture passes used for blending will revert to a flat surface. Another reason to avoid blending.
=Splines=
Spline assets provide a flexible mechanism for procedurally placing geometry to fit a curved line. Spline assets are typically more expensive to load into the scene than scenery objects, but have various benefits in usability and may have performance benefits.

When used over large areas, Splines offer the ability to define how much distance is covered by each LOD submesh (as opposed to scenery objects, which have a fixed size regardless of LOD). In theory this ability gives a spline the ability to drop to very low polygons-per-meter counts at lower LODs. In practice, this is heavily dependant on the spline creator doing a good job of the LOD, so while it is certainly possible for a spline to be more efficient than equivalent scenery objects, this does not necessarily translate into reality for any given spline asset.

Some key points when creating spline assets include:
* Remember that by far the majority of your most of your spline will be in the far distance. While it's important to keep the high-LOD polygon count under control, it's equally important to ensure that the super-low-LOD has an extremely low polygons-per-meter count. This is typically achieved by using long mesh lengths and subdividing at high LOD.
* Avoid using multiple materials. A single draw call per spline is ideal.
* Avoid using unnecessary child splines. There's no harm in this if you need it, but in many cases it's feasible to build all the geometry into a single spline. If you do use child splines, use a [[texture atlas]] if possible to enable [[mesh stitching]] between the splines.
* Use a good-quality texture with parallax in preference to excessive numbers of polygons. Have enough polygons to provide the basic silhouette, but don't try to model every nook and cranny with geometry.
* Use [[preview asset]] performance analysis mode to test your spline's performance.
==Bridge Splines==
TBD.

==Track Splines==
TBD.

==Road Splines==
Road splines can come in many variations. This section specifically refers to road splines with negligible depth, as opposed to elevated highways or similar (which could probably be considered 'large splines').

* TBD: z-fighting and ground penetration

* LOD0 - polygons, meters?
* LOD1 - polygons, meters?
* LOD2 - polygons, meters?

* TBD: crossroads
* TBD: train crossings
==Large Splines==
This includes splines such as high-voltage transmission towers, large dam walls, etc. These are items which will be visible from a substantial distance, but of which there are unlikely to be a large number in the scene. These are items which are naturally splines- not things like a line of discrete trees which could equally be built as a non-spline object.

* LOD0 - polygons, meters?
* LOD1 - polygons, meters?
* LOD2 - polygons, meters?
==Minor Splines==
This includes splines such as fences, residential power-lines, hedges, small cliffs, etc. These are items which may be visible from a moderate distance, but aren't overly prominent. These are items which are naturally splines- not things like a line of discrete trees which could equally be built as a non-spline object.

* LOD0 - polygons, meters?
* LOD1 - polygons, meters?
* LOD2 - polygons, meters?
==Detail Splines==
A "Detail Spline" is a scenery-only spline which is used to represent a line of some repeating mesh such as shrubs, flowers, cars, etc. It is typically either used to simplify placement (two clicks rather than one click per mesh) or in an attempt (often misguided) to improve performance by rendering large sections of geometry with a single object.

Using splines to represent fine details is not recommended. This approach tends to be slow to load and is often expensive to render. That's not to say that it's impossible, but any such splines should be used with caution as they can severely impact performance if misused, overused, or simply if poorly created.

Where detail splines are used, care must be taken to:

* Minimise the number of spline instances placed in a given scene.
* Minimise the number of detail spline assets used in the route.
* Minimise the polygon count per meter of the spline through efficient use of LOD.
* Use only a single draw call per spline asset. (ie. Only one material.)