⌨️ Input System
Uma camada de input baseada em ações, com bindings remapeáveis de teclado, rato e gamepad, exposta como estado de ações e eixos por frame sem dependência de SDL em tempo de compilação.
Visão Geral#
O Input System abstrai dispositivos (teclado, rato, gamepad) e expõe ações nomeadas em vez de scancodes crus. Isto permite remapear controlos sem alterar o código de gameplay.
Filosofia: o código do jogo nunca pergunta "foi pressionado W?" — pergunta
"foi ativada a ação MoveUp?". As bindings mapeiam W → MoveUp, mas o jogador
pode reconfigurá-las.
O header não tem dependência de SDL3. A aplicação anfitriã traduz eventos
SDL em chamadas injectKeyDown() / injectKeyUp() /
injectMouseButtonDown() / injectGamepadAxis(); os testes alimentam a mesma
API de injeção diretamente.
Arquitetura#
- Pump de eventos do host (SDL ou outro backend)
InputManager.beginFrame()— guarda o estado raw e de ações para o novo frame- O host injeta eventos (
injectKey*,injectMouse*,injectGamepad*) InputManager.endFrame()— avalia as bindings, atualizaActionState(pressed/justPressed/justReleased) e dispara callbacks- Os sistemas de jogo consultam
actionState()/axisState()durante o update
beginFrame() não faz polling de eventos e endFrame() não os injeta; essa
fronteira pertence ao host. Chame beginFrame() antes de injetar os eventos do
frame e endFrame() depois de todos terem sido injetados.
API#
namespace Caffeine::Input {
enum class Action : u8 {
MoveUp = 0, MoveDown, MoveLeft, MoveRight,
Jump, Attack, Interact, Pause,
Count
};
enum class Axis : u8 {
MoveX = 0,
MoveY,
LookX,
LookY,
Count
};
// Valores compatíveis com SDL; nenhum header SDL é incluído.
enum class Key : u16 { /* A–Z, dígitos, setas, Space, Escape, modificadores, ... */ };
enum class MouseButton : u8 { Left = 1, Middle, Right, X1, X2, Count };
enum class GamepadButton : u8 { A = 0, B, X, Y, /* ... */ Count };
enum class GamepadAxis : u8 { LeftX = 0, LeftY, RightX, RightY, TriggerLeft, TriggerRight, Count };
struct ActionState {
bool pressed = false; // mantido enquanto alguma binding estiver ativa
bool justPressed = false; // true apenas no primeiro frame
bool justReleased = false; // true apenas no frame da libertação
};
struct AxisState {
f32 value = 0.0f; // -1.0 .. +1.0
f32 delta = 0.0f; // mudança desde o frame anterior
};
enum class BindingType : u8 {
Key,
MouseButton,
GamepadButton,
GamepadAxis
};
struct Binding {
BindingType type;
union {
Key key;
MouseButton mouseButton;
GamepadButton gamepadButton;
GamepadAxis gamepadAxis;
};
static Binding fromKey(Key k);
static Binding fromMouseButton(MouseButton mb);
static Binding fromGamepadButton(GamepadButton gb);
static Binding fromGamepadAxis(GamepadAxis ga);
};
static constexpr usize MAX_BINDINGS_PER_ACTION = 4;
class InputManager {
public:
InputManager();
// --- Ciclo de frame (chamado pelo host/GameLoop) ---
void beginFrame();
void endFrame();
// --- Injeção de eventos (testável sem SDL3) ---
void injectKeyDown(Key key);
void injectKeyUp(Key key);
void injectMouseButtonDown(MouseButton button);
void injectMouseButtonUp(MouseButton button);
void injectMouseMove(f32 x, f32 y);
void injectGamepadButtonDown(GamepadButton button);
void injectGamepadButtonUp(GamepadButton button);
void injectGamepadAxis(GamepadAxis axis, f32 value);
// --- Consulta de estado ---
ActionState actionState(Action action) const;
AxisState axisState(Axis axis) const;
bool isKeyDown(Key key) const;
bool isMouseButtonDown(MouseButton button) const;
Vec2 mousePosition() const;
Vec2 mouseDelta() const;
// --- Gestão de bindings ---
void bind(Action action, Binding binding); // adiciona até 4 bindings
void clearBindings(Action action);
void clearAllBindings();
void resetToDefaults();
// --- Binding de eixo: uma binding negativa e uma positiva ---
void bindAxis(Axis axis, Binding negative, Binding positive);
// --- Callbacks ---
std::function<void(Action)> onActionPressed;
std::function<void(Action)> onActionReleased;
class IInputCallbacks {
public:
virtual ~IInputCallbacks() = default;
virtual void onActionPressed(Action action) = 0;
virtual void onActionReleased(Action action) = 0;
};
void setCallbackHandler(IInputCallbacks* handler);
};
} // namespace Caffeine::Input
Não existem
Action::None,CUSTOM_START, o acessorjustPressed(Action), o helperaxisValue()nem modo de rato relativo no header atual. UseactionState(action).justPressedeaxisState(axis).value.
Bindings por Omissão#
InputManager::resetToDefaults() instala:
| Ação | Teclado |
|---|---|
| MoveUp | W / ↑ |
| MoveDown | S / ↓ |
| MoveLeft | A / ← |
| MoveRight | D / → |
| Jump | Space |
| Pause | Esc |
Eixos:
| Eixo | Negativo | Positivo |
|---|---|---|
| MoveX | A | D |
| MoveY | S | W |
| LookX | Right stick X | Right stick X |
| LookY | Right stick Y | Right stick Y |
Attack e Interact não têm binding por omissão. Os botões de face do gamepad
também não estão ligados a ações por omissão; faça o binding explicitamente.
Exemplos de Uso#
Ligar ações e eixos#
Caffeine::Input::InputManager input;
input.bind(Caffeine::Input::Action::Jump,
Caffeine::Input::Binding::fromKey(Caffeine::Input::Key::Space));
input.bind(Caffeine::Input::Action::Jump,
Caffeine::Input::Binding::fromGamepadButton(
Caffeine::Input::GamepadButton::A));
input.bindAxis(Caffeine::Input::Axis::MoveX,
Caffeine::Input::Binding::fromKey(Caffeine::Input::Key::A),
Caffeine::Input::Binding::fromKey(Caffeine::Input::Key::D));
Ciclo de frame#
input.beginFrame();
// O host traduz eventos SDL em chamadas de injeção:
input.injectKeyDown(Caffeine::Input::Key::W);
input.injectMouseMove(mouseX, mouseY);
input.endFrame(); // avalia bindings e dispara callbacks
Ler input num sistema#
const Caffeine::Input::ActionState jump =
input.actionState(Caffeine::Input::Action::Jump);
if (jump.justPressed) {
velocity.y = jumpForce;
}
const Caffeine::Input::AxisState moveX =
input.axisState(Caffeine::Input::Axis::MoveX);
velocity.x = moveX.value * moveSpeed;
// Mouse look: acumule o delta de cada frame.
const Caffeine::Vec2 look = input.mouseDelta();
yaw += look.x * sensitivity;
pitch += look.y * sensitivity;
Reagir a ações#
input.onActionPressed = [](Caffeine::Input::Action action) {
if (action == Caffeine::Input::Action::Pause) {
togglePause();
}
};
Código de jogo que precise de mapeamentos por entidade pode definir o seu
próprio componente com valores Action / Axis; a engine não fornece um
componente PlayerInput.
Testes#
tests/test_input.cpp (34 casos) cobre:
- Transições de
justPressed/justReleasedentre frames - Múltiplas bindings numa ação
- Bindings de botão do rato e do gamepad
- Posição e delta do rato
- Pares negativo/positivo de eixos, pass-through de gamepad e delta por frame
- Limpar bindings e restaurar defaults
- Limite de 4 bindings por ação
onActionPressed/onActionReleasedeIInputCallbacks- Bindings WASD/setas por omissão
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Baseado em ações, não em scancodes | Jogos portáveis; remapping em runtime sem alterar código |
justPressed / justReleased por frame |
Sem deteção manual de transições no gameplay |
| Tabela de bindings mutável | Remapping em runtime num menu de opções |
| API de injeção de eventos | Testes e backends alternativos funcionam sem SDL |
| Sem headers SDL no header público de input | O core mantém-se independente do backend de janela |
| Arrays fixos indexados por enum | Consultas O(1) sem hashing no hot path |
| Até 4 bindings por ação | Cobre alternativas de teclado + gamepad sem crescimento ilimitado |
Dependências#
- Upstream:
Caffeine::Core::Types,Caffeine::Vec2,Caffeine::HashMap,Caffeine::Vector,<array>e<functional>da biblioteca padrão - Downstream: Game Loop, sistemas de gameplay que consultam ações/eixos
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| Sistemas de Jogo | Input alimenta sistemas ECS |
| Concorrência & Runtime | Input é processado no Game Loop |
Referências#
src/caffeine/input/InputManager.hpp/src/caffeine/input/InputManager.cpptests/test_input.cppdocs/architecture_specs.md— §3 Input Systemcore/game-loop.md— o host chamabeginFrame()/endFrame()- Índice de Tópicos Transversais