Asset Identity Belongs in Packaging and Installation, Not in ORTS Runtime

[kraus]

Why ORTS Should Not Attempt to Solve Asset Identity or Filename Collisions at Runtime

This issue comes up regularly, so I want to present a clear architectural argument for why asset‑identity problems cannot be solved inside the simulator and why attempting to do so would create more problems than it fixes.

1. By the time ORTS loads a route, all filenames are already fixed

When ORTS starts loading a route, it sees only the final installed directory tree:

ROUTE/
SHAPES/
TEXTURES/
WORLD/

At this point:

• filenames are already chosen
• world files already reference those filenames
• shapes already reference their texture filenames

The simulator has no opportunity to intervene without rewriting the user’s installed content.

2. ORTS has no access to the original source assets

To resolve a collision, ORTS would need to know:

• which asset the route author intended
• whether two files with the same name are identical or different
• whether the user has multiple versions of the same filename
• whether a mismatch is an error or intentional

The simulator has no visibility into any of this. It sees only the files that exist in the route folder. Without access to the original sources, ORTS cannot make correct decisions.

3. Runtime renaming is unsafe and breaks compatibility

To fix a collision at runtime, ORTS would need to:

• rename shapes
• rename textures
• rewrite .S files
• rewrite .SD files
• rewrite world files
• update any references in consists or scenery

Doing this dynamically would break:

• MSTS compatibility
• saved games
• multiplayer determinism
• repeatability of bug reports
• consistency across users

A simulator cannot safely rewrite its own data files while loading them.

4. ORTS cannot guess intent

If two assets share a filename, ORTS has no way to know:

• which one is correct
• which one the author used
• whether the route was packaged incorrectly
• whether the user has conflicting add‑ons

Guessing would produce nondeterministic behavior, which is unacceptable for a simulator.

5. Runtime fixes violate the principle of deterministic installs

A core requirement for a simulator is that:

• the same route
• installed on two different machines
• produces the same results

If ORTS tries to “fix” things dynamically, then:

• different users may get different filenames
• multiplayer sessions may desync
• debugging becomes impossible
• route authors lose control over their own content

Determinism must be preserved.

6. The correct layer to solve this problem is above the simulator

Asset identity and collision resolution belong in:

• packaging tools
• installers
• development workflows

These tools can:

• compute hashes
• detect collisions
• rename assets
• rewrite shapes
• update world files
• ensure the route is self‑contained and MSTS‑compatible

By the time ORTS loads the route, all of this must already be done.

7. ORTS should remain a simulator, not an asset‑management system

The simulator’s job is to:

• load the files that exist
• trust the filenames that are present
• behave consistently with MSTS

Trying to turn ORTS into a dynamic asset‑resolver would:

• expand its scope dramatically
• introduce instability
• break compatibility
• create nondeterministic behavior
• complicate maintenance

This is not the right layer for the problem.



Conclusion

ORTS cannot solve asset‑identity or filename‑collision problems at runtime because it lacks the information, the authority, and the safety guarantees to do so.
ORTS should not try, because doing so would break compatibility, determinism, and the simulator’s core design principles.

The correct solution is:

• identity and collision resolution during packaging
• verification and aliasing during installation
• stable filenames at runtime

This keeps ORTS predictable, compatible, and focused on simulation — not on repairing content on the fly

[kraus]

Summary: Why MSTS/ORTS Need a Packaging Layer (and How Bethesda Solved the Same Problem)

MSTS and ORTS both inherited a fundamental limitation from early 2000s game design: they treat filenames as the identity of an asset. That worked when content was small and controlled, but it breaks down in a modern ecosystem where creators reuse names, mix content from many sources, and distribute add‑ons that depend on assets they cannot legally include. The simulator has no way to detect collisions, no way to know which file the author intended, and no safe way to rewrite shapes, textures, or world files at runtime. This is why ORTS cannot and should not attempt to “fix” content dynamically.

The real solution is the same one used successfully in other long‑lived modding ecosystems: move identity, hashing, and conflict resolution above the simulator into a packaging and installation layer. Bethesda’s modding community faced identical problems—conflicting filenames, overwrites, nondeterministic installs—and solved them with tools like Mod Organizer and Vortex, which compute hashes, track provenance, detect conflicts, and build a clean virtual filesystem before the game ever loads. The game engine remains simple and deterministic; the tooling handles the complexity.

MSTS/ORTS can follow the same proven pattern. A packaging tool computes hashes, detects collisions, renames aliases, and records identity. An installer uses that identity to fetch the correct assets, rewrite references, and produce a clean, MSTS‑compatible route or repaint. At runtime, the simulator simply loads the resolved files—no guessing, no rewriting, no risk.

You can read the full explanation here:
Your article: https://*************.us/wordpress/2026/01/07/why-msts-orts-need-a-packaging-layer-and-how-bethesda-solved-the-same-problem/

A clear overview of the Bethesda mod‑management solution:
Bethesda modding background (example): https://loot.github.io/docs/

[eric]

Where did this come from? Is ORTS doing or proposing to do directory surfing for missing route assets?

[kraus]

Sean’s post from 09‑15‑2025 is exactly what I was responding to. He mentioned that ORTS had experimented with looking for missing DDS/ACE textures across configured content folders as a way to reduce the need for TSN routes to stay isolated. That’s what prompted my packaging‑layer idea.

My proposal isn’t based on ORTS doing directory‑surfing today, and it doesn’t require ORTS to do anything at runtime. It’s the opposite: instead of ORTS trying to search for missing assets (which runs into the identical‑filename problem Sean described), the package itself would declare exactly which route each asset comes from. The installer can then resolve everything deterministically without scanning the user’s system.

So the packaging layer is just an external, explicit way to avoid the ambiguity that runtime searching would create. ORTS isn’t involved in this at all.

TrainSimulations Scenery Assets in Freeware Routes: An Open Discussion - TrainSim.Com

[eric]

Ah. You should have just continued in that thread so that all the context was there.

My comment there still stands:

What ORTS might be capable of doing is searching all configured content directories and subdirectories for the first instance of a missing file or texture, which would be IO intensive, so maybe also writing a cross reference file into the route folder for use on future loading to reduce loading....

Between your concept and the ideas thrown about, I'm far more in favor of fewer applications and more intelligence within ORTS.

Maybe a different solution would be to mimic how the TRAINSET\Common folder came about i.e. allow a path for Common\Shapes and Common\Textures to be stored in the ORTS configs. Precedence could function much like DotNet did when it came out. Anything present in the application directory structure took precedent, SYSTEM directories second, with some proposing to look across PROGRAM FILES third. Writing the cross reference file wouldn't be necessary.

[kraus]

Thanks — and I understand the preference for keeping things inside ORTS. The reason I’ve been thinking about this as an external packaging layer is that ORTS can’t safely resolve filename collisions or asset provenance at runtime, even with a Common\Shapes or Common\Textures fallback. Two different routes can ship different files with the same name, and ORTS has no way to know which one the creator intended.

A packaging layer avoids that ambiguity by declaring dependencies explicitly at install time, so ORTS can stay simple and only load what’s already present in the route folder. It’s not meant to replace ORTS intelligence — just to handle the parts that ORTS can’t infer safely at runtime.

[PerryPlatypus]

ORTS is already capable of "seeing" multiple installation folders at once if they have been added to the Content tab in the Menu, so along the same lines, I think ORTS could search across all of the added installation folders to find a Route with a folder name that matches what is specified in a route database file, like a "AssetReferences.dat". This text file could be a simple list of text pairs loaded at run-time, where the first is the filename, and the second is the route foldername. (In case someone makes a mistake and writes the same referenced file more than once referring to different route folders, it could just default to the first-listed reference).

For example:
"fir_tree1.ace" "Mullan"
"House01.s" "SP_Shasta"
"Milwaukee_Substation.s" "RMD_West"
etc. etc.

Yes it would be a bit tedious to set up the first time if you have assets from numerous routes, but this should greatly save on disk space if the assets can all remain in their original respective route folders. (Someone could easily make a batch file where you select dozens or hundreds of files at once within a particular route folder, and it generates this cross-reference file)

I really REALLY don't like the idea of over-simplifying this to where ORTS would just search *all* route folders for an instance of a filename that matches, because of the high likelihood of duplicate filenames between multiple routes. This is bound to cause all sorts of goofy visual anomalies if ORTS pulls in the wrong version of House1.s, or Tree1.ace or whatever it may be, since in some cases there could be literally dozens of different versions of files with that same filename spread across the routes on someone's computer. I don't think the Common/Shapes and Common/Textures folders would work for this same reason - it breaks down the moment you have identically-named files.

[kraus]

That makes sense, and I agree completely about the danger of ORTS blindly searching for the first matching filename. The identical‑filename problem is exactly why I’ve been thinking about this as an install‑time solution rather than a runtime one.

Your AssetReferences.dat idea is essentially a manual provenance map — a way to tell ORTS which route a given file should come from. The packaging layer I’m proposing is the same concept, just moved earlier in the process. Instead of ORTS trying to resolve those references at runtime, the package declares them explicitly and the installer resolves them deterministically before the route ever loads.

That way ORTS doesn’t have to guess, doesn’t have to search across installs, and doesn’t have to maintain a cross‑reference file. Everything is already in the right place when the simulator starts, and the ambiguity that comes from identical filenames is eliminated up front.

My packaging idea is only meant for situations where a route wants to use shapes or textures that aren’t inside its own folder. If a route bundles all of its own assets, then nothing extra is needed and the packaging layer does nothing. The whole point is to avoid ambiguity when a route depends on external shapes with common filenames, because ORTS can’t safely guess which version the creator intended at runtime.

This becomes especially important for freeware routes that want to use payware shapes. Since those assets can’t be bundled, the only safe option is to declare the dependency explicitly so the installer can verify ownership and place the files correctly, without ORTS having to search across installs or risk pulling in the wrong file.

[pschlik]

Any new form of file tracking would be covered under the virtual file system. There is no need to reinvent something that there is already a spec and code for.

Though I would not expect that to arrive any time soon as the original dev has not done anything with OR in some time, and it's been even longer than that since the virtual file system had any attention. This isn't exactly a common enough problem for it to be at the top of everyone's mind, and the extra work required to use the virtual file system (or anything equivalent) would likely result in some creators failing to use the feature even when it would solve their file management woes.

[eric]

but this should greatly save on disk space if the assets can all remain in their original respective route folders.

Yes, but with storage capabilities increasing and SSD prices coming down, is this really a problem in search of a solution, or a solution in search of a problem?

One of the biggest complaints about ORTS compared to its contemporaries is confusion and complexity around installing content. We see this confusion manifested weekly with some of our older members.

Introducing a new packaging layer or requiring use of whatever new functionality might get rolled out with RouteRiter or some other yet to be determined tool does nothing to fix those complaints.

There's also the twenty year old solution of simply providing a relative reference in the .W filename property for a static object. It works fine for track substitution... it should work for statics, no?

[PerryPlatypus]

Yes, but with storage capabilities increasing and SSD prices coming down, is this really a problem in search of a solution, or a solution in search of a problem?

One of the biggest complaints about ORTS compared to its contemporaries is confusion and complexity around installing content. We see this confusion manifested weekly with some of our older members.

Introducing a new packaging layer or requiring use of whatever new functionality might get rolled out with RouteRiter or some other yet to be determined tool does nothing to fix those complaints.

There's also the twenty year old solution of simply providing a relative reference in the .W filename property for a static object. It works fine for track substitution... it should work for statics, no?

I don't disagree with that at all, but that sounds like we're just coming back around full circle to having a simple installer executable that copies the files directly into the route folder - which is pretty much what Klaus has been suggesting already. Perhaps just *slightly* more intelligent than the installer batch files we have traditionally used, with the capability to access your registry and find all of your install folders on your PC so that it can easily find the routes to copy assets from. At the end of the day, I still think it's critical that we can arrive at an installer executable know specifically which route to pull from on a file-by-file basis.

The "relative reference" idea only works if you can ensure the user is installing the new route in the same ORTS installation folder as all of the other "source" routes - which is never a guarantee unless you TELL the end user that they must do so.

[kraus]

I’m actually in full agreement with you here — the end result does look like “a simple installer that copies files into the route folder.” The difference is what the installer knows and how it decides what to copy.

The traditional batch‑file installers we’ve all used for 20 years don’t have any concept of provenance. They can’t tell which version of House01.s or Tree1.ace the route author intended, and they can’t safely navigate a system with multiple ORTS installs, mini‑routes, legacy MSTS folders, portable setups, or custom directory structures. They just assume everything is in one place and hope for the best.

What I’m proposing is still an installer — but one that is:
• deterministic (every file is identified by hash, not just by filename)
• explicit (the package declares exactly which route each asset comes from)
• collision‑proof (identical filenames don’t matter because identity is based on content)
• install‑time resolved (no runtime searching, no guessing, no ambiguity)

So yes, it ends with “copy the correct files into the route folder,” but the selection of those files is no longer dependent on the user’s folder layout, the order of their installs, or whether they happened to put everything under a single ORTS root.

That’s the part that relative references can’t solve. As you said, they only work if the user installs everything into the same root — and in today’s ORTS ecosystem, that’s simply not reality.

A smarter installer that knows exactly which route to pull from on a file‑by‑file basis is precisely the goal. The packaging layer is just the mechanism that makes that possible without relying on fragile assumptions about the user’s setup.

[kraus]

One thing worth pointing out is that the VFS approach actually requires more work from the route author when it comes time to distribute a route that depends on external content.

With the VFS, the author has to:
• structure their route so that all external references resolve correctly at runtime
• ensure the user installs the route into the correct ORTS root
• ensure the user has the required source routes installed in the correct locations
• avoid filename collisions across all mounted folders
• document all dependencies manually
• hope the user’s folder layout matches the assumptions baked into the route

That’s a lot of responsibility placed on the creator, and it still doesn’t guarantee deterministic results for the end user.

By contrast, the packaging idea I’m proposing keeps the author workload extremely small:
• include a file with hash entries
• that’s it

The installer does all the heavy lifting:
• verifies the user owns the required source routes
• finds the correct version of each shape by hash
• detects collisions
• copies the correct assets into the new route
• produces a self‑contained, deterministic install

So instead of the author having to engineer their route around the user’s unpredictable folder layout, the author just ships a file with identity information and lets the installer resolve everything at install‑time.

It’s actually less work for creators and far less confusion for end users.

[kraus]

Any new form of file tracking would be covered under the virtual file system. There is no need to reinvent something that there is already a spec and code for.

Though I would not expect that to arrive any time soon as the original dev has not done anything with OR in some time, and it's been even longer than that since the virtual file system had any attention. This isn't exactly a common enough problem for it to be at the top of everyone's mind, and the extra work required to use the virtual file system (or anything equivalent) would likely result in some creators failing to use the feature even when it would solve their file management woes.

The new VFS work — especially the ability to read assets directly from .zip archives like TSC’s .ap files — is definitely a nice improvement for runtime behavior and keeping route folders tidy. But it doesn’t actually reduce the workload for a route author who needs to distribute a route that depends on external or payware assets. With VFS, the author still has to ensure the user installs everything into the correct ORTS root, has the right source routes present, avoids filename collisions, and follows all the documented dependencies. By contrast, the packaging idea I’m proposing keeps the author’s job extremely simple: include a .ref file with hashes, and the installer handles everything else — verifying ownership, locating the correct source route, resolving collisions, and producing a deterministic, self‑contained install. VFS improves runtime lookup; the packaging layer improves distribution. They solve different problems