My previous post described the dangers of relying on art controls for an add-on that needs to be forward compatible with future versions of X-Plane; the short version is that art controls are an internal tool and not a public SDK, so we don’t try to maintain compatibility with updates.

So I figured I’d blog about the other dangerous way to build an add-on: creating an add-on by modifying X-Plane’s files.

All of the well-supported forward compatible ways to make add-ons (scenery packs, aircraft, and plugins) work by adding new files to X-Plane, usually in a folder specific to your add-on (a scenery pack, an aircraft folder, or a fat plugin).  This is very intentional – it ensures that add-ons don’t clash with our installer/updater over ownership of specific files.

But if you make an add-on that requires the user to replace one of our files with your own, all bets are off, and future patches of X-Plane will probably both screw up your add-on and be an updater nightmare for your users.  The best bet is to avoid modding our files.

Use the Library

The library system lets you virtually replace our files without actually touching them by mapping your own art assets to a given library path.  This is the right way to customize the scenery; editing the files on disk is not a good choice.  We may move files around within our own art assets in an update, but the library paths remain the same.  Thus building a library replacement is relatively safe; hacking the library scenery packs inside “Resources/default scenery” is not.

You should also use the library when you want to use our art assets; do not copy our art assets out of X-Plane into your scenery pack.  If you use the library, improvements to the art assets are automatically transferred to your scenery pack.

Some Dangerous Files

Here are some files that really aren’t meant to be modified in an add-on:

  • Our shaders
  • Random bitmaps in Resources/bitmaps, including sky and cloud textures
  • Lights.txt (the configuration file for named lights)

These files are all really part of X-Plane’s implementation and change regularly as we try to improve the sim.

You Can’t Share Naked Textures

You might notice that there is no way to directly use X-Plane’s textures in your add-on. At best you can use the .ter or .pol file that references them.

This is intentional!  Our artists may need to remap the location of elements within a texture as part of a future sim change, and when this happens, add-ons reference the texture would show the wrong part of the image.  That’s why add-ons can only reference some asset that itself references the texture; if we change the texture, we change our .pol files or .ter files or what-have-you to compensate for the UV map change.

X-Plane Is Not a Library

Austin and I get a steady stream of “can we just get access to X for our add-on” where X is some part of the sim that the add-on maker would like to re-use.  Unfortunately most cases where internals aren’t public are because we can’t safely share them; X-Plane is an application first and a library or platform second, and in many of these cases, to share these internal parts of X-Plane would be to commit to not ever making them better, which we don’t want to do.

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.

17 comments on “Overwriting X-Plane Files Is Like Smoking In A Fireworks Factory”

  1. I plead guilty, your honor. I’ve had great fun mucking with lights.txt. I’m sure you’ve seen various other public mods of this fine resource, and I worked up some of my own tweaks to suit my private efforts. I know well enough to copy the original, and then compare new and old whenever I update X-Plane to capture changes, and I’m generally loathe to share the file with anyone else for the precise reasoning in your post.

    However, in my mucking, I noticed a good deal of rather unique sections in the file that seemed directed towards custom efforts of folks on the team, and I realized I could add new light definitions of my own and reference them in objects.

    To make a long story short, would it be possible — or is there already a way — to create a supplemental file in the library that could also be referenced by X-Plane, but not overridden on update? Something like lights_user.txt? This concept might be extendable to other resources as well. A parallel might also be something similar to the way an aircraft specific plugins folder is currently implemented.

    As the song says… when it comes to X-Plane tweakin’ … I just can’t get enough! 😉

    1. Hi Steve,

      The BIG problem with the lights file is that the texture and UV map are owned by us…if we have to go re-organize the cell setup, we can’t fix your lights file for you. There are a few work-arounds:
      – The issue is a non-issue for spill lights -they can be completely specified using custom spills in OBJs…we can do this because there is no texture to get changed.
      – You can make custom billboards in an OBJ – since you own the texture, you get what you want. But perf wise custom billboards scale well for airplanes but not scenery.
      – We (LR) can take requests for lights..I’ve been meaning to do this for a while but haven’t been organized enough to do a good collection. But the idea is that if an author-provided named light is sane, models a real world phenomenon and makes it into the official version then we can ‘migrate’ them if the lights file changes.

      I wanted to do a lights.txt push in 1030 but it may have to wait until 1040.

      cheers
      ben

  2. Ben you seem to prepping us for the upcoming apocalypse. 10.25 has brought alot of tinkering to the forefront so going to assume we are closer….Woohooo!

    1. I like to hope that 1030 won’t be that apocalyptic for the amount of stuff in it…but we had an unusually quiet period because 10.20 back-burnered a lot of basic development to get _just_ 64-bit out…so I am trying to fight a false sense of safety.

      (The guidelines for making add-ons that don’t break are pretty much unchanged compared to v9 and v8 – it’s never been particularly safe to hack our files, and we focus all of our backward compatibility efforts on our ‘packs’ – scenery, aircraft, plugins.)

  3. I see your point, but I do agree to a certain stage. One aspect I do not agree is your “danger” and “risk” assesment. Ok so It is a figure of speach but, does it scares the “harden” flight simmer away, I think not. However I do believe that x-plane is the most well build flight simulator around and by far the most robust and stable. As and example one can have 10 different installations on your desktop and tweak 9 of them without ever having to update! Nevertheless the files and code needs to be updated and thank lord you guys do, but I do not think the major “geeks” or “hackers” out there (hackers in a good way) fare these updates but rather welcome them.

    I bet the majority just want to make our beloved sim more realistic than plausible, no offence intended. We want that athmospheric scattering, those lovely white night lights and enhanced clouds/skycolor. Some may work, some may not, but you know what the excellent part is? It unites an entire world and by god a better buisness model than that I would imagine are hard to find.

    Let’s face it, breaking x-plane is like trying to set fire to water, kinda impossible but if you manage it, just poor on more water.

    Keep it up Ben, you and the rest of the team is doing a heck of a good job!

    1. Hi Tom,

      The warnings here are not primarily for advanced users looking to tweak their sim.

      The warnings are for add-on makers (especially pay-ware add-on makers) who need to understand what their support commitment will be like!

      cheers
      ben

  4. So the lights could be tweaked without overwriting the normal lights file?

    Tweaking the lights has been one of my favorite tweaks to XP10 of all.

    Default lights are just too small, especially at distance (IMO)

    1. You can only tweak the lights for _your_ add-on, e.g. for an airplane.

      If you like to tweak the lights, go ahead.

      But an aircraft maker should not make custom sized lights by editing lights.txt – rather by using custom light params.

  5. Am I right to understand that some assets are not customisable with present mechanisms?

    I’m wondering what is the right way to change cloud textures or to change runway textures or to have Australia use wide taxiway marking? Can a developer change the colour of water?

    Thanks

    1. That is correct. Re: your examples:
      – clouds – no option.
      – runway textures – no option to globally change Australia, but a CUSTOM scenery pack CAN make their own runways, using draped polygons
      – taxi lines – can only be altered globally…annoyingly apt.dat usage of library art assets IGNORES regions, which is a design limitation I’d liek to fix.
      – water – no option.

  6. The add-on, called Wide Taxiway Markings Library Replacement works by using the library system. Works great, until you need default line. In this case I have not found a more simple way, than to copy default *.lin file into Custom Scenery folder and rename it to a file *_def.lin .

    Cheers, Youri

    1. Right – the problem is that the airport system doesn’t pay attention to ‘region’ info…something I would like to change some day.

  7. We as sceneries developers, we always try to stick to the rules, and we have always respected. The lasts 2 post are very good to know, though it sounds like prepar to Apocalypse, for who have not followed these 🙂

    Cheers!

  8. At the risk of being off topic, years ago, I modified the files for the deer and the birds to give them more natural animations. Where would something like that fit in, by that I mean, how could I make those files relative, rather than changing the root files, which are always trying to get updated and I have to exclude them each time?

    1. They are referenced in the library, so you can go find their library path and simply map your files to the same virtual path, e.g. with EXPORT_EXCLUDE.

  9. Yeah, I agree with an earlier poster it would be useful if we could override some of the other art assets such as the textures in High-Res Earth Orbit folder. In a scenery I’ve been working on I’ve replaced some of the Earth orbit textures with higher resolution textures and normal maps. It would be great to share it with the community without having to tell folks to re-copy over files each time they upgrade the sim.

    1. I personally would like to see those. I frequently fly a low Earth orbit Aircraft I designed. it would be refreshing to see the earth with some nice textures.

      Not trying to offend anyone but this whole plausible world thing doesn’t work. perhaps the guys at LR should really rethink that whole thing out. Go back to giving us a real world. Sorry off topic

Comments are closed.