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.

  • Facebook
  • Reddit
  • Twitter
  • LinkedIn

About Ben Supnik

Ben is a software engineer who works on X-Plane; he spends most of his days drinking coffee and swearing at the computer -- sometimes at the same time.
This entry was posted in File Formats, Scenery, Tools. Bookmark the permalink.

18 Responses to RFC: Library Dependencies

  1. wotaskd says:

    That's brilliant, thanks for that Ben.

    Maybe a way to determine whether a scenery file should be loaded without the dependencies is to make that a responsibility of the scenery author. Somewhere in the scenery package, list the required scenery, version, and fallback resolution (FAIL|IGNORE)?

    • Ben Supnik says:

      Hrm - there's two things I'm not a fan of...
      - Making things authors responsibility and not automatic means that action is far less likely to be done. In this case I expect most items owuld get the default setting whatever that is.
      - Is there a good reason why we want 'ignore'?

      In the _majority_ of the cases I've seen, the authors intentionally enhanced their airport with a third party library, and the user simply failed to follow the (possibly unclear or non-existent) installation procedure.

  2. Manuel says:

    the proposal looks good to me for the medium/long term run. For the short term, while all scenery include required dependencies (library / version) i propose you parse the "folder name" below custom scenery where missing files belong and enrich your existing warning message (your scenery may look wrong) asking the user to verify that the library "folder name" is installed and updated to latest version. All libraries are named the same than its folder name as long as i have seen. Hopefully this clue will reduce people flooding your bug database which waste valuable time and resources in the mean time.

    Loading or not? i would suggest not, that way users are forced to install missing libraries and problem solved for the immediate future when installing another scenery pack. There are only a bunch of libraries that covers 99% of the scenery after all.

    just my 2 cents.

    • Ben Supnik says:

      Where a library name is missing, trying to show something from the lib path isn't a bad idea - from what I can tell, some libraries use a prefix and some do not.

      Either way, cleaning up the error message is a good idea no matter what - the current error message is quite cryptic.

  3. Michel Zehnder says:

    From the Users point of view, it would be nice if:
    - You can somehow include a link in the "error message", e.g. OpenSceneryX missing, please check http://www.opensceneryx.com.
    - You can define a "min-version" for the dependency, e.g. MyLib requres OpenSceneryX - minimum v1234

    • Ben Supnik says:

      Re: version number, I think the version number in the RFC is implicitly a minimum; if a library wants to make a 'breaking' change it needs to pick a new "dependency name".
      Re: link, I'll think about that. If the library's hosting moves, the URL might become counter-productive - an alternative is to have the error message go to a LR support web page that explains (in detail) how to find a library and common places to look.

      • Michel Zehnder says:

        Re: version, not sure... I usually like static names not changing at all for better identification.
        Re: link: Could work. Point to LR, and then from LR point to the correct site. (kinda like a database - but let users "update" it?) I think the average user needs more help than "OpenSceneryX not found"

  4. Xplaneblog.de says:

    The idea is great. But there is one more point. If the library is installed, but not up to date. In this case an object could be missing, even when the library is installed.

    Just some more solutions could be:
    Every library needs also a version number.

    A library contains a file where there are all objects listed with a optional url where to load it.

    A central library server.

    • Ben Supnik says:

      I think serving people's third party content definitely goes way beyond this proposal!

      It does beg a question, however, whether in the long term that is a better solution...there aren't -that many- common third party libraries; if X-plane could install them, it could resolve the situation. That's a big jump though; right now X-Plane never installs third party content.

      • Michel Zehnder says:

        I was thinking about a "third-party-installer" myself, with dependencies and everything. It would certainly help!

  5. Jim Dalgleish says:

    Would it be possible, or even necessary, to have a version number be a mandatory part of the library title? I know that OpenSceneryX gets updated with new assets every once in a while, and I'm assuming that if you load an older version of OpenSceneryX (without the new assets used on the scenery you're trying to load), you would potentially get an error message that simply points out that OpenSceneryX is not installed (is that correct?) even though it is, and there might also be some kind future library that hasn't been created yet that could get random updates, so it might be a nice additional feature to know if X-Plane also can't find a specific version of a library that is currently installed.

    Also, I had no idea there was a fallback pack for OpenSceneryX...

    • Ben Supnik says:

      The spec has the version number separate from the library so that we can identify the case where "we have this thing, but it's not new enough". This is necessary because otherwise:
      - Each library has to introduce a new dependency name when it introduces new art assets.
      - My library 3.0 thus has _3 names_.
      - Thus when you use my library you pick up 3 dependencies.
      - Thus when you run your pack without my library, you are missing "three things": Ben's lib 1.0, Ben's lib 2.0, Ben's lib 3.0.

      And a user goes "oh noes, I can only find Ben's lib 3.0 on the net, where do I get the old ones?"

      By having the version separate, we can have a 'greater than' policy, and thus only Ben's Lib 3.0 is written in.

  6. myb says:

    Many years ago, when we had only one third party library called OpenSceneryX, an author should be insert the 'placeholder' files by OpenSceneryX, into his Scenery Pack folder. Thats all. Even OpenSceneryX wasn't install, we could started XP without any messages but and without any OSX's objects. Now we have more than alone OSX library, so much, like a birches in the Russian forest. However these libraries don't have own 'placeholder' pack. Few month ago,Chris K, had uploaded 'Backup Scenery Library v1.1' to the org, which solve a problem, you are talking about.

    • Ben Supnik says:

      Well, it _sort of_ solves the problem. 🙂

      It converts the penalty for not having libraries from "I can't run" to "I don't see any 3-d stuff."

      The user -still- isn't seeing the scenery pack -the way it was meant to be seen-. In fact, you could (perversely) argue that running with place-holders is worse: the user doesn't realize he or she is missing a library, and just goes "that scenery is not very good."

      Cheers
      Ben

  7. snagar says:

    Hi,
    Here is a thought that might be part of the design and I might missed it.
    If we have a scenery that uses 6 "custom libraries" but I'm missing 2 of them. Will the message include both of them or will it reject the scenery the moment an error was triggered (error = missing library/object).

    My 2cents, display all missing libraries and then reject. As an end user I'll highly appreciate it, since I won't need to encounter the same error for the one I was not aware off.

    Keep up the great work.
    Saar

    • Ben Supnik says:

      I think we -have- to list all missing libraries on the first problem. Since we don't know which art asset is from which library (an art asset might be from more than one) all we can do is collect all of the libraries in x-plane now, the dependencies registered with this scenery pack, and show the "missing" diff.

  8. rcmarple says:

    Something needs to change with libraries - they are proliferating and there are times I wish for the good old days when the only library you needed to worry about was OpenSceneryX (and that changed a couple of times a decade). Now we have scores of them that seem to get updated almost daily. It annoys me that a missing facade or object can bring down the sim but I get Ben's point that not to do this would encourage lazy authoring (ahem - I always put in the OpenScenery placeholders - I think?). I get the idea behind libraries, they add to the community and allow authors access to great objects and content. However, I can say is my setup crashes pretty much daily due to library issues and I don't always manage to keep up with library updates - do pre-flight checks now include "check all libraries are up to date"? Some hit the update section on the org, others use flightsim, some authors go missing, then come back...
    Glad it's on your radar Ben.

    • Ben Supnik says:

      A naive answer that doesn't involve X-Plane tech would be:
      - Authors list their dependent libraries in their scenery pack's install instructions.
      - Users look at that list when they install the scenery pack.
      - Users can look in the library to see it's version and get new ones.

      That's a lot of manual steps though. 🙁 The only thing my proposal will do is make the error message spell out that you should have done those things by hand. 🙁

Comments are closed.