I have a working prototype of a proposed modification for X-Plane 10.40: dataref-driven library regions.

The idea is simple: you can define a region in a library pack, and X-Plane will only load those art assets when datarefs written into the library.txt file evaluate to true.

One of the main usages for this is to implement seasonal or winter scenery add-ons that don’t require rebooting the sim to take effect. Right now if you want to change the look of the scenery you either:

  1. Write a script to replace files inside X-Plane.  This makes updating X-Plane tricky, but it lets you mod anything.  Of course, some of those mods may not work in future versions.
  2. Create a custom library pack that replaces library paths for the default art.  This requires  reboot to take effect but doesn’t affect updates and is stable.

With this extension, method 2 can be done without a reboot.  The custom library art assets are put in a region and the region is set to only be available when certain datarefs are set to certain values.


Changes to the datarefs require a scenery re-load to take effect; that’s the cost of being able to fully change the art asset in the library.  This does allow for a lot of flexibility, however – whole objects can be added or removed based on the date, for example.  For seasonal use, if the user can decide on a season before flying, the reload should not be a facotr.

Textures vs Library Paths

The original proposal was to allow textures to be swapped by dataref. I changed to library paths because a number of the existing seasonal/winter add-ons for X-Plane change properties of art assets other than the textures; for example, they change specularity values or add normal maps that were not otherwise present.  Only changing the library art asset allows for complete customization.

Proposed Syntax

The new syntax is a single library.txt line:

REGION_DREF <dataref> <comparison> <value>


REGION_DREF myplugin/use_snow == 1.0

Datarefs can come from the sim or a plugin; all six conditionals (< <= == != > >=) are available.  If more than one REGION_DREF line is present, all must evaluate to true to use the region.

Request For Comments

Please use the comments section to comment on this particular proposal. I’m going to be a bit fascist and nuke all off-topic comments.  This is about a specific proposed feature, not a general news update.

I have working code for this; if you’d like to try a developer build, please email me.


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.

12 comments on “RFC: Dataref-Driven Library Regions

  1. Interesting.

    Will it be possible to interpolate from one region to the other?

    That way people flying from the carribean to the northpole can gradually see the environment change.

    1. No. The effects can be customized _by_ region, but there’s no interpolation because the change is “use this art” or “use this art”. X-Plane can’t take two separate art files and “average” them. So an author who wants to create transitional zones would have to explicitly model this.

      There are tricks in .ter files and .pol files that can be used to help this without making more textures – it’s the kind of thing that where a script could help construct the ‘final’ art from a few master files.

      True interpolation is something I’d like to see, but it’s long term in that it requires -native- support for weather effects (think: snow and ice shader) built directly into X-PLane. That’s something I do want in the sim, but it’s not this proposal, it’s not coming soon, and it’s a much more significant change; this RFC is really “stupid library tricks” which are pretty tame and shippable in 1040.

  2. this is really cool proposal Ben, it is really impressive how the already available winter textures look but having to reload xplane and messing on the folders takes time. Very exciting times coming…

  3. Hi Ben, is a pleasure to read about this expected feature, and tell you that anyone of those proposed are good, but personaly prefer the second. Normaly i think the user do not change the season time in flight because want to fly in most realistic conditions. If i wrong

    This will open a new horizont of seasons textures in sceneries, but i have a question about how will affect this news rules about the default artset textures? How will be limited the size of the are where these rules will be aplied? Will coincide with area definition of a custom library?

    I wold like to try this code, the las time i sent email to you but withour answer, i dont know if not have the correct email or you do no recive it, but if you can please send us instruction to my mail, mobile[around]dai-media.com . Thank you a lot and looking for good news.
    Good luck and fast coding, Cheers!

    1. The custom library pack specifies _regions_ that are data-ref controlled. So if you want “only north america AND only with this dataref” you simply apply both a region direction (REGION_RECT or REGION_BITMAP) _and_ a dataref.

  4. This is excellent news… Is Lua the only language or are there other workable languages one can use to program scripts that interact with X-Plane. Lets say I wish to make a simple weather engine that fetches data from A and import into X-Plane? (can be anything) Do all scripts just have to include Data Refs or are there any library one can include/api to use?

    1. The only -native- languages are C/C++/Pascal. Lua and Python are available via -adapter- plugins that convert Lua to C (e.g. that’s what SASL, Gizmo, FWL, etc. are).

      The specifics of creating custom datarefs are, well, specific to the language or script being used.

  5. Witty method. In my mind it will be looks as hand loading the regional textures during flying say PANC-KMIA through a menu. In other words our flying began in the winter and finished in summer. Wouldn’t forget to load the correct textures. Great! I like it.

    1. Correct.

      The current code I have has a bug: the datarefs are not re-polled regularly; I think that’s just something I need to fix.

  6. It sounds like a great idea. My reboot time is often a few minutes, which is enough to have put me off from even investigating winter textures. Anything that helps with that can only be a good thing.

    I wonder what other uses for this innovation people will come up with?

Comments are closed.