I finally finished up an update to the OBJ8 specification, as well as the forest specification – see here for the documents.  These specifications are mostly of interest only to developers who are working on scenery exporters.

The OBJ specification is very thick – here are some of the hilights of what’s new.

Global Lighting

In X-Plane 10, you create global spill lights by attaching a light to an object.  (Thus, spill can come from any object-bearing part of the sim – an airplane, custom scenery, etc.)

One way to do this is with the existing named and parameterized lights – these features existed in version 9, but in version 10 there are some spill lights added to the light list.

What may be of more interest to custom authors is the new LIGHT_SPILL_CUSTOM command.  This lets you build a completely customized spill light. You control its size, color, shape and direction.  You can even optionally run the light through a dataref, giving a plugin custom control of the light.


In X-Plane 10, an object can contain geometry that is “draped” on the ground – that is, X-plane will subdivide, bend and modify part of your object mesh so it sits perfectly on the ground even if the ground is sloped.  ATTR_draped makes this happen.

This feature is a much better alternative to using ATTR_poly_os to make marks on the ground.  Draping produces objects with better performance, and the geometry always sits on the ground with no artifacts.

As an added bonus, you can optionally use a second, different texture for the draped part of your object from your regular object.  (Internally the draped geometry actually becomes something like a .pol file – this is why it can have its own texture.)

Draped geometry makes it much easier to make airport markings.  If you want a parking spot, simply draw it on a quad, make it draped, and drop it into place with WED.  Tom uses this heavily in our airport library.

Draped geometry also makes it easier to have ground markings that match the object they come with.  For example, if you want a house and the house comes with a driveway texture, you can make the driveway texture a draped quad and when you place the object, the draped driveway is always in the right place.

Global Attributes and Instancing

In X-Plane 10, it is possible to set a few key attributes (blending and shininess, among others) globally for the entire OBJ, rather than using an ATTR_ to change part of the object.

These global attributes make hardware instancing possible.  In hardware instancing, X-Plane draws many objects with a single instruction to the CPU.  In order for this to happen, X-Plane must be able to draw the entire object without needing CPU intervention mid-object.  This means an instanced object has to be free of animation, attributes, and a few other features.

The global attributes let you set things like shininess and still have a single-call draw object, ready for instancing.  Alex uses these heavily in the urban autogen, and it really helps performance.

My fear is that global attributes are going to be a source of confusion for authors.  When should you use them?  How do you add them?  This is my thinking:

  • Modeling program exporters should allow an author to identify an object as “for instancing” or not.
  • Authors should check “for instancing” for any object that is heavily repeated.  (A car or a single tree or a static airplane, for example.)
  • The modeling program can then try to prefer global attributes for instancing objects but not for regular ones, which should come very close to optimal behavior.


Conditionals are simple logic statements that include or ignore parts of an art file based on the rendering settings.  In particular, they let you change an OBJ based on whether HDR is on or shadows are on.  For example:

TEXTURE_LIT my_airplane_hdr_LIT.png
TEXTURE_LIT my_airplane_LIT.png

In this example, which LIT texture the OBJ uses will depend on HDR.

Because the conditionals can be used anywhere in the OBJ, you can change any aspect of the OBJ to customize for HDR.  You can replace a texture, remove lights, add more geometry, etc.

I don’t know how heavily people will use conditionals, but they give authors the option to make one file tuned for both HDR and non-HDR, shadows and non-shadows.

I think the two most common uses of conditionals will be:

  • Providing alternative LIT textures when HDR is on or off.  Note that only one texture is ever loaded (when the HDR rendering setting is changed, X-Plane unloads one and reloads the other) so this does not increase VRAM.
  • Removing drop shadows that are baked into a model when shadows are on.

That second case would look like:

# This is the shadow geometry
TRIS 300 6

When global shadowing is turned on, the entire set of draped geometry disappears, removing baked vs. real shaodw conflicts.

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.

31 comments on “What’s New in OBJects?

  1. Sounds advanced, sounds powerful, sounds like a colossal time waster. Use this texture if HDR is on or off, and this one if shadows are set to that or this, and that for HDR on but shadows off…. Burden the author to work around what the sim should be able to handle. Burden the user with hacking the objects when the author doesn’t provide the options to suit his poor hardware, or overweight scenery, or even weather preferences.

    Let me tell you what I don’t like about HDR: the ability and/or necessity to turn it off in the first place! Philosophically — if you were to ask me, and I’d rather you didn’t — I’d prefer a KISS-able solution: HDR is always on but degrades nicely if your hardware can’t handle it, as do shadows, and lighting and cloud quantity. For example, simply ignore LIT textures for general lighting related datarefs when global lighting is on (obviously not instrument related ones). Simply ignore shadows when not called for or don’t implement global shadowing unless it can work on 50% of user hardware.

    The front is advancing chaotically, docs are lagging, trivial bugs from version 9 (8?) are still there (for example, when the local map advances a tile, a selected nav point on the map shows the correct data but the rose is now rendered somewhere else); aircraft systems are still lagging… and we’re adding features that need a variety of workarounds because they are quite advanced for current hardware.

    Much respect for how you avoid burn-out 😉

    1. Since (1) hardware requirements for HDR are higher than the minimum system requirements and (2) many users turn HDR off for framerate, how exactly would you suggest that HDR degrade gracefully?

      If you think it would be acceptable to simply drop LIT textures when HDR is on, I fear you grossly misunderstand the level of workmanship that authors are now putting into their add-ons. Conditionals were planned from day 1 because we knew some authors would want to be able to customize their baked lights and shadows based on what the renderer did for them; this view has been validated by authors asking me for the conditional syntax once we shipped.

      No one _has_ to use conditionals, but for authors who put quality first and target more than just high-end hardware, they are there and available.

      My recent work to (1) at least partly document conditionals and (2) make them available in more file formats is about unifying an advancing front – by having a consistent interface with documentation.

  2. Thanks for the update Ben (not to mention all of your efforts that got us this far)

    I’ve been using some of these commands for awhile but I’ve had to add them manually into the obj file with a text editor because the current AC3D plugin doesn’t recognize the new lights and other features.

    Do you have plans to do an AC3D plugin that will allow us to add many or most of these new features from within AC3D?

    1. Hi Tom,
      Yes – I started work on an ac3d plugin update while Mallorca; my plan is to fully update the plugin to v10 syntax and also add automatic optimization so you don’t have to sort out your ac3d project objects by hand.

      1. And Blender scripts? I believe alot of the v10 artwork has been done in Blender and that there were scripts developed for this? Will these go public?

        1. There are mostly done blender scripts – I need to clean up some hacks so they are fully compatible with the extending ones from Jonathan, but they will go public!

    1. That was supposed to say the “alpha” parameter, but apparently my use of brackets is noob-level and messed it up. 😛

      1. For beacons and strobes, you should use the built-in param lights, not full custom lights; I still need to produce a master list. To customize the flash pattern, see the wiki for the “Beacons and strobes” example – that is a systems-level mod.

        For plugins, if you really want to do _your own thing_, the plugin author writes to the array index as desired – I think the basic v9 system is on the SDK wiki.

        1. By “built-in param lights”, do you mean named lights in objects, or ‘built-in’ lights in Planemaker?

          Because from what I’ve seen, the named-lights don’t “spill” onto the aircraft objects… unless I’m doin’ that wrong too.

          1. There are new named lights for spill. You don’t get spill “for free” from anything in an OBJ from v9 – we can’t safely guess where the spill should be. So IF you go for named lights, you must add new names.

            But I should also say: for beacons and strobes, the easiest and best way is probably to use the built-in plane-maker lights in v10. You get a lot with them with only a few params.

          2. …to use the built-in plane-maker lights in v10.

            Plane Maker lights at the wingtips don’t necessarily custom wing flex.

  3. And these “new names” can be found…. ??
    Or is that what you meant in the doc page by your comment, “Note: the list of available lights will be published in the future.” ? See, I read stuff! 😉

    I realize PM lights are generally easier to work with, but I’m trying to update a V9 plane with object-based lights (I find it easier to place and work with them in AC3D), and I thought it would be easiest to just go into the OBJ file and change the light-names and params.

    Also, I have a custom-animated landing-light that has to be in the object, so I hope there’s a name for those too. 🙂

    1. lights.txt for now…and yes, the list will be published in a more human-friendly form in the future. But if you feel brave, spill lights tend to end with _sp. 🙂

      You can add custom spill directly to your landing light animation – use a named landing light with _sp.

      1. Haha, ok cool, thanks.

        Hey we’re all geeks here, I think we’re OK with the non-human-friendly version. 😉

      2. Tried adding “_sp” to my light names…no dice. They just disappeared.

        i.e. “LIGHT_NAMED airplane_landing” became “LIGHT_NAMED airplane_landing_sp”, but the light just isn’t recognized.

        I must be doin’ somethin wrong…

        1. This is getting beyond the scope of what we can deal with in blog comments. You need to wait until I write docs. If I try to service everyone’s questions in detail personally, I will never get any docs done and we’ll all be in the dark for a lot longer. 🙁

  4. Since you’re going with conditionals, expand its usefulness. Examples:

    1) An airport might be predominantly used for daytime VFR so there’s no need to show certain activities at night, or keep hangars open / lit up like a Christmas tree.

    2) On a winter storm, nobody is going to take their gliders out of the hangar. Nor light up the barbie or lie beside the pool under an open parasol.

    Or is that all possible already? It’s just a series of dataref-driven Hides…

    1. That’s definitely _not_ the right use of conditionals. Conditionals actually delete the unused part of your scenery, not only saving memory, but allowing the rendering engine to optimize what is left. (The rendering engine can better optimize when unused stuff is gone.)

      Bu that means changing a conditional is a scenery reload, so the conditionals should not be tied to things that change in real time, dynamically, while you fly. You wouldn’t want a scenery reload because the METAR from real weather changed.

      Fortunately some aspects of this can already be done with show-hide datarefs. The underlying mechanism for “seasonal” textures is actually dataref-driven texture selection, so that will give you the other dataref-driven aspect of this.

      In other words, if you make two objects and use a show-hide, the sim keeps all that geometry in memory, and can animate in real time. If you use a conditional, the sim loads only the half it needs and reloads on a rendering setting change.

  5. All looking very promising. Couple of questions regarding lights after reading this blog and the spec doc…
    1) Am I right in thinking that the CUSTOM_SPILL_LIGHT command just creates the pool of cast light and should be used in conjunction with a second light command that depicts the light source itself, compelte with billboard texture if desired?
    2) Can authors create their own custom named lights in a lights.txt file in their scenery package? If so, can these be exported as a library or are they restricted to the local package?

    1. 1. Correct! Spill and billboards are always separate for maximum control.
      2. No. If you want custom you use the custom light and custom spill light commands and go home happy.

  6. I have tried to use WED 1.1r1 to position trees on a FOREST Pollygon area using the line and point placement method. I get no difference from the area coverage operation which results from using the default 1.0 value in the Density box for the area.
    Is this Trees operation improvement only implemented in WED 1.2??
    Neither 384 nor 512 shows what I would expected used with WED 1.1r1 on XP 10.
    Your new specs are a great help! Nice work Ben.4EUY

    1. V10 line/point trees are only available in WED 1.2.
      What you are doing is incorrect usage of WED.
      Please wait until we have a manual – I am trying to get this going now.

  7. Hi Ben

    Are the conditional commands functional in 10.04 (r3)? I’ve been trying to remove my baked in static aircraft shadows but can’t get it to work. Both shadows remain.

    Am I doing something wrong? or will this be a feature added in the next patch?

    In the example, the draped shadow is the last object in the hierarchy .

    ATTR_LOD 0.000000 1500.000000
    TRIS 0 16986
    # This is the shadow geometry
    TRIS 16986 6
    ATTR_LOD 1500.000000 4500.000000
    TRIS 16992 2265
    # This is the shadow geometry
    TRIS 19257 6

    1. They should be functional. Please submit a bug report with a very small test pack installed, e.g. so I can go to an airport by ICAO and see the object!

  8. Sorry Ben

    I just re-read your post on conditional shadows. I see that this WILL be added in the next patch (if I am reading it correctly).

Comments are closed.