Discussion A Record of My Own Noob Questions, for Reference to Other Noobs

[DecoFox]

I've been having a great time figuring Orbiter out, but wow can it be a difficult subject to google, and if you haven't sat down and read the manual end to end, it can be easy to miss stuff. Not to mention some of the manual is outdated. My intent with this thread is to create a record of all of the problems and questions I've run into, both basic and "advanced", that it either took me some time to dig out of the documentation, or that I failed to find answers to there. I'll update this post with the solutions I've found, with the hope of providing fodder for the google-fu attempts of people from the future searching "Orbiter Forum + [terms]". If I ran into a problem, I figure I won't be the last!

First, a note to said people from the future: Read the documentation. It's actually really good. I've tinkered with a lot of games over the years, and usually it's straight to google for any meaningful questions. Not so here! You can get something flying from scratch with the basics of a clickable VC without referring to anything else! I also recommend reverse-engineering the Shuttle-A. It is very simply-implemented, but also very feature-rich. The DeltaGlider is probably better designed, but it's less readable. If you're used to working on other, modern games, Orbiter will be much lower-level than you're used to, but don't let it intimidate you. Even if you barely understand what you're looking at, just start implementing what you can and it will very quickly start to make sense. Please be advised, the advice I give here may not be the best answer to many of these questions, just the answer I found. I'm a Unity developer. Do not mistake me for somebody who knows what he's talking about. I'm choosing to post this now because, by the time I do know what I'm talking about, I'll have forgotten what my original problems were. When you're figuring something out for the first time, sometimes what you need is someone who figured it out five minutes before you. I'm that guy.

I will continue to update this post with new answered questions as I encounter and solve problems, but I will not include answers that I have found elsewhere on the orbiter forum. The purpose of this thread is to populate search results that would otherwise come back empty. I encourage others to participate in this effort, either by contributing their own problems and solutions or by correcting any bad information I give. Together, maybe we can save future orbiter developers a few days.

With that, the record. These will be more or less in order that I encountered them:

General Development

• How do I get an Orbiter development environment set up in a modern IDE:
  • https://www.thomasantony.com/posts/2020/orbiter-sdk-vs-2019/
• I want to design a Virtual Cockpit. Am I crazy?
  • No! It's not nearly as bad as it seems. Please refer to the very helpful posts that bailed me out over here: https://www.orbiter-forum.com/threads/virtual-cockpit-best-practices.41755/
  • If you're coming from other games with the concept of a virtual cockpit, defining regions the way Orbiter does may seem gross and boiler-plate-y. Just bite the bullet. It'll start to make sense why it's done the way it is.
• Where is the Timestep() function the documentation refers to?
  • Obsolete, I think. You want clbkPreStep or clbkPostStep, depending on whether you want to execute before or after the frame update.
• Why are my touchdownvtx values so jumpy? Is vertex order important?
  • Yes! Vertex order is important, as it defines the normal direction for contact points as the cross product of p3-p1 and p2-p1. This is in the docs, but easy to miss.
    • This means generally you'll want to list the landing gear points center, left, right.
  • But! that probably wasn't actually your problem. If you're working from the ShuttlePB like I was, take a moment to appreciate how extremely low mass it is. You probably need to lower your stiffness and dampening figures, or make your vessel heavier. I have found moderately heavy vessels are far more cooperative on whole when it comes to ground contacts.
• Why can't I get point lights to render?
  • You probably have them turned off in your launcher settings. This overrides your d3d9 setting, if you're using it. The term used is "local lights", which I believe applies to any light that isn't baked or purely directional.
• Why are MFDs and HUD are invisible in the virtual cockpit?
  • The documentation says the HUD and MFDs should receive a special mesh flag. This information appears to be out of date. I am working with no mesh flags on either of them.
• Why do MFDs show black in the virtual cockpit? Why is the HUD blank?
  • Your UV maps probably didn't stick. I chased this for a full day and tore apart code left and right trying to figure out what was wrong. In reality, blender had elected not to save my UVs for some reason!
  • If exporting your .msh files from blender, you may need to assign a texture to your HUD/MFDs to get the normal map to export properly. The render target feature will replace it anyway.
• Do MFDs really have to be flat, triangulated squares, like the documentation says?
  • No. I don't know if that's an old limitation, or just a suggestion, but it looks to me like MFDs map across the whole UV map regardless of mesh configuration. You can make curved CRT displays all you want. You might even be able to do something like build a HUD into the glass of the front window itself, which might be neat. Haven't tried that yet.
• How do I define emissive maps? Orbiter supports material emission, but I can't assign multiple textures to a material.
  • You don't!***
  • Orbiter doesn't appear to support any more than one texture per material or more than one material per mesh group natively. If you enable emissivity, you'll notice that emission seems to scale with the value of each pixel in the texture that is assigned. The brighter the color, the brighter the emission (scaled by the emissivity you set in the material). This is a major limitation, but most Orbiter vessels appear to simply design around it as opposed to working around it. Take a look at a few stock vessels. You'll notice they have no emission maps defined, and, if you fly them on the dark side of a planet, they remain lit internally even if you have all lights off. That's the emission at work! While I can't explain the limitation itself, baking emission into all of your textures makes some sense when you consider Orbiter's age and the rendering cost of realtime lights. I think the intent here is that we paint our models like you would paint a picture, building the lighting right into the paint itself. Since emission is defined by pixel value, you're basically painting a lightmap as well as a color map as you go. In retrospect, this goes a long way to explaining Orbiter's distinctive, somewhat painterly look.
  • If you want to work-around anyway, you can always separate the mesh into more distinct groups. In example, my current project has a row of raised buttons with screens on top of them. I would like the screen to be backlit in white, but the rest of the button is not lit but still a pretty light color, so if I were to try to get a way with "painting" my way to victory, the whole button would appear to glow. A better artist than me could probably work around this, but what I did instead was separate the button faces and animate the buttons as groups of two mesh groups. The way Orbiter allows you to define multiple mesh group indices to perform a particular transformation on makes this trivial to do. The manual discusses keeping mesh group counts down, but I figure 2001 was 23 years ago and we can probably be fairly casual with them. I'm not aware of any actual engine limitations.
  • ***The D3D9 client actually does support multiple textures per material, which it does by appending the function of the texture to the name with a standard convention. See the D3D9 docs for details. The D3D9 client isn't exactly a bulletproof standard though, and, as I understand, there are more than one D3D9 clients. In interest of compatibility, I'll be leaving this feature alone for the time being.

Less General C++ Stuff:

• How do I draw text on dynamic textures?
  • The documentation is pretty thorough on this, and the Shuttle A has some good examples. The short version is you use the TextOut function on a Display Context (the thing you define when you're defining an active panel area). This is probably obvious if you're familiar with C++, but I was not. In general, Orbiter is much lower-level than I was expecting.
• I want to draw other shapes on dynamic textures.
  • The features you're looking for are members of wingdi.h: https://learn.microsoft.com/en-us/windows/win32/api/wingdi/
• How can I find the dimensions of a Display Context defined by a RegisterArea function?
  • You're actually after the underlying bitmap: https://stackoverflow.com/questions/3154620/how-to-find-out-dcs-dimensions
  • Looking into this generally for C++ will usually direct you to GetDeviceCaps, but unsurprisingly we can't get away with that here.
• How can I rotate/format text?
  • All that stuff gets done during font creation. It's a bit cumbersome in the boilerplate, but if you look at other vessels, you'll see they keep arrays of fonts, brushes, etc (see wingdi.h for details) and set/unset them in InitModule and ExitModule. They can then be accessed from wherever. If you need to change angle or font size or something in realtime, though, you'll have to create and destroy your font in realtime.
  • In example, a block of code that creates a font at a given size, writes with it, and then tosses it out:
  • HDC hDC;
    hDC = oapiGetDC(surf);
    HFONT hFont = CreateFont(fontSize, 0, 0, 0, FW_BOLD, 0, 0, 0, 0, 0, 0, 2, 0, "SYSTEM_FIXED_FONT");
    HFONT hTmp = (HFONT)SelectObject(hDC, hFont);
    SetTextAlign(hDC, TA_CENTER);
    SetBkMode(hDC, TRANSPARENT);
    COLORREF textCol = GetNavmodeState(navmode) ? RGB(255, 255, 255) : RGB(100, 100, 100);
    SetTextColor(hDC, textCol);
    TextOut(hDC, 95.5, 46, label, strlen(label));
    DeleteObject(SelectObject(hDC, hTmp));
    oapiReleaseDC(surf, hDC);