Learn how Prepar3D SimVars and events expose aircraft state, send commands through SimConnect, and avoid toggle, unit and write-access errors.
In Prepar3D, SimVars are named simulator values that describe aircraft, environment and system state, while events are commands that ask the simulator or an aircraft system to perform an action. Add-ons usually read SimVars for feedback, write only those marked settable, and transmit events for controls such as gear, lights or autopilot modes.
What is the difference between a SimVar and an event?
A SimVar reports a value; an event represents an action or notification. For example, an add-on might read AIRSPEED INDICATED to display speed, then transmit GEAR_TOGGLE when the pilot presses a hardware button.
| Characteristic | SimVar | Event |
|---|---|---|
| Purpose | Reports simulator or aircraft state | Requests an action or announces an occurrence |
| Examples | PLANE ALTITUDE, LIGHT LANDING, GENERAL ENG RPM:1 | GEAR_TOGGLE, LANDING_LIGHTS_TOGGLE, AP_MASTER |
| Persistence | Has a value that can be sampled repeatedly | Is normally a momentary message |
| Writing | Possible only when the variable is settable | Sent through an event interface, sometimes with a parameter |
| Confirmation | The value itself shows the resulting state | Read the relevant SimVar after sending the event |
This distinction matters with toggle commands. Sending GEAR_TOGGLE does not tell an add-on whether the gear is now up or down, and aircraft logic may reject the command. Read the gear-position or handle SimVar to confirm what actually happened.
Which kinds of Prepar3D events are there?
Prepar3D uses events for controls, simulator notifications and communication between add-ons.
- Simulation or control events request actions such as moving controls, changing lights or selecting an autopilot mode. Some accept an event-specific numeric parameter.
- System events notify a SimConnect client about simulator conditions such as a flight starting, pausing or producing a timed update.
- Client and custom events give developers their own identifiers or named communication channels. Their capabilities depend on the Prepar3D and SDK version.
An event received by an add-on is not necessarily proof that the aircraft completed the action. Hydraulic, electrical or custom aircraft logic can prevent the requested change.
How are SimVars and events used in Prepar3D add-ons?
Most external Prepar3D add-ons use SimConnect to request SimVars and transmit events, while panel gauges can access the same concepts through gauge expressions or native gauge APIs.
Which interface should I use?
Use SimConnect for an external application, networked utility or hardware interface; use the gauge APIs when the code runs inside a Prepar3D panel.
| Add-on type | Typical method |
|---|---|
| External program or cockpit hardware | SimConnect data definitions, requests and client events |
| XML gauge | A: expressions for SimVars and K: expressions for key events |
| Compiled gauge | The version-matched gauge SDK or SimConnect API |
In an XML gauge, (A:AIRSPEED INDICATED, knots) reads a SimVar, while (>K:GEAR_TOGGLE) sends an event. An L: variable is different: it is a gauge-local or add-on-defined variable, not a standard aircraft SimVar.
- Install the matching SDK. Use documentation and headers intended for the installed major Prepar3D version. Our overview of the tools required for flight-simulator add-on development explains where the SDK fits into the wider workflow.
- Choose the exact SimVar and unit. Check whether it is readable, settable, indexed or restricted to particular simulation objects. Engine variables commonly need an index such as
:1. - Define and request the data. A SimConnect client normally adds variables to a data definition, requests that definition for an object and processes the returned messages. See our practical SimConnect data and event workflow for the connection and message-processing steps.
- Map and transmit control events. A C or C++ client typically maps its own event identifier to the simulator's documented event name, then transmits that client event. Supply a parameter only in the format required by that event.
- Read the result back. Request the corresponding SimVar instead of assuming the event succeeded. This also keeps hardware annunciators and external displays synchronised with the aircraft.
- Use a sensible update rate. Fast-changing flight data may need frequent requests, but switches and warning states can usually be requested less often or only when changed. Unnecessary per-frame traffic wastes processing time.
Can every SimVar be changed?
No. Many Prepar3D SimVars are read-only, and writable values can still be overridden by the aircraft's systems on the next update.
If the SDK does not mark a SimVar as settable, use the appropriate control event where one exists. Complex add-on aircraft may maintain their own systems through local variables, custom events or a dedicated interface, so a standard event that works in a default aircraft may have no effect there.
Can an event be read back like a SimVar?
No; a control event is a transient message rather than stored aircraft state. SimConnect clients can subscribe to certain event notifications, but receiving one only shows that the event was delivered, not that the requested operation succeeded.
For reliable logic, treat the event as the command and a SimVar as the feedback. Prefer explicit set events over toggle events when the SDK supplies both, particularly for hardware switches whose physical position must remain synchronised with the simulator.
Why do SimVars or events fail to work?
Most failures come from an incorrect unit, missing index, read-only variable, unsuitable toggle command or mismatched SDK documentation.
- No SimConnect data arrives: confirm that the client is processing its dispatch messages, the request and definition identifiers match, and the requested simulation object exists.
- The value is zero or belongs to the wrong engine: check the SimVar's required index, unit and data type. Do not assume an unindexed engine variable represents all engines.
- A written value immediately changes back: the aircraft's systems are probably recalculating it. Use the intended event or the aircraft's supported custom interface.
- A switch reverses unpredictably: a toggle event has been sent without checking the starting state. Read the state first or use separate set, on and off events where available.
- The event works in a default aircraft but not an add-on: the add-on may use custom logic rather than the standard simulator control.
- An event name is rejected: verify it against the SDK installed for that Prepar3D version rather than copying an identifier from another simulator or release.
Do SimVar and event definitions change between versions?
Yes. Core names tend to remain familiar, but event availability, custom-event support and SDK behaviour can change between Prepar3D releases.
Compile and test against the SDK matching the target simulator, and do not assume that a custom event supported by one release exists in another. The summary of Prepar3D v6 SDK and custom-event changes illustrates why version checks matter for add-on developers.