937f05595c
F1: the human watched the real game and it repeats on a held direction, on the stick AND (confirmed separately) the d-pad. gamepad.gd had predicted this exact refutation in its own words, so one-step-per-deflection stops being the conservative reading and becomes a known defect. Mechanism: Gamepad.held_direction() polls the DEVICES -- not Input.is_action_pressed, because ui_up/ui_down sit on the stick at Godot's 0.50 deadzone while the port steps at the game's measured 0.61, so polling the action would repeat through the exact band ENTER exists to exclude. Boot._menu_repeat() re-applies the same guards a real press gets, rather than sharing them, because a second input path is where this port's defects hide. The RATE is NOT shipped, on instruction: an invented interval is indistinguishable from a measured one later. An earlier draft of this change had 0.40/0.20 with a why attached; that was the named failure mode and the numbers are removed, not commented out. repeat_due() returns 0 until both are set. Flagged at the adoption site: verify-input's 'a held stick is ONE step, not six' asserts the ABSENCE of this feature and will go red when a rate lands -- for the right reason, and looking exactly like the jitter bug returning.
273 lines
12 KiB
GDScript
273 lines
12 KiB
GDScript
class_name Gamepad
|
||
extends RefCounted
|
||
|
||
## The physical controller: the two buttons Godot does not bind, and the one
|
||
## input that is not an edge.
|
||
##
|
||
## 🔴 BOTH DEFECTS WERE REPORTED BY A HUMAN PLAYING THE PORT (2026-09-01), and
|
||
## neither could have been caught by the `--script` harness, because that harness
|
||
## sends `InputEventAction` — which bypasses the input map and is not an analog
|
||
## axis. The unattended P5 walk passed on every iteration while Ⓐ did nothing at
|
||
## all on a real pad. **A synthetic-input test asserts the code after the input
|
||
## map, never the input map itself.**
|
||
##
|
||
## ## 1. Godot 4.7.2 binds no joypad button to `ui_accept` or `ui_cancel`
|
||
##
|
||
## Measured on this exact build rather than remembered, because the answer has
|
||
## changed between Godot versions and the remembered one was wrong:
|
||
##
|
||
## ```
|
||
## ui_accept key:Enter, key:Kp Enter, key:Space <- no joypad at all
|
||
## ui_cancel key:Escape <- no joypad at all
|
||
## ui_up key:Up, JOYBTN:11, JOYAXIS:1- <- d-pad AND left stick
|
||
## ui_down key:Down, JOYBTN:12, JOYAXIS:1+
|
||
## ui_left key:Left, JOYBTN:13, JOYAXIS:0-
|
||
## ui_right key:Right, JOYBTN:14, JOYAXIS:0+
|
||
## ```
|
||
##
|
||
## That asymmetry is the whole bug report: navigation worked on the pad and Ⓐ/Ⓑ
|
||
## did nothing, which reads like a broken controller and is a complete input map
|
||
## for four actions out of six.
|
||
##
|
||
## The events are **added to** the built-in actions, never redefined. Declaring
|
||
## `ui_accept` in `project.godot` replaces the built-in wholesale, so the
|
||
## keyboard bindings would have to be restated there and would silently rot the
|
||
## next time Godot changes them.
|
||
##
|
||
## ## 2. A stick is not a button
|
||
##
|
||
## `ui_up`/`ui_down` are bound to **axis 1**, so the left stick navigates — which
|
||
## is correct, the real game accepts it too. But an axis emits a fresh
|
||
## `InputEventJoypadMotion` every time the value *changes*, and a real stick held
|
||
## at deflection jitters continuously. Every one of those events reports the
|
||
## action as pressed, so a held stick was one cursor step per jitter: the human's
|
||
## words were "moves the cursor too fast", and on a five-item menu it crosses
|
||
## faster than the eye follows.
|
||
##
|
||
## So the stick is **latched**: it fires once when it leaves the neutral zone and
|
||
## not again until it comes back. That makes it behave exactly like the d-pad,
|
||
## which needs no latch because a button already is an edge.
|
||
##
|
||
## ⚠️ ~~AUTHORED, NOT MEASURED — and deliberately the conservative half.~~
|
||
## 🔴 **THE GAME DOES REPEAT, and this paragraph predicted its own refutation.**
|
||
## It said: *"If the game does repeat, this is a difference a human will notice
|
||
## as 'I have to flick it again'."* On 2026-09-02 a human who has played both
|
||
## reported exactly that — *"holding only moves one item. In game it actually
|
||
## continues to move when holding up/down, just at a medium pace"*.
|
||
##
|
||
## So one-step-per-deflection is no longer the conservative reading; it is a
|
||
## known defect. The mechanism is implemented below and the **rate is not
|
||
## shipped** — see `REPEAT_DELAY` for why an approximate one is worse than none.
|
||
|
||
## ✅ DECODED 2026-09-01, and it replaces an authored value.
|
||
##
|
||
## This was **0.5**, chosen as a *floor* rather than as a value: Godot's action
|
||
## deadzone for the `ui_*` actions is 0.50, so the latch must not arm below it —
|
||
## the action itself would not read as pressed and the step would be swallowed
|
||
## anyway, leaving the latch armed against a press that never happened. That
|
||
## reasoning still holds and 0.61 is comfortably above the floor.
|
||
##
|
||
## The game's own threshold is now measured: it **digitises the left stick to
|
||
## four direction bits at 61 % deflection**, so it never sees a velocity at all
|
||
## (`docs/re/input-button-numbering-is-remapped.md` and the corrected
|
||
## `input-pad-read-path.md`). Between 0.50 and 0.61 Godot reports `ui_down`
|
||
## pressed and the real game reports nothing; at 0.5 this port stepped there.
|
||
##
|
||
## 📌 The mechanism also corroborates the human's fix rather than merely
|
||
## agreeing with it: a control that digitises to bits cannot express a rate, so
|
||
## "one step per deflection" is what the hardware layer *can* produce, not a
|
||
## conservative guess that happened to look right.
|
||
##
|
||
## ⚠️ **The 0.11 gap to `RELEASE` stays AUTHORED.** Nothing measured says the
|
||
## game has hysteresis at all, let alone how wide. Only the arm threshold moved.
|
||
##
|
||
## 🔴 **This changes how the stick feels and a human chose the old number.**
|
||
## Asserted at the device level below and in `tools/port/verify-input`, but a
|
||
## feel-test is the real check: revert this one constant to 0.5 if 0.61 reads as
|
||
## a stick that needs pushing too far.
|
||
const ENTER := 0.61
|
||
|
||
## Release lower than it arms. Without the gap a stick resting near 0.5 chatters
|
||
## across the boundary and re-arms on noise, which is the original bug wearing a
|
||
## smaller number.
|
||
const RELEASE := 0.4
|
||
|
||
## ## 3. A held direction repeats — MECHANISM PRESENT, RATE NOT SHIPPED
|
||
##
|
||
## A human who has played both reported it on 2026-09-02: *"holding only moves
|
||
## one item. In game it actually continues to move when holding up/down, just at
|
||
## a medium pace"*, and separately *"Confirmed D-Pad does repeat when holding
|
||
## too."* So the FACT covers both input devices, which is why `held_direction()`
|
||
## polls the pad and the keyboard and not just the stick.
|
||
##
|
||
## 🔴 **THE RATE IS DELIBERATELY UNSET, AND THE REPEAT DOES NOT RUN UNTIL IT IS
|
||
## MEASURED.** The instruction is explicit: *"Take the RATE from the Decoder — do
|
||
## NOT ship a placeholder interval. An invented rate here is indistinguishable
|
||
## from a measured one later, and this is the exact field where that already cost
|
||
## us."*
|
||
##
|
||
## An earlier draft of this file had 0.40 / 0.20 with a paragraph explaining that
|
||
## they were authored. **That is precisely the failure mode named above** — the
|
||
## explanation would have been merged, the numbers would have felt roughly right,
|
||
## and nothing afterwards could distinguish them from a measurement. They are
|
||
## removed rather than commented out.
|
||
##
|
||
## 📌 **A constant interval is the right SHAPE, and that part IS measured.** The
|
||
## game digitises the left stick to four direction bits at 61 % deflection
|
||
## (`ENTER` above), so it cannot see deflection magnitude at all — a repeat it
|
||
## drives cannot be faster-the-harder-you-push. That excludes the one competing
|
||
## model, so only the two constants are open, and one measurement closes both.
|
||
##
|
||
## ⚠️ **TO ADOPT, TWO THINGS CHANGE, NOT ONE.** Set both constants to the
|
||
## measured seconds — and update `tools/port/verify-input`, whose row *"a held
|
||
## stick is ONE step, not six"* currently asserts **the absence of this
|
||
## feature**. It passes today because the repeat is inert; the moment a rate is
|
||
## adopted a held stick SHOULD produce further steps, and that green row would
|
||
## go red for the right reason and be read as a regression.
|
||
##
|
||
## 📌 That row is not wrong. A check written against today's behaviour becomes an
|
||
## assertion that the behaviour never changes, and this one has the additional
|
||
## trap of looking like a bug-fix regression test — it was written for the
|
||
## jitter defect, and the repeat is not that defect returning.
|
||
## `pad-repeat` in `BLOCKED.md` carries the request.
|
||
const REPEAT_DELAY := -1.0
|
||
const REPEAT_INTERVAL := -1.0
|
||
|
||
|
||
## Whether a measured repeat rate has been adopted. Until it has, the port keeps
|
||
## its current one-step-per-deflection behaviour, which is KNOWN WRONG but is
|
||
## wrong in a way nobody will mistake for a measurement.
|
||
static func repeat_rate_known() -> bool:
|
||
return REPEAT_DELAY > 0.0 and REPEAT_INTERVAL > 0.0
|
||
|
||
## Only the left stick. The triggers are axes too, and latching them here would
|
||
## silently swallow input the port does not read yet but might.
|
||
const STICK := [JOY_AXIS_LEFT_X, JOY_AXIS_LEFT_Y]
|
||
|
||
var _latched: Dictionary = {}
|
||
var _repeat_direction := 0
|
||
var _repeat_clock := 0.0
|
||
|
||
|
||
## Add the joypad buttons the built-in map omits. Returns a human-readable line,
|
||
## or "" if nothing needed adding — so a future Godot that ships these bindings
|
||
## makes this quietly stop reporting rather than double-binding.
|
||
static func bind_missing() -> String:
|
||
var added := PackedStringArray()
|
||
for pair in [["ui_accept", JOY_BUTTON_A, "Ⓐ"], ["ui_cancel", JOY_BUTTON_B, "Ⓑ"]]:
|
||
var action: String = pair[0]
|
||
var button: int = pair[1]
|
||
if not InputMap.has_action(action):
|
||
# Not a warning we can act on, but silence here would present as the
|
||
# original bug and send the next person back to the controller.
|
||
push_warning("gamepad: no such action %s -- pad button unbound" % action)
|
||
continue
|
||
if _has_button(action, button):
|
||
continue
|
||
var ev := InputEventJoypadButton.new()
|
||
ev.button_index = button
|
||
InputMap.action_add_event(action, ev)
|
||
added.append("%s -> %s" % [pair[2], action])
|
||
if added.is_empty():
|
||
return ""
|
||
return "pad: bound %s (Godot 4.7.2 binds no joypad button to either)" % \
|
||
", ".join(added)
|
||
|
||
|
||
static func _has_button(action: String, button: int) -> bool:
|
||
for e in InputMap.action_get_events(action):
|
||
if e is InputEventJoypadButton and e.button_index == button:
|
||
return true
|
||
return false
|
||
|
||
|
||
## True if this event should be acted on. Everything that is already an edge —
|
||
## keys, d-pad, mouse — passes straight through; only the analog stick is
|
||
## latched, and only on the two axes the navigation actions are bound to.
|
||
func accepts(event: InputEvent) -> bool:
|
||
if not (event is InputEventJoypadMotion):
|
||
return true
|
||
var axis: int = event.axis
|
||
if not STICK.has(axis):
|
||
return true
|
||
var value: float = event.axis_value
|
||
var direction := 0
|
||
if value >= ENTER:
|
||
direction = 1
|
||
elif value <= -ENTER:
|
||
direction = -1
|
||
|
||
if direction == 0:
|
||
# Neutral enough to re-arm? The gap between RELEASE and ENTER is the
|
||
# hysteresis band: inside it the stick is neither a new press nor
|
||
# released, so the latch is left exactly as it was.
|
||
if absf(value) <= RELEASE:
|
||
_latched[axis] = 0
|
||
return false
|
||
if int(_latched.get(axis, 0)) == direction:
|
||
return false # still held in the same direction: not a new press
|
||
_latched[axis] = direction
|
||
return true
|
||
|
||
|
||
## Which way a direction is being HELD right now, as -1 (up), 0 or +1 (down).
|
||
##
|
||
## 🔴 **Polled at the DEVICE, never through `Input.is_action_pressed`.** `ui_up`
|
||
## and `ui_down` are bound to the stick axis at Godot's 0.50 action deadzone,
|
||
## while this port steps at the game's measured 0.61. Polling the action would
|
||
## repeat throughout the 0.50–0.61 band — the exact band `ENTER` exists to
|
||
## exclude — so the repeat would contradict the threshold on the same stick.
|
||
## That is the input-map lesson again: assert the device, not the layer above it.
|
||
func held_direction() -> int:
|
||
# The stick, from the latch `accepts()` already maintains, so the repeat and
|
||
# the first step read one state and cannot disagree about hysteresis.
|
||
var stick := int(_latched.get(JOY_AXIS_LEFT_Y, 0))
|
||
if stick != 0:
|
||
return stick
|
||
for device in Input.get_connected_joypads():
|
||
if Input.is_joy_button_pressed(device, JOY_BUTTON_DPAD_UP):
|
||
return -1
|
||
if Input.is_joy_button_pressed(device, JOY_BUTTON_DPAD_DOWN):
|
||
return 1
|
||
if Input.is_key_pressed(KEY_UP):
|
||
return -1
|
||
if Input.is_key_pressed(KEY_DOWN):
|
||
return 1
|
||
return 0
|
||
|
||
|
||
## One repeat step, or 0. Call once per frame with the frame's delta.
|
||
##
|
||
## The FIRST step is not this function's: it comes from the event edge in
|
||
## `_unhandled_input`, and the clock below starts from that same frame, so a held
|
||
## direction gives one step now and the next only after `REPEAT_DELAY`. A change
|
||
## of direction restarts the delay rather than inheriting the old cadence.
|
||
func repeat_due(delta: float) -> int:
|
||
if not repeat_rate_known():
|
||
return 0
|
||
var direction := held_direction()
|
||
if direction == 0 or direction != _repeat_direction:
|
||
_repeat_direction = direction
|
||
_repeat_clock = 0.0
|
||
return 0
|
||
_repeat_clock += delta
|
||
if _repeat_clock < REPEAT_DELAY:
|
||
return 0
|
||
# Subtract rather than reset, so the cadence cannot drift with the frame rate
|
||
# -- at 140 fps and at 30 fps the same number of steps happen per second.
|
||
_repeat_clock -= REPEAT_INTERVAL
|
||
return direction
|
||
|
||
|
||
## The pads Godot can see, for the startup line. A run where the human believes
|
||
## a controller is connected and Godot disagrees should say so on its own,
|
||
## rather than presenting as unresponsive buttons.
|
||
static func report_devices() -> String:
|
||
var pads := Input.get_connected_joypads()
|
||
if pads.is_empty():
|
||
return "pad: none connected -- keyboard only (Enter/Space = Ⓐ, Escape = Ⓑ)"
|
||
var names := PackedStringArray()
|
||
for j in pads:
|
||
names.append("[%d] %s" % [j, Input.get_joy_name(j)])
|
||
return "pad: " + ", ".join(names)
|