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>
This commit is contained in:
dingo
2026-10-02 11:30:17 -04:00
co-authored by Claude Opus 5.5
parent bb8c2fc359
commit 5cf8709912
23 changed files with 1292 additions and 45 deletions
+18 -1
View File
@@ -1,10 +1,13 @@
#pragma once
#include "evo/client/bindings.hpp"
#include "evo/client/input.hpp"
#include "evo/render/frame.hpp"
#include <cstdint>
#include <expected>
#include <filesystem>
#include <functional>
#include <memory>
#include <optional>
#include <string>
namespace evo::client {
@@ -48,8 +51,22 @@ class Application {
[[nodiscard]] WindowState state() const noexcept;
[[nodiscard]] std::expected<void, Error> poll_events();
[[nodiscard]] std::expected<Step, Error> present(const render::Frame& frame);
// External modal/widget capture cannot be disabled by the legacy Tab toggle.
// External modal/widget capture cannot be disabled by the toggle-capture action.
void set_ui_capture(bool captured) noexcept;
// Replaces the key-to-action map (ADR-0085). Every held world action is released;
// input queued before the change is drained, then fresh presses are required.
void set_bindings(const Bindings& bindings) noexcept;
[[nodiscard]] const Bindings& bindings() const noexcept;
// Binding capture: the next non-repeat key press (any key, including Escape) is
// consumed for take_captured_key() and reaches neither the toolkit nor the world.
// World input stays captured while armed; focus loss cancels it without a key.
void begin_key_capture() noexcept;
void cancel_key_capture() noexcept;
[[nodiscard]] bool key_capture_active() const noexcept;
[[nodiscard]] std::optional<KeyCode> take_captured_key() noexcept;
// Per-user settings directory, created when needed; nullopt when unavailable.
// Callable without an open Application.
[[nodiscard]] static std::optional<std::filesystem::path> settings_directory();
[[nodiscard]] bool ui_captured() const noexcept;
void set_overlay(Overlay overlay);
// The toolkit held the pointer during the last poll (no world click, pan or zoom).
+112
View File
@@ -0,0 +1,112 @@
#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