[1.12.x] AutoAGL v1.2: Automatically switches altimeter between AGL and ASL as appropriate.

[Snark]

What it does

• Automatically switches the altimeter between AGL and ASL modes as appropriate for the ship's current situation.
• Looks at terrain both underneath and ahead of the ship, to anticipate looming mountains and such.
• Configurable settings let you adjust how it behaves.
• You can still manually switch as you like-- the mod won't "arm-wrestle" you. 

Download from SpaceDock
License: CC-BY-NC-SA 4.0
Source code

 

How to install

Unzip the contents of "GameData" to your GameData folder, same as with most mods.

 

Why would anyone want this?

KSP 1.7 introduces a new feature that allows toggling the altimeter between "ASL" mode (height above sea level, i.e. what it's always been since the dawn of KSP) and "AGL" mode (height above ground level-- this is the new KSP 1.7 feature).  All you need to do to toggle between the two is to click on the little blue-or-green button on the left end of the altimeter.  It's a great feature, very handy, and one that KSP players have wanted for a long time. 

I'm really happy about it... but I'm also very lazy.  I'd like it to just automatically set to ASL or AGL based on what's "right" for the current situation, so that I don't have to mess with it.  On the other hand... I still want to be able to switch it manually whenever I want, since "special circumstances" can always come up where I need to decide on my own what to set it to.

Well, this mod takes care of all that.  It just automatically sets the altimeter to the "right" mode (more on what this means, below) based on the ship's current situation, but the player can still manually toggle as desired and the mod will respect that.

 

What do you mean, the "right" mode?

Here's what the mod does, by default (though note that you can customize via settings, see below):

• It sets to ASL when you're landed or splashed.
• It sets to AGL when you're "low", i.e. "close" to the ground (more below on what this means).
• It sets to ASL when you're higher up.

"Low" is defined as follows, by default (again, see customization options below):

• At Kerbin sea-level pressure or higher:  If your free-fall time from the ship's current position to the surface is under 10 seconds.
  • It also does path projection by default, which looks at the terrain ahead of you.  So if you're cruising in level flight and there's a mountain looming up ahead, it'll switch to AGL sooner in anticipation.
• In a vacuum:  If your free-fall time from the ship's current position to the surface is under 30 seconds.
• If you have any activated parachutes:  If your height above the surface is less than 2x the parachute's "open" altitude.

A few additional notes, for the curious, in spoiler:

Spoiler

• If the local pressure is between Kerbin sea-level pressure and a vacuum, it interpolates between the "atmosphere" and "vacuum" settings.  For example, if the local pressure is 0.5 atmospheres, then it will be the midpoint between 10 seconds and 30 seconds, i.e. 20 seconds.  ("Local pressure" is defined as the pressure at surface level directly beneath the ship.)
• If the ship is falling, then its downward velocity is incorporated into the "free-fall time to surface" calculations.  This means that a rapidly falling ship will switch to AGL mode at a higher altitude than a ship that's not falling.
• If you have multiple parachutes activated, then the "parachute altitude" that it uses will be whichever of them is the highest setting.

The practical upshot of this is that on Kerbin, the altitude boundary between ASL and AGL modes will be a bit under 500 meters if you're close to sea level (e.g. at KSC), somewhat higher if you're over higher-altitude terrain.  If you're falling rapidly, it'll be higher still.  If you have any active parachutes, it'll be 2000 meters (i.e. twice the parachute's activation altitude, assuming you've got it set to the default 1000m).

 

What happens if I manually toggle the altimeter?

It "just works".  It switches to the mode you choose, and stays that way without automatically switching back.  However, it'll later revert to automatic mode when circumstances are "appropriate".  Nitty-gritty details in spoiler if you're curious, but the practical upshot is that it "just works" and does pretty much what you'd want it to. 

Spoiler

• When you manually toggle the altimeter, it switches to the mode you choose and stays that way.
• It will revert to automatic if you then transition to the opposite "auto-zone" and then back again.

What I mean by that:

Let's say you take off from the surface.  You're "low", so AutoAGL immediately automatically switches to AGL mode.  Suppose you don't like that, and you manually switch it to ASL mode.  It'll stay that way.  However, if you then climb into the "high" zone (i.e. to an altitude where normally AutoAGL would switch to ASL), and then back to the "low" zone... then it will automatically switch back to AGL.

So, suppose your settings are such that the boundary between "high" and "low" zones is about 500 m above the surface.  If you manually switch to ASL while you're still below 500, it'll switch to ASL and stay that way as long as you stay under 500 m.  However, if you climb above 500 m, that "resets" it, so that if you afterwards fall back below 500 m, it'll automatically switch to AGL.

 

Configurable settings

The default behavior is tweaked to be the way that I, personally, like it, since it's my mod. 

However, the mod provides configuration settings in the KSP settings dialog:

Here's a rundown of the options available:

• Enabled:  Checked by default.  If you uncheck it, it completely disables the mod.  A handy way to temporarily shut it up without needing to completely uninstall the mod.
• Preference When Landed/Splashed:  Which mode do you want the altimeter to be in while you're landed or splashed?  Choices are "ASL" and "AGL".  Defaults to "ASL".
• Collision Threshold (atmospheric):   Defaults to 10 seconds.  When local pressure is Kerbin sea-level atmospheric or higher, it automatically switches to AGL when you're within this many free-fall seconds of hitting terrain.
• Collision Threshold (vacuum):  Defaults to 30 seconds.  Like the setting above, but for when you're in a vacuum.
• Parachute Altitude Multiplier:  Defaults to 2.0x.  If your vessel has any armed parachutes, will automatically switch to AGL mode when your height above the surface is less than this number, times the highest activation altitude of any armed parachutes.
• Enable path projection:  Checked by default.  When enabled, AutoAGL looks at the terrain a few seconds ahead of the ship, so it can switch to AGL mode earlier if there's a mountain rising up in front of you.  Uncheck to disable this feature and make the mod only look at the ground directly under your current location.

[linuxgurugamer]

1st post.

WOw, that was fast. A new mod for 1 .7 release on the day of 1. 7 release

Edited April 10, 2019 by linuxgurugamer

[Snark]

3 minutes ago, linuxgurugamer said:

WOw, that was fast. A new mod for 1 .7 release on the day of 1. 7 release

Had to resist, with every muscle in my body, the urge to add "First!" to the OP. 

[Freshmeat]

I like your reasoning. My hardware altimeter has the same functionality.

[RealKerbal3x]

Another useful mod from @Snark, making the useful features of an update just released even more useful?

Brilliant! I may, however, have a small sense of deja vu 

This is going straight in my GameData folder, fantastic work!

[kerbiloid]

Spoiler

All of us are tired of that uncomfy manual switching between AGL and ASL modes.
And at last someone has solved this problem!

 

[Superfluous J]

Insta-install.

That's a hard set of words to portmanteau.

Anyway, awesome and amazing. Awemazing.

You should get together with the guy who does Better Burn Time and see if you can add distance to target if you're in target mode.

Spoiler

 

[Xurkitree]

Thanks! You're fast and keep making just tiny QoL mods.

[Superfluous J]

Oh and maybe a "distance from center of planet" when you're in high orbit. Though that would require a hardcore rewiring of my neural pathways, it'd be more correcter to think that way that high up.

[Wallygator]

This is how the altimeter should have worked in the first place.

Thank you @Snark!

[FreeThinker]

@Snark  How is it possible you created this mod so fast? It appears you created after a few minutes after release. Do you have access to a time dilation device?

Edited April 11, 2019 by FreeThinker

[Snark]

1 hour ago, FreeThinker said:

How is it possible you created this mod so fast? It appears you created after a few minutes after release. Do you have access to a time dilation device?

Careful planning, fast typing, and clean living, my friend! 

Spoiler

Seriously, though, there's a "Pre-launch Pioneers" focus group that I'm fortunate enough to be a part of (it's listed on the KSP credits screen, if you look).  We're volunteers who get to play with pre-release versions of KSP for a little while before each launch, to help flush out bugs.  My personal shtick is that I like to test moddability, by seeing if I can build mods on top of new features they're adding.  Helps to spot "moddability holes" where there may be missing needed hooks.

So, this mod's an example of that.  Had it all queued up and ready to go, but couldn't release it publicly (or even talk about it) until 1.7 had shipped.  I mean, yeah, I'm good, but not that good. 

I hasten to add that it's a small, closed group, so to anyone reading this, please don't go pestering Squad asking to join-- if they ever need more recruits, they'll put out the word.  Also, don't bother asking me questions about what it's like, because it's covered by NDA and I can't talk about what goes on in there.  I've now already told you just about all I can say.

 

[BlueLineSwinger]

11 hours ago, 5thHorseman said:

Oh and maybe a "distance from center of planet" when you're in high orbit. Though that would require a hardcore rewiring of my neural pathways, it'd be more correcter to think that way that high up.

 

If you have Kerbal Engineer (or maybe MechJeb?) installed the semi-major and semi-minor axes provide this.

[Superfluous J]

3 minutes ago, BlueLineSwinger said:

 

If you have Kerbal Engineer (or maybe MechJeb?) installed the semi-major and semi-minor axes provide this.

The whole purpose of the display, and this mod making the display more automatic, is in my mind to replace KER.

[DStaal]

15 hours ago, 5thHorseman said:

The whole purpose of the display, and this mod making the display more automatic, is in my mind to replace KER.

I don't think any of this is intended to totally replace KER.  There's a lot of info that KER can show - Squad's just bringing in the most common.

 

BTW: I can now officially say that this mod came out three days before I was able to download the game update.   

[Beetlecat]

I didn't even need to check who the author was -- Immediate subscribe.

 

A shame squad didn't expose a keybind for the AGL/ASL toggle. Any chance of adding that? as a manual override? 

[Snark]

6 hours ago, Beetlecat said:

A shame squad didn't expose a keybind for the AGL/ASL toggle. Any chance of adding that? as a manual override?

Yeah, really.  It just cries out for one, IMO.  I mean, heck, I realize that there are so many key bindings out there now that it may be hard to find an unused one, but... fine!  Just give us a key binding slot, and have it unassigned by default, and then the user can just bind it to whatever they want.  (For example, I never ever use the toggle-mouselook feature of backslash, I could just repurpose it to that, or whatever.)

Unfortunately, key bindings are unmoddable.  That is, I believe it's not possible for a mod to add a new key-binding slot to the set of available key-binding options in the game. 

And no, I'm not gonna write code to try to manually build that in to the mod, mainly because I believe a thing should either be done right or not at all, and if I did it, it wouldn't be done "right".  It would be a kludgy hack, implemented in the wrong place, undoubtedly with edge conditions that would be irritating.  I'd just rather not go there at all.

What I would like to do is agitate to Squad "give us a key binding please".    If enough people ask for it long enough, maybe they would add it.  Especially given that it doesn't actually have to have a default assignment, which makes it a much easier lift from a game-design perspective:  just provide an empty slot, and the player can put whatever they like in it.

[DMagic]

3 hours ago, Snark said:

Unfortunately, key bindings are unmoddable.  That is, I believe it's not possible for a mod to add a new key-binding slot to the set of available key-binding options in the game.

Do you mean the list of keyboard shortcuts available in the settings menu? I guess it would be a lot of trouble to stuff another option in there (definitely possible, it's just a standard UI, but tedious), but there is no real need to do so. The stock list of keyboard shortcuts is a just a reference that various stock scripts use when listening for input. 

You can just load a KeyCode value from a config file and listen for that key press, you don't even need to parse the value from a config file if you are using the standard KSP ConfigNode, it supports KeyCode values. And a simple solution to having too many existing keyboard shortcuts is to require that the modifier key be held down, also.

private KeyCode shortcut = KeyCode.G;

private void Update()
{
	if (Input.GetKeyDown(shortcut) && GameSettings.MODIFIER_KEY.GetKey(false))
	{
		//Do something
	}
}

 

[HansonKerman]

Thanks! I needed this!

[ioresult]

Snark, thanks for the mod. A suggestion:

Can you add the option of having it switch to AGL immediately upon switch from High to Low Space in a vacuum? Also switch to AGL immediately upon entering atmosphere (or at a certain percent of sea level pressure, use case for me: at the moment wings can generate significant lift...)?

That's how I like it.

 

[Snark]

16 hours ago, DMagic said:

You can just load a KeyCode value from a config file and listen for that key press, you don't even need to parse the value from a config file if you are using the standard KSP ConfigNode, it supports KeyCode values. And a simple solution to having too many existing keyboard shortcuts is to require that the modifier key be held down, also.

Sure, I could certainly code it into the mod somewhere by manually trapping key events and such (for example, I recently did that when adding the new synchrony-tracker feature to BetterBurnTime).  And thank you for the programming tip-- you're always an excellent source for that sort of thing. 

However, my concern is that doing it that way would be (at least for me, and in the context of this mod) doing it in the wrong place.  There would be several things about such a solution that would grate on me:

• The need to do it in config rather than as a UI-dialog setting.  I already implemented this mod to have a UI settings tab, and it doesn't currently need any config at all, so that would be both breaking new ground and expecting users to tinker with two different places.
• The inconsistency with the UI experience for other KSP features.
• The need to manually go through all the edge cases that normal key-press processing involves (e.g. dealing with input locks and so forth).

And on top of all of that... this is a thing that I don't want to code.  I want KSP to fix it in stock.  For me, the auto-switching covers enough of the default behavior that I want, that the "leftover" cases where I find myself wanting to manually switch are fairly few and far between-- and since it's something that I only very occasionally need to do, the manual click-on-the-altimeter-button thing works fine for me.

3 hours ago, ioresult said:

Can you add the option of having it switch to AGL immediately upon switch from High to Low Space in a vacuum?

Hmmm... I mean, sure, it's possible to code something like that, but I'm having trouble coming up with a use case.  High/low space boundary is so high up, generally, that the surface topography is pretty much irrelevant at that altitude.  What's the use case?  For example, if I'm orbiting 250 km above Kerbin, why would the player care whether they happen to be over a mountain or a plain?  It seems to me that using AGL at such an altitude wouldn't really accomplish anything other than introduce a lot of random jitter to the numeric readout.

3 hours ago, ioresult said:

Also switch to AGL immediately upon entering atmosphere (or at a certain percent of sea level pressure, use case for me: at the moment wings can generate significant lift...)?

Hmm, now there's an interesting idea.  I think the way to implement such a thing would be to have a slider for the threshold, with units of "atmosphere per gravity", ranging from 0 to, say, 1.5 or so.  In other words, it would be dependent on gravity as well as pressure (after all, if you only have 50% gravity, you only need 50% as much atmosphere to stay aloft.)

Again, though, I'm trying to see exactly what the use case is.  If I'm in an airplane, either I'm close enough to the ground to worry about terrain collision, or I'm not.  If I am, then I absolutely want AGL so that I can see if I'm in imminent danger of crashing.  However, if I'm high enough that I don't need to worry about terrain collision-- say, cruising along on Kerbin at 9km up-- why would the player care about the height of the terrain beneath?

In fact, if I'm flying a plane around up there, I'm actually more interested in ASL height than AGL... because ASL is what determines atmospheric pressure, and therefore things like wing lift, airbreathing engine ceiling, etc.  What's the rationale (i.e. the usefulness) of having AGL set when way up in the sky?

[Kerbart]

To prevent flipping back & forth when flying right on the threshold of "low," would it be an idea to build in some hysteresis? EG low->high at 2000m but high->low at 1800m?

Of course, nothing is impossible for the person who doesn't have to do it themselves, so it's easy for me to suggest it.

[DStaal]

5 minutes ago, Kerbart said:

To prevent flipping back & forth when flying right on the threshold of "low," would it be an idea to build in some hysteresis? EG low->high at 2000m but high->low at 1800m?

Of course, nothing is impossible for the person who doesn't have to do it themselves, so it's easy for me to suggest it.

The current system basically has that, from what I understand: The trigger for sea-level to surface is largely vertical speed-dependent, so if you're staying at a relatively level altitude you won't trigger it.

[Snark]

1 hour ago, Kerbart said:

To prevent flipping back & forth when flying right on the threshold of "low," would it be an idea to build in some hysteresis? EG low->high at 2000m but high->low at 1800m?

Well, I did put a temporal hysteresis feature in-- the mod keeps track of "when was the last time the altimeter changed state, for any reason" (whether automatic or manually by the player), and won't change the state itself unless at least one second has passed.  This helps prevent spastic thrashing if you're hovering right on the boundary.

I considered adding an explicit hysteresis effect by altitude, as you describe, but decided not to-- aside from the fact that it would add somewhat more complexity to the code, I also spent quite a bit of time play-testing this before releasing it, and flip-back-and-forth-at-the-boundary was simply not something that came up to any significant extent in gameplay, at least not for me.

[ioresult]

20 hours ago, Snark said:

Hmmm... I mean, sure, it's possible to code something like that, but I'm having trouble coming up with a use case.  High/low space boundary is so high up, generally, that the surface topography is pretty much irrelevant at that altitude.  What's the use case?  For example, if I'm orbiting 250 km above Kerbin, why would the player care whether they happen to be over a mountain or a plain?  It seems to me that using AGL at such an altitude wouldn't really accomplish anything other than introduce a lot of random jitter to the numeric readout.

Hmm, now there's an interesting idea.  I think the way to implement such a thing would be to have a slider for the threshold, with units of "atmosphere per gravity", ranging from 0 to, say, 1.5 or so.  In other words, it would be dependent on gravity as well as pressure (after all, if you only have 50% gravity, you only need 50% as much atmosphere to stay aloft.)

Again, though, I'm trying to see exactly what the use case is.  If I'm in an airplane, either I'm close enough to the ground to worry about terrain collision, or I'm not.  If I am, then I absolutely want AGL so that I can see if I'm in imminent danger of crashing.  However, if I'm high enough that I don't need to worry about terrain collision-- say, cruising along on Kerbin at 9km up-- why would the player care about the height of the terrain beneath?

In fact, if I'm flying a plane around up there, I'm actually more interested in ASL height than AGL... because ASL is what determines atmospheric pressure, and therefore things like wing lift, airbreathing engine ceiling, etc.  What's the rationale (i.e. the usefulness) of having AGL set when way up in the sky?

There are airless moons with huge mountains. Especially with planet packs like OPM (Priax comes to mind). I've crashed more than once especially in map mode in low orbits. I've even recently crashed on Earth's Moon because I thought I was 11km AGL but I was in ASL and hit a 11.5km mountain. Switching high up makes the altitude fluctuate, but I really just look at the big numbers. So no surprises 10 seconds before impact when it's too late to burn radially.

Same reason in atmosphere if I'm flying above high mountains. OPM's Tekto is a good example. Lift comes very high up but low gravity also means high plateaus and mountains. I like to see AGL when approaching KSC on Kerbin over the mountains there. Also when trying to approach the two mountain monoliths using a VTOL on Kerbin.

I like doing weird stuff, that's all. I can continue using Kerbal Engineer it's no trouble.