Hello, I wrote a script to “scrape” all the Event IDs from the SDK
Documentation HTML pages and stick them into a database. This same script can
parse “gauges.h” header and import all the ‘KEY_’ macro names. After that it
is simple to run queries to see what is missing/doesn’t match. (I do plan on
publishing the tool/data in case anyone is interested.) This is a report run
against the latest “release” published docs
(https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Event_IDs.htm)
and SDK v0.19.3.0. (My scraper script is likely not perfect and may possibly
have missed some events, but I verified a lot of these manually and it all
seems correct.) In gauges.h but not documented: In documentation but not in
gauges.h: Also run against the “flighting” version of the docs
(https://docs.flightsimulator.com/flighting/html/Programming_Tools/Event_IDs/Event_IDs.htm),
but I do not have the equivalent version of gauges.h (presuming it has/will
change). In gauges.h but not documented: In documentation but not in gauges.h:
Regards, -Max
Hello! Thank you for this feedback… I’ll go through the information you’ve
provided and check it against our own tools and see what discrepancies I can
find. At a glance I can say that many of the things you’ve listed are
already in the docs (for example ZOOM_1X, ROTOR_BRAKE, or all the BREAKER
events). Also, many have been added to the documentation for SU11, but are not
available in flighting documentation yet (for example: THROTTLE X _INCR, or
MIXTURE X _SET). However, you have found a few others that I was unaware of
- eg: MAGNETO_BOTH - which is very helpful and I’ll make sure to get these
discrepancies added if appropriate. I also noticed one or two that ARE
documented, but have typos, which is why your scrape didn’t find them! This
will be fixed too! Thanks very much for taking the time to do this and help us
improve the docs.
Just to update this… having gone through the complete list, about 95% of
them HAVE been documented. The confusion here comes from the fact that in the
code, some keys use a name that is NOT the same as the “public facing” key
event name. For example: AUTOPILOT_AIRSPEED_HOLD_CURRENT This is actually
assigned to the key event: AP_PANEL_SPEED_HOLD_TOGGLE Or KNEEBOARD, which is
assigned to: KNEEBOARD_VIEW And so on… The few that are missing from the
docs will be added for SU11, assuming they are still valid.
Hi @Nocturne , Thank you for your quick follow-up
and responses. Sorry about the “noise” with the first version where it clearly
didn’t scrape some events properly. The BREAKER events were all missed due to
unique formatting in that HTML table. Most/all the others were missed because
I originally used the tag link id elements for the names, but those don’t
always match the actual event name. This has all been fixed, along with some
other things, thanks again to you going through that first batch. The utility
and data is now available at <https://github.com/mpaperno/MSFS-
Tools/tree/main/MSFS-DocImport> I did download SDK v0.20.2.0 so those KEY_
macros could be compared to flighting version docs (though if those haven’t
been updated yet then of course this is of limited use.) FWIW, here are the
latest comparison reports for release and flighting versions. Also, the script
can now produce these on demand. A couple minor issues I ran into (not
directly related to this topic):
- The title of the https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Aircraft_Fuel_System_Events.htm page is incorrect (“Event IDs” vs. “Aircraft Fuel System Events”), also in flighting version.
- The ZOOM_1X event is well hidden in Miscellaneous Events → Miscellaneous category (took me forever to find it)… perhaps it could be moved to View/Camera Events → Zoom and Pan along with the rest of the “ZOOM_” events.
Regarding your last post…
The confusion here comes from the fact that in the code, some keys use a
name that is NOT the same as the “public facing” key event name.
Do I understand correctly that effectively there is some sort of internal
lookup/translation employed between “public facing” event names and the actual
KEY_* macro name/value? If so…
- Are the “public” names used only in SimConnect, or does, say, execute_calculator_code() also understand/use these public aliases?
- Is there some reference which can map the “public” names to actual KEY_* macro names (or the actual IDs)? Or IOW, how could one programmatically determine which KEY_* macro to use for trigger_key_event_EX1 based on the public event documentation? (Preferably w/out resorting to fuzzy language analysis techniques
)
Just as some background why I’m doing all this (besides improving the docs, of
course 
is that I’d like to present the users of my
program with a UI where
they can drill down to select Key Events (and SimVars) from a list of
known/published/documented items (whether they actually work or not is a
different matter of course). The events may be triggered by either SimConnect
or a custom WASM module (if they have it installed). For all this to work as
intended, I need to actually verify what I’m presenting to the user is correct
(as much as practically possible, anyway). Thank you again, and I hope this
exercise can be mutually beneficial to all. Best, -Max
Hello again! To answer your two questions: 1) “Are the “public” names used
only in SimConnect, or does, say, execute_calculator_code() also
understand/use these public aliases?” - The Public names are indeed used in
the execute_calculator_code() function (You would use (>K:MAGNETO1_LEFT)
rather than (>K:KEY_MAGNETO1_LEFT), for example) as well as in the checklists.
2) "Is there some reference which can map the “public” names to actual KEY*
macro names (or the actual IDs)?"_ - Not currently. We’ll discuss this
internally and see if it’s something that we can/want to provide. All the
best!
Hi @Nocturne, thanks for getting back to me on
this.
(You would use (>K:MAGNETO1_LEFT) rather than (>K:KEY_MAGNETO1_LEFT), for
example)
Well yes, w/out the “KEY_” part, but I was asking about cases like the example
you provided… eg. AUTOPILOT_AIRSPEED_HOLD_CURRENT →
AP_PANEL_SPEED_HOLD_TOGGLE. (Especially ironic since there a bunch of KEY_AP_*
macros also, but a few which do not follow the convention.)
Not currently. We’ll discuss this internally and see if it’s something that
we can/want to provide.
So, if one is using the Gauge API trigger_key_event[_EX1]() we have to
guess/deduce the correct KEY_ macro which equates to the documented Event ID?
Or am I missing something? Perhaps the public names could at least be added to
KEY_ macros as aliases for the actual macro name. There’s at least one alias
in there already. The whole “discovery” part of the documentation vs. reality
gets kinda old, TBH. Thanks, -Max
Hello! On re-reading your comments and investigating, you are indeed correct
that this is an omission and the documentation hasn’t taken into account the
use of macros in the trigger_key_event_EX1() function. We’ll rectify this in
some way as soon as possible (either through the docs or through a file
included with the SDK)… Sorry about that!
Thanks, good docs are much appreciated! And saves us devs and users a lot of
time, even though it does take up yours (Asobo’s) of course. Along those
lines, I would really urge you folks to play with a database of the published
events/vars/units… either using my utility or whatever y’all have on your
side. One can really reveal a lot with some simple sorting and filtering. For
example I just spent a bunch of hours fixing up (“normalizing”) all the sim
var Units since they’re all over the place with spelling and whatnot… which
is fine for me and my software users, but a waste overall because the next
person who needs that data will have to go through it all again. (I could post
a longish list of errata in the Units, but then you’ll really hate me… LOL)
Cheers! -Max
Please, feel free to share anything you have with us! It’s always GREATLY
appreciated when a user takes the time to help us out, which in turn helps out
the rest of the community!
Here is my current (as of SDK v 0.22.3.0) list of published Key Event aliases to actual KEY macros from gauages.h. This is derived through “guesswork” and manually maintained by me on every SDK update.
// Aliases for published Event IDs which do not match KEY IDs
{ "ADF1_WHOLE_DEC", KEY_ADF_WHOLE_DEC },
{ "ADF1_WHOLE_INC", KEY_ADF_WHOLE_INC },
{ "ALTITUDE_SLOT_INDEX_SET", KEY_AP_ALTITUDE_SLOT_INDEX_SET },
{ "ANTIDETONATION_TANK_VALVE_TOGGLE", KEY_TOGGLE_ANTIDETONATION_TANK_VALVE },
{ "AP_HEADING_BUG_SET_EX1", KEY_HEADING_BUG_SET_EX1 },
{ "AP_PANEL_MACH_HOLD_TOGGLE", KEY_AUTOPILOT_MACH_HOLD_CURRENT },
{ "AP_PANEL_SPEED_HOLD_TOGGLE", KEY_AUTOPILOT_AIRSPEED_HOLD_CURRENT },
{ "ATTITUDE_BARS_POSITION_DOWN", KEY_ATTITUDE_BARS_POSITION_DEC },
{ "ATTITUDE_BARS_POSITION_UP", KEY_ATTITUDE_BARS_POSITION_INC },
{ "ATTITUDE_CAGE_BUTTON", KEY_TOGGLE_ATTITUDE_CAGE },
{ "AUTORUDDER_TOGGLE", KEY_AUTOCOORD_TOGGLE },
{ "BACK_TO_FLY", KEY_NULL }, // Not a real Event ??
{ "COM_STBY_RADIO_SWAP", KEY_COM_STBY_RADIO_SWITCH_TO },
{ "DECREASE_AUTOBRAKE_CONTROL", KEY_DEC_AUTOBRAKE_CONTROL },
{ "DECREASE_DECISION_ALTITUDE_MSL", KEY_DECISION_ALTITUDE_MSL_DEC },
{ "DECREASE_DECISION_HEIGHT", KEY_DECISION_HEIGHT_DEC },
{ "DECREASE_HELO_GOV_BEEP", KEY_HELI_BEEP_DECREASE },
{ "FLIGHT_LEVEL_CHANGE", KEY_AP_FLIGHT_LEVEL_CHANGE },
{ "FLIGHT_LEVEL_CHANGE_OFF", KEY_AP_FLIGHT_LEVEL_CHANGE_OFF },
{ "FLIGHT_LEVEL_CHANGE_ON", KEY_AP_FLIGHT_LEVEL_CHANGE_ON },
{ "HEADING_SLOT_INDEX_SET", KEY_AP_HEADING_SLOT_INDEX_SET },
{ "INCREASE_AUTOBRAKE_CONTROL", KEY_INC_AUTOBRAKE_CONTROL },
{ "INCREASE_DECISION_ALTITUDE_MSL", KEY_DECISION_ALTITUDE_MSL_INC },
{ "INCREASE_DECISION_HEIGHT", KEY_DECISION_HEIGHT_INC },
{ "INCREASE_HELO_GOV_BEEP", KEY_HELI_BEEP_INCREASE },
{ "KNEEBOARD_VIEW", KEY_KNEEBOARD },
{ "MP_ACTIVATE_CHAT", KEY_MULTIPLAYER_ACTIVATE_CHAT },
{ "MP_BROADCAST_VOICE_CAPTURE_START", KEY_MULTIPLAYER_BROADCAST_VOICE_CAPTURE_START },
{ "MP_BROADCAST_VOICE_CAPTURE_STOP", KEY_MULTIPLAYER_BROADCAST_VOICE_CAPTURE_STOP },
{ "MP_CHAT", KEY_MULTIPLAYER_CHAT },
{ "MP_PAUSE_SESSION", KEY_MULTIPLAYER_PAUSE_SESSION },
{ "MP_PLAYER_CYCLE", KEY_MULTIPLAYER_PLAYER_CYCLE },
{ "MP_PLAYER_FOLLOW", KEY_MULTIPLAYER_PLAYER_FOLLOW },
{ "MP_TRANSFER_CONTROL", KEY_MULTIPLAYER_TRANSFER_CONTROL },
{ "MP_VOICE_CAPTURE_START", KEY_MULTIPLAYER_VOICE_CAPTURE_START },
{ "MP_VOICE_CAPTURE_STOP", KEY_MULTIPLAYER_VOICE_CAPTURE_STOP },
{ "NITROUS_TANK_VALVE_TOGGLE", KEY_TOGGLE_NITROUS_TANK_VALVE } ,
{ "PRESSURIZATION_PRESSURE_DUMP_SWTICH", KEY_PRESSURIZATION_PRESSURE_DUMP_SWITCH },
{ "RELOAD_USER_AIRCRAFT", KEY_CONTROL_RELOAD_USER_AIRCRAFT },
{ "REQUEST_FUEL_KEY", KEY_REQUEST_FUEL },
{ "ROTOR_AXIS_TAIL_ROTOR_SET", KEY_AXIS_TAIL_ROTOR_SET },
{ "ROTOR_BRAKE_SET", KEY_AXIS_ROTOR_BRAKE_SET },
{ "RPM_SLOT_INDEX_SET", KEY_AP_RPM_SLOT_INDEX_SET },
{ "SET_DECISION_ALTITUDE_MSL", KEY_DECISION_ALTITUDE_MSL_SET },
{ "SET_HELO_GOV_BEEP", KEY_HELI_BEEP_SET },
{ "SET_REVERSE_THRUST_OFF", KEY_SET_THROTTLE_REVERSE_THRUST_OFF },
{ "SET_REVERSE_THRUST_ON", KEY_SET_THROTTLE_REVERSE_THRUST_ON },
{ "SPEED_SLOT_INDEX_SET", KEY_AP_SPEED_SLOT_INDEX_SET },
{ "TOGGLE_AUTOFEATHER_ARM", KEY_TOGGLE_ARM_AUTOFEATHER },
{ "TOGGLE_DME", KEY_DME_TOGGLE } ,
{ "TOGGLE_PROPELLER_SYNC", KEY_TOGGLE_PROP_SYNC },
{ "TOGGLE_PUSHBACK", KEY_PUSHBACK_SET }, // ?
{ "TOW_PLANE_REQUEST", KEY_REQUEST_TOW_PLANE },
{ "TRUE_AIRSPEED_CAL_DEC", KEY_TRUE_AIRSPEED_CALIBRATE_DEC },
{ "TRUE_AIRSPEED_CAL_INC", KEY_TRUE_AIRSPEED_CALIBRATE_INC },
{ "VARIOMETER_SOUND_TOGGLE", KEY_TOGGLE_VARIOMETER_SWITCH }, // ?
{ "VERTICAL_SPEED_SET", KEY_AP_VS_SET },
{ "VIEW_AXIS_INDICATOR_CYCLE", KEY_AXIS_INDICATOR_CYCLE },
{ "VIEW_CAMERA_SELECT_START", KEY_VIEW_CAMERA_SELECT_STARTING },
{ "VIEW_WINDOW_TITLES_TOGGLE", KEY_WINDOW_TITLES_TOGGLE },
{ "VS_SLOT_INDEX_SET", KEY_AP_VS_SLOT_INDEX_SET },
(What the heck is “BACK_TO_FLY”? Not an actual key event?
-Max
Going back in time and space, the KEY_* macro names used to be listed along with the “SimConnect name” in references. I can’t find where exactly the old official docs used to be published, but there’s plenty of evidence to the fact… For example the P3D references still use that format (is it tacky to post a link to them here?), as does/did MS ESP reference: https://learn.microsoft.com/en-us/previous-versions/microsoft-esp/cc526980(v=msdn.10). I also found user posts on various forums which copy/paste/screenshot the old format with they KEY IDs next to the names.