Files
aevolution/include/evo/client/bindings.hpp
T
dingoandClaude Opus 5.5 5cf8709912 Add M9.8d rebindable engineering controls
SDL-free action/HID-key bindings with conflict validation, a staging editor and
a versioned all-or-nothing controls file (ADR-0085). The adapter maps keys
through the bindings, releases and drains on rebinding, and captures the chosen
key ahead of the toolkit and world. The client adds a Controls panel, key hints,
startup loading with a bounded rejection notice, and --controls/--show-controls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 11:30:17 -04:00

113 lines
4.6 KiB
C++

#pragma once
// M9.8d rebindable engineering controls (ADR-0085). Actions are separate from
// physical keys; keys are USB HID keyboard usages (page 7), the numbering SDL
// scancodes also use, so this contract stays SDL-free. Mouse selection/zoom are not
// rebindable. The file stores key names only: never credentials, paths or grants.
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <filesystem>
#include <optional>
#include <string>
#include <string_view>
namespace evo::client {
enum class Action : std::uint8_t {
move_left,
move_right,
move_up,
move_down,
pan_left,
pan_right,
pan_up,
pan_down,
toggle_capture
};
inline constexpr std::size_t action_count = 9;
using KeyCode = std::uint16_t; // HID usage; 0 means unbound.
inline constexpr KeyCode no_key = 0;
inline constexpr KeyCode escape_key = 41; // Reserved: cancels binding capture.
struct KeySlot {
KeyCode primary{no_key}, secondary{no_key};
friend bool operator==(const KeySlot&, const KeySlot&) = default;
};
using KeySlots = std::array<KeySlot, action_count>;
enum class BindingError : std::uint8_t {
unbindable_key, // Not in the supported key table, or reserved (Escape).
conflict, // One physical key bound to two actions or both slots.
missing_primary, // Every action needs a primary key.
malformed, // File syntax, unknown action/key name, duplicate action line.
unsupported_version,
too_large,
unreadable,
write_failed
};
// Why a set of bindings was refused, for fixed-wording display.
struct BindingProblem {
BindingError error{BindingError::malformed};
std::optional<Action> action, other;
KeyCode key{no_key};
};
[[nodiscard]] std::string_view action_id(Action action) noexcept; // "move_up" (file token)
[[nodiscard]] std::string_view action_name(Action action) noexcept; // "Move up" (label)
[[nodiscard]] std::optional<Action> action_from_id(std::string_view id) noexcept;
// Display/file name of a supported key ("W", "Up", "F5"); empty when unsupported.
[[nodiscard]] std::string_view key_name(KeyCode key) noexcept;
[[nodiscard]] std::optional<KeyCode> key_from_name(std::string_view name) noexcept;
[[nodiscard]] bool bindable(KeyCode key) noexcept;
[[nodiscard]] std::string describe(const BindingProblem& problem);
// An always-valid binding set: every action has a bindable primary, at most one
// bindable secondary, and no key appears twice.
class Bindings {
public:
[[nodiscard]] static Bindings defaults() noexcept;
[[nodiscard]] static std::expected<Bindings, BindingProblem> make(const KeySlots& slots);
[[nodiscard]] std::optional<Action> action(KeyCode key) const noexcept;
[[nodiscard]] const KeySlot& slot(Action action) const noexcept {
return slots_[static_cast<std::size_t>(action)];
}
[[nodiscard]] const KeySlots& slots() const noexcept {
return slots_;
}
friend bool operator==(const Bindings&, const Bindings&) = default;
private:
explicit Bindings(const KeySlots& slots) noexcept : slots_{slots} {}
KeySlots slots_;
};
// Staged edits for a controls panel. Nothing applies until apply() validates the
// whole set; an assignment that would conflict is refused and leaves the draft as is.
class BindingEditor {
public:
explicit BindingEditor(const Bindings& current) noexcept : draft_{current.slots()} {}
[[nodiscard]] std::expected<void, BindingProblem> assign(Action action, bool secondary,
KeyCode key);
void clear_secondary(Action action) noexcept;
void reset_defaults() noexcept;
[[nodiscard]] const KeySlots& draft() const noexcept {
return draft_;
}
[[nodiscard]] std::expected<Bindings, BindingProblem> apply() const;
private:
KeySlots draft_;
};
// Versioned text: "evo-controls 1", then one "action key [key]" line per action.
// All actions must appear exactly once; '#' starts a comment. Rejected as a whole
// on any error (never partially applied).
inline constexpr std::size_t max_bindings_bytes = 4096;
[[nodiscard]] std::string serialize(const Bindings& bindings);
[[nodiscard]] std::expected<Bindings, BindingProblem> parse_bindings(std::string_view text);
[[nodiscard]] std::expected<Bindings, BindingProblem>
load_bindings(const std::filesystem::path& file);
// Writes a sibling temporary file, then replaces `file`.
[[nodiscard]] std::expected<void, BindingProblem> save_bindings(const Bindings& bindings,
const std::filesystem::path& file);
} // namespace evo::client