This topic is confusing, so I’m going to try to summarize “how to do it the correct way” without going into “under the hood”, first.
DataRefs of the form:
give you information about the wings – in particular, they tell you the degrees of deflection of the flaps, elevators, etc. etc.
But what number do you use for N?
The answer is: you pick “N” depending on which airfoil you are animating!
In X-Plane, the horizontal and vertical stabilizers are “wings” too – we call anything that has an airfoil a wing. So you use this table to pick an N that matches what you are doing.
sim/flightmodel2/wing/aileron1_deg # left aileron
sim/flightmodel2/wing/aileron1_deg # right aileron
sim/flightmodel2/wing/elevator1_deg # left elevator
sim/flightmodel2/wing/elevator1_deg # right elevator
sim/flightmodel2/wing/rudder1_deg # rudder
Usually not good:
sim/flightmodel2/wing/aileron1_deg # aileron on an hstab??
sim/flightmodel2/wing/aileron1_deg # aileron on a rudder?!
sim/flightmodel2/wing/elevator1_deg # elevator on a wing?
sim/flightmodel2/wing/elevator1_deg # elevator on a rudder?
sim/flightmodel2/wing/rudder1_deg # rudder on a wing??
The moral of the story is: pick an array index that matches the part of the plane you are trying to animate!
I said “usually not good” above because there are airplanes with rudders on the wings (think of a flying wing) or V-tails where the tail is half-rudder, half-elevator. The rule still applies: use the index that you are animating! So if you have a rudder on your wing, then use index 0 (left wing 1) for the left wing, etc. The important thing is to pick an array index that matches the Plane-Maker part.
Why Is It Like This?
If you understand what was written above, you should probably stop reading now. And if you didn’t understand it, you should probably stop reading now.
Okay then. Why are the datarefs like this? The answer is that X-Plane is a completely flexible simulator: it lets you put any control surface on any flying surface. If you want to make an experimental design with elevators on the wings, X-Plane is not going to tell you that your idea is stupid. (I might tell you that the idea is stupid, but you can ignore me, because the only airplane I ever designed from scratch in Plane-Maker couldn’t take off without JATOs.)
In particular, because any flying surface can have any control surface, the datarefs are set up with array indices for all flying surfaces for all control surfaces.
But if your airplane does not have rudders on the wings, the value of those daterfs won’t be useful – they might be ‘correct’, they might be zero, they might be wrong. Don’t trust them! Use the correct array index for the correct wing and your plane will work correctly.
If your add-on uses LuaJIT (e.g. via SASL, Gizmo, FlyLua, or directly) then this tool may help. It’s a special build of X-Plane 10.21 for 64-bit Mac that can show total Lua memory use. Use DataRefEditor and filter on “lua” to see the numbers.
Since Lua uses garbage collection, you’ll see the number rise up and then “fall” periodically as garbage gets cleaned up. Non-Lua allocations by plugins are not counted.
If you use LuaJIT in your add-on (or a plugin that uses LuaJIT), please try to keep the amount of Lua memory used below 300 MB or so – more is available, but if you use it all, your plugin won’t inter-operate with other plugins.
That got your attention, eh? Sorry, this is not a tip on how to tune your X-Plane system; it’s a tip for aircraft authors to make sure their 3-d cockpits are running at maximum performance.
Prefill is when X-Plane blocks out the clouds that will be behind the airplane cockpit. The biggest cause of GPU slow-down is cloud rendering, so reducing the area that the clouds have to fill is really important.
In the 2-d cockpit, X-Plane pre-fills automatically. But in a 3-d cockpit, the airplane author has to specify which objects should be used to pre-fill.
Aircraft Authors: go watch this video or read this page to learn how to set up pre-fill in your aircraft! If you aircraft has a 3-d cockpit this optimization is very important!
Update: We are going to release a new release candidate (10.21 rc2) tonight that puts the light sizing back to normal, while still fixing the SSAA bug. This will have two effects:
- Runway lights won’t be as bright as in the RC. Sorry guys, we will get this fixed, but clearly it’s not something that I should try to change by jamming a code change in at the last minute.
- Airplane lights will look the same as they do in 10.20 and 10.11.
The rest of the original post follows…
I jammed a change into X-Plane 10.21 rc1 that maybe wasn’t such a great idea: in X-Plane 10.21 the light billboards get bigger when your screen resolution gets bigger.
The idea behind this change is that the percentage of lit pixels in the night scene should not get smaller when you go to a bigger monitor – if they do, then the night scene looks dark. In X-Plane 10.20 (and 10.10 and 10.05!) the billboard sizes are fixed in pixels – in a bigger monitor they tend to be tiny little dots, potentially harder to see.
This change makes a mess of aircraft lighting, and almost certainly needs to be changed (again) for an RC2. But the choices aren’t good.
- If we keep the old behavior (light size is constant in pixels) then authors have a lousy choice: make the lights too big in a small window or too small in a big window. There’s no way to get your billboards to look good on a laptop and a 1440p monitor. This is what authors have been living with, and it’s lousy. If you make a plane, you know that your lights only look right if the user has the same screen resolution as you – something you just should not assume.
- If we take the new behavior, what size should the lights be? We have to pick a screen size to use as “official” from 10.20. In rc1, I picked 1024 x 768 – that is, the smallest resolution we support. This choice makes the runway lights look good, but virtually all airplanes are going to have lights that look too huge.
So I am considering one of the following choices:
- Match the 10.21 lights to 1020 at 1080p (or some other intermediate resolution), in the hope that most airplanes will look good on average.
- Revert the change entirely (and keep only the fix for 4x SSAA) and solve this in 10.30. This isn’t good because (per above) authors are again stuck with the airplane only looking good at one resolution. But at least in 10.30 we could do something more clever (e.g. different behaviors for old and new airplanes or who-knows-what-else). Alex is still out of the country, so the thought of punting this until he can look at the results of some of the choices is tempting.
- Apply mixed behavior (e.g. different math for scenery vs. airplanes). With anything “clever” like this, we risk the equations getting complicated, with too much fine print for authoring.
Anyway, I think it’s 95% likely we’ll cut an RC2; I’ll post something when we pick a strategy.
If you are creating an airplane or scenery pack and you need to create a fully customized spill light (visible in HDR mode only in v10) there are two ways to do it.
First, we have a parameterized light called “full_custom_halo” that takes nine parameters, e.g.
LIGHT_PARAM full_custom_halo 0 20 0 1 0.5 0.5 1 50 0 -1 0 0.5
(Phew!) The first 3 numbers 0,20, are the XYZ position (this light is 20 meters above our object origin). The next four are the RGBA color (100% red, 50% yellow, 50% green, 100% brightness*), so it’s a very light red. RGB colors for spills are in linear space, so you’ll have to experiment to get your colors perfect. The size is 50 meters (a huge light throw), and it points in the direction 0, -1, 0 (straight down). 0.5 is the “semi-width” of the cone – 60 degrees in this case. Basically cosine(cone width * 0.5) gives you this width parameter, or pass 1.0 for an omnidirectional light.
This light is on all the time – use full_custom_halo_night for the night version.
There’s a second option: OBJ files have a custom spill command:
LIGHT_SPILL_CUSTOM 0 20 0 1 0.5 0.5 1 50 0 -1 0 0.5 your/dataref/here
The position and 9 light parameters all have the same meanings, but in this case you get to provide a dataref. The dataref must be a float-array dataref of size 9; when your dataref callback is called, the array is pre-initialized to the 9 params, and you can change them at will. With this dataref, your plugin can change the light parameters in real-time.
Which technique should you use?
- Use LIGHT_SPILL_CUSTOM if you need the dataref to do clever customization.
- Use the PARAM_LIGHT with the nine params if you don’t need the dataref.
For scenery the param-light version may be notably faster when used many times in an object. So if you’re building a light used a lot (a streetlight, a taxiway light, an airport lighting fixture) you really want that param version.
Update: this was not documented at the time, but if you are using datarefs with LIGHT_CUSTOM_SPILL, the dataref format does not match the OBJ8 format. This page now documents the right format for plugin objects!
* The mathematically minded will note that there is no need to have an alpha on lights because they are additive. This is true – just set alpha to 1.0 and use darker colors!
I seem to be having the same conversation with lots of third party developers via email, so I’m going to write up some of my recent thinking on Lua – if nothing else, it will save me typing the same thing over and over.
One thing was very clear in the X-Plane 10.20 beta: while authors can’t agree on Gizmo vs. SASL*, the entire authoring community is surprisingly united around Lua as a scripting language – it’s everywhere in the payware add-on market.
But Lua is being used for a lot of different things – and these levels of usage are paralleled in Gizmo and SASL; my opinion on the use of Lua must be qualified by which usage we are talking about.
- The simplest level is “datarefs and math”. At this point, to fully utilize the aircraft SDK, an author needs to be able to create and do very simple math with datarefs – something that is not possible inside an OBJ or panel.** Right now we don’t have an easy way to do this basic dataref math. Writing a C plugin and compiling for 3 platforms is a huge hurdle to jump just to wire up an animation to a custom rotary switch.
- Gizmo and SASL both provide ‘add-on’ SDKs – custom sound APIs, particle systems, physics, gauges – basically replacement SDKs for parts of the sim’s own extension system where authors wanted more than we provide. This stuff isn’t Lua at all – the underlying systems are coded in C++ and thus can only be maintained by the C++ developer who writes the Lua-based plugin. The development cost (in man-hours) to do a particle system in Gizmo or SASL is abotu the same as it would be to build it into the sim.
- Some authors have written fairly huge scripts in Lua – for example, doing complete systems simulations or navigation code in Lua. (At least, that’s what I am told, e.g. the JAR A320 – I haven’t read the Lua scripts myself.) This is “Lua as language for a huge program.”
This is my current thinking on these three tasks:
- Datarefs and math are a great use of Lua – it lowers the bar for authors, it’s exactly what scripting languages in games are meant for, and the underlying code in C++ is finite, limited, and therefore not a maintenance problem. I don’t know what LR’s relation to Lua, Gizmo, SASL, or scripting is yet, but I have been saying for a while (internally in company discussions) that we need something easier than C for this.
- I think that if an authoring SDK is limited in X-Plane, we (LR) need to make it better. In the most useful cases where people are doing things with Gizmo and SASL, we sometimes have on our road map features to add to X-Plane that are similar. (But note that these features aren’t necessarily coming soon – authors get a time to market advantage by using these outside SDKs.) I consider this plugin code to be a possible maintenance problem. For example, you can write graphics code in a plugin, but it may not integrate well with next-generation rendering engine features.
- I don’t see huge plugins or huge scripts as something LR should get involved in. If you want to make a truly huge or complicated add-on, that’s great, but it’s a big undertaking and it just takes a development team. I don’t know if Lua is good for huge development; the people who say no (people like me) have no serious Lua experience, and the people who say yes have no serious C++ experience. So far I’ve only heard from people who have lived on one side of the grass.
Anyway, one thing is clear: having LuaJIT work in a plugin is a necessity for X-Plane now; with 10.20 we’ve sunk the engineering cost to make this happen. I do not yet know how else (or if) we will leverage Lua.
* Don’t even bother to comment on Gizmo vs. SASL – I will delete any attempts to start a Gizmo vs. SASL discussion so fast that your head will spin around 360 degrees!
** No math in OBJs or panels. An OBJ is a 3-d model – it is data that you view, not a simulation to be executed! We do not want to mix visualization with simulation or data with code!
Edit: Normally I label the overly technical posts as being for a target audience, but I did not this time. My bad — this post is really only of interest (and will only make sense) to serious 3-d modelers – the advanced airplane and scenery nerds!
The brightness of specular hilights is out of sync between HDR and non-HDR mode in X-Plane 10.11. This wasn’t intentional – it’s a bug. 10.20 will fix this; specualr hilights will have the brightness you see in non-HDR mode (which we think is more like they were supposed to work*) but the tinting of HDR mode (non-HDR mode was overly red in 10.11).
I get a lot of requests for ‘hardness’ control – that is, the exponent that controls how wide a specular hilight is. We’ll get this feature eventually – it’s too important to ignore. The main delay in having this feature is that X-Plane uses a deferred renderer, so the specular exponent has to be stored in the G-Buffer somewhere, and storage is tight.
For similar reasons, it is very very unlikely that we’ll ever have RGB tinting of specular hilights. Doing so is 3x as expensive in G-Buffer storage, and we need that storage for other features.
* That is, unless we discover that non-HDR mode looks spectacularly bad in some cases, in which case we may have to push things a little more toward how HDR was.
We have received a number of bug reports on the livery system in X-Plane 10, as well as complaints from both users and authors about how the system works. This post describes what I am thinking for liveries; if this proposal seems hair-brained, the comments section would be a good place to counter-propose.
Two notes on UI discussion before we jump into the details:
- We hate check-boxes. If the UI debate is “which is better, UI A or B”, then the answer is pretty much never “let the user pick A or B with a check-box”, because the point of UI is to present the program in a human-friendly manner. Having two different UIs with selection forces the user to become the UI designer, which is inherently harder. So while we don’t have zero check-boxes in our UI, we really try to keep the ‘have it your way’ stuff to a minimum; X-Plane is a product for sophisticated users and if we put in a check-box every time we get a request for one, the product would be absolutely unusable.
- In arguing for UI, describe what you want to do, not how you want to do it. If you describe an implementation but we can’t do the implementation, the discussion is over. If you describe what you want to do, we can find several implementations and pick the best one.
As of X-Plane 10.11, you can:
- Select your livery when you open a plane using Open Aircraft…
But you cannot:
- Change the livery without reloading the airplane, mid-flight.*
- Select your livery from the Quick Flight dialog box.
- Change your livery quickly (since a plane reload is slow).
- Change which livery the QF dialog box picks for you – it always pick “no livery” (that is, default paint).
These first two bugs go hand-in-hand. Because you have to reload the plane to change liveries, you lose the initialization that Quick Flight may have done for you.
* There is one bug to note: if you go to the open aircraft dialog box, select a different livery and hit cancel, X-Plane will change your livery on the fly but not reload the plane. Some users have noticed this and use it as a back-door way to change livery mid-flight.
For the short term, I am converting the bug in the Open Aircraft dialog box into a feature – the dialog box will have a “change livery and keep flying” button to change your livery on the fly, and the “cancel” button will not unexpectedly change your livery. Thus the functionality of the old “open livery…” v9 functionality will be part of “Open Aircraft.”
This isn’t perfect, but it at least addresses the issues of changing liveries quickly, or changing them while flying, without having to know about and use a hidden UI bug.
For the Future
There are more features we’d like to do in the future:
- Have a dedicated livery-change UI again – perhaps one that ‘floats’ over the main window while you fly, so that you can see the liveries as you click on them. This would be a quicker way to rapidly preview a large number of liveries.
- Remember the last user selected livery in the per-aircraft preferences (along with quick-look keys) so that if you go to open an aircraft and don’t do anything else, we can pick the last livery you used.
- Someday have ‘drill down’ functionality in the Quick Flight window so that you can set more detailed info about your plane (livery, weight and balance, fuel, weapons) and then go back to the main QuickFlight window. This is a long ways off though.
None of this is going to make it into 10.20 – I mention it only to explain where we’re trying to go – the change for 10.20 are designed to not interfere with this future work. The future work is all based on user selected livery choice, with preferences an easy selection.
Livery Choice in Plane-Maker
This finally brings me to livery choice in Plane-Maker. I have always considered this a bit of a weird feature; it is inoperative in 10.20 and we are looking to get rid of it permanently – that is, setting a livery in Plane-Maker has no use in any of the above plans. Our view:
- The first livery you see if you first open a plane for the very first time in QuickFlight will be the default one.
- Preferences should record the users choice of livery, and this should be done entirely from X-Plane. It should not be necessary to open Plane-Maker to change livery preferences, any more than Plane-Maker is needed to change rendering settings or joystick preferences. User customization should be 100% in-X-Plane.
As I said before in the top of this article, if this seems half-baked to you, please describe what you want to do, not how you want to do it. And please understand that when it comes to UI, less is more; we need to identify a small, highly leveragable set of UI options to cover a wide variety of features. We don’t want to have 6 ways to do everything!
X-Plane 10.20 beta 3 is out. This build went out without new art assets. We have a pile of new art assets waiting to go out the door: autogen from Alex, more terrain textures from Albert, an airplane upgrade from Javier, and fixes to airplanes and aircraft from Tom.
But I held them back and kept them out of this release. Why am I such a bastard?
The answer is: two complex low level changes went into this beta, and I want to capture at least one beta’s worth of crash report data to check for destabilization. The new art assets may use more memory (especially if users crank them up to see what’s going on); if we rolled everything into one beta, we wouldn’t be able to tell art-induced crashes from code-change induced crashes. So we’ll roll things out in steps. As I have said before, the purpose of betas is not to have an awesome flying experience, it’s to find bugs!
Bear in mind that not all of the bugs reported are fixed; we cut beta 3 to get these two specific code changes fixed; more bug fixes are coming soon. Please see the release notes for what is fixed. please do not re-report bugs unless they are listed as fixed but still show up as broken on your machine.
I’m hoping to get a beta 4 out over the weekend with art assets if beta 3 goes smoothly.
So What Did You Do?
So what are the two bug fixes that are major enough to warrant their own beta?
- A change in the load order between X-Plane’s sound code and OpenAL. I realized that the old way we load sound (e.g. in 10.10) makes it virtually impossible for a globally installed plugin (one in Resources/plugins) to share OpenAL, even if it follows all of the rules set out in the OpenAL plugin tech-note. This change fixes that, apparently fixes conflicts between Gizmo and SASL, and hopefully should let plugins do the right thing. Plugin developers, see here for more info. (The original load order assumed that OpenAL would be more robust to two copies being opened; it now appears that this is not the case and OpenAL can be quite picky at times.)
- The OS X 64-bit memory layout has been modified to be compatible with LuaJIT 2.0, the Lua engine inside most Lua-based plugins (e.g. Gizmo, SASL, FlyLua, etc). This does not entirely fix the porting problems developers have been seeing with LuaJIT, but it at least makes the plugins work under light memory conditions. (These plugins would fail 100% of the time in beta 2.) Here’s the technote; I am in contact with most of the plugin developers using Lua, but if you use Lua and haven’t heard from me, email ben at x-plane dot com.
These are not the only bug fixes in beta 3, but they are the two that are weird enough that we want ‘clean’ bug data, without additional art assets to cloud our view.
So: hopefully these two changes will go smoothly and we’ll get on to beta 4 and art assets soon. The artists work their butts off to create this stuff and we want to roll it out!
Will Lua Ever Work With 64-Bit OS X?
A few developers who depend on SASL and Gizmo have asked me whether Lua will work with 64-bit X-Plane on OS X. The only answer that I can give is that I do not know, but I am optimistic that we will engineer a solution. I consider making Lua work to be a very high priority.
Lua is in almost every commercial third party airplane we’ve seen in the last few years; the market has spoken and third party developers have said “we like Lua.” So I think it’s worth doing some serious engineering to keep Lua working. Making Lua work with 64-bit OS X is currently my top priority bug.
I’m trying to migrate our developer documentation from the Wiki to this site. See the menu up top for articles, file formats, and tools.
One document I just posted here: A Checklist for Updating Aircraft to X-Plane 10. If you are working on airplane conversion, I strongly recommend looking over the various items. A lot are “check that X isn’t hosed” – there are very few mandatory changes.