Module trace 

Why an input did what it did: the resolution trace an input inspector shows, which is the answer to “input eaten mysteriously” by the context stack.

Opt in, and bounded

Nothing is recorded until ActionMap::set_tracing turns it on, and an input then costs the map nothing more than the check of that switch. On, the map keeps the most recent RESOLUTION_TRACE_CAP entries and drops the oldest — a ring of recent inputs rather than one frame’s, because a frame’s list is empty again before anyone has read it. An input that repeats the newest entry exactly, input and outcome both, counts on that entry (TraceEntry::count) instead of pushing another: a touchpad’s scroll is dozens of wheel events a second, and would otherwise push every key press out of the ring before it was read.

What is traced

Each press: a key going down (an OS auto-repeat of a key already down is not a new press), a pointer button going down, a wheel turn, an on-screen button pressed or an on-screen stick leaving centre, a pad button going down, and a pad stick or trigger pushed out past PAD_ACTIVITY_THRESHOLD — the same travel that makes the pad the last device.

Not traced: releases, whose route is the press’s; pointer motion and the pointer’s position, which arrive every frame the mouse moves and would fill the ring with themselves; and a stick or trigger moving while already out, which is a held level, not a new press.

What an entry says

Each TraceEntry names the input and its Outcome, read off the same routes resolution reads (context.rs): the context that owns the input and every binding in it that read the input, with the action it drives (Outcome::Read) — an empty list there is an input the context owns and no binding of a live action read, a chord’s key pressed without its modifier, say; that the owner withholds it until it is released (Outcome::Withheld); that a modal context stopped it on its way down to a context that binds it (Outcome::Blocked); or that no active context binds it (Outcome::Unbound). Something that takes an input before it reaches the map — the engine loop’s reserved keys, a menu over the game — says so with ActionMap::trace_claimed (Outcome::Claimed).

It never changes resolution

An entry is explained after the input has resolved, by reading the routes, the withheld inputs and the raw state, and nothing in this module writes any of them. tests::resolution_is_identical_with_tracing_on_and_off drives two maps through one script, one tracing and one not, and compares every action after every step.

Structs

TraceEntry

One row of the trace: an input, where it went, and how many times in a row it went there.

TracedRead

One binding that read a traced input, and the action it drives.

Enums

Outcome

Where a traced input went — see the module docs.

TracedInput

One input the trace records — see the module docs for which.

Constants

RESOLUTION_TRACE_CAP

The most entries ActionMap::trace holds: the inputs of the last few seconds of play, and as many rows as an inspector panel can show beside the rest of the input section.