feat(input): add configurable action contexts and rebinding

Author: OmarAglan

AGENTS.md

@@ -3,13 +3,13 @@
 ## Scope
 
 - `Engine/` builds the C++17 `PyramidEngine` library.
-- Active modules are Core, Graphics, Math, Platform, and Utils.
+- Active modules are Core, Graphics, Input, Math, Platform, and Utils.
 - `Examples/BasicGame` and `Examples/BasicRendering` are the graphical references.
-- `Tests/PublicApiLinkage.cpp` protects selected public symbols. Focused tests cover platform input state, resize behavior, camera/frustum logic, framebuffers, texture loading, spatial updates/queries/configuration/compaction, render bounds, resources/caches, registry handles/manifests, the authoritative entity scene, and scene serialization. `Tests/EntitySceneTests.cpp` protects stable entity IDs, cycle-safe hierarchy transforms, inherited visibility, component attachment, generated renderer/light proxies, and recursive destruction. `Tests/SceneSerializationTests.cpp` protects deterministic version-2 entity/component round trips, exact manifest references, hierarchy validation, and missing/stale resource diagnostics.
+- `Tests/PublicApiLinkage.cpp` protects selected public symbols. Focused tests cover platform input state, generic action mapping, resize behavior, camera/frustum logic, framebuffers, texture loading, spatial updates/queries/configuration/compaction, render bounds, resources/caches, registry handles/manifests, the authoritative entity scene, and scene serialization. `Tests/EntitySceneTests.cpp` protects stable entity IDs, cycle-safe hierarchy transforms, inherited visibility, component attachment, generated renderer/light proxies, and recursive destruction. `Tests/SceneSerializationTests.cpp` protects deterministic version-2 entity/component round trips, exact manifest references, hierarchy validation, and missing/stale resource diagnostics.
 - `Tests/Consumer` validates the installed CMake package.
 - `vendor/glad` is a bundled public dependency. libjpeg-turbo is an external open-source dependency resolved through CMake `FindJPEG`.
 - The supported Windows toolchain is MSYS2 UCRT64 with MinGW-w64 GCC; Clang is also validated. Visual Studio is not required.
-- Real Win32 keyboard/mouse polling is implemented. Action mapping, audio, physics, editor, scripting, DirectX, Vulkan, Linux, and macOS are not yet supported. The first product target is a Windows RTS vertical slice; Linux follows it, a full editor is planned, and Baa is the long-term scripting and rewrite target.
+- Real Win32 keyboard/mouse polling and engine-generic action mapping are implemented. Controllers, audio, physics, editor, scripting, DirectX, Vulkan, Linux, and macOS are not yet supported. The first product target is a Windows RTS vertical slice; Linux follows it, a full editor is planned, and Baa is the long-term scripting and rewrite target.
 
 ## Build and test
 
@@ -32,7 +32,7 @@ ctest --preset test-gcc-release
 
 - C++17, four spaces, braces on new lines.
 - Types/public methods use `PascalCase`; locals/parameters use `camelCase`; fields use `m_`.
-- Prefer RAII, explicit ownership, and `PYRAMID_LOG_*` diagnostics. Geometry passed to scenes must use `Mesh`; do not reintroduce raw vertex-array fields on `RenderObject`. Shared reusable geometry should be acquired through the game-owned `ResourceRegistry::Meshes()` cache; do not create parallel uploads for byte-identical mesh specifications. Shared shader programs should be acquired through `ResourceRegistry::Shaders()`; do not mutate cached `ShaderProgram` instances directly or compile identical stage source repeatedly. Shared sampled textures should use `ResourceRegistry::Textures()`; cached `TextureResource` instances are immutable, color space is part of identity, and file changes must be published through transactional reload. Scene renderables should acquire immutable `Material` resources through `ResourceRegistry::Materials()` rather than ad-hoc shader/texture fields; per-draw matrices belong in command-buffer uniforms, not material identity. Platform input must remain backend-neutral at the public API boundary: native messages feed `InputState`, games poll it through `Game::GetInput()`, and focus loss must release held controls. Long-lived scene and serialized references should use typed registry handles. Handles must stay non-owning, every alias bind/remap/removal must advance its generation, direct cache mutation must invalidate existing handles, and stale handles must resolve to null rather than a replacement resource.
+- Prefer RAII, explicit ownership, and `PYRAMID_LOG_*` diagnostics. Geometry passed to scenes must use `Mesh`; do not reintroduce raw vertex-array fields on `RenderObject`. Shared reusable geometry should be acquired through the game-owned `ResourceRegistry::Meshes()` cache; do not create parallel uploads for byte-identical mesh specifications. Shared shader programs should be acquired through `ResourceRegistry::Shaders()`; do not mutate cached `ShaderProgram` instances directly or compile identical stage source repeatedly. Shared sampled textures should use `ResourceRegistry::Textures()`; cached `TextureResource` instances are immutable, color space is part of identity, and file changes must be published through transactional reload. Scene renderables should acquire immutable `Material` resources through `ResourceRegistry::Materials()` rather than ad-hoc shader/texture fields; per-draw matrices belong in command-buffer uniforms, not material identity. Platform input must remain backend-neutral at the public API boundary: native messages feed `InputState`, `Game` evaluates generic `InputActionSystem` contexts before updates, and focus loss must release held controls. Never hard-code RTS or other game-specific action names into the input module; reference profiles belong in examples or games. Long-lived scene and serialized references should use typed registry handles. Handles must stay non-owning, every alias bind/remap/removal must advance its generation, direct cache mutation must invalidate existing handles, and stale handles must resolve to null rather than a replacement resource.
 - Scene authoring must use `Entity` plus components; do not reintroduce `SceneNode` or make `RenderObject` transforms authoritative. Renderer/light proxies are generated from the scene. Stable entity IDs and hierarchy invariants must remain serialization-safe.
 - Do not add required interface methods with silent no-op defaults.
 - Do not expose source-tree absolute paths through installed target interfaces.

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to Pyramid Engine are documented here. The project is pre-al
 
 ## [Unreleased]
 
+### Generic input action mapping
+
+- Added engine-generic button, one-dimensional, and two-dimensional named actions above the platform `InputState` snapshot.
+- Added prioritized input contexts with enable/disable state, active-control consumption, deterministic ordering, and non-consuming observation contexts.
+- Added keyboard, mouse-button, mouse-delta, and wheel bindings with scaling, axis selection, optional key/mouse-button chords, and runtime rebinding/removal.
+- Integrated one `InputActionSystem` into `Game`; actions are evaluated after native message processing and before every `onUpdate()`.
+- Migrated both examples to named actions. `BasicRendering` provides an RTS-style reference profile without placing RTS semantics in the engine module.
+- Added `Input.ActionMapping`; CTest now registers 31 tests.
+
 ### Win32 input foundation
 
 - Added platform-neutral keyboard and mouse enums plus per-frame `InputState` polling.

CMakeLists.txt

@@ -53,6 +53,7 @@ install(
         Engine/Core/include/
         Engine/Graphics/include/
         Engine/Platform/include/
+        Engine/Input/include/
         Engine/Math/include/
         Engine/Utils/include/
         vendor/glad/include/

Engine/CMakeLists.txt

@@ -4,6 +4,7 @@ add_library(Pyramid::Engine ALIAS PyramidEngine)
 add_subdirectory(Core)
 add_subdirectory(Graphics)
 add_subdirectory(Platform)
+add_subdirectory(Input)
 add_subdirectory(Math)
 add_subdirectory(Utils)
 
@@ -19,6 +20,7 @@ target_include_directories(PyramidEngine
         $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/Engine/Core/include>
         $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/Engine/Graphics/include>
         $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/Engine/Platform/include>
+        $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/Engine/Input/include>
         $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/Engine/Math/include>
         $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/Engine/Utils/include>
         $<INSTALL_INTERFACE:include>

Engine/Core/include/Pyramid/Core/Game.hpp

@@ -1,6 +1,7 @@
 #pragma once
 #include <Pyramid/Graphics/GraphicsDevice.hpp>
 #include <Pyramid/Platform/Window.hpp> // Added for std::unique_ptr<Window>
+#include <Pyramid/Input/InputActions.hpp>
 #include <memory>
 
 namespace Pyramid {
@@ -108,6 +109,15 @@ class Game
      */
     const InputState& GetInput() const;
 
+    /**
+     * @brief Engine-generic named action and input-context system.
+     *
+     * Configure contexts and bindings during onCreate(). Game evaluates them
+     * once per frame after native input messages and before onUpdate().
+     */
+    InputActionSystem& GetInputActions() { return m_inputActions; }
+    const InputActionSystem& GetInputActions() const { return m_inputActions; }
+
     /**
      * @brief Register the camera whose projection follows the window client size.
      * @param camera Non-owning camera pointer, or nullptr to detach it.
@@ -144,6 +154,7 @@ class Game
     std::unique_ptr<Window> m_window;
     std::unique_ptr<IGraphicsDevice> m_graphicsDevice;
     std::unique_ptr<ResourceRegistry> m_resourceRegistry;
+    InputActionSystem m_inputActions;
     Camera* m_activeCamera;
     Renderer::RenderSystem* m_renderSystem;
     bool m_isRunning;

Engine/Core/source/Game.cpp

@@ -282,6 +282,10 @@ namespace Pyramid
             // Clamp delta time to prevent large jumps (e.g., when debugging or system lag)
             deltaTime = (std::min)(deltaTime, maxDeltaTime);
 
+            // Evaluate engine-generic action contexts from the completed native
+            // input snapshot before game logic reads named actions.
+            m_inputActions.Update(GetInput());
+
             // Update game logic
             onUpdate(deltaTime);
 

Engine/Input/CMakeLists.txt

@@ -0,0 +1,14 @@
+target_sources(PyramidEngine
+    PRIVATE
+        source/InputActions.cpp
+    PRIVATE
+        include/Pyramid/Input/InputActions.hpp
+)
+
+target_include_directories(PyramidEngine
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/source
+)

Engine/Input/include/Pyramid/Input/InputActions.hpp

@@ -0,0 +1,240 @@
+#pragma once
+
+#include <Pyramid/Core/Prerequisites.hpp>
+#include <Pyramid/Platform/Input.hpp>
+
+#include <cstddef>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace Pyramid
+{
+    /**
+     * @brief Shape of the value produced by an input action.
+     */
+    enum class InputActionType : u8
+    {
+        Button = 0,
+        Axis1D,
+        Axis2D
+    };
+
+    /**
+     * @brief Axis selected by a binding on a two-dimensional action.
+     */
+    enum class InputAxisComponent : u8
+    {
+        X = 0,
+        Y
+    };
+
+    /**
+     * @brief Platform-neutral physical source read from InputState.
+     */
+    enum class InputBindingSource : u8
+    {
+        Key = 0,
+        MouseButton,
+        MouseDeltaX,
+        MouseDeltaY,
+        MouseWheel,
+        MouseHorizontalWheel
+    };
+
+    struct InputActionVector2
+    {
+        f32 x = 0.0f;
+        f32 y = 0.0f;
+    };
+
+    /**
+     * @brief One physical input binding for a named action.
+     *
+     * A binding can optionally require one keyboard key and/or one mouse
+     * button to be held. This supports generic chords such as Alt+Enter and
+     * gated analog input such as right-button mouse dragging without exposing
+     * native platform codes.
+     */
+    struct InputBinding
+    {
+        InputBindingSource source = InputBindingSource::Key;
+        InputAxisComponent component = InputAxisComponent::X;
+        Key key = Key::Unknown;
+        MouseButton mouseButton = MouseButton::Count;
+        Key requiredKey = Key::Unknown;
+        MouseButton requiredMouseButton = MouseButton::Count;
+        f32 scale = 1.0f;
+
+        [[nodiscard]] static InputBinding KeyBinding(
+            Key key,
+            f32 scale = 1.0f,
+            InputAxisComponent component = InputAxisComponent::X);
+        [[nodiscard]] static InputBinding MouseButtonBinding(
+            MouseButton button,
+            f32 scale = 1.0f,
+            InputAxisComponent component = InputAxisComponent::X);
+        [[nodiscard]] static InputBinding MouseDeltaXBinding(
+            f32 scale = 1.0f,
+            InputAxisComponent component = InputAxisComponent::X);
+        [[nodiscard]] static InputBinding MouseDeltaYBinding(
+            f32 scale = 1.0f,
+            InputAxisComponent component = InputAxisComponent::Y);
+        [[nodiscard]] static InputBinding MouseWheelBinding(
+            f32 scale = 1.0f,
+            InputAxisComponent component = InputAxisComponent::X);
+        [[nodiscard]] static InputBinding MouseHorizontalWheelBinding(
+            f32 scale = 1.0f,
+            InputAxisComponent component = InputAxisComponent::X);
+
+        InputBinding& RequireKey(Key modifier);
+        InputBinding& RequireMouseButton(MouseButton modifier);
+
+        [[nodiscard]] bool IsValid() const;
+        [[nodiscard]] bool IsDigital() const;
+    };
+
+    /**
+     * @brief Evaluated state of one action for the current frame.
+     */
+    struct InputActionState
+    {
+        InputActionType type = InputActionType::Button;
+        InputActionVector2 value{};
+        bool active = false;
+        bool pressed = false;
+        bool released = false;
+
+        [[nodiscard]] f32 GetValue() const { return value.x; }
+        [[nodiscard]] InputActionVector2 GetValue2D() const { return value; }
+        [[nodiscard]] bool IsDown() const { return active; }
+        [[nodiscard]] bool WasPressed() const { return pressed; }
+        [[nodiscard]] bool WasReleased() const { return released; }
+    };
+
+    /**
+     * @brief Named, prioritized collection of input actions and bindings.
+     *
+     * Contexts are engine-generic. Games can create gameplay, UI, editor,
+     * vehicle, console, photo-mode, or any other context without changing the
+     * platform backend. Higher-priority consuming contexts prevent active
+     * controls from reaching lower-priority contexts.
+     */
+    class InputContext final
+    {
+    public:
+        [[nodiscard]] const std::string& GetName() const { return m_name; }
+        [[nodiscard]] i32 GetPriority() const { return m_priority; }
+        void SetPriority(i32 priority) { m_priority = priority; }
+
+        [[nodiscard]] bool IsEnabled() const { return m_enabled; }
+        void SetEnabled(bool enabled) { m_enabled = enabled; }
+
+        [[nodiscard]] bool ConsumesInput() const { return m_consumeInput; }
+        void SetConsumesInput(bool consumeInput) { m_consumeInput = consumeInput; }
+
+        [[nodiscard]] bool AddAction(std::string name, InputActionType type);
+        [[nodiscard]] bool RemoveAction(std::string_view name);
+        [[nodiscard]] bool HasAction(std::string_view name) const;
+        [[nodiscard]] std::size_t GetActionCount() const { return m_actions.size(); }
+
+        [[nodiscard]] bool AddBinding(std::string_view actionName, const InputBinding& binding);
+        [[nodiscard]] bool Rebind(
+            std::string_view actionName,
+            std::size_t bindingIndex,
+            const InputBinding& replacement);
+        [[nodiscard]] bool RemoveBinding(std::string_view actionName, std::size_t bindingIndex);
+        [[nodiscard]] bool ClearBindings(std::string_view actionName);
+        [[nodiscard]] std::size_t GetBindingCount(std::string_view actionName) const;
+        [[nodiscard]] const InputBinding* GetBinding(
+            std::string_view actionName,
+            std::size_t bindingIndex) const;
+
+        [[nodiscard]] const InputActionState* FindActionState(std::string_view name) const;
+
+    private:
+        friend class InputActionSystem;
+
+        struct Action
+        {
+            std::string name;
+            InputActionState state{};
+            std::vector<InputBinding> bindings;
+            bool previousActive = false;
+        };
+
+        InputContext(std::string name, i32 priority, bool consumeInput, u64 insertionOrder);
+
+        [[nodiscard]] Action* FindAction(std::string_view name);
+        [[nodiscard]] const Action* FindAction(std::string_view name) const;
+        void ResetRuntimeState(bool emitRelease);
+
+        std::string m_name;
+        i32 m_priority = 0;
+        bool m_enabled = true;
+        bool m_consumeInput = true;
+        u64 m_insertionOrder = 0;
+        std::vector<Action> m_actions;
+    };
+
+    /**
+     * @brief Evaluates named actions from the current platform input snapshot.
+     */
+    class InputActionSystem final
+    {
+    public:
+        InputActionSystem() = default;
+        InputActionSystem(const InputActionSystem&) = delete;
+        InputActionSystem& operator=(const InputActionSystem&) = delete;
+
+        [[nodiscard]] InputContext* CreateContext(
+            std::string name,
+            i32 priority = 0,
+            bool consumeInput = true);
+        [[nodiscard]] bool RemoveContext(std::string_view name);
+        void ClearContexts();
+
+        [[nodiscard]] InputContext* FindContext(std::string_view name);
+        [[nodiscard]] const InputContext* FindContext(std::string_view name) const;
+        [[nodiscard]] std::size_t GetContextCount() const { return m_contexts.size(); }
+
+        /**
+         * @brief Evaluate every enabled context from one InputState snapshot.
+         *
+         * Call exactly once after native messages are processed and before game
+         * update logic reads action states. Game performs this automatically.
+         */
+        void Update(const InputState& input);
+
+        [[nodiscard]] const InputActionState* FindActionState(
+            std::string_view contextName,
+            std::string_view actionName) const;
+
+        /**
+         * @brief Find an action in the highest-priority enabled context.
+         */
+        [[nodiscard]] const InputActionState* FindActionState(
+            std::string_view actionName) const;
+
+        [[nodiscard]] bool IsActionDown(
+            std::string_view contextName,
+            std::string_view actionName) const;
+        [[nodiscard]] bool WasActionPressed(
+            std::string_view contextName,
+            std::string_view actionName) const;
+        [[nodiscard]] bool WasActionReleased(
+            std::string_view contextName,
+            std::string_view actionName) const;
+        [[nodiscard]] f32 GetActionValue(
+            std::string_view contextName,
+            std::string_view actionName) const;
+        [[nodiscard]] InputActionVector2 GetActionValue2D(
+            std::string_view contextName,
+            std::string_view actionName) const;
+
+    private:
+        std::vector<std::unique_ptr<InputContext>> m_contexts;
+        u64 m_nextInsertionOrder = 1;
+    };
+} // namespace Pyramid