Blog

RFC: Library Dependencies

This is another “Request for Comments” post – please discuss the proposal in the comments; if you comment asking about the OccRift your comment will be piped to /dev/null.

There’s one aspect of the library system that acts as a sharp unprotected corner, poking users on a regular basis: some scenery packs require other scenery packs to function. For example, many freeware airport scenery packs require OpenSceneryX. When the library pack is not available, X-Plane will not load the custom pack because it is missing art assets.* Users report this to us as a bug surprisingly often.

In my view, the big problem here is that a user has no way of knowing from X-Plane’s diagnostic message what library they should have installed. The diagnostic message isn’t useful because X-Plane doesn’t know either.  All X-Plane knows is that there was a library path, no one is providing art for it, and therefore life isn’t worth living.

The Proposal: Library Pack Dependencies

My proposal goes like this:

• A library scenery pack can declare its “official name”, e.g. “opensceneryx” or “proaddons/trees” or what-ever.  Like plugin names, the goal is to pick a reasonably verbose name tied to your identity to avoid conflicts.  This directive would go in your library.txt file.
• A scenery pack that needs that library declares a need for the library by the same name.
• When X-Plane tries to load an art asset from the scenery pack and it is missing, if at least one dependent library is not present in the system, then the error message changes to something like

The scenery pack “KLAS Las Vegas” could not be loaded because the library “OpenSceneryX” is not installed.

The log.txt file would contain complete details, but hopefully it would be clear(er) to an end-user what has gone wrong: OpenSceneryX is missng, and thus KLAS Las Vegas cannot be used.

How Is The Link Made

In order for this proposal to work, scenery packs that require library X have to contain a directive stating so.  Therefore this proposal is not a cure-all for existing load problems. It would help in the long term as new scenery packs and libraries are created with these directives.

How would the link be made?  WorldEditor (or other scenery editing tools) would automatically write the dependency into the scenery pack by looking at the dependencies in place on the author’s machine and copying them into the scenery pack when the user picks “Build”.  Thus as long as the libraries had correct “naming” annotations (this does require library authors to update) then new packs made with WED would contain the right dependencies automatically.

Nasty Details

A few nasty details:

• Library packs would need to contain both their “permanent” name and some kind of “human readable name” for error reporting.
• The dependency statement in custom scenery packs would list the permanent names of needed libraries and copies of the human-readable names; if we need “librutrees” and it is missing, we don’t know that it’s real name is “Russian Trees 2.0” unless this has been copied at build time.
• Dependencies would also need an integer version number.  This allows us to declare the case where the library is installed, but it is too old.

X-Plane’s built-in libraries would not contain dependency names because they are always available.

Dependency names for scenery packs would be written as DSF properties; there is no guarantee or need for the non-library scenery pack to have a library.txt file.

Open Issue: if a scenery pack declares a dependency and it is missing, should it be allowed to load if all of the art assets are present?  This is the more permissive use case, but it implies something fairly strange is happening on the end user’s machine. Permissiveness might be desirable during the transition into using dependency names.

Will It Work

The library system has (for quite a few years now) allowed “place-holder” objects to be declared in a scenery pack that act as fall-backs for missing objects.  The use case goes like this:

• OpenSceneryX provides a “fallback” pack that is dumped directly into the scenery pack with blank objects for every library path.
• If the end user has OpenSceneryX installed, they see the real art.
• Otherwise they see nothing – the fallbacks are blank, and no error is generated.

It seems clear from the number of users who report a missing OpenSceneryX object as a “bug” that this is not working. Authors who use OpenSceneryX are not bothering to copy the “fallback” pack.  This might not even be a bug – maybe the authors don’t want their work being viewed without OpenSceneryX installed. My guess, however, is that the authors just don’t know that the fallback pack exists.  Since the authors have OpenSceneryX installed, they have no need for the fallback and can’t even tell if it is working properly.

My hope is that the library dependency scheme can be more successful in the long run because it requires no action by individual scenery authors, as long as a small number of library maintainers update their libraries.  The work of annotating scenery packs is automatic.

* Please do not try to convince me that what X-Plane should do is ignore this problem and proceed. With the RFC proposed above, we could do something less drastic, like not loading the scenery pack if the library isn’t present. But I am strongly against “load what we can and keep going”.

If X-Plane treats errors in authorship as acceptable results, then authors trying to get actual work done will have to do a lot more work to detect human mistakes in their own authorship. We need a bug to be a bug.