diff --git a/.cursor/rules/godot-client-script-organization.md b/.cursor/rules/godot-client-script-organization.md index 168a2d6..3e8e95b 100644 --- a/.cursor/rules/godot-client-script-organization.md +++ b/.cursor/rules/godot-client-script-organization.md @@ -27,6 +27,10 @@ Use **sparingly** (e.g. shared config many scenes need). Default to **scene-loca - **One obvious concern per script** (picking vs network vs locomotion)—not one file per tiny helper. - **New work:** add `res://scripts/.gd` (or a subfolder when a feature set grows) rather than extending `main.gd` by default. +## Godot `.uid` companion files (Godot 4) + +Godot writes a **`*.gd.uid`** next to each script (editor import / asset scan). **Commit it with the `.gd`** in the same change: do not leave new scripts with untracked `.uid` files, and do **not** add `*.uid` to `.gitignore`—this repo already tracks hundreds of them for stable `uid://` references. Applies to `client/scripts/` and `client/test/` the same way. + ## Examples ```text diff --git a/AGENTS.md b/AGENTS.md index 854468d..ab415c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,3 +16,5 @@ Optional **personas** for Cursor. Enable by **@ mentioning** the rule in chat or Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). **Planning / implementation decisions** must be written into `docs/plans/` (and related docs)—[`.cursor/rules/planning-implementation-docs.md`](.cursor/rules/planning-implementation-docs.md). **Manual QA checklists** for user-visible ticketed work are generated during implementation at `docs/manual-qa/{KEY}.md` (same rule). **Automated tests (AAA, mandatory):** **C#** — every new or changed **`[Fact]` / `[Theory]`** method in **`*Tests.cs`** must use full **Arrange → Act → Assert**: the three **`// Arrange` / `// Act` / `// Assert`** labels, **Act** = behavior under test only, **Assert** = all expectations including **`ReadFromJsonAsync`** (etc.) for verification (no blank line required after the phase comments) — [csharp-style](.cursor/rules/csharp-style.md#unit-and-integration-tests-arrange-act-assert), [testing-expectations](.cursor/rules/testing-expectations.md); snippets **`xut`** / **`xutc`**. **GdUnit (`client/test/`)** — same AAA with **`# Arrange` / `# Act` / `# Assert`** — [gdscript-style](.cursor/rules/gdscript-style.md#gdunit-test-layout-aaa). **Godot client layout** (thin `main.gd`, split by concern): [`.cursor/rules/godot-client-script-organization.md`](.cursor/rules/godot-client-script-organization.md). **Git:** agents may **commit** at discretion on story/ticket work; **never** `git push` unless the user asks — [`.cursor/rules/commit-and-review.md`](.cursor/rules/commit-and-review.md). **Open PR:** when the user asks, use the **GitHub MCP** **`create_pull_request`** tool (`user-github`) with a title starting **`NEO-123:`** ([commit-and-review](.cursor/rules/commit-and-review.md)); **do not use `gh` CLI for GitHub operations in this repo**. **Story lifecycle:** kickoff [`.cursor/rules/story-kickoff.md`](.cursor/rules/story-kickoff.md); after merge / end of story — `checkout main`, `pull`, delete local story branch — [`.cursor/rules/story-end.md`](.cursor/rules/story-end.md). **Linear:** on **end story**, use **`AskQuestion`** multiple choice for **In Test** / **Done** / **Skip** when Agent mode supports it ([story-end](.cursor/rules/story-end.md) §4a); otherwise ask in prose. Wait for the choice (or the same message naming the state) **before** `save_issue`; do not guess. **PR / push text:** no “Made-with: Cursor” boilerplate (same file). **Commits tied to a Linear issue** must start the subject with the **issue id** and a colon (e.g. `NEO-8: …`). Branch naming and exceptions (`chore:` when there is no ticket) — [`.cursor/rules/linear-git-naming.md`](.cursor/rules/linear-git-naming.md). + +**Godot `*.uid`:** When adding or renaming scripts under `client/`, stage and commit the matching **`*.gd.uid`** in the **same commit** as the `.gd` file. These companion files are **tracked in git** (not gitignored) so `uid://` references stay stable across clones. See [godot-client-script-organization](.cursor/rules/godot-client-script-organization.md). diff --git a/bruno/neon-sprawl-server/ability-cast/Post cast happy.bru b/bruno/neon-sprawl-server/ability-cast/Post cast happy.bru index e076b31..07b2c64 100644 --- a/bruno/neon-sprawl-server/ability-cast/Post cast happy.bru +++ b/bruno/neon-sprawl-server/ability-cast/Post cast happy.bru @@ -22,6 +22,7 @@ body:json { tests { test("status 200", function () { // NEO-30 review follow-up: cast JSON contract unchanged (server comments only). + // Optional: NEON_SPRAWL_API_LOG=1 on server prints ability_cast_requested for accepted JSON. expect(res.getStatus()).to.equal(200); }); diff --git a/bruno/neon-sprawl-server/cooldown-snapshot/Get cooldown snapshot.bru b/bruno/neon-sprawl-server/cooldown-snapshot/Get cooldown snapshot.bru new file mode 100644 index 0000000..f2f3974 --- /dev/null +++ b/bruno/neon-sprawl-server/cooldown-snapshot/Get cooldown snapshot.bru @@ -0,0 +1,29 @@ +meta { + name: GET cooldown snapshot + type: http + seq: 1 +} + +docs { + NEO-32: expired slot entries are pruned when building the snapshot (server-side store hygiene). +} + +get { + url: {{baseUrl}}/game/players/dev-local-1/cooldown-snapshot + body: none + auth: none +} + +tests { + test("status 200", function () { + expect(res.getStatus()).to.equal(200); + }); + + test("schema and eight slots", function () { + const body = res.getBody(); + expect(body.schemaVersion).to.equal(1); + expect(body.playerId).to.equal("dev-local-1"); + expect(Array.isArray(body.slots)).to.equal(true); + expect(body.slots.length).to.equal(8); + }); +} diff --git a/client/scenes/main.tscn b/client/scenes/main.tscn index ee4f6ad..f260701 100644 --- a/client/scenes/main.tscn +++ b/client/scenes/main.tscn @@ -1147,3 +1147,17 @@ theme_override_constants/outline_size = 6 theme_override_font_sizes/font_size = 15 autowrap_mode = 3 text = "Cast: —" + +[node name="CooldownSlotsLabel" type="Label" parent="UICanvas" unique_id=9000006] +offset_left = 8.0 +offset_top = 384.0 +offset_right = 520.0 +offset_bottom = 460.0 +grow_horizontal = 0 +grow_vertical = 0 +theme_override_colors/font_color = Color(0.78, 0.92, 0.86, 1) +theme_override_colors/font_outline_color = Color(0.08, 0.08, 0.1, 1) +theme_override_constants/outline_size = 6 +theme_override_font_sizes/font_size = 14 +autowrap_mode = 3 +text = "Cooldowns: —" diff --git a/client/scripts/cooldown_snapshot_client.gd b/client/scripts/cooldown_snapshot_client.gd new file mode 100644 index 0000000..cbd6b14 --- /dev/null +++ b/client/scripts/cooldown_snapshot_client.gd @@ -0,0 +1,63 @@ +extends Node + +## NEO-32: prototype HTTP client for [code]GET /game/players/{id}/cooldown-snapshot[/code]. +signal snapshot_received(snapshot: Dictionary) + +@export var base_url: String = "http://127.0.0.1:5253" +@export var dev_player_id: String = "dev-local-1" +@export var injected_http: Node = null + +var _http: Node +var _busy: bool = false + + +func _ready() -> void: + if injected_http != null: + _http = injected_http + else: + _http = HTTPRequest.new() + add_child(_http) + if _http is HTTPRequest: + (_http as HTTPRequest).timeout = 30.0 + @warning_ignore("unsafe_method_access") + _http.request_completed.connect(_on_request_completed) + + +func request_sync_from_server() -> void: + if _busy: + return + _busy = true + var url := "%s/game/players/%s/cooldown-snapshot" % [_base_root(), _player_path_segment()] + var err: Error = _http.request(url) + if err != OK: + push_warning("CooldownSnapshotClient: GET failed to start (%s)" % err) + _busy = false + + +func _base_root() -> String: + return base_url.strip_edges().rstrip("/") + + +func _player_path_segment() -> String: + return dev_player_id.strip_edges() + + +func _on_request_completed( + result: int, response_code: int, _headers: PackedStringArray, body: PackedByteArray +) -> void: + _busy = false + if result != HTTPRequest.RESULT_SUCCESS: + push_warning("CooldownSnapshotClient: HTTP failed (result=%s)" % result) + return + if response_code == 404: + push_warning("CooldownSnapshotClient: HTTP 404 (player unknown)") + return + if response_code < 200 or response_code >= 300: + push_warning("CooldownSnapshotClient: HTTP %s" % response_code) + return + var text := body.get_string_from_utf8() + var parsed: Variant = JSON.parse_string(text) + if not parsed is Dictionary: + push_warning("CooldownSnapshotClient: non-JSON body") + return + snapshot_received.emit(parsed as Dictionary) diff --git a/client/scripts/cooldown_snapshot_client.gd.uid b/client/scripts/cooldown_snapshot_client.gd.uid new file mode 100644 index 0000000..6f00d9f --- /dev/null +++ b/client/scripts/cooldown_snapshot_client.gd.uid @@ -0,0 +1 @@ +uid://p8w2fcyiuvws diff --git a/client/scripts/cooldown_state.gd b/client/scripts/cooldown_state.gd new file mode 100644 index 0000000..d52f93a --- /dev/null +++ b/client/scripts/cooldown_state.gd @@ -0,0 +1,87 @@ +extends RefCounted + +## Local mirror for GET [code]/game/players/{id}/cooldown-snapshot[/code] (NEO-32). +## Uses [code]serverTimeUtc[/code] + receive tick to approximate server "now" between polls. + +const SLOT_COUNT: int = 8 +## Reject bogus [method Time.get_unix_time_from_datetime_string] results (failed parse → 0). +const MIN_VALID_UNIX_ANCHOR: float = 1_000_000_000.0 + +var _slot_end_unix: PackedFloat64Array = PackedFloat64Array() +var _server_unix_at_receive: float = 0.0 +var _ticks_msec_at_receive: int = 0 + + +func _init() -> void: + _slot_end_unix.resize(SLOT_COUNT) + for i in range(SLOT_COUNT): + _slot_end_unix[i] = 0.0 + + +func apply_snapshot(snapshot: Dictionary) -> void: + for i in range(SLOT_COUNT): + _slot_end_unix[i] = 0.0 + var st: Variant = snapshot.get("serverTimeUtc", null) + var anchor: float = 0.0 + if st is String: + var su: String = (st as String).strip_edges() + if not su.is_empty(): + anchor = Time.get_unix_time_from_datetime_string(su) + elif st is float: + anchor = st as float + elif st is int: + anchor = float(st as int) + if anchor < MIN_VALID_UNIX_ANCHOR: + anchor = Time.get_unix_time_from_system() + _server_unix_at_receive = anchor + _ticks_msec_at_receive = Time.get_ticks_msec() + var slots: Variant = snapshot.get("slots", []) + if slots is Array: + for item in slots as Array: + if not item is Dictionary: + continue + var d: Dictionary = item + var idx: int = int(d.get("slotIndex", -1)) + if idx < 0 or idx >= SLOT_COUNT: + continue + var end_v: Variant = d.get("cooldownEndsAtUtc", null) + if end_v is String and not (end_v as String).is_empty(): + var end_s: String = (end_v as String).strip_edges() + var end_unix: float = Time.get_unix_time_from_datetime_string(end_s) + if end_unix >= MIN_VALID_UNIX_ANCHOR: + _slot_end_unix[idx] = end_unix + + +func _effective_server_unix() -> float: + return _server_unix_at_receive + (Time.get_ticks_msec() - _ticks_msec_at_receive) * 0.001 + + +func remaining_for_slot(slot_index: int) -> float: + if slot_index < 0 or slot_index >= _slot_end_unix.size(): + return 0.0 + var end_u: float = _slot_end_unix[slot_index] + if end_u <= 0.0: + return 0.0 + return maxf(0.0, end_u - _effective_server_unix()) + + +func is_slot_cooling(slot_index: int) -> bool: + return remaining_for_slot(slot_index) > 0.0 + + +func any_slot_cooling() -> bool: + for i in range(_slot_end_unix.size()): + if remaining_for_slot(i) > 0.0: + return true + return false + + +func build_hud_line() -> String: + var parts: PackedStringArray = PackedStringArray() + for i in range(_slot_end_unix.size()): + var rem: float = remaining_for_slot(i) + if rem > 0.0: + parts.append("slot %d: %.1fs" % [i, rem]) + if parts.is_empty(): + return "Cooldowns: (ready)" + return "Cooldowns: " + ", ".join(parts) diff --git a/client/scripts/cooldown_state.gd.uid b/client/scripts/cooldown_state.gd.uid new file mode 100644 index 0000000..0805dd2 --- /dev/null +++ b/client/scripts/cooldown_state.gd.uid @@ -0,0 +1 @@ +uid://cl1m1cpb6dsua diff --git a/client/scripts/main.gd b/client/scripts/main.gd index 7a4c5f5..246c82f 100644 --- a/client/scripts/main.gd +++ b/client/scripts/main.gd @@ -40,6 +40,8 @@ const AUTH_SNAP_LOCOMOTION_VEL_HZ_SQ: float = 0.12 const PrototypeTargetConstants := preload("res://scripts/prototype_target_constants.gd") const HotbarCastSlotResolver := preload("res://scripts/hotbar_cast_slot_resolver.gd") +const CooldownStateScript := preload("res://scripts/cooldown_state.gd") +const COOLDOWN_REASON_ON_CD := "on_cooldown" ## Bump on each rejection so older one-shot timers do not clear a newer message. var _move_reject_msg_token: int = 0 @@ -69,6 +71,9 @@ var _dev_obstacle_smoke: Node3D var _hotbar_state: Node = null var _hotbar_client: Node = null var _ability_cast_client: Node = null +var _cooldown_state: RefCounted = null +var _cooldown_client: Node = null +var _cooldown_poll_timer: Timer = null @onready var _camera: Camera3D = $World/IsometricFollowCamera/Camera3D @onready var _world: Node3D = $World @@ -82,6 +87,7 @@ var _ability_cast_client: Node = null @onready var _player_pos_label: Label = $UICanvas/PlayerPositionLabel @onready var _target_lock_label: Label = $UICanvas/TargetLockLabel @onready var _cast_feedback_label: Label = $UICanvas/CastFeedbackLabel +@onready var _cooldown_slots_label: Label = $UICanvas/CooldownSlotsLabel @onready var _target_client: Node = $TargetSelectionClient @onready var _interaction_client: Node = $InteractionRequestClient @onready var _floor: StaticBody3D = $World/NavigationRegion3D/Floor @@ -143,6 +149,9 @@ func _physics_process(_delta: float) -> void: var p: Vector3 = _player.global_position _player_pos_label.text = _build_player_position_text(p) _render_target_lock_label(p) + if _cooldown_state != null and _cooldown_state.has_method("any_slot_cooling"): + if bool(_cooldown_state.call("any_slot_cooling")): + _render_cooldown_slots_label() ## HUD: client position on top, and (once a `move-stream` / boot GET has landed) the @@ -259,6 +268,83 @@ func _setup_hotbar_loadout_sync() -> void: _hotbar_client.call("set_hotbar_state", _hotbar_state) if _hotbar_client.has_method("request_sync_from_server"): _hotbar_client.call("request_sync_from_server") + _setup_cooldown_sync() + + +func _setup_cooldown_sync() -> void: + # NEO-32: server cooldown snapshot + local mirror for HUD and cast spam guard. + _cooldown_state = CooldownStateScript.new() + _cooldown_client = load("res://scripts/cooldown_snapshot_client.gd").new() + _cooldown_client.name = "CooldownSnapshotClient" + add_child(_cooldown_client) + if is_instance_valid(_authority): + var authority_base_url: Variant = _authority.get("base_url") + var authority_player_id: Variant = _authority.get("dev_player_id") + if authority_base_url is String and not (authority_base_url as String).is_empty(): + _cooldown_client.set("base_url", authority_base_url) + if authority_player_id is String and not (authority_player_id as String).is_empty(): + _cooldown_client.set("dev_player_id", authority_player_id) + if _cooldown_client.has_signal("snapshot_received"): + _cooldown_client.connect( + "snapshot_received", Callable(self, "_on_cooldown_snapshot_received") + ) + if _hotbar_client.has_signal("loadout_changed"): + _hotbar_client.connect( + "loadout_changed", Callable(self, "_on_hotbar_loadout_changed_sync_cooldown") + ) + _ensure_cooldown_poll_timer() + + +func _ensure_cooldown_poll_timer() -> void: + if is_instance_valid(_cooldown_poll_timer): + return + _cooldown_poll_timer = Timer.new() + _cooldown_poll_timer.name = "CooldownPollTimer" + _cooldown_poll_timer.one_shot = true + _cooldown_poll_timer.wait_time = 0.25 + _cooldown_poll_timer.timeout.connect(_on_cooldown_poll_timeout) + add_child(_cooldown_poll_timer) + + +func _on_hotbar_loadout_changed_sync_cooldown(_loadout: Dictionary) -> void: + if ( + is_instance_valid(_cooldown_client) + and _cooldown_client.has_method("request_sync_from_server") + ): + _cooldown_client.call("request_sync_from_server") + + +func _on_cooldown_poll_timeout() -> void: + if ( + is_instance_valid(_cooldown_client) + and _cooldown_client.has_method("request_sync_from_server") + ): + _cooldown_client.call("request_sync_from_server") + + +func _on_cooldown_snapshot_received(snapshot: Dictionary) -> void: + if _cooldown_state == null or not _cooldown_state.has_method("apply_snapshot"): + return + _cooldown_state.call("apply_snapshot", snapshot) + _render_cooldown_slots_label() + if not _cooldown_state.has_method("any_slot_cooling"): + return + if bool(_cooldown_state.call("any_slot_cooling")): + if is_instance_valid(_cooldown_poll_timer) and _cooldown_poll_timer.is_stopped(): + _cooldown_poll_timer.start() + return + if is_instance_valid(_cooldown_poll_timer): + _cooldown_poll_timer.stop() + + +func _render_cooldown_slots_label() -> void: + if not is_instance_valid(_cooldown_slots_label): + return + if _cooldown_state == null or not _cooldown_state.has_method("build_hud_line"): + return + var line: Variant = _cooldown_state.call("build_hud_line") + if line is String: + _cooldown_slots_label.text = line as String ## Combines cached server state (`_last_target_state`) with per-anchor horizontal @@ -299,6 +385,9 @@ func _on_cast_result_received(accepted: bool, reason_code: String) -> void: return if accepted: _cast_feedback_label.text = "Cast: accepted" + if is_instance_valid(_cooldown_client): + if _cooldown_client.has_method("request_sync_from_server"): + _cooldown_client.call("request_sync_from_server") return var rc := reason_code.strip_edges() if rc.is_empty(): @@ -384,6 +473,14 @@ func _request_hotbar_cast_slot(slot_index: int) -> void: var ability_id: String = outcome[HotbarCastSlotResolver.KEY_ABILITY_ID] as String var resolved_slot: int = int(outcome.get(HotbarCastSlotResolver.KEY_SLOT_INDEX, slot_index)) var target_id: Variant = outcome.get(HotbarCastSlotResolver.KEY_TARGET_ID, null) + if _cooldown_state != null and _cooldown_state.has_method("is_slot_cooling"): + if bool(_cooldown_state.call("is_slot_cooling", resolved_slot)): + if is_instance_valid(_cast_feedback_label): + _cast_feedback_label.text = ( + "ability_cast_denied: %s (client guard)" % COOLDOWN_REASON_ON_CD + ) + push_warning("ability_cast_denied reasonCode=%s (client guard)" % COOLDOWN_REASON_ON_CD) + return var started: bool = false if is_instance_valid(_ability_cast_client) and _ability_cast_client.has_method("request_cast"): started = bool( diff --git a/client/test/cooldown_state_test.gd b/client/test/cooldown_state_test.gd new file mode 100644 index 0000000..1cc4ae9 --- /dev/null +++ b/client/test/cooldown_state_test.gd @@ -0,0 +1,51 @@ +extends GdUnitTestSuite + +## Covers [code]cooldown_state.gd[/code] snapshot math (NEO-32). +## Paired with [code]main.gd[/code] wiring when that file changes (pre-commit). +const CooldownStateScript := preload("res://scripts/cooldown_state.gd") + + +func test_remaining_is_zero_when_end_before_server_time() -> void: + # Arrange — server anchor after end → slot reads as ready. + var state: RefCounted = CooldownStateScript.new() + var snap := { + "serverTimeUtc": "2026-01-01T12:01:00.000Z", + "slots": [{"slotIndex": 0, "cooldownEndsAtUtc": "2026-01-01T12:00:05.000Z"}], + } + + # Act + state.call("apply_snapshot", snap) + var rem: float = state.call("remaining_for_slot", 0) as float + + # Assert + assert_that(rem).is_equal(0.0) + + +func test_remaining_positive_when_end_after_server_time() -> void: + # Arrange + var state: RefCounted = CooldownStateScript.new() + var snap := { + "serverTimeUtc": "2026-01-01T12:00:00.000Z", + "slots": [{"slotIndex": 0, "cooldownEndsAtUtc": "2026-01-01T12:00:10.000Z"}], + } + + # Act + state.call("apply_snapshot", snap) + var rem: float = state.call("remaining_for_slot", 0) as float + + # Assert + assert_that(rem).is_greater(9.0) + assert_that(rem).is_less(11.0) + + +func test_invalid_server_time_string_does_not_lock_slot_ready() -> void: + # Arrange: bogus ISO parses as 0; anchor must fall back so slot 0 is not stuck cooling. + var state: RefCounted = CooldownStateScript.new() + var snap := {"serverTimeUtc": "__not_iso__", "slots": [{"slotIndex": 0}]} + + # Act + state.call("apply_snapshot", snap) + var cooling: bool = bool(state.call("is_slot_cooling", 0)) + + # Assert + assert_that(cooling).is_false() diff --git a/client/test/cooldown_state_test.gd.uid b/client/test/cooldown_state_test.gd.uid new file mode 100644 index 0000000..9973480 --- /dev/null +++ b/client/test/cooldown_state_test.gd.uid @@ -0,0 +1 @@ +uid://bkbdb41gqg7g diff --git a/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md b/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md index a5b9329..1a796d8 100644 --- a/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md +++ b/docs/decomposition/modules/E1_M4_AbilityInputScaffold.md @@ -42,7 +42,7 @@ Epic 1 **Slice 3** — `ability_cast_requested`, `ability_cast_denied` with reas ## Implementation snapshot -- **Current state:** NEO-29 landed prototype `HotbarLoadout` v1 contract and hydration path (`GET`/`POST /game/players/{id}/hotbar-loadout`, fixed 8 slots, deny reason codes). NEO-31 landed prototype **`POST /game/players/{id}/ability-cast`** plus client digit hotbar → cast payload wiring (target id from server-ack target state). **NEO-28** extends that cast POST with **server lock + registry + range** validation (`invalid_target`, `out_of_range`) and a **HUD cast feedback** line on deny/accept. **NEO-30** documents Epic 1 Slice 3 **telemetry hook sites** for `ability_cast_requested` / `ability_cast_denied`: comment markers + payload notes in [`AbilityCastApi.cs`](../../../server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs); client dev **`print`** / **`push_warning`** in [`main.gd`](../../../client/scripts/main.gd) and [`ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd) (all **TODO(E9.M1)** for cataloged ingest). `CooldownSnapshot` wiring is still pending ([NEO-32](https://linear.app/neon-sprawl/issue/NEO-32/e1m4-04-cooldownsnapshot-sync-slot-presentation)). +- **Current state:** NEO-29 landed prototype `HotbarLoadout` v1 contract and hydration path (`GET`/`POST /game/players/{id}/hotbar-loadout`, fixed 8 slots, deny reason codes). NEO-31 landed prototype **`POST /game/players/{id}/ability-cast`** plus client digit hotbar → cast payload wiring (target id from server-ack target state). **NEO-28** extends that cast POST with **server lock + registry + range** validation (`invalid_target`, `out_of_range`) and a **HUD cast feedback** line on deny/accept. **NEO-30** documents Epic 1 Slice 3 **telemetry hook sites** for `ability_cast_requested` / `ability_cast_denied`: comment markers + payload notes in [`AbilityCastApi.cs`](../../../server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs); client dev **`print`** / **`push_warning`** in [`main.gd`](../../../client/scripts/main.gd) and [`ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd) (all **TODO(E9.M1)** for cataloged ingest). **NEO-32** landed **`CooldownSnapshot`**: `GET /game/players/{id}/cooldown-snapshot` (`CooldownSnapshotResponse` v1: `serverTimeUtc`, eight `slots` with optional `cooldownEndsAtUtc`), prototype **global cooldown** on successful accept, JSON deny **`on_cooldown`**, Godot [`cooldown_snapshot_client.gd`](../../../client/scripts/cooldown_snapshot_client.gd) + [`cooldown_state.gd`](../../../client/scripts/cooldown_state.gd) + **`CooldownSlotsLabel`** HUD + client cast guard ([`main.gd`](../../../client/scripts/main.gd)); plan [NEO-32](../../plans/NEO-32-implementation-plan.md), manual QA [`NEO-32.md`](../../manual-qa/NEO-32.md). - **Prototype persistence policy (NEO-29):** per-player loadout key; Postgres when `ConnectionStrings:NeonSprawl` exists, in-memory fallback otherwise. - **Prototype backlog:** [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md) defines five vertical slices from hotbar loadout contract to cast telemetry hooks. - **Dependency expectation:** first implementation stories assume E1.M3 target selection flow exists and E5.M1 provides minimum cast accept/deny contract. @@ -58,7 +58,7 @@ Parent epic: [Epic 1 — Core Player Runtime](https://linear.app/neon-sprawl/pro | **E1M4-01** | [NEO-29](https://linear.app/neon-sprawl/issue/NEO-29/e1m4-01-hotbarloadout-v1-contract-baseline-persistence-path) — `HotbarLoadout` v1 contract + baseline persistence path | | **E1M4-02** | [NEO-31](https://linear.app/neon-sprawl/issue/NEO-31/e1m4-02-input-to-abilitycastrequest-path) — Input to `AbilityCastRequest` path | | **E1M4-03** | [NEO-28](https://linear.app/neon-sprawl/issue/NEO-28/e1m4-03-combat-acceptdeny-integration-reason-code-ux) — Combat accept/deny integration + reason-code UX | -| **E1M4-04** | TBD — `CooldownSnapshot` sync + slot presentation | +| **E1M4-04** | [NEO-32](https://linear.app/neon-sprawl/issue/NEO-32/e1m4-04-cooldownsnapshot-sync-slot-presentation) — `CooldownSnapshot` sync + slot presentation | | **E1M4-05** | [NEO-30](https://linear.app/neon-sprawl/issue/NEO-30/e1m4-05-slice-3-telemetry-hooks-for-cast-funnel) — Slice 3 telemetry hooks for cast funnel | Issues should carry label **`E1.M4`** per [Linear alignment](../README.md#linear-alignment). diff --git a/docs/decomposition/modules/documentation_and_implementation_alignment.md b/docs/decomposition/modules/documentation_and_implementation_alignment.md index 8a2193d..c9dd5b7 100644 --- a/docs/decomposition/modules/documentation_and_implementation_alignment.md +++ b/docs/decomposition/modules/documentation_and_implementation_alignment.md @@ -49,7 +49,7 @@ Rows appear when work starts; default for unlisted modules is **Planned** / not | E1.M1 | Ready | Prototype milestone **Done** ([E1.M1](https://linear.app/neon-sprawl/project/e1m1-inputandmovementruntime-20eb28dd3db4)). Authoritative `PositionState` + **MoveCommand** over HTTP (JSON v1 snap); **in-memory** store by default, **Postgres** when configured ([NEO-8](../../plans/NEO-8-implementation-plan.md)); shared **NpgsqlDataSource** disposed on host shutdown ([NEO-13](../../plans/NEO-13-implementation-plan.md)); Godot sync + path-follow ([NEO-7](../../plans/NEO-7-implementation-plan.md), [NEO-11](../../plans/NEO-11-implementation-plan.md)); **InteractionRequest** + horizontal range ([NEO-9](../../plans/NEO-9-implementation-plan.md)). Follow-on: prediction/reconciliation, Slice 1 telemetry, Protobuf wire per [contracts.md](contracts.md). | [NEO-6](../../plans/NEO-6-implementation-plan.md), [NEO-7](../../plans/NEO-7-implementation-plan.md), [NEO-8](../../plans/NEO-8-implementation-plan.md), [NEO-9](../../plans/NEO-9-implementation-plan.md), [NEO-10](../../plans/NEO-10-implementation-plan.md), [NEO-11](../../plans/NEO-11-implementation-plan.md), [NEO-13](../../plans/NEO-13-implementation-plan.md); `server/NeonSprawl.Server/Game/PositionState/`, `Game/Interaction/`; [server README](../../../server/README.md) | | E1.M2 | Ready | **Slice 2 prototype slice closed:** follow + `CameraState` ([NEO-15](https://linear.app/neon-sprawl/issue/NEO-15)); zoom bands ([NEO-16](https://linear.app/neon-sprawl/issue/NEO-16)); occlusion ([NEO-17](https://linear.app/neon-sprawl/issue/NEO-17)); occluder pick-through ([NEO-20](https://linear.app/neon-sprawl/issue/NEO-20)); contracts + hardening ([NEO-18](https://linear.app/neon-sprawl/issue/NEO-18)). Client-local; no server use of camera pose. | [NEO-15](../../plans/NEO-15-implementation-plan.md), [NEO-16](../../plans/NEO-16-implementation-plan.md), [NEO-17](../../plans/NEO-17-implementation-plan.md), [NEO-18](../../plans/NEO-18-implementation-plan.md), [NEO-20](../../plans/NEO-20-implementation-plan.md); `client/scripts/isometric_follow_camera.gd`, `camera_state.gd`, `zoom_band_config.gd`, `occlusion_policy.gd`, `ground_pick.gd`; [E1_M2_IsometricCameraController.md](E1_M2_IsometricCameraController.md) | | E1.M3 | In Progress | **NEO-23 landed:** JSON v1 targeting read + select (`GET`/`POST …/target`, `Game/Targeting/`, [NEO-23](../../plans/NEO-23-implementation-plan.md)) — `PlayerTargetStateResponse` / soft lock / `reasonCode` denials; wire name differs from illustrative **`TargetState`** in module doc (called out in plan + README). **NEO-24 landed:** client tab-target + lock HUD synced to server ([NEO-24](../../plans/NEO-24-implementation-plan.md)) — `TargetSelectionClient` ([`client/scripts/target_selection_client.gd`](../../../client/scripts/target_selection_client.gd)), Tab / Esc bindings, `TargetLockLabel` HUD, hybrid movement-triggered refresh via new `PositionAuthorityClient.authoritative_ack` signal (fires on every server-confirmed position, boot + `move-stream` 200) with a 250 ms cooldown; manual QA in [`docs/manual-qa/NEO-24.md`](../../manual-qa/NEO-24.md). **NEO-25 landed:** versioned **`GET /game/world/interactables`** ([NEO-25](../../plans/NEO-25-implementation-plan.md)) — `InteractablesListResponse` / `InteractablesWorldApi` in `server/NeonSprawl.Server/Game/Interaction/`; Godot `interactables_catalog_client.gd` + `interactable_world_builder.gd` (fetch-driven props + glow); [server README — Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25). **NEO-26 landed:** prototype **`SelectionEvent`** — **`TargetSelectionClient.selection_event`** ([NEO-26](../../plans/NEO-26-implementation-plan.md)) when **`lockedTargetId`** changes; optional **`log_selection_events`**. **NEO-27 landed:** Slice 3 telemetry hook sites documented — `selection_event` maps to product `target_changed` in `target_selection_client.gd`; server lock transition hook comments in `InMemoryPlayerTargetLockStore`; reserved `ability_cast_requested` / `ability_cast_denied` comments in `client/scripts/main.gd` (all TODO(E9.M1)); see [NEO-27](../../plans/NEO-27-implementation-plan.md) and [`docs/manual-qa/NEO-27.md`](../../manual-qa/NEO-27.md). **Follow-on / still open:** richer **`InteractableDescriptor`** consumers beyond list projection + existing `POST …/interact`; production telemetry ingest/catalog after E9.M1. **Precursor (E1.M1):** [NEO-9](../../plans/NEO-9-implementation-plan.md) `POST …/interact`. | Linear [NEO-24](https://linear.app/neon-sprawl/issue/NEO-24)–[NEO-27](https://linear.app/neon-sprawl/issue/NEO-27); [E1_M3_InteractionAndTargetingLayer.md](E1_M3_InteractionAndTargetingLayer.md); [E1M3 prototype backlog](../../plans/E1M3-prototype-backlog.md); [server README — Targeting](../../../server/README.md#targeting-neo-23), [Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25), [Interaction](../../../server/README.md#interaction-neo-9) | -| E1.M4 | In Progress | **NEO-29 landed:** prototype `HotbarLoadout` v1 server contract (`GET`/`POST /game/players/{id}/hotbar-loadout`) with stable deny reason codes, per-player scope, and persistence policy matching NEO-8/NS-17 (Postgres when configured, in-memory fallback otherwise). Client boot hydration is wired via `hotbar_loadout_client.gd` + `hotbar_state.gd` from `main.gd`; manual QA checklist created. **NEO-31 landed:** prototype **`POST /game/players/{id}/ability-cast`**, digit-key cast wiring from `main.gd`, `ability_cast_client.gd`, and `hotbar_cast_slot_resolver.gd` (target id from `lockedTargetId` in cached target state); GdUnit covers resolver + HTTP client; manual QA [NEO-31](../../manual-qa/NEO-31.md). **NEO-28 landed:** cast POST validates **lock + registry + range** (`invalid_target`, `out_of_range`); **`AbilityCastClient.cast_result_received`** + **`CastFeedbackLabel`** HUD line; manual QA [NEO-28](../../manual-qa/NEO-28.md). **NEO-30 landed:** Slice 3 cast funnel telemetry **hook-site comments** in [`AbilityCastApi.cs`](../../../server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs) (`ability_cast_requested` on authoritative accept, `ability_cast_denied` + non-empty `reasonCode` on each JSON deny branch); client dev hooks unchanged; manual QA [NEO-30](../../manual-qa/NEO-30.md); plan [NEO-30](../../plans/NEO-30-implementation-plan.md). **Still open:** `CooldownSnapshot` sync ([NEO-32](https://linear.app/neon-sprawl/issue/NEO-32/e1m4-04-cooldownsnapshot-sync-slot-presentation)). | [NEO-29](../../plans/NEO-29-implementation-plan.md), [NEO-31](../../plans/NEO-31-implementation-plan.md), [NEO-28](../../plans/NEO-28-implementation-plan.md), [NEO-30](../../plans/NEO-30-implementation-plan.md); [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md); [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md); `server/NeonSprawl.Server/Game/AbilityInput/`; [`client/scripts/hotbar_loadout_client.gd`](../../../client/scripts/hotbar_loadout_client.gd), [`client/scripts/hotbar_state.gd`](../../../client/scripts/hotbar_state.gd), [`client/scripts/ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd), [`client/scripts/hotbar_cast_slot_resolver.gd`](../../../client/scripts/hotbar_cast_slot_resolver.gd); [server README — Hotbar loadout](../../../server/README.md#hotbar-loadout-neo-29), [Ability cast (NEO-31)](../../../server/README.md#ability-cast-neo-31) | +| E1.M4 | In Progress | **NEO-29 landed:** prototype `HotbarLoadout` v1 server contract (`GET`/`POST /game/players/{id}/hotbar-loadout`) with stable deny reason codes, per-player scope, and persistence policy matching NEO-8/NS-17 (Postgres when configured, in-memory fallback otherwise). Client boot hydration is wired via `hotbar_loadout_client.gd` + `hotbar_state.gd` from `main.gd`; manual QA checklist created. **NEO-31 landed:** prototype **`POST /game/players/{id}/ability-cast`**, digit-key cast wiring from `main.gd`, `ability_cast_client.gd`, and `hotbar_cast_slot_resolver.gd` (target id from `lockedTargetId` in cached target state); GdUnit covers resolver + HTTP client; manual QA [NEO-31](../../manual-qa/NEO-31.md). **NEO-28 landed:** cast POST validates **lock + registry + range** (`invalid_target`, `out_of_range`); **`AbilityCastClient.cast_result_received`** + **`CastFeedbackLabel`** HUD line; manual QA [NEO-28](../../manual-qa/NEO-28.md). **NEO-30 landed:** Slice 3 cast funnel telemetry **hook-site comments** in [`AbilityCastApi.cs`](../../../server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs) (`ability_cast_requested` on authoritative accept, `ability_cast_denied` + non-empty `reasonCode` on each JSON deny branch); client dev hooks unchanged; manual QA [NEO-30](../../manual-qa/NEO-30.md); plan [NEO-30](../../plans/NEO-30-implementation-plan.md). **NEO-32 landed:** `GET /game/players/{id}/cooldown-snapshot` + `on_cooldown` cast deny + prototype global cooldown commit; [`cooldown_snapshot_client.gd`](../../../client/scripts/cooldown_snapshot_client.gd), [`cooldown_state.gd`](../../../client/scripts/cooldown_state.gd), **`CooldownSlotsLabel`** in [`main.gd`](../../../client/scripts/main.gd); manual QA [NEO-32](../../manual-qa/NEO-32.md); plan [NEO-32](../../plans/NEO-32-implementation-plan.md). | [NEO-29](../../plans/NEO-29-implementation-plan.md), [NEO-31](../../plans/NEO-31-implementation-plan.md), [NEO-28](../../plans/NEO-28-implementation-plan.md), [NEO-30](../../plans/NEO-30-implementation-plan.md), [NEO-32](../../plans/NEO-32-implementation-plan.md); [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md); [E1M4 prototype backlog](../../plans/E1M4-prototype-backlog.md); `server/NeonSprawl.Server/Game/AbilityInput/`; [`client/scripts/hotbar_loadout_client.gd`](../../../client/scripts/hotbar_loadout_client.gd), [`client/scripts/hotbar_state.gd`](../../../client/scripts/hotbar_state.gd), [`client/scripts/ability_cast_client.gd`](../../../client/scripts/ability_cast_client.gd), [`client/scripts/hotbar_cast_slot_resolver.gd`](../../../client/scripts/hotbar_cast_slot_resolver.gd), [`client/scripts/cooldown_snapshot_client.gd`](../../../client/scripts/cooldown_snapshot_client.gd), [`client/scripts/cooldown_state.gd`](../../../client/scripts/cooldown_state.gd); [server README — Hotbar loadout](../../../server/README.md#hotbar-loadout-neo-29), [Ability cast (NEO-31)](../../../server/README.md#ability-cast-neo-31), [Cooldown snapshot (NEO-32)](../../../server/README.md#cooldown-snapshot-neo-32) | --- diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 61515a9..aa9d573 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -21,7 +21,7 @@ Fleshed-out scope, contracts, and integration notes live in **per-module documen **E1.M3 note:** Decomposition expanded in [E1_M3_InteractionAndTargetingLayer.md](E1_M3_InteractionAndTargetingLayer.md) (E1.M1 vs E1.M3 boundary, contract sketches, Slice 3 alignment). **Partial (NEO-23):** versioned JSON v1 **`PlayerTargetStateResponse`** + **`POST …/target/select`** under `server/NeonSprawl.Server/Game/Targeting/` ([NEO-23](../../plans/NEO-23-implementation-plan.md); [server README — Targeting](../../../server/README.md#targeting-neo-23)) — throwaway HTTP spike per [contracts.md](contracts.md). **Partial (NEO-25):** versioned **`GET /game/world/interactables`** + `InteractablesListDtos` / `InteractablesWorldApi` in `Game/Interaction/`; Godot `interactables_catalog_client.gd` + `interactable_world_builder.gd` ([NEO-25](../../plans/NEO-25-implementation-plan.md); [server README — Interactable descriptors](../../../server/README.md#interactable-descriptors-neo-25)). **NEO-26 (prototype `SelectionEvent`):** Godot **`TargetSelectionClient.selection_event`** on **`lockedTargetId`** changes ([NEO-26](../../plans/NEO-26-implementation-plan.md)). **Follow-on / in progress:** richer multi-consumer **`InteractableDescriptor`** targeting on later Linear issues. **Precursor (E1.M1):** **`InteractionRequest`** + horizontal reach ([NEO-9](../../plans/NEO-9-implementation-plan.md); `Game/Interaction/`, `Game/World/HorizontalReach.cs`). -**E1.M4 note:** Vertical-slice decomposition is defined in [E1M4-prototype-backlog.md](../../plans/E1M4-prototype-backlog.md) with story slugs **E1M4-01** through **E1M4-05** (loadout contract, cast path, accept/deny UX, cooldown sync, telemetry hooks). **NEO-29** started implementation with `HotbarLoadout` v1 server APIs + persistence wiring and client hydration; **NEO-31** added the prototype cast POST + client digit-key path and resolver tests; **NEO-28** added server target lock + range gates and client cast feedback UX; **NEO-30** documented Epic 1 Slice 3 cast-funnel telemetry hook sites (comment-only, `AbilityCastApi`) — module status remains **In Progress**; see [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md), [NEO-29 plan](../../plans/NEO-29-implementation-plan.md), [NEO-31 plan](../../plans/NEO-31-implementation-plan.md), [NEO-28 plan](../../plans/NEO-28-implementation-plan.md), and [NEO-30 plan](../../plans/NEO-30-implementation-plan.md). +**E1.M4 note:** Vertical-slice decomposition is defined in [E1M4-prototype-backlog.md](../../plans/E1M4-prototype-backlog.md) with story slugs **E1M4-01** through **E1M4-05** (loadout contract, cast path, accept/deny UX, cooldown sync, telemetry hooks). **NEO-29** started implementation with `HotbarLoadout` v1 server APIs + persistence wiring and client hydration; **NEO-31** added the prototype cast POST + client digit-key path and resolver tests; **NEO-28** added server target lock + range gates and client cast feedback UX; **NEO-30** documented Epic 1 Slice 3 cast-funnel telemetry hook sites (comment-only, `AbilityCastApi`); **NEO-32** added `GET …/cooldown-snapshot`, `on_cooldown` deny, and client HUD + poll sync — module status remains **In Progress**; see [E1_M4_AbilityInputScaffold.md](E1_M4_AbilityInputScaffold.md), [NEO-29 plan](../../plans/NEO-29-implementation-plan.md), [NEO-31 plan](../../plans/NEO-31-implementation-plan.md), [NEO-28 plan](../../plans/NEO-28-implementation-plan.md), [NEO-30 plan](../../plans/NEO-30-implementation-plan.md), and [NEO-32 plan](../../plans/NEO-32-implementation-plan.md). ### Epic 2 — Skills and Progression Framework diff --git a/docs/manual-qa/NEO-30.md b/docs/manual-qa/NEO-30.md index 784285c..1eaf29d 100644 --- a/docs/manual-qa/NEO-30.md +++ b/docs/manual-qa/NEO-30.md @@ -10,13 +10,14 @@ ## 1) Code / docs sanity -- [ ] Open `server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs` and confirm **NEO-30** comments mark **`ability_cast_denied`** on each `Results.Json` deny and **`ability_cast_requested`** on the final accept return; each deny branch notes **TODO(E9.M1)**. +- [ ] Open `server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs` and confirm **NEO-30** comments mark **`ability_cast_denied`** on each JSON deny return and **`ability_cast_requested`** on the final accept return; each deny branch notes **TODO(E9.M1)**. - [ ] Confirm **400** / **404** early returns are documented as **not** Slice 3 `ability_cast_denied` JSON paths. - [ ] Skim `docs/decomposition/modules/E1_M4_AbilityInputScaffold.md` — snapshot mentions NEO-30 hook file paths; **E1M4-05** row links to Linear **NEO-30**. ## 2) Client hook vocabulary (regression with NEO-31 / NEO-28) - [ ] With server running and slot **0** bound to `prototype_pulse`, **Tab** lock **alpha**, press **1**: Godot Output line starts with **`ability_cast_requested`** and includes `slot=0`, `ability_id=prototype_pulse`, `targetId=` consistent with HUD lock. +- [ ] **Optional (server stdout):** same scenario with **`NEON_SPRAWL_API_LOG=1`** (see [server README — Run](../../server/README.md)) — server console shows **`[ability-cast] ability_cast_requested`** for that accept (Slice 3 hook name alignment). - [ ] **Without** lock (or wrong target), press **1**: **`CastFeedbackLabel`** shows **`ability_cast_denied: …`** with a **non-empty** reason; Output warning includes **`ability_cast_denied`** and **`reasonCode=`** (see [`docs/manual-qa/NEO-28.md`](NEO-28.md) for concrete cases). ## 3) Server JSON deny (reason non-empty) diff --git a/docs/manual-qa/NEO-32.md b/docs/manual-qa/NEO-32.md new file mode 100644 index 0000000..96ce6ab --- /dev/null +++ b/docs/manual-qa/NEO-32.md @@ -0,0 +1,11 @@ +# Manual QA — NEO-32 (CooldownSnapshot + slot HUD) + +Prereq: game server running (`NeonSprawl.Server`), client pointed at same `base_url` / `dev_player_id` as dev player with position + hotbar seed. + +1. **Cooling HUD after accept** — Tab-lock a prototype target in range, bind slot 0 to `prototype_pulse` if needed, press `1` to cast. Expect `Cast: accepted` and **Cooldowns:** line to show `slot 0: ~3.0s` (counts down). After ~3s expect `Cooldowns: (ready)`. + +2. **Server deny on spam** — Immediately double-tap cast during cooling (or remove client guard temporarily): second attempt should show `ability_cast_denied: on_cooldown` (server) on the cast feedback line when POST completes. + +3. **Client guard** — While slot 0 shows cooling, press `1` repeatedly. Expect **`ability_cast_denied: on_cooldown (client guard)`** on **`CastFeedbackLabel`** on most presses (local mirror blocks the POST). **Optional:** run the server with **`NEON_SPRAWL_API_LOG=1`** (or launch profile **`http+apiLog`**) — each cast that reaches the server and returns JSON prints **`[ability-cast] ability_cast_denied …`** or **`ability_cast_requested`** to the process console, so rapid `1` with the guard on should produce **fewer** lines than without the guard. **Optional proof the server still enforces cooldown:** in Bruno (or `curl`), send **`POST …/ability-cast`** twice in a row with the same valid body while the snapshot still shows slot 0 cooling — second response **`accepted": false`**, **`reasonCode": "on_cooldown"`** (same contract as step 2). + +4. **Reconnect / rehydrate** — With slot 0 mid-cooldown, restart the client (or reload scene) while server keeps running; after boot expect cooldown line to match server within one GET cycle (same dev player id). diff --git a/docs/plans/NEO-32-implementation-plan.md b/docs/plans/NEO-32-implementation-plan.md new file mode 100644 index 0000000..62537e7 --- /dev/null +++ b/docs/plans/NEO-32-implementation-plan.md @@ -0,0 +1,110 @@ +# NEO-32 implementation plan — CooldownSnapshot sync + slot presentation + +## Story reference + +- **Key:** NEO-32 +- **Title:** E1M4-04: CooldownSnapshot sync + slot presentation +- **Linear:** https://linear.app/neon-sprawl/issue/NEO-32/e1m4-04-cooldownsnapshot-sync-slot-presentation +- **Project:** E1.M4 — AbilityInputScaffold · **Label:** E1.M4 + +## Kickoff clarifications + +**Asked (transport):** Initial multiple-choice offered “dedicated GET”, “embed in `HotbarLoadoutResponse`”, or “hybrid”. User asked for a recommendation; agent recommended **dedicated GET** (smaller poll payload, keeps hotbar loadout schema focused on bindings). User then **confirmed dedicated GET** for the plan. + +**Asked (duration):** Global constant vs per-ability registry. User selected **one global prototype cooldown duration** for all known abilities (server-side constant until E5.M1 catalog). + +**Linear note:** Issue still lists **blocked by NEO-28**; repo work for NEO-28 is already described as landed in decomposition/docs. Clear the Linear blocker when you consider that dependency satisfied. + +## Goal, scope, and out-of-scope + +**Goal:** Add a `CooldownSnapshot` wire contract and a server-backed update path so the hotbar reflects cooldown truth; gate repeat casts while a slot is cooling with synchronized server deny behavior and client presentation. + +**In scope (from Linear):** + +- Define `CooldownSnapshot` prototype fields and a **GET** route that returns authoritative state. +- Update hotbar slot presentation (ready vs cooling; remaining time or clear non-animated indicator). +- Server: reject casts for a slot on active cooldown with a stable **reasonCode**; client: optional local guard so spam does not flood HTTP (must still align with server deny). + +**Out of scope (from Linear):** + +- Final polished animation treatments for cooldown visuals. + +## Acceptance criteria checklist + +- [x] After a successful cast, the affected slot shows a cooling state until the server snapshot says the cooldown has completed. +- [x] The client cannot repeatedly fire a cooling ability without server deny (and/or aligned guard UX) — `reasonCode` for cooldown documented and tested. +- [x] After reconnect, cooldown UI matches server state by **re-fetching** the snapshot (same process lifetime as today’s prototype stores). + +## Technical approach + +1. **Wire contract (`CooldownSnapshot` v1)** + - New JSON DTOs (C#) with `schemaVersion`, `playerId`, **`serverTimeUtc`** (ISO-8601) for client remaining-time math, and a fixed **8-slot** list aligned with `HotbarLoadoutResponse.SlotCountV1`. + - Per slot: `slotIndex`, optional `abilityId` echo (or omit if redundant — prefer mirror loadout binding from client cache only; snapshot focuses on **cooldownEndsAtUtc** nullable). When `cooldownEndsAtUtc` is null or ≤ `serverTimeUtc`, slot is **ready** for cast from a cooldown perspective. + +2. **Server authority** + - **`IPlayerAbilityCooldownStore`** (or equivalent name): in-memory per-player map `slotIndex → cooldown end (UTC)`. Registered as **singleton** in DI (prototype: no Postgres; resets on process restart, consistent with ephemeral combat-adjacent state). + - **Global constant** `TimeSpan` (e.g. 3s — pick one value in implementation) applied on **accepted** cast after all existing NEO-28 gates. + - **`AbilityCastApi`:** before accept, if slot has active cooldown → JSON deny with new **`reasonCode`** (e.g. `on_cooldown`). On accept → record cooldown end for that slot. + - **`GET /game/players/{id}/cooldown-snapshot`:** 404 if player unknown to `IPositionStateStore` (same pattern as other player routes); otherwise return computed snapshot from the cooldown store + `UtcNow`. + +3. **Client** + - New **`CooldownSnapshotClient`** (parallel to `HotbarLoadoutClient`): GET on boot after loadout sync (or chained on loadout success), plus a **Timer** or low-rate poll (e.g. 200–500ms while any slot cooling, idle when all ready — implementation detail) to refresh remaining UI. + - New **`CooldownState`** (or extend `HotbarState` minimally): hold per-slot `cooldownEndsAt` / “is cooling” derived from last snapshot + local clock vs `serverTimeUtc` offset. + - **Presentation:** minimal HUD per slot (e.g. extend existing labels or a single debug row listing cooling slots + seconds remaining — avoid “final animation” scope). + - **`main.gd`:** before `request_cast`, if local cooldown mirror says slot still cooling, **skip POST** and optionally mirror deny UX (must not contradict server; server remains source of truth). On `cast_result_received` accepted, optionally trigger immediate snapshot GET to avoid poll latency. + +4. **Bruno** + - Request folder for GET cooldown snapshot + optional flow after cast POST. + +5. **Manual QA** + - Add `docs/manual-qa/NEO-32.md` during implementation (cast → cooling → expiry; spam during cooldown; reconnect + GET). + +## Files to add + +| Path | Purpose | +|------|---------| +| `server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotDtos.cs` | `CooldownSnapshotResponse` + per-slot JSON records (`schemaVersion`, `serverTimeUtc`, slots). | +| `server/NeonSprawl.Server/Game/AbilityInput/IPlayerAbilityCooldownStore.cs` | Interface: try get / set cooldown end per player+slot; clear or implicit expiry by time comparison. | +| `server/NeonSprawl.Server/Game/AbilityInput/InMemoryPlayerAbilityCooldownStore.cs` | Singleton in-memory implementation. | +| `server/NeonSprawl.Server/Game/AbilityInput/AbilityCooldownServiceCollectionExtensions.cs` | `AddAbilityCooldownStore()` registration (in-memory only for prototype). | +| `server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotApi.cs` | `MapCooldownSnapshotApi` — GET route. | +| `server/NeonSprawl.Server.Tests/Game/AbilityInput/CooldownSnapshotApiTests.cs` | HTTP tests for GET shape, 404, and snapshot after cast. | +| `client/scripts/cooldown_snapshot_client.gd` | HTTP GET + signal for parsed snapshot. | +| `client/scripts/cooldown_state.gd` | Local mirror + helpers for “slot cooling” / remaining seconds. | +| `client/test/cooldown_snapshot_client_test.gd` | GdUnit: parse / apply snapshot behavior (mock HTTP if pattern exists in repo). | +| `bruno/neon-sprawl-server/...` (GET cooldown-snapshot `.bru`) | Manual API verification. | +| `docs/manual-qa/NEO-32.md` | Checklist: cooling display, deny on spam, reconnect hydration. | + +## Files to modify + +| Path | Rationale | +|------|-----------| +| `server/NeonSprawl.Server/Program.cs` | Register cooldown store DI; `MapCooldownSnapshotApi()`. | +| `server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs` | Inject cooldown store; `on_cooldown` deny; start cooldown on accept. | +| `server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs` | Assert cooldown deny + accept commits cooldown (via follow-up GET or store-visible behavior through API). | +| `client/scripts/main.gd` | Instantiate client/state; boot + poll wiring; gate `_request_hotbar_cast_slot` when cooling; connect cast result → refresh snapshot. | +| `docs/decomposition/modules/E1_M4_AbilityInputScaffold.md` | Document `CooldownSnapshot` route + wire fields (module “current state”). | +| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | E1.M4 row: NEO-32 landed note when implemented. | + +## Tests + +| Test file | Coverage | +|-----------|----------| +| `CooldownSnapshotApiTests.cs` | GET returns v1 schema; unknown player 404; known player empty snapshot; after accepted cast, slot shows future `cooldownEndsAtUtc`; after wall-clock / fake time if we use injectable clock — **if no injectable clock**, assert ordering with short duration + spin wait or expose test hook only if justified. Prefer **`TimeProvider`** / injectable time abstraction on store if tests need deterministic expiry without flakiness. | +| `AbilityCastApiTests.cs` | Second POST to same slot while cooling → `accepted: false`, `reasonCode` `on_cooldown` (exact string documented in plan + API const). | +| `client/test/cooldown_snapshot_client_test.gd` | JSON → state: ready vs cooling; `serverTimeUtc` offset handling for remaining display helper. | + +**If time injection is too large for this slice:** document in **Open questions** and use integration-style test with real short duration (e.g. 100ms) + generous timeout — only as fallback. + +## Open questions / risks + +- **Flaky timing in CI:** Resolved with **`FakeTimeProvider`** in `InMemoryWebApplicationFactory` + `TimeProvider` injection on cast and snapshot routes. +- **Linear blocked-by NEO-28:** Remove relation in Linear when you accept NEO-28 as done for scheduling. +- **None** for wire shape or duration model — locked in kickoff. + +## Implementation reconciliation (shipped) + +- **Wire:** `CooldownSnapshotResponse` v1 + `GET /game/players/{id}/cooldown-snapshot`; cast deny **`on_cooldown`** (`AbilityCastApi.ReasonOnCooldown`); global duration `AbilityPrototypeCooldown.GlobalDuration` (3s). +- **Client:** `cooldown_snapshot_client.gd`, `cooldown_state.gd`, `CooldownSlotsLabel` + poll timer + loadout-changed sync + cast-accept refresh in `main.gd`. +- **Tests:** `CooldownSnapshotApiTests.cs`, cooldown cases in `AbilityCastApiTests.cs`, `client/test/cooldown_state_test.gd`. +- **Bruno:** `bruno/neon-sprawl-server/cooldown-snapshot/Get cooldown snapshot.bru`. diff --git a/docs/reviews/2026-04-30-NEO-32.md b/docs/reviews/2026-04-30-NEO-32.md new file mode 100644 index 0000000..6f44720 --- /dev/null +++ b/docs/reviews/2026-04-30-NEO-32.md @@ -0,0 +1,47 @@ +# Code review — NEO-32 (CooldownSnapshot sync + slot presentation) + +**Date:** 2026-04-30 + +**Scope:** Branch `NEO-32-cooldown-snapshot-sync-slot-presentation` vs merge-base with `origin/main` (commits through `56f7ae8`: cooldown snapshot API, cast `on_cooldown`, client HUD/sync, optional `NEON_SPRAWL_API_LOG`, HUD anchor fix for bad `serverTimeUtc`). + +**Base:** `origin/main` at merge-base `0790a3398d1b7138643e8e91f4b28db4fd7c554e`. + +## Verdict + +**Approve with nits** + +## Summary + +The branch delivers the planned NEO-32 slice: authoritative in-memory per-player slot cooldowns after an accepted cast, JSON deny `on_cooldown`, `GET /game/players/{id}/cooldown-snapshot` with v1 DTOs, `FakeTimeProvider` in the test host for deterministic time, Godot `CooldownSnapshotClient` + `CooldownState` with poll-while-cooling and a client-side cast guard aligned with the same reason string, plus Bruno and manual QA. Server tests pass (`dotnet test`). Overall risk is low for a prototype vertical slice; remaining notes are test-structure polish and a minor store hygiene detail. + +## Documentation checked + +| Document | Result | +|----------|--------| +| `docs/plans/NEO-32-implementation-plan.md` | **Matches** — dedicated GET, global duration, `on_cooldown`, in-memory store, client poll + guard, `FakeTimeProvider`, reconciliation section matches shipped filenames (`cooldown_state_test.gd` vs earlier table mentioning `cooldown_snapshot_client_test.gd`; reconciliation already reflects state tests). | +| `docs/decomposition/modules/E1_M4_AbilityInputScaffold.md` | **Matches** — current state paragraph describes route, DTOs, client scripts, HUD, and plan link. | +| `docs/decomposition/modules/module_dependency_register.md` | **Matches** — NEO-32 note alongside prior E1.M4 slices. | +| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | **Matches** — E1.M4 row includes NEO-32 pointers. | +| `docs/decomposition/modules/client_server_authority.md` | **Matches** — cooldown enforced on server; client guard is optional spam/UX layer, consistent with “server validates every intent.” | +| `docs/decomposition/modules/E5_M1_CombatRulesEngine.md` | **N/A** for conflict — still notes prototype accept does not imply full combat resolution; NEO-32 does not claim engine-level cooldown catalog. | + +**Register / tracking:** No change required beyond what the branch already updates; E1.M4 correctly stays **In Progress**. + +## Blocking issues + +(none) + +## Suggestions + +1. ~~**C# AAA layout on new integration tests** — `CooldownSnapshotApiTests.GetCooldownSnapshot_ShouldExposeSlotEnd_WhenCastAccepted_ThenClear_WhenAdvancedPastDuration` and the two new cooldown tests in `AbilityCastApiTests` bundle HTTP calls and `FakeClock.Advance` inside a single `// Act` block. Per [csharp-style](.cursor/rules/csharp-style.md#unit-and-integration-tests-arrange-act-assert), split so **Act** is only the invocations under assertion (or use clearly separated Act steps per phase) and keep clock advances in Arrange or interleaved with labeled sections. Low priority but keeps CI lint/review consistency for future edits.~~ **Deferred (won’t do).** Scenario-style integration tests read better with one narrated timeline; strict per-call Act splits are optional here. + +2. ~~**Stale cooldown entries in the in-memory store** — `TryGetCooldownEndUtc` does not prune expired ends; `BuildSnapshot` omits them from JSON, so wire behavior is correct. Expired rows linger until `IsOnCooldown` runs (e.g. next cast to that slot). For a long-lived prototype process this is negligible; if you ever extend GET-heavy paths, consider pruning in `TryGetCooldownEndUtc` or snapshot build for symmetry with `IsOnCooldown`.~~ **Done.** `TryGetCooldownEndUtc` now takes `DateTimeOffset now` and shares pruning with `IsOnCooldown`; `InMemoryPlayerAbilityCooldownStoreTests` covers prune-on-read. + +## Nits + +- ~~**Nit:** Untracked Godot `.uid` files for new scripts appeared in the working tree (`cooldown_snapshot_client.gd.uid`, etc.). Decide whether to commit them (team Godot 4 convention) or ignore via `.gitignore` so CI/agents do not see noise.~~ **Done.** Companion `*.gd.uid` committed; convention documented in `AGENTS.md` and [godot-client-script-organization.md](../../.cursor/rules/godot-client-script-organization.md). + +## Verification + +- `cd server && dotnet test NeonSprawl.Server.Tests/NeonSprawl.Server.Tests.csproj` — all tests passed (96) at review time. +- Manual: follow `docs/manual-qa/NEO-32.md` (HUD countdown, server deny, client guard, rehydrate); optional `NEON_SPRAWL_API_LOG=1` / `http+apiLog` profile for stdout tracing. diff --git a/server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs b/server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs index 41eaee9..9787621 100644 --- a/server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs +++ b/server/NeonSprawl.Server.Tests/Game/AbilityInput/AbilityCastApiTests.cs @@ -13,6 +13,7 @@ namespace NeonSprawl.Server.Tests.Game.AbilityInput; /// NEO-30: every JSON deny ( false) asserts a non-whitespace /// — matches Slice 3 ability_cast_denied payload expectations; /// authoritative hook-site comments live on (cast route: MapAbilityCastApi extension in the same source file). +/// Optional dev: NEON_SPRAWL_API_LOG=1 enables one-line ability_cast_* stdout per JSON cast response (see ). /// public sealed class AbilityCastApiTests { @@ -414,4 +415,69 @@ public sealed class AbilityCastApiTests // Assert Assert.Equal(HttpStatusCode.NotFound, response.StatusCode); } + + [Fact] + public async Task PostAbilityCast_ShouldDenyOnCooldown_WhenRepeatedWhileCooling() + { + // Arrange + await using var factory = new InMemoryWebApplicationFactory(); + var client = factory.CreateClient(); + await BindSlot0PulseAsync(client); + await LockPrototypeTargetAlphaAsync(client); + var cast = new AbilityCastRequest + { + SchemaVersion = AbilityCastRequest.CurrentSchemaVersion, + SlotIndex = 0, + AbilityId = PrototypeAbilityRegistry.PrototypePulse, + TargetId = PrototypeTargetRegistry.PrototypeTargetAlphaId, + }; + + // Act + var first = await client.PostAsJsonAsync("/game/players/dev-local-1/ability-cast", cast); + var second = await client.PostAsJsonAsync("/game/players/dev-local-1/ability-cast", cast); + + // Assert + var body1 = await first.Content.ReadFromJsonAsync(); + var body2 = await second.Content.ReadFromJsonAsync(); + Assert.Equal(HttpStatusCode.OK, first.StatusCode); + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.NotNull(body1); + Assert.NotNull(body2); + Assert.True(body1!.Accepted); + Assert.False(body2!.Accepted); + Assert.Equal(AbilityCastApi.ReasonOnCooldown, body2.ReasonCode); + } + + [Fact] + public async Task PostAbilityCast_ShouldAcceptAgain_WhenCooldownElapsed() + { + // Arrange + await using var factory = new InMemoryWebApplicationFactory(); + var client = factory.CreateClient(); + Assert.NotNull(factory.FakeClock); + await BindSlot0PulseAsync(client); + await LockPrototypeTargetAlphaAsync(client); + var cast = new AbilityCastRequest + { + SchemaVersion = AbilityCastRequest.CurrentSchemaVersion, + SlotIndex = 0, + AbilityId = PrototypeAbilityRegistry.PrototypePulse, + TargetId = PrototypeTargetRegistry.PrototypeTargetAlphaId, + }; + + // Act + var first = await client.PostAsJsonAsync("/game/players/dev-local-1/ability-cast", cast); + factory.FakeClock!.Advance(AbilityPrototypeCooldown.GlobalDuration + TimeSpan.FromMilliseconds(50)); + var second = await client.PostAsJsonAsync("/game/players/dev-local-1/ability-cast", cast); + + // Assert + var body1 = await first.Content.ReadFromJsonAsync(); + var body2 = await second.Content.ReadFromJsonAsync(); + Assert.Equal(HttpStatusCode.OK, first.StatusCode); + Assert.Equal(HttpStatusCode.OK, second.StatusCode); + Assert.NotNull(body1); + Assert.NotNull(body2); + Assert.True(body1!.Accepted); + Assert.True(body2!.Accepted); + } } diff --git a/server/NeonSprawl.Server.Tests/Game/AbilityInput/CooldownSnapshotApiTests.cs b/server/NeonSprawl.Server.Tests/Game/AbilityInput/CooldownSnapshotApiTests.cs new file mode 100644 index 0000000..2950f84 --- /dev/null +++ b/server/NeonSprawl.Server.Tests/Game/AbilityInput/CooldownSnapshotApiTests.cs @@ -0,0 +1,105 @@ +using System.Net; +using System.Net.Http.Json; +using NeonSprawl.Server.Game.AbilityInput; +using NeonSprawl.Server.Game.Targeting; +using NeonSprawl.Server.Tests; +using Xunit; + +namespace NeonSprawl.Server.Tests.Game.AbilityInput; + +public sealed class CooldownSnapshotApiTests +{ + private static async Task BindSlot0PulseAsync(HttpClient client) + { + var post = await client.PostAsJsonAsync( + "/game/players/dev-local-1/hotbar-loadout", + new HotbarLoadoutUpdateRequest + { + SchemaVersion = HotbarLoadoutUpdateRequest.CurrentSchemaVersion, + Slots = [new HotbarSlotBindingJson { SlotIndex = 0, AbilityId = PrototypeAbilityRegistry.PrototypePulse }], + }); + post.EnsureSuccessStatusCode(); + } + + private static async Task LockPrototypeTargetAlphaAsync(HttpClient client) + { + var response = await client.PostAsJsonAsync( + "/game/players/dev-local-1/target/select", + new TargetSelectRequest + { + SchemaVersion = TargetSelectRequest.CurrentSchemaVersion, + TargetId = PrototypeTargetRegistry.PrototypeTargetAlphaId, + }); + response.EnsureSuccessStatusCode(); + } + + [Fact] + public async Task GetCooldownSnapshot_ShouldReturnNotFound_WhenPlayerUnknown() + { + // Arrange + await using var factory = new InMemoryWebApplicationFactory(); + var client = factory.CreateClient(); + + // Act + var response = await client.GetAsync("/game/players/missing-player/cooldown-snapshot"); + + // Assert + Assert.Equal(HttpStatusCode.NotFound, response.StatusCode); + } + + [Fact] + public async Task GetCooldownSnapshot_ShouldReturnV1Schema_WithEightSlots_WhenPlayerKnown() + { + // Arrange + await using var factory = new InMemoryWebApplicationFactory(); + var client = factory.CreateClient(); + + // Act + var response = await client.GetAsync("/game/players/dev-local-1/cooldown-snapshot"); + + // Assert + var body = await response.Content.ReadFromJsonAsync(); + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + Assert.NotNull(body); + Assert.Equal(CooldownSnapshotResponse.CurrentSchemaVersion, body!.SchemaVersion); + Assert.Equal("dev-local-1", body.PlayerId); + Assert.Equal(HotbarLoadoutResponse.SlotCountV1, body.Slots.Count); + Assert.All(body.Slots, s => Assert.Null(s.CooldownEndsAtUtc)); + } + + [Fact] + public async Task GetCooldownSnapshot_ShouldExposeSlotEnd_WhenCastAccepted_ThenClear_WhenAdvancedPastDuration() + { + // Arrange + await using var factory = new InMemoryWebApplicationFactory(); + var client = factory.CreateClient(); + Assert.NotNull(factory.FakeClock); + await BindSlot0PulseAsync(client); + await LockPrototypeTargetAlphaAsync(client); + var cast = new AbilityCastRequest + { + SchemaVersion = AbilityCastRequest.CurrentSchemaVersion, + SlotIndex = 0, + AbilityId = PrototypeAbilityRegistry.PrototypePulse, + TargetId = PrototypeTargetRegistry.PrototypeTargetAlphaId, + }; + + // Act + var castResponse = await client.PostAsJsonAsync("/game/players/dev-local-1/ability-cast", cast); + var snapDuring = await client.GetAsync("/game/players/dev-local-1/cooldown-snapshot"); + factory.FakeClock!.Advance(AbilityPrototypeCooldown.GlobalDuration + TimeSpan.FromMilliseconds(50)); + var snapAfter = await client.GetAsync("/game/players/dev-local-1/cooldown-snapshot"); + + // Assert + castResponse.EnsureSuccessStatusCode(); + var during = await snapDuring.Content.ReadFromJsonAsync(); + var after = await snapAfter.Content.ReadFromJsonAsync(); + Assert.NotNull(during); + Assert.NotNull(after); + var slot0During = during!.Slots.Single(s => s.SlotIndex == 0); + Assert.NotNull(slot0During.CooldownEndsAtUtc); + Assert.True(slot0During.CooldownEndsAtUtc > during.ServerTimeUtc); + var slot0After = after!.Slots.Single(s => s.SlotIndex == 0); + Assert.Null(slot0After.CooldownEndsAtUtc); + } +} diff --git a/server/NeonSprawl.Server.Tests/Game/AbilityInput/InMemoryPlayerAbilityCooldownStoreTests.cs b/server/NeonSprawl.Server.Tests/Game/AbilityInput/InMemoryPlayerAbilityCooldownStoreTests.cs new file mode 100644 index 0000000..800eb93 --- /dev/null +++ b/server/NeonSprawl.Server.Tests/Game/AbilityInput/InMemoryPlayerAbilityCooldownStoreTests.cs @@ -0,0 +1,41 @@ +using NeonSprawl.Server.Game.AbilityInput; +using Xunit; + +namespace NeonSprawl.Server.Tests.Game.AbilityInput; + +public sealed class InMemoryPlayerAbilityCooldownStoreTests +{ + [Fact] + public void TryGetCooldownEndUtc_ShouldReturnEnd_WhenNowBeforeCooldownEnd() + { + // Arrange + var store = new InMemoryPlayerAbilityCooldownStore(); + var t0 = new DateTimeOffset(2026, 4, 30, 12, 0, 0, TimeSpan.Zero); + store.StartCooldown("p1", 2, t0, TimeSpan.FromSeconds(3)); + + // Act + var has = store.TryGetCooldownEndUtc("p1", 2, t0 + TimeSpan.FromSeconds(1), out var endUtc); + + // Assert + Assert.True(has); + Assert.Equal(t0 + TimeSpan.FromSeconds(3), endUtc); + } + + [Fact] + public void TryGetCooldownEndUtc_ShouldPruneAndReturnFalse_WhenNowAtOrAfterEnd() + { + // Arrange + var store = new InMemoryPlayerAbilityCooldownStore(); + var t0 = new DateTimeOffset(2026, 4, 30, 12, 0, 0, TimeSpan.Zero); + store.StartCooldown("p1", 0, t0, TimeSpan.FromSeconds(3)); + var after = t0 + TimeSpan.FromSeconds(5); + + // Act + var pruned = store.TryGetCooldownEndUtc("p1", 0, after, out _); + var second = store.TryGetCooldownEndUtc("p1", 0, after, out _); + + // Assert + Assert.False(pruned); + Assert.False(second); + } +} diff --git a/server/NeonSprawl.Server.Tests/InMemoryWebApplicationFactory.cs b/server/NeonSprawl.Server.Tests/InMemoryWebApplicationFactory.cs index 5d60c87..d93b96b 100644 --- a/server/NeonSprawl.Server.Tests/InMemoryWebApplicationFactory.cs +++ b/server/NeonSprawl.Server.Tests/InMemoryWebApplicationFactory.cs @@ -3,6 +3,7 @@ using Microsoft.AspNetCore.Mvc.Testing; using Microsoft.AspNetCore.TestHost; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Time.Testing; using NeonSprawl.Server.Game.AbilityInput; using NeonSprawl.Server.Game.PositionState; using Npgsql; @@ -12,6 +13,9 @@ namespace NeonSprawl.Server.Tests; /// Forces the in-memory position store by replacing Postgres registrations after the host builds services (overrides process env e.g. CI ConnectionStrings__NeonSprawl). public sealed class InMemoryWebApplicationFactory : WebApplicationFactory { + /// Controllable UTC clock shared by cast + cooldown routes in tests (NEO-32). + public FakeTimeProvider? FakeClock { get; private set; } + protected override void ConfigureWebHost(IWebHostBuilder builder) { builder.ConfigureTestServices(services => @@ -21,6 +25,8 @@ public sealed class InMemoryWebApplicationFactory : WebApplicationFactory(fakeTime); services.AddSingleton(); services.AddSingleton(); + services.AddSingleton(); }); } } diff --git a/server/NeonSprawl.Server.Tests/NeonSprawl.Server.Tests.csproj b/server/NeonSprawl.Server.Tests/NeonSprawl.Server.Tests.csproj index 7b811f6..22d6cbb 100644 --- a/server/NeonSprawl.Server.Tests/NeonSprawl.Server.Tests.csproj +++ b/server/NeonSprawl.Server.Tests/NeonSprawl.Server.Tests.csproj @@ -13,6 +13,7 @@ + diff --git a/server/NeonSprawl.Server/Diagnostics/PrototypeApiConsoleLog.cs b/server/NeonSprawl.Server/Diagnostics/PrototypeApiConsoleLog.cs new file mode 100644 index 0000000..e9e8e13 --- /dev/null +++ b/server/NeonSprawl.Server/Diagnostics/PrototypeApiConsoleLog.cs @@ -0,0 +1,55 @@ +namespace NeonSprawl.Server.Diagnostics; + +/// Optional one-line stdout traces for prototype HTTP routes (manual QA / dev until E9.M1). +/// +/// Enable with environment variable NEON_SPRAWL_API_LOG set to 1, true, yes, or on (case-insensitive). +/// +public static class PrototypeApiConsoleLog +{ + /// Slice 3 hook names; matches product telemetry vocabulary in AbilityCastApi comments. + public static bool IsAbilityCastStdoutEnabled() + { + var raw = Environment.GetEnvironmentVariable("NEON_SPRAWL_API_LOG"); + if (string.IsNullOrWhiteSpace(raw)) + { + return false; + } + + var v = raw.Trim(); + return v is "1" or "true" or "yes" + || string.Equals(v, "on", StringComparison.OrdinalIgnoreCase); + } + + /// One line per JSON ability-cast response (HTTP 200 with AbilityCastResponse). + public static void WriteAbilityCastLine( + string playerId, + int slotIndex, + string? abilityId, + string? targetId, + bool accepted, + string? reasonCode) + { + if (!IsAbilityCastStdoutEnabled()) + { + return; + } + + if (accepted) + { + Console.WriteLine( + "[ability-cast] ability_cast_requested player={0} slot={1} ability={2} target={3}", + playerId, + slotIndex, + abilityId ?? "", + targetId ?? ""); + } + else + { + Console.WriteLine( + "[ability-cast] ability_cast_denied player={0} slot={1} reason={2}", + playerId, + slotIndex, + reasonCode ?? ""); + } + } +} diff --git a/server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs b/server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs index f4d7da4..fec55fc 100644 --- a/server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs +++ b/server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs @@ -1,3 +1,4 @@ +using NeonSprawl.Server.Diagnostics; using NeonSprawl.Server.Game.PositionState; using NeonSprawl.Server.Game.Targeting; using NeonSprawl.Server.Game.World; @@ -9,7 +10,9 @@ namespace NeonSprawl.Server.Game.AbilityInput; /// Epic 1 Slice 3 product telemetry names ability_cast_requested and ability_cast_denied /// (on JSON denies, — wire JSON reasonCode) — hook sites are marked inline below. /// TODO(E9.M1): emit cataloged events (payload: route player id, slotIndex, abilityId, targetId; on deny include reasonCode). +/// Optional dev stdout: set NEON_SPRAWL_API_LOG=1 (see ) for one line per JSON cast response. /// HTTP 400/404 here are outside the v1 cast deny contract (no JSON AbilityCastResponse). +/// NEO-32: JSON deny on_cooldown when the slot is inside the prototype global cooldown window. /// public static class AbilityCastApi { @@ -24,6 +27,25 @@ public static class AbilityCastApi /// Locked prototype target is outside horizontal reach of authoritative position (NEO-28). public const string ReasonOutOfRange = TargetValidity.OutOfRange; + /// Slot still inside server-authoritative cooldown window (NEO-32). + public const string ReasonOnCooldown = "on_cooldown"; + + private static IResult JsonAbilityCast( + string id, + AbilityCastRequest body, + AbilityCastResponse response, + string? abilityIdForLog = null) + { + PrototypeApiConsoleLog.WriteAbilityCastLine( + id, + body.SlotIndex, + abilityIdForLog ?? body.AbilityId, + body.TargetId, + response.Accepted, + response.ReasonCode); + return Results.Json(response); + } + public static WebApplication MapAbilityCastApi(this WebApplication app) { app.MapPost( @@ -33,7 +55,9 @@ public static class AbilityCastApi AbilityCastRequest? body, IPositionStateStore positions, IPlayerHotbarLoadoutStore store, - IPlayerTargetLockStore locks) => + IPlayerTargetLockStore locks, + IPlayerAbilityCooldownStore cooldowns, + TimeProvider clock) => { // NEO-30: not a Slice 3 `ability_cast_denied` site — no AbilityCastResponse body. if (body is null || body.SchemaVersion != AbilityCastRequest.CurrentSchemaVersion) @@ -56,7 +80,9 @@ public static class AbilityCastApi if (body.SlotIndex < 0 || body.SlotIndex >= HotbarLoadoutResponse.SlotCountV1) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, @@ -68,7 +94,9 @@ public static class AbilityCastApi string.IsNullOrWhiteSpace(boundAbility)) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, @@ -80,7 +108,9 @@ public static class AbilityCastApi !PrototypeAbilityRegistry.TryNormalizeKnown(body.AbilityId, out var normalizedRequest)) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, @@ -91,7 +121,9 @@ public static class AbilityCastApi if (!string.Equals(normalizedRequest, boundAbility, StringComparison.Ordinal)) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, @@ -102,7 +134,9 @@ public static class AbilityCastApi if (string.IsNullOrWhiteSpace(body.TargetId)) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, ReasonCode = ReasonInvalidTarget }); } @@ -110,7 +144,9 @@ public static class AbilityCastApi if (!PrototypeTargetRegistry.TryGet(lookupKey, out var entry)) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, ReasonCode = ReasonInvalidTarget }); } @@ -119,20 +155,40 @@ public static class AbilityCastApi !string.Equals(lookupKey, lockIdLowercase, StringComparison.Ordinal)) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, ReasonCode = ReasonInvalidTarget }); } if (!HorizontalReach.IsWithinHorizontalRadius(snap.X, snap.Z, entry.X, entry.Z, entry.LockRadius)) { // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). - return Results.Json( + return JsonAbilityCast( + id, + body, new AbilityCastResponse { Accepted = false, ReasonCode = ReasonOutOfRange }); } + var now = clock.GetUtcNow(); + if (cooldowns.IsOnCooldown(id, body.SlotIndex, now)) + { + // NEO-30 telemetry hook site: `ability_cast_denied` + reasonCode (TODO(E9.M1): catalog emit). + return JsonAbilityCast( + id, + body, + new AbilityCastResponse { Accepted = false, ReasonCode = ReasonOnCooldown }); + } + + cooldowns.StartCooldown(id, body.SlotIndex, now, AbilityPrototypeCooldown.GlobalDuration); + // NEO-30 telemetry hook site: `ability_cast_requested` at authoritative accept (TODO(E9.M1): catalog emit). // Payload notes for E9.M1: player id = route `id`, body.SlotIndex, normalized ability id, body.TargetId (lock-aligned). - return Results.Json(new AbilityCastResponse { Accepted = true }); + return JsonAbilityCast( + id, + body, + new AbilityCastResponse { Accepted = true }, + normalizedRequest); }); return app; diff --git a/server/NeonSprawl.Server/Game/AbilityInput/AbilityCooldownServiceCollectionExtensions.cs b/server/NeonSprawl.Server/Game/AbilityInput/AbilityCooldownServiceCollectionExtensions.cs new file mode 100644 index 0000000..6e23da4 --- /dev/null +++ b/server/NeonSprawl.Server/Game/AbilityInput/AbilityCooldownServiceCollectionExtensions.cs @@ -0,0 +1,12 @@ +namespace NeonSprawl.Server.Game.AbilityInput; + +/// Registers prototype ability cooldown store + (NEO-32). +public static class AbilityCooldownServiceCollectionExtensions +{ + public static IServiceCollection AddAbilityCooldownStore(this IServiceCollection services) + { + services.AddSingleton(TimeProvider.System); + services.AddSingleton(); + return services; + } +} diff --git a/server/NeonSprawl.Server/Game/AbilityInput/AbilityPrototypeCooldown.cs b/server/NeonSprawl.Server/Game/AbilityInput/AbilityPrototypeCooldown.cs new file mode 100644 index 0000000..aa91066 --- /dev/null +++ b/server/NeonSprawl.Server/Game/AbilityInput/AbilityPrototypeCooldown.cs @@ -0,0 +1,8 @@ +namespace NeonSprawl.Server.Game.AbilityInput; + +/// Prototype global cooldown applied on successful cast (NEO-32) until E5.M1 ability catalog. +public static class AbilityPrototypeCooldown +{ + /// Single duration for every known prototype ability on accept. + public static readonly TimeSpan GlobalDuration = TimeSpan.FromSeconds(3); +} diff --git a/server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotApi.cs b/server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotApi.cs new file mode 100644 index 0000000..76f8948 --- /dev/null +++ b/server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotApi.cs @@ -0,0 +1,50 @@ +using NeonSprawl.Server.Game.PositionState; + +namespace NeonSprawl.Server.Game.AbilityInput; + +/// GET /game/players/{{id}}/cooldown-snapshot (NEO-32). +public static class CooldownSnapshotApi +{ + public static WebApplication MapCooldownSnapshotApi(this WebApplication app) + { + app.MapGet( + "/game/players/{id}/cooldown-snapshot", + (string id, IPositionStateStore positions, IPlayerAbilityCooldownStore cooldowns, TimeProvider clock) => + { + if (!positions.TryGetPosition(id, out _)) + { + return Results.NotFound(); + } + + return Results.Json(BuildSnapshot(id, cooldowns, clock)); + }); + + return app; + } + + internal static CooldownSnapshotResponse BuildSnapshot( + string playerId, + IPlayerAbilityCooldownStore cooldowns, + TimeProvider clock) + { + var now = clock.GetUtcNow(); + var slots = new List(HotbarLoadoutResponse.SlotCountV1); + for (var i = 0; i < HotbarLoadoutResponse.SlotCountV1; i++) + { + DateTimeOffset? end = null; + if (cooldowns.TryGetCooldownEndUtc(playerId, i, now, out var endUtc)) + { + end = endUtc; + } + + slots.Add(new CooldownSlotSnapshotJson { SlotIndex = i, CooldownEndsAtUtc = end }); + } + + return new CooldownSnapshotResponse + { + PlayerId = playerId, + ServerTimeUtc = now, + Slots = slots, + }; + } +} diff --git a/server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotDtos.cs b/server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotDtos.cs new file mode 100644 index 0000000..e876db7 --- /dev/null +++ b/server/NeonSprawl.Server/Game/AbilityInput/CooldownSnapshotDtos.cs @@ -0,0 +1,35 @@ +using System.Text.Json.Serialization; + +namespace NeonSprawl.Server.Game.AbilityInput; + +/// GET response for per-slot cooldown ends (NEO-32). +public sealed class CooldownSnapshotResponse +{ + public const int CurrentSchemaVersion = 1; + + [JsonPropertyName("schemaVersion")] + public int SchemaVersion { get; init; } = CurrentSchemaVersion; + + [JsonPropertyName("playerId")] + public required string PlayerId { get; init; } + + /// Authoritative instant for remaining-time math on the client. + [JsonPropertyName("serverTimeUtc")] + public DateTimeOffset ServerTimeUtc { get; init; } + + /// Slots 0..7 in ascending order. + [JsonPropertyName("slots")] + public required IReadOnlyList Slots { get; init; } +} + +/// Cooldown end for one hotbar slot; null when ready. +public sealed class CooldownSlotSnapshotJson +{ + [JsonPropertyName("slotIndex")] + public required int SlotIndex { get; init; } + + /// UTC instant when the slot leaves cooldown, or null when not cooling. + [JsonPropertyName("cooldownEndsAtUtc")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public DateTimeOffset? CooldownEndsAtUtc { get; init; } +} diff --git a/server/NeonSprawl.Server/Game/AbilityInput/IPlayerAbilityCooldownStore.cs b/server/NeonSprawl.Server/Game/AbilityInput/IPlayerAbilityCooldownStore.cs new file mode 100644 index 0000000..408b0cc --- /dev/null +++ b/server/NeonSprawl.Server/Game/AbilityInput/IPlayerAbilityCooldownStore.cs @@ -0,0 +1,14 @@ +namespace NeonSprawl.Server.Game.AbilityInput; + +/// In-memory per-player hotbar slot cooldown ends (NEO-32). +public interface IPlayerAbilityCooldownStore +{ + /// Returns true when the slot has a cooldown end strictly after . + bool IsOnCooldown(string playerId, int slotIndex, DateTimeOffset now); + + /// Sets cooldown end for a slot to + . + void StartCooldown(string playerId, int slotIndex, DateTimeOffset now, TimeSpan duration); + + /// Gets active cooldown end when is strictly before that end; removes expired entries (same hygiene as ). + bool TryGetCooldownEndUtc(string playerId, int slotIndex, DateTimeOffset now, out DateTimeOffset endUtc); +} diff --git a/server/NeonSprawl.Server/Game/AbilityInput/InMemoryPlayerAbilityCooldownStore.cs b/server/NeonSprawl.Server/Game/AbilityInput/InMemoryPlayerAbilityCooldownStore.cs new file mode 100644 index 0000000..8d1ad06 --- /dev/null +++ b/server/NeonSprawl.Server/Game/AbilityInput/InMemoryPlayerAbilityCooldownStore.cs @@ -0,0 +1,59 @@ +using System.Collections.Concurrent; + +namespace NeonSprawl.Server.Game.AbilityInput; + +/// Thread-safe in-memory cooldown map (NEO-32); not persisted across process restarts. +public sealed class InMemoryPlayerAbilityCooldownStore : IPlayerAbilityCooldownStore +{ + private readonly ConcurrentDictionary> ends = new(StringComparer.Ordinal); + + public bool IsOnCooldown(string playerId, int slotIndex, DateTimeOffset now) + { + return TryGetActiveCooldownEnd(playerId, slotIndex, now, out _); + } + + public void StartCooldown(string playerId, int slotIndex, DateTimeOffset now, TimeSpan duration) + { + var perSlot = ends.GetOrAdd(playerId, _ => new ConcurrentDictionary()); + perSlot[slotIndex] = now + duration; + } + + public bool TryGetCooldownEndUtc(string playerId, int slotIndex, DateTimeOffset now, out DateTimeOffset endUtc) + { + return TryGetActiveCooldownEnd(playerId, slotIndex, now, out endUtc); + } + + /// Shared read path: returns true with when cooldown is active; removes slot entry when >= stored end. + private static bool TryGetActiveCooldownEnd( + ConcurrentDictionary> ends, + string playerId, + int slotIndex, + DateTimeOffset now, + out DateTimeOffset endUtc) + { + endUtc = default; + if (!ends.TryGetValue(playerId, out var perSlot)) + { + return false; + } + + if (!perSlot.TryGetValue(slotIndex, out var end)) + { + return false; + } + + if (now >= end) + { + perSlot.TryRemove(slotIndex, out _); + return false; + } + + endUtc = end; + return true; + } + + private bool TryGetActiveCooldownEnd(string playerId, int slotIndex, DateTimeOffset now, out DateTimeOffset endUtc) + { + return TryGetActiveCooldownEnd(ends, playerId, slotIndex, now, out endUtc); + } +} diff --git a/server/NeonSprawl.Server/Program.cs b/server/NeonSprawl.Server/Program.cs index e4b1fe9..70ddda9 100644 --- a/server/NeonSprawl.Server/Program.cs +++ b/server/NeonSprawl.Server/Program.cs @@ -6,6 +6,7 @@ using NeonSprawl.Server.Game.Targeting; var builder = WebApplication.CreateBuilder(args); builder.Services.AddPositionStateStore(builder.Configuration); builder.Services.AddHotbarLoadoutStore(builder.Configuration); +builder.Services.AddAbilityCooldownStore(); builder.Services.AddSingleton(); var app = builder.Build(); @@ -25,6 +26,7 @@ app.MapInteractionApi(); app.MapInteractablesWorldApi(); app.MapTargetingApi(); app.MapHotbarLoadoutApi(); +app.MapCooldownSnapshotApi(); app.MapAbilityCastApi(); app.Run(); diff --git a/server/NeonSprawl.Server/Properties/launchSettings.json b/server/NeonSprawl.Server/Properties/launchSettings.json index 7a8e7ca..90f02ec 100644 --- a/server/NeonSprawl.Server/Properties/launchSettings.json +++ b/server/NeonSprawl.Server/Properties/launchSettings.json @@ -18,6 +18,16 @@ "ASPNETCORE_ENVIRONMENT": "Development" } }, + "http+apiLog": { + "commandName": "Project", + "dotnetRunMessages": true, + "launchBrowser": true, + "applicationUrl": "http://localhost:5253", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development", + "NEON_SPRAWL_API_LOG": "1" + } + }, "IIS Express": { "commandName": "IISExpress", "launchBrowser": true, diff --git a/server/README.md b/server/README.md index c6b79ba..a23eb52 100644 --- a/server/README.md +++ b/server/README.md @@ -16,6 +16,14 @@ dotnet run - Default URL is printed by Kestrel (see `Properties/launchSettings.json`, typically `http://localhost:5253`). - Check `GET /health` for a JSON heartbeat. +**Optional prototype API stdout (manual QA / dev):** set **`NEON_SPRAWL_API_LOG`** to **`1`**, **`true`**, **`yes`**, or **`on`** (case-insensitive). While enabled, each **`POST …/ability-cast`** that returns JSON **`AbilityCastResponse`** (HTTP 200) prints one line to the process console: either **`ability_cast_requested`** (accept) or **`ability_cast_denied`** with **`reason=`** (deny). **`400`** / **`404`** paths do not emit these lines. Implementation: `Diagnostics/PrototypeApiConsoleLog.cs` (wired from `AbilityCastApi`). Example: + +```bash +NEON_SPRAWL_API_LOG=1 dotnet run --project server/NeonSprawl.Server/NeonSprawl.Server.csproj +``` + +IDE: use launch profile **`http+apiLog`** (same URL as **`http`**, sets the variable). + ## Position persistence (NEO-8) When **`ConnectionStrings:NeonSprawl`** is set to a valid PostgreSQL connection string, the server uses the **`player_position`** table (relational columns `pos_x` … `sequence`, not JSONB). DDL lives in [`server/db/migrations/V001__player_position.sql`](../db/migrations/V001__player_position.sql); the app applies that script on startup and on first store use (idempotent `CREATE TABLE IF NOT EXISTS`). The configured dev player (`Game:DevPlayerId` / `Game:DefaultPosition`) is seeded once at host startup, matching the in-memory store’s constructor seed (not on every HTTP request). @@ -227,7 +235,7 @@ Current prototype allowlist: `prototype_pulse`, `prototype_guard`, `prototype_da Prototype **cast intent** (no full combat resolution — see E5.M1). **NEO-28** adds server-side target lock + registry + range gates and documents `invalid_target` / `out_of_range` denies; the Godot client surfaces accept/deny on **`CastFeedbackLabel`**. -- **`POST /game/players/{id}/ability-cast`** with `AbilityCastRequest` v1 (`schemaVersion`, `slotIndex` `0..7`, `abilityId`, `targetId`) validates the player exists, the slot is bound in persisted hotbar loadout, and `abilityId` matches that binding and the prototype allowlist. **NEO-28:** `targetId` must be **non-empty**, exist in **`PrototypeTargetRegistry`**, **match** the server's current combat lock (`IPlayerTargetLockStore`), and the lock must be **within horizontal reach** of the authoritative position snapshot (same XZ radius rule as targeting). Returns **`AbilityCastResponse` v1** JSON (`schemaVersion`, `accepted`, optional `reasonCode`). +- **`POST /game/players/{id}/ability-cast`** with `AbilityCastRequest` v1 (`schemaVersion`, `slotIndex` `0..7`, `abilityId`, `targetId`) validates the player exists, the slot is bound in persisted hotbar loadout, and `abilityId` matches that binding and the prototype allowlist. **NEO-28:** `targetId` must be **non-empty**, exist in **`PrototypeTargetRegistry`**, **match** the server's current combat lock (`IPlayerTargetLockStore`), and the lock must be **within horizontal reach** of the authoritative position snapshot (same XZ radius rule as targeting). **NEO-32:** rejects with `on_cooldown` when the slot is still cooling; on accept, starts the prototype global cooldown for that slot. Returns **`AbilityCastResponse` v1** JSON (`schemaVersion`, `accepted`, optional `reasonCode`). **HTTP status:** @@ -247,8 +255,17 @@ Prototype **cast intent** (no full combat resolution — see E5.M1). **NEO-28** | `unknown_ability` | `abilityId` failed registry normalization (empty/garbage/off-list). | | `invalid_target` | `targetId` missing/empty, unknown prototype id, or not equal to the server's locked target id (NEO-28). | | `out_of_range` | Locked target is outside horizontal reach of authoritative player position vs. prototype anchor (NEO-28). | +| `on_cooldown` | Slot is still inside the server-authoritative cooldown window after a prior successful accept (NEO-32). | -Implementation: `server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs`, `AbilityCastDtos.cs`. +Implementation: `server/NeonSprawl.Server/Game/AbilityInput/AbilityCastApi.cs`, `AbilityCastDtos.cs`. Optional **Slice 3–named** one-line stdout per JSON response when **`NEON_SPRAWL_API_LOG`** is set (see **Optional prototype API stdout** under **Run** above). + +## Cooldown snapshot (NEO-32) + +Prototype **per-slot cooldown ends** (in-memory per process; not persisted to Postgres). **Global duration** `AbilityPrototypeCooldown.GlobalDuration` applies on each successful cast after all NEO-28 gates pass. + +- **`GET /game/players/{id}/cooldown-snapshot`** → `CooldownSnapshotResponse` v1 (`schemaVersion`, `playerId`, `serverTimeUtc`, `slots[]` with `slotIndex` and optional `cooldownEndsAtUtc` per slot). **404** when the player id is unknown to position state (same rule as loadout GET). + +Implementation: `CooldownSnapshotApi.cs`, `CooldownSnapshotDtos.cs`, `IPlayerAbilityCooldownStore` / `InMemoryPlayerAbilityCooldownStore.cs`. **NEO-30 (Slice 3 telemetry):** authoritative hook-site comments in `AbilityCastApi.cs` for product names `ability_cast_requested` (accept) and `ability_cast_denied` (each JSON deny + `reasonCode`); cataloged emit deferred to **E9.M1** (`TODO` in source).