* feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163) Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad; Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading. Every byte and reading under test was written by hand: no report from a real controller has passed through this code. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160) Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered, the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns. Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): the input reader, which the Agent does not start yet - raw input for controllers, XInput, the time of the last input (D155, D158, D159) Application.Input.InputReader takes a slice about ten times a second from Infrastructure.Input.Win32InputBackend, on the thread of InputDeviceHub, which exists only while a session has a view of it. It opens no device, sends nothing to one and registers for no keyboard or mouse. tools/input-readonly-check.ps1 holds its Windows calls to a list. With no controller at hand, what the reader does with one connected is not established. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): no using that makes the file's own qualified names redundant (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): what InspectCode reported in the reader's tests - redundant casts, a hub disposed twice, a suppression not needed Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * wip(input): the Agent records what a session was played with - the switch, the terms, the legal texts Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * style(input): import order in the Agent's composition; no redundant qualifier in a test (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * wip(input): what a store lists of controller support, the input libraries, the game page's three rows * wip(input): the game page's details tests expect the three controller rows; the library names test without ToLowerInvariant Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * docs(guide): the settings page listed Controllers and input twice Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): a session's summary says what it was played with - the shares, the controllers and their batteries, two charts, marks on the frame-time chart; Trend, Compare and the CSV export (D155-D163) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * release: 0.1.0-beta.50 - what a session was played with: controllers and input, read from outside the game; owner-only item 48 (D155-D163; with D152, D154) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(app): the bar's gap is named by the class that has it; one sentence for the frames session's own sensors Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(app): the fixture's constant is named as the format check wants Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): the last-input time is asked not to go back, not to match .NET's tick - the two differ by the time the PC slept; the finding in 21_INPUT_DEVICES and HANDOFF's traps Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * refactor(app): the notes of a session's input need its controllers' record, not its row Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * docs(handoff): auto-merge does not wait for Qodana - the trap, and what was fixed here Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
17 KiB
21 — Input devices: controllers, and keyboard-and-mouse activity
What FrameLedger reads about game controllers and about the keyboard and mouse, from where, and what it never reads.
The numbers a session makes of it are in 03_METRICS.md §Input; the columns are in
06_DATA_MODEL.md.
Status, 2026-11-14 — the Agent records it; the App does not show it yet. A session recorded with the option on, after the terms were accepted, stores what it was played with: the model and the arithmetic (
FrameLedger.Domain.Input,FrameLedger.Application.Input,Application.Recording.InputSessionBuilder), the storage (schema 0024, the.partialfile's chunk 11 —06_DATA_MODEL), the reader (Application.Input.InputReader,Infrastructure.Input) and its composition into the Agent (capture.input_devices,Application.Input.InputTerms) are written and under test; and a game's page shows the three pieces of evidence for "supports controllers" (05_DETECTION§Does a game support controllers). The session's own screens come in the next pull request, and this note is rewritten by it. No report from a real controller has passed through any of this code (owner decision D157): the developer has no controller, and what happens on a real one is owner-only item 48.
The owner's request and decisions (2026-11-14)
The request: whether a game supports controllers, on the game's page; the share of a session played with a controller and with the keyboard; how often a controller connected and disconnected in a session; the battery state that lasted longest; switches between makers' controllers and each maker's share; stored, and drawn; Xbox controllers and the DualSense first.
| Decision | |
|---|---|
| D155 | Controllers are read by the Agent, from outside the game. No hook is added to a game and CLAUDE.md rule 4 is untouched. A session that is not hooked has the numbers as a hooked one does. |
| D156 | The reading is on unless switched off (Settings ▸ Controllers and input, capture.input_devices), and reads nothing until the Privacy Policy that describes it — 2.22 or later — has been accepted on the PC. An Agent that the logon task started after an update records sessions without it until the App has been opened once. |
| D157 | Built without a probe. Asked whether to run a probe tool with real controllers first, the owner chose to build straight. So every source says what it did (§What the reader says about itself), and each pull request and LIMITATIONS.md say what was verified against hand-made data only. |
| D158 | Keyboard and mouse are one class, known only by the time of the last input (GetLastInputInfo). No Raw Input registration for a keyboard or a mouse, no hook: no key ever enters FrameLedger's process. |
| D159 | Nothing is ever sent to a controller: no output report, no feature-report request, no XInputSetState. A DualSense on Bluetooth therefore has a battery level only when Steam or the game has already switched it to its long report (§DualSense). |
| D160 | The numbers are in the CSV/JSON export and in a bug bundle — they are columns of sessions, as the display mode's are — and the Privacy Policy's §3A says so. |
| D161 | A session that is not hooked is: duration, hardware telemetry, the reason — and what the Agent reads from outside the game (the game's memory since beta.12, controllers now). Every field measured inside the game still reads N/A. CLAUDE.md's sentence is amended with the pull request that makes it true. |
| D162 | Also built: the number of switches between a controller and the keyboard and mouse, and the share of time with no input; marks on the frame-time chart where a controller connected, dropped or ran low; a battery's first and last level and its rate; the kind of connection; a note where Steam Input presented the controller as an Xbox pad; a trend metric, a row in Compare, and "usually played with" on the game's page. |
| D163 | "Supports controllers" is three pieces of evidence, never a verdict: what Steam's own file on the disk says (no network: rule 8), which input libraries the game loaded, and how the game was actually played. From outside a game one can know that a controller was in use while the game was in front — not what the game did with it. |
The switch, and the terms
capture.input_devices — Settings ▸ Recording ▸ Controllers and input — is on unless switched off (D156), and
is read at each session's start like every setting the Agent reads. On is not enough: the Agent is usually started
at logon, and after an update that is before the App has shown the Privacy Policy that describes this reading. So
SettingsRecorderPolicy gives a session the reader only when legal_acceptance holds the Privacy Policy at
InputTerms.MinimumPrivacyVersion (2.22) or later. Until then the session reads nothing of controllers or of the
keyboard and mouse, stores none of schema 0024's columns, and says so: the slot input=terms_pending in
sessions.capture_notes (CaptureNotes.InputHeldForTerms), and a line in its .partial file's notes. An operator's console with no acceptance store reads
nothing either. Off, or held back, a session is byte for byte what it was before the reading existed.
What is read, and from where
Everything is a Windows API in a library Windows ships. No third-party library is added.
| Source | What it gives | Why this one |
|---|---|---|
Raw Input (RegisterRawInputDevices, usage page 1, usages 4 and 5, RIDEV_INPUTSINK | RIDEV_DEVNOTIFY; GetRawInputBuffer, GetRawInputData, GetRawInputDeviceInfo, GetRawInputDeviceList) |
the reports game controllers send, while the Agent is in the background; a controller arriving and leaving; its vendor and product ids | the documented way to receive a HID controller's reports without being in front, and it opens no handle to the device |
XInput 1.4 (XInputGetState, XInputGetCapabilities, XInputGetBatteryInformation) |
each of its four pads: its state, wired or wireless, a battery in four levels | what an Xbox pad's battery is reported through |
GetLastInputInfo |
the time of the last keyboard or mouse input in the user's session | a time and nothing else (D158) |
GetForegroundWindow, GetWindowThreadProcessId |
whose window is in front | already used for the focus sample (04_CAPTURE) |
Steam's appcache\appinfo.vdf, on the disk |
whether the store lists controller support for a library game | a local file: no request is made (rule 8) |
The time GetLastInputInfo gives is compared only with the time it gave before — "did it change since the last
slice". It is never set against a clock of .NET's. Measured 2026-11-15, by accident: on the developer PC, which
had slept for five hours since it started, that time and Environment.TickCount stood five hours apart — Windows'
tick counts the time asleep and .NET's does not — and a test that assumed one clock failed (it now asks only that
the time does not go back). Anything built on these times later — the time actually played, 15_ROADMAP §After the
controller train — must work in differences of this one source, or it breaks on every PC that sleeps.
Rejected, with the reason (the checklist of 18_GPU_VENDOR_APIS §Checklist applies to any library):
- Windows.Gaming.Input — its readings stop when the program is not in front, which the Agent never is.
- GameInput — on a PC it is a NuGet package under Microsoft's licence terms with a redistributable to install.
- Opening the HID device (
CreateFile) — a handle of FrameLedger's on a controller can make a game's, or a remapper's, exclusive open of it fail. Raw Input needs none. - A sixth native library — parsing bytes a device controls in C++, inside an Agent that may run as administrator.
The reader is C#, and what parses a report is
FrameLedger.Domain.Input, with no pointer in it. - Windows' own HID parser (
hid.dll'sHidP_*), to read any controller generically. It would have let a controller of a maker this build does not know count as in use — and nothing here could be tried on one. A controller whose layout this build does not know is listed, with its connections and drops, and is never in use: a guess would be a made-up number (§The reader).
What is never read
Which button, where a stick or a trigger is, the motion sensors, the touchpad; which key, what was typed, where the
mouse is; a controller's serial number, its Bluetooth address, its device path. A report is looked at to answer one
question — is anything on this pad in use? — and, for a DualSense, to take its battery byte; the answer is kept and
the report is not. InputSessionBuilderTests hold the stored JSON to a list of keys, so a key that could carry an
identifier has to be added to a test first.
Who a controller is
By its USB vendor and product ids only (Domain.Input.ControllerCatalog): Microsoft is the Xbox family, Sony
PlayStation, Nintendo Nintendo, anything else other — except that a pad Windows presents through XInput is in the
Xbox family whoever made it, because that is all Windows says of it. A model has a name only where the catalog lists
its ids; a wrong name would be worse than none. Two pads of one model on one kind of connection cannot be told apart
across a reconnect, and are not.
XInput
A state is a pad in use when a button is down, a trigger is past XINPUT_GAMEPAD_TRIGGER_THRESHOLD or a stick is
outside its XINPUT_GAMEPAD_*_THUMB_DEADZONE (Domain.Input.XInputPad) — a stick held counts, one that drifts inside
the dead zone does not. Its battery is XInput's words: a wired pad, or four levels with no word for charging.
Two things about XInput are not established and are what item 48 is for: Microsoft's page for XInputEnable says
that on Windows 10 and later "game controller input is automatically enabled/disabled by the system based on the
application window focus", which may mean a program in the background reads a neutral state; and a pad on Bluetooth
is reported not to answer XInputGetBatteryInformation. XInput also has no documented way to say which device one of
its four pads is.
DualSense
Sony's 054C:0CE6, and the Edge, 054C:0DF2 (Domain.Input.DualSenseReport). Three reports:
| Connection | Report | What it carries |
|---|---|---|
| USB | 0x01, 64 bytes |
sticks, triggers, buttons — and the battery: a level in tenths and what the battery is doing |
| Bluetooth, as connected | 0x01, 10 bytes |
sticks, buttons, triggers. No battery |
| Bluetooth, once switched | 0x31, 78 bytes |
the USB report's body, one byte later |
The pad sends the short report until some program asks it for a feature report or sends it an output report; from then
until it reconnects it sends the long one. FrameLedger never asks (D159): a game that reads the short report through
DirectInput would lose its input. So over Bluetooth the level is there when Steam or the game switched the pad, and is
not otherwise. Windows hands every report of a device over at the length of the device's longest, so the short report
arrives padded to 78 bytes with the id the USB report has: the connection, not the length, says which layout a report
0x01 has.
The layout was written from the open descriptions of the protocol. No code was taken from the Linux kernel's driver, which is under a licence this project cannot take code from.
The reader
Application.Input.InputReader over Infrastructure.Input.Win32InputBackend, on the thread of
Infrastructure.Input.InputDeviceHub — named fl-input, and there only while a session has a view of the hub:
with no session there is no thread, no window and no registration.
A slice, about ten times a second. The reader takes what Windows has: the controllers that came and went, the
reports that arrived (in bulk — GetRawInputBuffer — not one message at a time: a DualSense sends some hundreds a
second, and the Agent's whole budget is 2.5 % of one core, NFR-2), the state of XInput's connected pads, the time of
the last keyboard or mouse input, and the process whose window is in front. From that it makes one InputSlice,
the same for every session that is running; each session's view counts it when a window of its game was in front
(Application.Input.InputTickAccumulator), and the telemetry poller takes the sum once a second.
The window. Raw input is delivered to a window. The reader's is a child of HWND_MESSAGE: never shown, in no
task bar, receiving no broadcast, answered by Windows' default procedure. It is registered for HID usage page 1,
usages 4 (joystick) and 5 (gamepad) — InputReader.RegisteredUsages — and for nothing else.
What a controller is. Each of XInput's pads that is connected is one; each controller Windows does not present through XInput is one. A device Windows presents through XInput is also seen by raw input and is not a second controller: it gives the pads their name where that cannot be mistaken — every XInput-class device a player could hold has the same two ids — and is otherwise only the witness of the next paragraph. An empty XInput slot is asked about once in twenty slices (XInput looks for a device each time) and at once when a controller arrives or leaves; a connected pad's battery once in fifty.
Where XInput says nothing. If XInput returns a pad at rest for ever because the Agent's window is never in front
(§XInput), the device's own reports are the evidence: a slice in which an XInput-class device's reports changed
while no pad's packet number moved — in that slice or the one before — is counted (XInputSilent). After ten of
them, and only if XInput has never once been seen to move, such a slice counts the lowest connected pad as in
use. That is coarser than XInput's dead zones — a stick that drifts counts — and is used only where the better
source is silent; a session's stored counts say which it was.
Which controllers are read for use. XInput's pads, and a DualSense by its own reports. Any other controller — a DualShock 4, a Switch Pro controller — is listed with its connections and drops and is never in use.
Faults. A slice that throws is counted and skipped; twenty in a row end the run with one line in the Agent's log, and the sessions go on without readings. When a run ends, one line says what it did: slices, whether Windows accepted the registration, reports received and not read, XInput's reads and silent slices, whether the time of the last input could be read, the thread's processor time, faults. Nothing in it names a device.
Held by a gate. tools/input-readonly-check.ps1 (12_BUILD step 14g): the reader's calls are a committed list,
none of which sends to a device, injects input or reads a key; no other managed source and no native source names
an input function.
What the reader says about itself
Application.Input.InputHealth, carried by every reading and stored with the session: whether Windows accepted the
registration, how many reports came and how many could not be read, whether XInput's library was there and how many
states it returned, how often a controller's own reports said in use while XInput said nothing, whether the time of
the last input could be read, how many slices were taken and how much processor time the reader's thread used. Counts
and yes-or-no answers; nothing in it names a device.
In the App
08_UI §Session summary has the detail; the short of it (0.1.0-beta.50):
| Where | What | From |
|---|---|---|
| A session's summary, Played with | the four classes as a bar and a table, the changes between a controller and the keyboard and mouse, the controllers with their batteries, the makers' shares, what the reader could not do; why a session has none | the row's input_* columns and input_devices (Services.InputPresentation) |
| The same, two charts | what each second was played with; each controller's battery | the input.* series (Charts.InputSeries) |
| The frame-time chart, Controller marks | a connection, a drop, a battery that fell to low, as lines across the frames | the same series, placed by frame_blobs.first_present_ms; hooked sessions only |
| A game's page, Details | what the store lists, the input libraries loaded, how it was played | 05_DETECTION §Does a game support controllers |
| Trend | Controller share, Keyboard and mouse share | the row, every tier |
| Compare | Played with, Controllers | the row, never ranked |
| The CSV export | # input: - the milliseconds, the switches, the sources, each controller |
03_METRICS §Export schema |
| The JSON export, the bug report | the row's columns as they are | Privacy Policy 3A |
A mark is drawn from the series, not from the row: a controller's input.dev.N.active goes from no value to a value
where it connected and back where it dropped, and the row's connects says whether the first of them was the
session's start. A battery "fell to low" where its level went from above XInput's low, or above 10 %, to at or
under it - a falling level is a battery running down, and the state is not in the series.
Everything in this table has been drawn from synthetic sessions only. What a real controller's series look like - how often a Bluetooth pad flaps, whether a DualSense's battery steps as the fixture's does - is owner-only item 48.