Documentation
¶
Overview ¶
Package input provides a high-level, ergonomic input system.
The mental model is tiny:
Create an Action -> Bind hardware -> Attach logic -> Enable/Disable/Unbind as needed.
The user only ever touches *Action values. There is no separate Subscription object: enabling, disabling, unbinding and rebinding all happen directly on the Action (or on the Manager for bindings). Callbacks stay alive across enable/disable and rebind operations.
Raw input arrives through a Backend (e.g. gogpu or headless). The Manager maintains input state (key/button state, mouse position, timers) and derives higher-level events (hold, tap, toggle, combo, drag) from it before dispatching to the bound Actions.
All event consumption is single-threaded: call Manager.Update once per frame from your main loop.
Index ¶
- type Action
- func (a *Action) Disable()
- func (a *Action) Enable()
- func (a *Action) Enabled() bool
- func (a *Action) IsActive() bool
- func (a *Action) IsDown() bool
- func (a *Action) Name() string
- func (a *Action) OnDrag(fn func(float64, float64, Context))
- func (a *Action) OnHold(threshold float64, fn func(Context))
- func (a *Action) OnPressed(fn func(Context))
- func (a *Action) OnReleased(fn func(Context))
- func (a *Action) OnTap(fn func(Context))
- func (a *Action) OnToggle(fn func(bool, Context))
- func (a *Action) Unbind()
- type ActionEvent
- type ActionEventType
- type Backend
- type Binding
- type Context
- type Event
- type EventKind
- type Key
- type Manager
- func (m *Manager) Action(name string) *Action
- func (m *Manager) BindKey(a *Action, k Key)
- func (m *Manager) BindMouseButton(a *Action, b MouseButton)
- func (m *Manager) Clock() float64
- func (m *Manager) Combo(name string, keys ...Key) *Action
- func (m *Manager) Drain() []ActionEvent
- func (m *Manager) IsDown(a *Action) bool
- func (m *Manager) MousePosition() (x, y float64)
- func (m *Manager) Rebind(a *Action, k Key)
- func (m *Manager) SetRecording(on bool)
- func (m *Manager) Update(dt float64)
- type MouseButton
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
// contains filtered or unexported fields
}
Action is the single user-facing input object. The user binds hardware to it, attaches callbacks to it, and controls it directly via Enable, Disable and Unbind.
func (*Action) Disable ¶
func (a *Action) Disable()
Disable stops event delivery but keeps callbacks and bindings. Input state for the Action stays up to date so re-enabling does not emit a stale press.
func (*Action) Enable ¶
func (a *Action) Enable()
Enable resumes event delivery. Callbacks and bindings are preserved.
func (*Action) OnDrag ¶
OnDrag registers a callback fired whenever the pointer moves while the Action is held. dx, dy are the per-frame movement deltas.
func (*Action) OnHold ¶
OnHold registers a callback fired every frame the Action has been held longer than its own threshold (seconds). Each handler is gated on its own threshold, so OnHold(0.1) and OnHold(1.0) fire independently. Because the callback fires every frame, scale accumulations by ctx.Dt() to stay frame-rate independent.
func (*Action) OnReleased ¶
OnReleased registers a callback fired once on the release edge.
func (*Action) OnTap ¶
OnTap registers a callback fired on a quick press+release, where "quick" means shorter than defaultTapMax (0.22s). The tap window is fixed and does not depend on any OnHold threshold.
type ActionEvent ¶
type ActionEvent struct {
Type ActionEventType
Action *Action
Now float64 // Manager clock (seconds) at dispatch
Dt float64 // frame delta (seconds) that produced this event
Active bool // toggle state, for EventTypeToggle
DX, DY float64 // movement delta, for EventTypeDrag
}
ActionEvent is a recorded, replayable derived event. It mirrors what the callbacks see, but as data instead of function calls, so the game can convert input into a command stream bound to simulation ticks. Use Manager.SetRecording(true) and Manager.Drain() to collect them.
type ActionEventType ¶
type ActionEventType uint8
ActionEventType enumerates the derived events recorded by Manager.Drain.
const ( EventTypePressed ActionEventType = iota EventTypeReleased EventTypeHold EventTypeTap EventTypeToggle EventTypeDrag )
type Backend ¶
type Backend interface {
Poll() []Event
}
Backend supplies raw input events to the Manager.
Implementations must be safe to call from the same goroutine that calls Manager.Update. Poll is called once per frame and should return the events that occurred since the previous call (an empty slice is fine).
type Binding ¶
type Binding struct {
// contains filtered or unexported fields
}
Binding maps hardware input to an Action.
- bindKey: the Action is active while key is down.
- bindMouse: the Action is active while the button is down.
- bindCombo: the Action is active only while ALL combo keys are down.
An Action with multiple bindings is active if ANY binding is active.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context is passed to every callback. It is a value type and is reused across dispatches within a single frame, so callbacks must consume it synchronously (they always do).
func (Context) Dt ¶
Dt returns the frame delta (seconds) that produced the current dispatch.
OnHold fires once per frame, so any accumulation must scale by Dt to be frame-rate independent: charge += rate*ctx.Dt().
func (Context) MousePosition ¶
MousePosition returns the current pointer position in window coordinates.
type Event ¶
type Event struct {
Kind EventKind
Key Key
Button MouseButton
X, Y float64 // valid for mouse events
}
Event is a single raw input event produced by a Backend.
type EventKind ¶
type EventKind uint8
EventKind enumerates the kinds of raw events a Backend can emit.
const ( // EventKeyDown is emitted on a key press edge. EventKeyDown EventKind = iota // EventKeyUp is emitted on a key release edge. EventKeyUp // EventMouseDown is emitted on a mouse button press edge. EventMouseDown // EventMouseUp is emitted on a mouse button release edge. EventMouseUp // EventMouseMove is emitted when the pointer changes position. EventMouseMove )
type Key ¶
type Key uint16
Key identifies a physical keyboard key.
The numeric values intentionally match the gogpu input package (github.com/gogpu/gogpu/input) so the gogpu backend can pass key codes through without a conversion table. They are stable for a given engine version and are only used internally as opaque identifiers.
const ( KeyUnknown Key = iota // KeyF1 Function keys KeyF1 KeyF2 KeyF3 KeyF4 KeyF5 KeyF6 KeyF7 KeyF8 KeyF9 KeyF10 KeyF11 KeyF12 // Key0 Number keys Key0 Key1 Key2 Key3 Key4 Key5 Key6 Key7 Key8 Key9 // KeyA Letter keys KeyA KeyB KeyC KeyD KeyE KeyF KeyG KeyH KeyI KeyJ KeyK KeyL KeyM KeyN KeyO KeyP KeyQ KeyR KeyS KeyT KeyU KeyV KeyW KeyX KeyY KeyZ // KeySpace Special keys KeySpace KeyEnter KeyEscape KeyBackspace KeyTab KeyCapsLock KeyShiftLeft KeyShiftRight KeyControlLeft KeyControlRight KeyAltLeft KeyAltRight KeySuperLeft // Windows/Command key KeySuperRight // Windows/Command key // KeyUp Arrow keys KeyUp KeyDown KeyLeft KeyRight // KeyInsert Navigation keys KeyInsert KeyDelete KeyHome KeyEnd KeyPageUp KeyPageDown // KeyMinus Punctuation KeyMinus KeyEqual KeyLeftBracket KeyRightBracket KeyBackslash KeySemicolon KeyApostrophe KeyGrave KeyComma KeyPeriod KeySlash // KeyNumpad0 Numpad KeyNumpad0 KeyNumpad1 KeyNumpad2 KeyNumpad3 KeyNumpad4 KeyNumpad5 KeyNumpad6 KeyNumpad7 KeyNumpad8 KeyNumpad9 KeyNumpadAdd KeyNumpadSubtract KeyNumpadMultiply KeyNumpadDivide KeyNumpadEnter KeyNumpadDecimal KeyNumLock // KeyPrintScreen Other KeyPrintScreen KeyScrollLock KeyPause KeyCancel // Win32 Ctrl+Break (VK_CANCEL); distinct from KeyPause KeyCount // Number of keys )
Keyboard key codes.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns all Actions and drives event processing.
func NewManager ¶
NewManager creates a Manager fed by the given Backend.
func (*Manager) BindKey ¶
BindKey adds a keyboard binding to an Action. Bindings accumulate; an Action fires when any of its bindings is active.
func (*Manager) BindMouseButton ¶
func (m *Manager) BindMouseButton(a *Action, b MouseButton)
BindMouseButton adds a mouse button binding to an Action.
func (*Manager) Combo ¶
Combo returns (creating if needed) an Action that fires only when all the given keys are held simultaneously. The combo is treated as a single binding on the returned Action.
func (*Manager) Drain ¶
func (m *Manager) Drain() []ActionEvent
Drain returns and clears the derived events recorded since the last call. Use it to build a deterministic command stream for the simulation; attach callbacks on top for non-simulation concerns (camera, UI).
func (*Manager) IsDown ¶
IsDown reports whether the Action is currently considered pressed, based on its bindings and the live input state. Disabled Actions still report accurate state.
func (*Manager) MousePosition ¶
MousePosition returns the current pointer position.
func (*Manager) Rebind ¶
Rebind clears an Action's hardware bindings and binds a single key. Callbacks and live state are preserved (the pressed flag is reset, so no release is synthesized for a key that was physically still held).
func (*Manager) SetRecording ¶
SetRecording enables or disables recording of derived events. When enabled, every dispatched derived event is appended to an internal buffer that Drain returns. Recording is off by default so the default callback path stays allocation-free.
type MouseButton ¶
type MouseButton uint8
MouseButton identifies a mouse button.
The numeric values intentionally match the gogpu input package.
const ( MouseButtonLeft MouseButton = iota MouseButtonRight MouseButtonMiddle MouseButton4 MouseButton5 MouseButtonCount )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
backend
|
|
|
gogpu
Package gogpu adapts the gogpu application event model to the input system.
|
Package gogpu adapts the gogpu application event model to the input system. |
|
headless
Package headless provides an injectable Backend for the input system.
|
Package headless provides an injectable Backend for the input system. |