.. SPDX-FileCopyrightText: 2026 James Turner .. SPDX-License-Identifier: GPL-2.0-or-later Actions ####### Actions are an abstraction for user-facing behaviours, that can be defined centrally, modified by an aircraft or addon, and attached in a robust way to an input source such as the keyboard, GUI or a joystick. Actions formalize some long-standing concepts around commands, standard properties for particular features, and conventions on closely related commands, into a set of explicit data that can be queried at runtime. The key new feature this will allow is runtime GUIs which edit joystick and keyboard bindings. Internally, defining a central abstraction point for these behaviours, avoids duplication between aircraft animations, joystick Common concepts ---------------- Actions have a unique ID, and a human-readable (translateable) name and description. They define a type (such as repeating, momentary or toggle), and can be enabled or disabled. Depending on the action type, there may be a set of related additional actions defined by **proxies**, which are implemented in terms of the basic action. For example, a toggle action might have proxy actions to force its value to true or false. Overriding ---------- By design, actions can be extended by aircraft. This allows a common action to existing in FlightGear, and be bound to inputs, but for the current aircraft to specify the behaviour: for example the number of values in an enumerated action, or the enable / disable conditions for a command to be permitted. In addition, any command can have additional bindings attached as pre- or post- steps to the main bindings. This allows a robust way for add-ons or aircraft to take action when an action is invoked, such as pausing, changing the view, or similar. Types of action --------------- * momentary actions are invoked when triggrered, and fire a 'release' binding when released. They have an optional ``delay`` before triggering. * toggle actions model a boolean state, which can be defined in various modes such as on/off, open/closed, or up/down. Triggering the main action toggles the value, and proxies exist to set an explicit state. * enumerated actions are similar to toggle, but have multiple states, with the ability to cycle through them, or set a specific state. Wrapping or non-wrapping of the states is configurable. (By design, a toggle action can be overridden to become enumerated, so that it can work as eg a tri-state switch) * quantized actions define states but associate each one with a numeric boundary value. This allows the action to control a numerical property such as ``flap-position``, with aircraft-specific detent values defined.