diff --git a/client/scripts/autoloads/sim_bridge.gd b/client/scripts/autoloads/sim_bridge.gd index 0f03e41b9..8137afc9b 100644 --- a/client/scripts/autoloads/sim_bridge.gd +++ b/client/scripts/autoloads/sim_bridge.gd @@ -425,10 +425,19 @@ func send_named_action(action_name: String, action_data: Variant = null) -> void ## Request a body's generation-cascade layers from the server (#960, D-225). ## Live mode only — sends an AtlasLayerRequest frame; the response arrives via the ## atlas_layers_received signal. No-op in test mode (no server connection). -func request_atlas_layers(body_id: String, up_to: String = "Topography") -> void: +## +## window_center/window_n (T-1138, D-226 T-1124 amendment §1): optional +## windowed district-resolution regional-map query, riding alongside any +## up_to value (the window derivation only needs TerrainAnalysis/BodyParams, +## not a specific whole-body layer to be cached first). Omitted by every +## whole-body-layer caller (show_body()'s existing request), so their wire +## traffic is byte-unchanged. +func request_atlas_layers( + body_id: String, up_to: String = "Topography", window_center: Variant = null, window_n: int = 0 +) -> void: if test_mode or _bridge == null or state != ConnectionState.CONNECTED: return - var bytes := Protocol.encode_atlas_layer_request(body_id, up_to) + var bytes := Protocol.encode_atlas_layer_request(body_id, up_to, window_center, window_n) if bytes.is_empty(): return var err: int = _bridge.send_message(bytes) diff --git a/client/scripts/protocol/atlas_map_protocol.gd b/client/scripts/protocol/atlas_map_protocol.gd index cc6a0e5d9..bbda6245a 100644 --- a/client/scripts/protocol/atlas_map_protocol.gd +++ b/client/scripts/protocol/atlas_map_protocol.gd @@ -16,10 +16,33 @@ class_name AtlasMapProtocol ## A bare map {body_id, up_to} — NOT the Vec array — so the server's ## frame demux routes it to the atlas proxy. up_to is a CascadeLayer unit variant ## (bare string: "Heightmap" | "Topography"). +## +## `window_center`/`window_n` (T-1138, D-226 T-1124 amendment §1): the windowed +## district-resolution regional-map query. Both are OMITTED from the encoded +## map (not sent as null) when window_center is null — this is what makes +## `#[serde(default)]` on the Rust side decode absence as `window_center: None` +## for every whole-body-only caller (request_atlas_layers()'s existing call +## sites), byte-identical to pre-T-1138 wire traffic. window_center is a +## DistrictPos, wire-encoded as the same [row, col] int-pair convention every +## other position field on this channel already uses (road_graph node +## positions, settlement positions, Layer-1 river-cell positions) — there is +## no separate DistrictPos struct-map on the wire, just a 2-element array. +## window_n is left unclamped here — §1 is explicit the server clamps to +## [1, DISTRICT_WINDOW_MAX_N] itself and never trusts the wire value; the +## client-side default/cap constants (DISTRICT_WINDOW_DEFAULT_N/MAX_N) live on +## the regional-window viewer, not duplicated into the codec. static func encode_atlas_layer_request( - mp, body_id: String, up_to: String = "Topography" + mp, + body_id: String, + up_to: String = "Topography", + window_center: Variant = null, + window_n: int = 0 ) -> PackedByteArray: var msg := {"body_id": body_id, "up_to": up_to} + if window_center != null: + var center: Vector2i = window_center + msg["window_center"] = [center.x, center.y] + msg["window_n"] = window_n var result = mp.encode(msg) if result.status != null: push_error("Protocol: encode_atlas_layer_request failed: %s" % result.status) @@ -37,12 +60,22 @@ static func encode_atlas_layer_request( ## the L4 quarter-footprint aggregates, same passthrough pattern — ## QuarterFootprintLayer.entries is a BTreeMap on ## the wire, decoding to a Dictionary with int keys (city_id), no reshaping. -## Key names "road_graph"/"settlements"/"region_grid"/"quarter_footprints" are -## the CONFIRMED wire contract — identical to server/src/atlas/layer_proxy.rs -## AtlasLayerResponse's field names (region_grid pinned 2026-07-14, -## quarter_footprints pinned 2026-07-18; round-tripped by -## test_atlas_overlays.gd and the server's msgpack round-trip tests). This -## remains the one client-side spot to touch if the contract ever changes. +## district_window (T-1138, D-226 T-1124 amendment §2): the windowed +## DistrictWindowLayer — a DISTINCT payload by design (keyed on the request's +## (body, center, n), not the body alone), but the wire passthrough is the +## same shape as every sibling: raw.get() with no reshaping, `None` on the +## wire decodes to GDScript `null` exactly like every other Option field here. +## The response's `center`/`n` echo (inside the layer dict itself) is the +## client's race-condition/staleness guard (§2) — read by the window cache, +## not unwrapped here. +## Key names "road_graph"/"settlements"/"region_grid"/"quarter_footprints"/ +## "district_window" are the CONFIRMED wire contract — identical to +## server/src/atlas/layer_proxy.rs AtlasLayerResponse's field names +## (region_grid pinned 2026-07-14, quarter_footprints pinned 2026-07-18, +## district_window per the D-226 T-1124 amendment §2 struct; round-tripped by +## test_atlas_overlays.gd/test_atlas_data_delivery.gd and the server's msgpack +## round-trip tests). This remains the one client-side spot to touch if the +## contract ever changes. static func atlas_response_from_raw(raw: Variant) -> Variant: if not raw is Dictionary or not raw.has("status"): return null @@ -64,6 +97,7 @@ static func atlas_response_from_raw(raw: Variant) -> Variant: "settlements": raw.get("settlements"), "region_grid": raw.get("region_grid"), "quarter_footprints": raw.get("quarter_footprints"), + "district_window": raw.get("district_window"), } diff --git a/client/scripts/protocol/protocol.gd b/client/scripts/protocol/protocol.gd index e697aef34..c9989a350 100644 --- a/client/scripts/protocol/protocol.gd +++ b/client/scripts/protocol/protocol.gd @@ -776,16 +776,24 @@ static func encode_request_bookmark_catalog() -> PackedByteArray: ## above. Every function below is a thin delegate under its ORIGINAL public ## name — external callers (sim_bridge.gd, test_atlas_overlays.gd, ## test_atlas_data_delivery.gd) are unaffected by the move. +## window_center/window_n (T-1138, D-226 T-1124 amendment §1): optional +## windowed district-resolution regional-map query — see +## atlas_map_protocol.gd's encode_atlas_layer_request doc for the wire shape. +## Omitted callers (every whole-body-layer call site predating T-1138) are +## byte-unchanged. static func encode_atlas_layer_request( - body_id: String, up_to: String = "Topography" + body_id: String, + up_to: String = "Topography", + window_center: Variant = null, + window_n: int = 0 ) -> PackedByteArray: - return _amp().encode_atlas_layer_request(_mp(), body_id, up_to) + return _amp().encode_atlas_layer_request(_mp(), body_id, up_to, window_center, window_n) ## Decode an AtlasLayerResponse (#969, D-225). Returns a Dictionary ## {body_id, status, error, layer1, district_grid, road_graph, settlements, -## region_grid, quarter_footprints}, or null if the bytes are not an atlas -## response (no "status" key — e.g. an ObserverSnapshot). +## region_grid, quarter_footprints, district_window}, or null if the bytes are +## not an atlas response (no "status" key — e.g. an ObserverSnapshot). static func decode_atlas_layer_response(bytes: PackedByteArray) -> Variant: return atlas_response_from_raw(decode_raw(bytes)) diff --git a/client/tests/test_atlas_data_delivery.gd b/client/tests/test_atlas_data_delivery.gd index e0986150d..7c84fa5aa 100644 --- a/client/tests/test_atlas_data_delivery.gd +++ b/client/tests/test_atlas_data_delivery.gd @@ -12,6 +12,12 @@ class_name TestAtlasDataDelivery extends GdUnitTestSuite +# T-1138: REGION_TEMP_NONE_DC sentinel reused verbatim for district_window's +# temp_dc field (D-226 T-1124 amendment §2 — one colorizer/sentinel scheme +# across both zoom levels). No class_name on atlas_overlay_colors.gd (review +# #8 precedent elsewhere in this suite) — preloaded by path. +const AtlasOverlayColors := preload("res://ui/implant/apps/atlas/atlas_overlay_colors.gd") + # ============================================================================= # Encode/decode round-trips @@ -177,6 +183,70 @@ func test_atlas_response_road_graph_and_settlements_default_null() -> void: assert_that((decoded as Dictionary).get("settlements")).is_null() +# ============================================================================= +# T-1138 (D-226 T-1124 amendment): windowed district-resolution regional map +# ============================================================================= + + +## §1: window_center/window_n are OMITTED (not sent as null) when no window is +## requested — this is what makes an old-shaped call (every whole-body-layer +## call site) byte-identical to pre-T-1138 wire traffic. +func test_encode_atlas_layer_request_omits_window_fields_by_default() -> void: + var bytes := Protocol.encode_atlas_layer_request("GJ1c", "Topography") + var decoded = Messagepack.decode(bytes) + assert_that(decoded.status == null).is_true() + assert_bool(decoded.value.has("window_center")).is_false() + assert_bool(decoded.value.has("window_n")).is_false() + + +## §1: a windowed request carries window_center as a [row, col] pair (the same +## int-pair convention every other position field on this channel already +## uses — road_graph nodes, settlements, Layer-1 river cells) and window_n +## verbatim, unclamped (the server owns the [1, DISTRICT_WINDOW_MAX_N] clamp). +func test_encode_atlas_layer_request_carries_window_params() -> void: + var bytes := Protocol.encode_atlas_layer_request( + "GJ1c", "Topography", Vector2i(140, 260), 32 + ) + var decoded = Messagepack.decode(bytes) + assert_that(decoded.status == null).is_true() + assert_that(decoded.value.get("body_id")).is_equal("GJ1c") + assert_that(decoded.value.get("window_center")).is_equal([140, 260]) + assert_that(decoded.value.get("window_n")).is_equal(32) + + +## §2: district_window is a distinct payload (echoes center/n for the +## client's staleness guard) but the codec passthrough is the same shape as +## every sibling layer — raw.get(), no reshaping. Field types follow the +## established district_grid/region_grid convention: u8 arrays decode as +## PackedByteArray, i16 (temp_dc, REGION_TEMP_NONE_DC sentinel scheme) as a +## plain Array (test_region_grid_round_trips' mean_temp_dc precedent). +func test_atlas_response_district_window_passthrough() -> void: + var window := { + "center": [140, 260], + "n": 32, + "morphology": PackedByteArray([8, 14, 0, 5]), + "elev_q": PackedByteArray([40, 62, 5, 88]), + "temp_dc": [120, 95, AtlasOverlayColors.REGION_TEMP_NONE_DC, 60], + "moisture_q": PackedByteArray([50, 30, 90, 20]), + "vegetation": PackedByteArray([2, 1, 6, 3]), + "glaciation": PackedByteArray([0, 0, 1, 2]), + } + var raw := {"body_id": "GJ1c", "status": "Ready", "district_window": window} + var decoded: Variant = Protocol.atlas_response_from_raw(raw) + assert_that(decoded).is_not_null() + assert_that((decoded as Dictionary).get("district_window")).is_equal(window) + + +## A body with no window requested (or not yet derived — §1's background-queue +## serving model: the completion may not have landed yet) must decode with +## district_window absent -> null, same "layer hasn't produced yet" contract +## every other Option layer already has. +func test_atlas_response_district_window_default_null() -> void: + var decoded: Variant = Protocol.atlas_response_from_raw({"body_id": "GJ1c", "status": "Ready"}) + assert_that(decoded).is_not_null() + assert_that((decoded as Dictionary).get("district_window")).is_null() + + # ============================================================================= # SimBridge routing — receive_bytes emits the right signal with the right value # ============================================================================= diff --git a/client/tests/test_atlas_descend_entry.gd b/client/tests/test_atlas_descend_entry.gd new file mode 100644 index 000000000..dde9e334f --- /dev/null +++ b/client/tests/test_atlas_descend_entry.gd @@ -0,0 +1,162 @@ +## T-1138 (D-226 T-1124 amendment §5 entry revision): tests for the planetary +## AtlasViewer's click-through descent — the fixed view (no drag-pan/wheel- +## zoom), the pixel-to-DistrictPos inverse mapping (atlas_descend_geometry.gd), +## and the city-click-wins disambiguation rule. +class_name TestAtlasDescendEntry +extends GdUnitTestSuite + +const AtlasDescendGeometry := preload("res://ui/implant/apps/atlas/atlas_descend_geometry.gd") + + +# ============================================================================= +# atlas_descend_geometry.gd — pure geometry (no scene tree needed) +# ============================================================================= + + +## The default n=32 window's real footprint is 32 * 2.048 km = 65.536 km, so +## the label reads "~66 x 66 km" (rounded) — pins the number the amendment's +## "honest labeling" resolution depends on. +func test_reticle_label_extent_matches_district_window_default_n() -> void: + var label: Dictionary = AtlasDescendGeometry.reticle_label(Vector2(100.0, 100.0)) + var expected_km: float = 32.0 * 2048.0 / 1000.0 + assert_str(label["text"]).is_equal("~%.0f × %.0f km" % [expected_km, expected_km]) + + +func test_reticle_label_position_offsets_from_center() -> void: + var center := Vector2(50.0, 60.0) + var label: Dictionary = AtlasDescendGeometry.reticle_label(center) + var pos: Vector2 = label["position"] + assert_float(pos.x).is_greater(center.x) # offset to the right, per §5's resolution + + +## Eight segments (four L-shaped bracket corners, two arms each) — every +## segment's "from" endpoint is exactly one of the four corner anchors, and no +## segment has zero length (a degenerate reticle would be invisible). +func test_reticle_segments_has_eight_nonzero_segments() -> void: + var segments: Array = AtlasDescendGeometry.reticle_segments(Vector2(200.0, 150.0)) + assert_int(segments.size()).is_equal(8) + for seg: Array in segments: + assert_that(seg[0]).override_failure_message( + "a reticle segment must not be zero-length" + ).is_not_equal(seg[1]) + + +## The reticle's overall bounding box is centered on `center` and sized by +## DESCEND_RETICLE_SIZE — a regression guard against an off-center or +## mis-scaled bracket. +func test_reticle_segments_centered_on_input_point() -> void: + var center := Vector2(300.0, 300.0) + var segments: Array = AtlasDescendGeometry.reticle_segments(center) + var min_pt := Vector2(INF, INF) + var max_pt := Vector2(-INF, -INF) + for seg: Array in segments: + for p: Vector2 in seg: + min_pt.x = minf(min_pt.x, p.x) + min_pt.y = minf(min_pt.y, p.y) + max_pt.x = maxf(max_pt.x, p.x) + max_pt.y = maxf(max_pt.y, p.y) + var bbox_center: Vector2 = (min_pt + max_pt) * 0.5 + assert_float(bbox_center.x).is_equal_approx(center.x, 0.01) + assert_float(bbox_center.y).is_equal_approx(center.y, 0.01) + + +# ============================================================================= +# district_pos_at — pixel-to-DistrictPos inverse mapping +# ============================================================================= + + +## No radius (tiny test body fallback, matches the server's own derive_district +## fallback): the district grid IS the heightmap grid 1:1, so a canvas point +## maps to the nearest integer district coordinate directly. +func test_district_pos_at_no_radius_is_1to1_pixel_mapping() -> void: + var pos: Vector2i = AtlasDescendGeometry.district_pos_at( + Vector2(12.4, 7.6), 100.0, 100.0, 0.0 + ) + assert_that(pos).is_equal(Vector2i(12, 8)) + + +func test_district_pos_at_zero_texture_size_is_safe() -> void: + var pos: Vector2i = AtlasDescendGeometry.district_pos_at(Vector2(10.0, 10.0), 0.0, 0.0, 6371.0) + assert_that(pos).is_equal(Vector2i.ZERO) + + +## The equatorial center of the texture (px = tex_w/2) is district column +## district_cols/2 on a body with a radius (equator wraps at district (0,0) +## per the server's own doc: "district (0,0) sits at lon 0 / the equator"). +## The vertical center (py = tex_h/2) is the equator row (row 0). +func test_district_pos_at_center_of_texture_is_near_equator_row_zero() -> void: + var radius_km := 6371.0 + var tex_w := 1024.0 + var tex_h := 512.0 + var pos: Vector2i = AtlasDescendGeometry.district_pos_at( + Vector2(0.0, tex_h * 0.5), tex_w, tex_h, radius_km + ) + assert_int(pos.y).override_failure_message( + "the vertical texture center must map to row 0 (the equator)" + ).is_equal(0) + + +## Panning across the texture's full width sweeps through the FULL district +## column range (not clamped to a tiny sub-range) — a coarse sanity check that +## district_cols is actually being derived from the body's circumference, not +## left at some degenerate default. +func test_district_pos_at_sweeps_full_column_range_across_texture_width() -> void: + var radius_km := 6371.0 + var tex_w := 1024.0 + var tex_h := 512.0 + var left: Vector2i = AtlasDescendGeometry.district_pos_at( + Vector2(0.0, tex_h * 0.5), tex_w, tex_h, radius_km + ) + var right: Vector2i = AtlasDescendGeometry.district_pos_at( + Vector2(tex_w - 1.0, tex_h * 0.5), tex_w, tex_h, radius_km + ) + # An Earth-radius body has thousands of equatorial districts (circumference + # ~40,075 km / 2.048 km per district ≈ 19,568) — near-full-width should + # sweep a large fraction of that, not a handful of columns. + assert_int(absi(right.x - left.x)).is_greater(1000) + + +# ============================================================================= +# AtlasViewer — fixed view (no drag-pan/wheel-zoom) + click-through descent +# ============================================================================= + + +## T-1120 capture API (set_view/get_view_offset/get_view_zoom) must survive +## the removal of user pan/zoom — this is the ticket's own explicit note, and +## the visual-golden harness depends on it. +func test_set_view_still_works_after_pan_zoom_removal() -> void: + var v: AtlasViewer = auto_free(AtlasViewer.new()) + add_child(v) + v.set_view(3.0, Vector2(50.0, -20.0)) + assert_that(v.get_view_zoom()).is_equal_approx(3.0, 0.001) + assert_that(v.get_view_offset()).is_equal(Vector2(50.0, -20.0)) + + +## Clicking (with no heightmap loaded — the guard AtlasViewer's _gui_input +## checks first) must not emit a descend request — there is nothing to +## descend into yet. +func test_no_descend_signal_without_a_loaded_heightmap() -> void: + var v: AtlasViewer = auto_free(AtlasViewer.new()) + add_child(v) + var received: Array = [] + v.district_descend_requested.connect(func(c: Vector2i) -> void: received.append(c)) + # _heightmap_texture stays null (no show_body() call) — _gui_input's + # early-return guard should prevent any click handling at all. + var mb := InputEventMouseButton.new() + mb.button_index = MOUSE_BUTTON_LEFT + mb.pressed = true + mb.position = Vector2(100.0, 100.0) + v._gui_input(mb) + assert_int(received.size()).is_equal(0) + + +## RegionalScreen forwards AtlasViewer's district_descend_requested verbatim — +## the nav-stack wiring atlas_app.gd depends on. +func test_regional_screen_forwards_district_descend_requested() -> void: + var screen: RegionalScreen = auto_free(RegionalScreen.new()) + add_child(screen) + var received: Array = [] + screen.district_descend_requested.connect(func(c: Vector2i) -> void: received.append(c)) + screen._viewer.district_descend_requested.emit(Vector2i(5, 7)) + assert_int(received.size()).is_equal(1) + assert_that(received[0]).is_equal(Vector2i(5, 7)) diff --git a/client/tests/test_atlas_window_cache.gd b/client/tests/test_atlas_window_cache.gd new file mode 100644 index 000000000..1471f7823 --- /dev/null +++ b/client/tests/test_atlas_window_cache.gd @@ -0,0 +1,121 @@ +## T-1138 (D-226 T-1124 amendment §4): tests for the client-side +## DistrictWindowLayer LRU cache — keyed on (body_id, center, n), LRU-evict +## only (D-227 determinism means no freshness check is ever needed). +class_name TestAtlasWindowCache +extends GdUnitTestSuite + +const AtlasWindowCache := preload("res://ui/implant/apps/atlas/atlas_window_cache.gd") + + +func test_make_key_distinguishes_body_center_and_n() -> void: + var k1 := AtlasWindowCache.make_key("GJ1c", Vector2i(10, 20), 32) + var k2 := AtlasWindowCache.make_key("GJ1d", Vector2i(10, 20), 32) # different body + var k3 := AtlasWindowCache.make_key("GJ1c", Vector2i(11, 20), 32) # different center + var k4 := AtlasWindowCache.make_key("GJ1c", Vector2i(10, 20), 64) # different n + assert_str(k1).is_not_equal(k2) + assert_str(k1).is_not_equal(k3) + assert_str(k1).is_not_equal(k4) + + +func test_miss_returns_null_and_has_reports_false() -> void: + var cache := AtlasWindowCache.new() + assert_that(cache.get_window("GJ1c", Vector2i(0, 0), 32)).is_null() + assert_bool(cache.has("GJ1c", Vector2i(0, 0), 32)).is_false() + + +func test_put_then_get_round_trips_exact_window() -> void: + var cache := AtlasWindowCache.new() + var window := {"center": [10, 20], "n": 32, "morphology": PackedByteArray([1, 2, 3])} + cache.put("GJ1c", Vector2i(10, 20), 32, window) + assert_bool(cache.has("GJ1c", Vector2i(10, 20), 32)).is_true() + assert_that(cache.get_window("GJ1c", Vector2i(10, 20), 32)).is_equal(window) + + +## D-227: a window fetched once is valid FOREVER for that (body, center, n) — +## no expiry, no invalidation path. Repeated get_window() calls across a +## simulated time gap (just repeated calls here — there is no clock in this +## cache at all) must keep returning the same stored value. +func test_cached_window_never_expires() -> void: + var cache := AtlasWindowCache.new() + var window := {"center": [0, 0], "n": 32} + cache.put("GJ1c", Vector2i(0, 0), 32, window) + for _i in range(50): + assert_that(cache.get_window("GJ1c", Vector2i(0, 0), 32)).is_equal(window) + + +## Different (body_id, center, n) tuples never collide — this is the whole +## point of the composite key (§4: "cacheable client-side keyed on +## (body_id, center, n)"). +func test_different_bodies_same_center_do_not_collide() -> void: + var cache := AtlasWindowCache.new() + var window_a := {"body": "GJ1c"} + var window_b := {"body": "GJ1d"} + cache.put("GJ1c", Vector2i(10, 20), 32, window_a) + cache.put("GJ1d", Vector2i(10, 20), 32, window_b) + assert_that(cache.get_window("GJ1c", Vector2i(10, 20), 32)).is_equal(window_a) + assert_that(cache.get_window("GJ1d", Vector2i(10, 20), 32)).is_equal(window_b) + + +## Overwriting the same key replaces the value (e.g. a re-fetch of an +## already-cached window from a server that somehow returns a different +## payload — should never happen under D-227, but the cache itself must not +## silently keep the stale one on an explicit put()). +func test_put_overwrites_existing_key() -> void: + var cache := AtlasWindowCache.new() + cache.put("GJ1c", Vector2i(0, 0), 32, {"v": 1}) + cache.put("GJ1c", Vector2i(0, 0), 32, {"v": 2}) + assert_int(cache.size()).is_equal(1) + assert_that(cache.get_window("GJ1c", Vector2i(0, 0), 32)).is_equal({"v": 2}) + + +# ============================================================================= +# LRU eviction +# ============================================================================= + + +func test_eviction_drops_least_recently_used_on_overflow() -> void: + var cache := AtlasWindowCache.new(2) # max 2 entries + cache.put("GJ1c", Vector2i(0, 0), 32, {"id": "a"}) + cache.put("GJ1c", Vector2i(1, 0), 32, {"id": "b"}) + cache.put("GJ1c", Vector2i(2, 0), 32, {"id": "c"}) # evicts (0,0) — oldest, untouched + + assert_int(cache.size()).is_equal(2) + assert_bool(cache.has("GJ1c", Vector2i(0, 0), 32)).override_failure_message( + "oldest entry should have been evicted" + ).is_false() + assert_bool(cache.has("GJ1c", Vector2i(1, 0), 32)).is_true() + assert_bool(cache.has("GJ1c", Vector2i(2, 0), 32)).is_true() + + +## get_window() touches an entry (moves it to most-recently-used) — reading an +## entry must protect it from the NEXT eviction, otherwise "LRU" degrades to +## FIFO the moment anything reads from the cache (the common case: Esc-then- +## re-enter and pan-back are exactly "read a recently-cached window", §4). +func test_get_touches_entry_and_protects_it_from_eviction() -> void: + var cache := AtlasWindowCache.new(2) + cache.put("GJ1c", Vector2i(0, 0), 32, {"id": "a"}) + cache.put("GJ1c", Vector2i(1, 0), 32, {"id": "b"}) + cache.get_window("GJ1c", Vector2i(0, 0), 32) # touch (0,0) — now most-recently-used + cache.put("GJ1c", Vector2i(2, 0), 32, {"id": "c"}) # should evict (1,0), not (0,0) + + assert_bool(cache.has("GJ1c", Vector2i(0, 0), 32)).override_failure_message( + "touched entry should survive eviction" + ).is_true() + assert_bool(cache.has("GJ1c", Vector2i(1, 0), 32)).override_failure_message( + "untouched entry should be the one evicted" + ).is_false() + + +func test_max_entries_clamped_to_at_least_one() -> void: + var cache := AtlasWindowCache.new(0) + cache.put("GJ1c", Vector2i(0, 0), 32, {"id": "a"}) + cache.put("GJ1c", Vector2i(1, 0), 32, {"id": "b"}) + assert_int(cache.size()).is_equal(1) + + +func test_clear_empties_the_cache() -> void: + var cache := AtlasWindowCache.new() + cache.put("GJ1c", Vector2i(0, 0), 32, {"id": "a"}) + cache.clear() + assert_int(cache.size()).is_equal(0) + assert_bool(cache.has("GJ1c", Vector2i(0, 0), 32)).is_false() diff --git a/client/tests/test_atlas_window_colors.gd b/client/tests/test_atlas_window_colors.gd new file mode 100644 index 000000000..0ddb20746 --- /dev/null +++ b/client/tests/test_atlas_window_colors.gd @@ -0,0 +1,170 @@ +## T-1138 (D-226 T-1124 amendment §5): pure color-ramp tests for the +## regional-window base layer + toggle overlays. Every function under test +## lives on atlas_overlay_colors.gd (no class_name — preloaded by path, +## matching test_atlas_overlays.gd's own AtlasOverlayColors const). +class_name TestAtlasWindowColors +extends GdUnitTestSuite + +const AtlasOverlayColors := preload("res://ui/implant/apps/atlas/atlas_overlay_colors.gd") + + +# ============================================================================= +# Base layer: morphology hue + elev_q lightness modulation +# ============================================================================= + + +## MORPHOLOGY_RGB_OPAQUE must be the SAME 17-entry hue table as the planetary +## overlay's MORPHOLOGY_COLORS (D-226 T-1124 amendment §5: "reusing the T-1123 +## probe's 17-entry MORPHOLOGY_RGB hues verbatim") — only alpha differs (the +## window base is opaque; the planetary overlay draws semi-transparent over a +## heightmap texture). +func test_district_window_morphology_hues_match_planetary_overlay() -> void: + assert_int(AtlasOverlayColors.MORPHOLOGY_RGB_OPAQUE.size()).is_equal( + AtlasOverlayColors.MORPHOLOGY_COLORS.size() + ) + for zone in range(AtlasOverlayColors.MORPHOLOGY_RGB_OPAQUE.size()): + var opaque: Color = AtlasOverlayColors.MORPHOLOGY_RGB_OPAQUE[zone] + var overlay: Color = AtlasOverlayColors.MORPHOLOGY_COLORS[zone] + assert_float(opaque.r).override_failure_message( + "zone %d hue mismatch (r)" % zone + ).is_equal_approx(overlay.r, 0.005) + assert_float(opaque.g).override_failure_message( + "zone %d hue mismatch (g)" % zone + ).is_equal_approx(overlay.g, 0.005) + assert_float(opaque.b).override_failure_message( + "zone %d hue mismatch (b)" % zone + ).is_equal_approx(overlay.b, 0.005) + assert_float(opaque.a).override_failure_message( + "district-window base layer must be OPAQUE (a=1.0), zone %d" % zone + ).is_equal_approx(1.0, 0.001) + + +func test_district_window_morphology_color_out_of_range_is_magenta_sentinel() -> void: + var c: Color = AtlasOverlayColors.district_window_morphology_color(999) + assert_float(c.r).is_equal_approx(1.0, 0.001) + assert_float(c.g).is_equal_approx(0.0, 0.001) + assert_float(c.b).is_equal_approx(1.0, 0.001) + + +## elev_q=0 -> 0.7x lightness; elev_q=100 -> 1.0x lightness (full base color); +## elev_q=50 -> 0.85x (the midpoint of the documented [0.7, 1.0] range). +func test_district_window_elevation_lightness_modulation() -> void: + var base := Color(0.4, 0.4, 0.4, 1.0) + var low: Color = AtlasOverlayColors.district_window_elevation_lightness(base, 0) + var mid: Color = AtlasOverlayColors.district_window_elevation_lightness(base, 50) + var high: Color = AtlasOverlayColors.district_window_elevation_lightness(base, 100) + + assert_float(low.r).is_equal_approx(0.4 * 0.7, 0.001) + assert_float(mid.r).is_equal_approx(0.4 * 0.85, 0.001) + assert_float(high.r).is_equal_approx(0.4 * 1.0, 0.001) + # Alpha is untouched by the lightness multiply. + assert_float(low.a).is_equal_approx(1.0, 0.001) + + +func test_district_window_elevation_lightness_clamps_out_of_range_elev_q() -> void: + var base := Color(0.4, 0.4, 0.4, 1.0) + var below: Color = AtlasOverlayColors.district_window_elevation_lightness(base, -20) + var above: Color = AtlasOverlayColors.district_window_elevation_lightness(base, 500) + assert_float(below.r).is_equal_approx(0.4 * 0.7, 0.001) + assert_float(above.r).is_equal_approx(0.4 * 1.0, 0.001) + + +# ============================================================================= +# Vegetation ramp (Marine transparent, D-226 T-1124 amendment §3/§5) +# ============================================================================= + + +## Marine (VegetationClass discriminant 6, T-1126) MUST render transparent — +## "non-negotiable inclusion, not a nice-to-have" per the amendment §3. This is +## the one assertion in this suite with the highest stakes: a regression here +## re-introduces the exact ocean-blind-vegetation bug T-1126 was created to fix. +func test_vegetation_marine_is_transparent() -> void: + var c: Color = AtlasOverlayColors.vegetation_color(AtlasOverlayColors.VEGETATION_MARINE) + assert_that(c).is_equal(Color.TRANSPARENT) + assert_int(AtlasOverlayColors.VEGETATION_MARINE).is_equal(6) + + +## Every VegetationClass discriminant (0 Absent .. 5 RiparianThicket, excluding +## 6 Marine which is transparent) must resolve to a DISTINCT, non-transparent +## color — the amendment's exhaustive-disposition mandate (§3) extended to the +## full field-list, matching quarter_notch_kind's own "every variant reads as +## something" test precedent in test_atlas_overlays.gd. +func test_vegetation_ramp_is_exhaustive_and_distinct() -> void: + var seen: Array = [] + for vc in range(0, 6): # 0..5, Marine (6) handled separately above + var c: Color = AtlasOverlayColors.vegetation_color(vc) + assert_float(c.a).override_failure_message( + "VegetationClass %d must not be transparent" % vc + ).is_greater(0.0) + assert_that(seen).override_failure_message( + "VegetationClass %d collides with an earlier entry's color" % vc + ).not_contains([c]) + seen.append(c) + + +func test_vegetation_color_unrecognized_falls_back_to_absent_reading() -> void: + var unknown: Color = AtlasOverlayColors.vegetation_color(999) + var absent: Color = AtlasOverlayColors.vegetation_color(0) + assert_that(unknown).is_equal(absent) + + +# ============================================================================= +# Glaciation ice-tint modifier (D-226 T-1124 amendment §5, ported apply_ice_tint) +# ============================================================================= + + +## None (0) and Light (1) must return the base color UNCHANGED — this is the +## load-bearing divergence from the amendment's own prose summary ("gated on +## glaciation_grade >= Light"): the REFERENCE implementation the amendment +## names for porting (aliveness_probe::apply_ice_tint) excludes Light too, +## because grade 1 is glacial-erosion signatures, not visible ice. This test +## pins that the port, not the summary, is what shipped. +func test_glaciation_tint_none_and_light_are_no_ops() -> void: + var base := Color(0.3, 0.5, 0.3, 0.8) + _assert_color_approx(AtlasOverlayColors.glaciation_tint(base, 0), base) # None + _assert_color_approx(AtlasOverlayColors.glaciation_tint(base, 1), base) # Light + + +## Moderate (2) / Heavy (3) / IceCap (4) blend increasingly toward +## GLACIATION_ICE_WHITE — each grade strictly closer to white than the last +## (monotonic tint strength), matching apply_ice_tint's 0.30/0.50/0.70 alphas. +func test_glaciation_tint_increases_with_grade() -> void: + var base := Color(0.1, 0.1, 0.1, 1.0) # far from ice-white, maximizes signal + var white: Color = AtlasOverlayColors.GLACIATION_ICE_WHITE + + var moderate: Color = AtlasOverlayColors.glaciation_tint(base, 2) + var heavy: Color = AtlasOverlayColors.glaciation_tint(base, 3) + var ice_cap: Color = AtlasOverlayColors.glaciation_tint(base, 4) + + var dist_moderate: float = _color_distance(base, moderate) + var dist_heavy: float = _color_distance(base, heavy) + var dist_ice_cap: float = _color_distance(base, ice_cap) + + assert_float(dist_heavy).override_failure_message( + "Heavy should tint more than Moderate" + ).is_greater(dist_moderate) + assert_float(dist_ice_cap).override_failure_message( + "IceCap should tint more than Heavy" + ).is_greater(dist_heavy) + + # IceCap (alpha 0.70) should land noticeably closer to white than to base. + assert_float(_color_distance(ice_cap, white)).is_less(_color_distance(ice_cap, base)) + + +func test_glaciation_tint_out_of_range_grade_is_no_op() -> void: + var base := Color(0.3, 0.5, 0.3, 0.8) + _assert_color_approx(AtlasOverlayColors.glaciation_tint(base, 999), base) + + +func _assert_color_approx(actual: Color, expected: Color) -> void: + assert_float(actual.r).is_equal_approx(expected.r, 0.0001) + assert_float(actual.g).is_equal_approx(expected.g, 0.0001) + assert_float(actual.b).is_equal_approx(expected.b, 0.0001) + assert_float(actual.a).is_equal_approx(expected.a, 0.0001) + + +## Godot 4's Color has no distance_to() — plain Euclidean over RGB (alpha +## deliberately excluded: the tint blend leaves alpha untouched, so including +## it would just add a constant offset with no signal). +static func _color_distance(a: Color, b: Color) -> float: + return Vector3(a.r, a.g, a.b).distance_to(Vector3(b.r, b.g, b.b)) diff --git a/client/tests/test_atlas_window_viewer.gd b/client/tests/test_atlas_window_viewer.gd new file mode 100644 index 000000000..22d7ab41f --- /dev/null +++ b/client/tests/test_atlas_window_viewer.gd @@ -0,0 +1,204 @@ +## T-1138 (D-226 T-1124 amendment §1-§5): tests for AtlasWindowViewer + its +## companion request/cache orchestration (atlas_window_request.gd) — pure +## logic against hand-built AtlasLayerResponse-shaped dicts, matching the +## ticket's "unit tests against hand-built response dicts" instruction. Live +## end-to-end verification against a real spawned server is separate +## (companion-run evidence, not gdUnit — this file never touches SimBridge's +## live-mode path, only the response-handling/cache/overlay logic that path +## eventually feeds). +class_name TestAtlasWindowViewer +extends GdUnitTestSuite + +# atlas_window_request.gd has no class_name (review #8 precedent throughout +# this cluster) — preloaded once here, not re-load()ed per test (gdlint +# duplicated-load). +const AtlasWindowRequest := preload("res://ui/implant/apps/atlas/atlas_window_request.gd") + + +## Build a hand-authored DistrictWindowLayer dict (n=2, matching the shape +## district_grid/region_grid fixtures already use elsewhere in this suite). +static func _mock_window(center: Vector2i, n: int = 2) -> Dictionary: + return { + "center": [center.x, center.y], + "n": n, + "morphology": PackedByteArray([8, 14, 0, 1]), + "elev_q": PackedByteArray([40, 90, 5, 60]), + "temp_dc": [120, 95, -32768, 60], + "moisture_q": PackedByteArray([50, 30, 90, 20]), + "vegetation": PackedByteArray([2, 1, 6, 3]), + "glaciation": PackedByteArray([0, 0, 1, 2]), + } + + +static func _mock_response(body_id: String, window: Variant) -> Dictionary: + return {"body_id": body_id, "status": "Ready", "district_window": window} + + +# ============================================================================= +# AtlasWindowViewer — entry + overlay defs +# ============================================================================= + + +func test_enter_with_no_response_leaves_window_null_and_pending() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.enter({"body_id": "GJ380c"}, {}, Vector2i(10, 20)) + assert_that(v.get_district_window()).is_null() + + +## Feeding a matching Ready response (via the SAME SimBridge.atlas_layers_received +## routing path the viewer subscribes to in _ready()) must populate the window. +func test_enter_then_matching_response_populates_window() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.enter({"body_id": "GJ380c"}, {}, Vector2i(10, 20), 2) + + var window: Dictionary = _mock_window(Vector2i(10, 20), 2) + SimBridge.atlas_layers_received.emit(_mock_response("GJ380c", window)) + + assert_that(v.get_district_window()).is_equal(window) + + +## A response for a DIFFERENT body must not populate the window — the +## body_id scoping AtlasWindowRequest.on_response() checks. +func test_response_for_different_body_is_ignored() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.enter({"body_id": "GJ380c"}, {}, Vector2i(10, 20), 2) + + var window: Dictionary = _mock_window(Vector2i(10, 20), 2) + SimBridge.atlas_layers_received.emit(_mock_response("GJ_wrong_body", window)) + + assert_that(v.get_district_window()).is_null() + + +## A response whose echoed (center, n) does NOT match what was last asked for +## is stale — §2's race-condition guard. Simulates a superseded-by-a-later-pan +## response arriving after the fact. +func test_response_with_mismatched_echo_is_discarded_as_stale() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.enter({"body_id": "GJ380c"}, {}, Vector2i(10, 20), 2) + + var stale_window: Dictionary = _mock_window(Vector2i(99, 99), 2) # wrong center + SimBridge.atlas_layers_received.emit(_mock_response("GJ380c", stale_window)) + + assert_that(v.get_district_window()).is_null() + + +## §1: an as-yet-underived window rides as `district_window: None` inside a +## Ready response — this is NOT an error, the viewer just keeps waiting +## (get_district_window() stays null, no crash, no window content shown). +func test_ready_response_with_null_district_window_keeps_waiting() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.enter({"body_id": "GJ380c"}, {}, Vector2i(10, 20), 2) + SimBridge.atlas_layers_received.emit(_mock_response("GJ380c", null)) + assert_that(v.get_district_window()).is_null() + + +func test_overlay_defs_include_the_three_toggle_ids() -> void: + var ids: Array = [] + for d: Dictionary in AtlasWindowViewer.OVERLAY_DEFS: + ids.append(d["id"]) + assert_that(ids).contains(["gen_dw_temp", "gen_dw_moisture", "gen_dw_veg"]) + + +## Glaciation is explicitly NOT a toggle id (§5: "an always-on modifier, not +## a toggle") — a regression here would silently re-introduce it as a switch. +func test_overlay_defs_do_not_include_glaciation() -> void: + var ids: Array = [] + for d: Dictionary in AtlasWindowViewer.OVERLAY_DEFS: + ids.append(d["id"]) + assert_that(ids).not_contains(["gen_dw_glaciation", "gen_dw_ice"]) + + +func test_set_overlay_visible_toggles_and_is_overlay_visible_reflects_it() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + assert_bool(v.is_overlay_visible("gen_dw_temp")).is_false() + v.set_overlay_visible("gen_dw_temp", true) + assert_bool(v.is_overlay_visible("gen_dw_temp")).is_true() + + +func test_set_overlay_visible_unknown_id_is_a_noop() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.set_overlay_visible("not_a_real_overlay", true) + assert_bool(v.is_overlay_visible("not_a_real_overlay")).is_false() + + +# ============================================================================= +# T-1120 capture-API parity (the ticket's explicit note: must survive here too) +# ============================================================================= + + +func test_set_view_and_getters_round_trip() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.set_view(2.5, Vector2(30.0, -10.0)) + assert_that(v.get_view_zoom()).is_equal_approx(2.5, 0.001) + assert_that(v.get_view_offset()).is_equal(Vector2(30.0, -10.0)) + + +func test_set_view_clamps_to_min_max_zoom() -> void: + var v: AtlasWindowViewer = auto_free(AtlasWindowViewer.new()) + add_child(v) + v.set_view(0.01, Vector2.ZERO) + assert_that(v.get_view_zoom()).is_equal_approx(AtlasWindowViewer.MIN_ZOOM, 0.001) + v.set_view(1000.0, Vector2.ZERO) + assert_that(v.get_view_zoom()).is_equal_approx(AtlasWindowViewer.MAX_ZOOM, 0.001) + + +# ============================================================================= +# AtlasWindowRequest — cache reuse (§4's Esc-then-re-enter / pan-back hit) +# ============================================================================= + + +func test_window_request_cache_hit_emits_synchronously_no_pending() -> void: + var owner_stub := RefCounted.new() + var req = auto_free(AtlasWindowRequest.new(owner_stub)) + add_child(req) + + # Prime the cache directly (bypassing the network path) — the ticket's + # own instruction: unit test against hand-built response dicts. + req.get_cache().put("GJ380c", Vector2i(1, 1), 2, _mock_window(Vector2i(1, 1), 2)) + + var received: Array = [] + req.window_ready.connect(func(w: Dictionary) -> void: received.append(w)) + req.request_now("GJ380c", Vector2i(1, 1), 2) + + assert_int(received.size()).is_equal(1) + assert_bool(req.is_pending()).override_failure_message( + "a cache hit must never leave the request pending" + ).is_false() + + +func test_window_request_cache_miss_leaves_pending_true() -> void: + var owner_stub := RefCounted.new() + var req = auto_free(AtlasWindowRequest.new(owner_stub)) + add_child(req) + req.request_now("GJ380c", Vector2i(5, 5), 2) + assert_bool(req.is_pending()).is_true() + + +## on_response() with a matching Ready+window response resolves the pending +## request AND populates the cache — verified by a second request_now() call +## for the same (center, n) becoming a cache hit with zero additional pending. +func test_on_response_resolves_and_populates_cache_for_next_request() -> void: + var owner_stub := RefCounted.new() + var req = auto_free(AtlasWindowRequest.new(owner_stub)) + add_child(req) + + req.request_now("GJ380c", Vector2i(2, 2), 2) + assert_bool(req.is_pending()).is_true() + + var window: Dictionary = _mock_window(Vector2i(2, 2), 2) + req.on_response(_mock_response("GJ380c", window)) + assert_bool(req.is_pending()).is_false() + + # Re-request the SAME (body, center, n) — must be a cache hit, no pending. + req.request_now("GJ380c", Vector2i(2, 2), 2) + assert_bool(req.is_pending()).override_failure_message( + "a second request for an already-resolved window must hit the cache" + ).is_false() diff --git a/client/ui/implant/apps/atlas/atlas_app.gd b/client/ui/implant/apps/atlas/atlas_app.gd index 85fa9a3ec..7e79fd34d 100644 --- a/client/ui/implant/apps/atlas/atlas_app.gd +++ b/client/ui/implant/apps/atlas/atlas_app.gd @@ -13,6 +13,7 @@ var _reach_screen = null # ReachScreen var _system_screen = null # SystemScreen var _planet_screen = null # PlanetScreen var _regional_screen = null # RegionalScreen +var _district_screen = null # DistrictScreen (T-1138) func _ready() -> void: @@ -47,8 +48,13 @@ func on_install() -> void: _regional_screen = RegionalScreen.new() _regional_screen.back_requested.connect(_on_regional_back) _regional_screen.economics_link_requested.connect(_forward_economics_link) + _regional_screen.district_descend_requested.connect(_on_district_descend_requested) register_screen("regional", _regional_screen) + _district_screen = DistrictScreen.new() + _district_screen.back_requested.connect(_on_district_back) + register_screen("district", _district_screen) + nav.set_default("reach") @@ -65,7 +71,12 @@ func _unhandled_key_input(event: InputEvent) -> void: return if not event.is_pressed() or event.is_echo(): return - if current_screen_id() == "regional": + # "regional" (the planetary heightmap, AtlasViewer) and "district" (the + # windowed regional-window screen, AtlasWindowViewer, T-1138) both handle + # their own Esc via _gui_input — same delegation shape for both, so a + # stray M/other unhandled key on either screen doesn't ALSO fire this + # app's own _handle_key underneath the viewer's own handling. + if current_screen_id() == "regional" or current_screen_id() == "district": return _handle_key(event as InputEventKey) get_viewport().set_input_as_handled() @@ -137,6 +148,25 @@ func _on_regional_back() -> void: nav.pop() +## T-1138: the planetary click-through descent (§5 entry revision) — pushes +## the "district" screen centered on the click point's derived DistrictPos. +## A real nav.push() (not a swap-in-place, unlike the superseded zoom- +## threshold design) so Esc's existing nav.pop() path (DistrictScreen's own +## back_requested -> _on_district_back below) returns to exactly the +## planetary body the player descended from, at whatever crumb depth got +## them there (reach -> system -> regional -> district). +func _on_district_descend_requested(district_center: Vector2i) -> void: + nav.push("district", { + "body": nav.current_payload().get("body", {}), + "system": nav.current_payload().get("system", {}), + "district_center": district_center, + }) + + +func _on_district_back() -> void: + nav.pop() + + func _forward_economics_link(system_id: String) -> void: economics_link_requested.emit(system_id) diff --git a/client/ui/implant/apps/atlas/atlas_descend_geometry.gd b/client/ui/implant/apps/atlas/atlas_descend_geometry.gd new file mode 100644 index 000000000..4202052f3 --- /dev/null +++ b/client/ui/implant/apps/atlas/atlas_descend_geometry.gd @@ -0,0 +1,107 @@ +extends RefCounted + +## Pure geometry helpers for AtlasViewer's T-1138 descent affordance (D-226 +## T-1124 amendment §5 entry revision) — factored out to keep atlas_viewer.gd +## under gdlint's max-file-lines cap, same rationale/shape as +## atlas_overlay_colors.gd's split from atlas_marker_overlay.gd (draw_line()/ +## draw_string() are CanvasItem instance methods called implicitly on `self`, +## so the actual draw calls stay on AtlasViewer — only the pure lookups/math +## that decide WHERE/WHAT to draw move here): +## const AtlasDescendGeometry := preload("res://ui/implant/apps/atlas/atlas_descend_geometry.gd") +## +## D-243: 2,048 m per district side — the source-canonical unit the server's +## derive_district()/DISTRICT_WINDOW_DEFAULT_N (32) both key off of. +const DISTRICT_M: float = 2048.0 +const DISTRICT_WINDOW_DEFAULT_N: int = 32 + +## Fixed on-screen reticle size (px) — deliberately NOT scaled to the +## window's true planetary footprint. +## +## The true footprint of a DISTRICT_WINDOW_DEFAULT_N=32 window is +## 32 * 2.048 km = ~65.5 km per side (~131 km at the n=64 cap) — at every +## zoom level AtlasViewer's _fit_to_view() ever produces for a whole-planet +## heightmap (MAX_ZOOM=8.0 on a texture that already spans the full body), +## that distance is on the order of a handful of PIXELS. A true-extent +## rectangle would therefore be visually indistinguishable from a dot +## regardless of zoom — not an honest representation, just an illegible one; +## the amendment explicitly rejects "implying more coverage than real" but a +## sub-pixel rectangle fails the OPPOSITE way (implying almost no coverage, +## which is equally dishonest about what a click actually captures). +## +## The resolution (D-226 T-1124 amendment §5's open design point, resolved +## here): a small FIXED-SIZE bracket reticle (reads clearly at any zoom, same +## idiom as the marker overlay's fixed-size POI glyphs elsewhere on this map) +## plus a text label giving the REAL extent in km — "honest" comes from the +## label's number, not from the reticle's pixel size pretending to be to +## scale. This is a reticle, explicitly not scaled to true size, with the +## real extent stated next to it — the amendment's second named option +## (chosen over a true-extent rectangle + zoom-in cut). +const DESCEND_RETICLE_SIZE: float = 28.0 +const COLOR_DESCEND_RETICLE: Color = Color(0.70, 0.88, 1.0, 0.85) # matches COLOR_GATE_MARKER family + + +## The eight line segments (as [from, to] pairs) for the reticle's four +## L-shaped bracket corners — reads as "this is a bounded region", distinct +## from the circular city-marker glyphs and diamond gate markers already on +## this map (D-226's hue=type/shape=identity instinct applied to interaction +## affordances). Flat segment-pair array so the caller's draw_line() loop is +## a one-liner, not a struct AtlasViewer needs to know the shape of. +static func reticle_segments(center: Vector2) -> Array: + var half: float = DESCEND_RETICLE_SIZE * 0.5 + var arm: float = half * 0.5 + var corners: Array = [ + center + Vector2(-half, -half), + center + Vector2(half, -half), + center + Vector2(half, half), + center + Vector2(-half, half), + ] + var h_dirs: Array = [Vector2(1, 0), Vector2(-1, 0), Vector2(-1, 0), Vector2(1, 0)] + var v_dirs: Array = [Vector2(0, 1), Vector2(0, 1), Vector2(0, -1), Vector2(0, -1)] + var segments: Array = [] + for i in range(4): + segments.append([corners[i], corners[i] + h_dirs[i] * arm]) + segments.append([corners[i], corners[i] + v_dirs[i] * arm]) + return segments + + +## Label position (offset from the reticle center, to the right of it) + the +## real-extent text — "~65 x 65 km" for the default n=32 window. +static func reticle_label(center: Vector2) -> Dictionary: + var half: float = DESCEND_RETICLE_SIZE * 0.5 + var extent_km: float = float(DISTRICT_WINDOW_DEFAULT_N) * DISTRICT_M / 1000.0 + return { + "position": center + Vector2(half + 6.0, 4.0), + "text": "~%.0f × %.0f km" % [extent_km, extent_km], + } + + +## Inverse of the server's derive_district() pixel mapping +## (server/src/atlas/district_profile.rs) — a `true_district_of_pixel`-style +## function, per the amendment's §5 carry-over wording. The server's forward +## mapping (body has a radius) is: +## px = ((dx * DISTRICT_M) / circumference_m mod 1.0) * tex_w +## py = (0.5 + clamp(dy * DISTRICT_M / meridian_m, -0.5, 0.5)) * tex_h +## which is a linear scaling of the same world-metre fraction the equatorial/ +## meridian district COUNT already IS (district_cols = round(circumference_m +## / DISTRICT_M), the same value build_district_grid()'s `cols` converges to +## for a body tiled edge-to-edge) — so inverting is "pixel fraction * district +## count", not a re-derivation of the server's geodesy. Self-contained: does +## NOT depend on district_grid (the whole-body layer) having arrived yet, so +## descent works immediately on entry even before that async layer resolves. +## The "no radius" branch (tiny test bodies, body_radius_km absent/<=0) +## mirrors the server's own fallback: the district grid IS the heightmap +## grid 1:1. +static func district_pos_at( + canvas_pt: Vector2, tex_w: float, tex_h: float, body_radius_km: float +) -> Vector2i: + if tex_w <= 0.0 or tex_h <= 0.0: + return Vector2i.ZERO + if body_radius_km <= 0.0: + return Vector2i(roundi(canvas_pt.x), roundi(canvas_pt.y)) + var circumference_m: float = TAU * body_radius_km * 1000.0 + var meridian_m: float = PI * body_radius_km * 1000.0 + var district_cols: float = roundf(circumference_m / DISTRICT_M) + var district_rows_half: float = roundf((meridian_m / DISTRICT_M) * 0.5) + var col: int = roundi((canvas_pt.x / tex_w) * district_cols) + var row: int = roundi(((canvas_pt.y / tex_h) - 0.5) * district_rows_half * 2.0) + return Vector2i(col, row) diff --git a/client/ui/implant/apps/atlas/atlas_overlay_colors.gd b/client/ui/implant/apps/atlas/atlas_overlay_colors.gd index fe0e61cb3..eff411d7c 100644 --- a/client/ui/implant/apps/atlas/atlas_overlay_colors.gd +++ b/client/ui/implant/apps/atlas/atlas_overlay_colors.gd @@ -86,6 +86,82 @@ const QUARTER_GLYPH_DENSITY_SCALE: float = 6.0 const COLOR_QUARTER_LOW_DENSITY: Color = Color(0.55, 0.48, 0.30, 0.6) # dim gold const COLOR_QUARTER_HIGH_DENSITY: Color = Color(0.94, 0.82, 0.38, 1.0) # COLOR_SETTLEMENT gold +## T-1138 (D-226 T-1124 amendment §5) — the regional-window base layer's +## MORPHOLOGY_RGB hues, port of aliveness_probe.rs's 17-entry table (same +## file/discriminant order as MORPHOLOGY_COLORS above, but FULL ALPHA — those +## colors carry a 0.55 alpha for the "semi-transparent overlay ON the +## heightmap" planetary-view use case; the window's morphology layer IS the +## base terrain read (no heightmap texture underneath it to show through), so +## the district-window base needs opaque versions of the identical hues, not +## a second independently-chosen palette. +const MORPHOLOGY_RGB_OPAQUE: Array = [ + Color(0.102, 0.200, 0.451, 1.0), # 0 OpenOcean + Color(0.200, 0.400, 0.651, 1.0), # 1 Lake + Color(0.451, 0.549, 0.502, 1.0), # 2 TidalFlat + Color(0.851, 0.780, 0.451, 1.0), # 3 DuneStrand + Color(0.502, 0.502, 0.549, 1.0), # 4 CliffCoast + Color(0.302, 0.400, 0.502, 1.0), # 5 Fjord + Color(0.400, 0.651, 0.600, 1.0), # 6 Delta + Color(0.302, 0.549, 0.549, 1.0), # 7 Estuarine + Color(0.302, 0.600, 0.302, 1.0), # 8 AlluvialPlain + Color(0.451, 0.702, 0.400, 1.0), # 9 RiverBank + Color(0.349, 0.600, 0.502, 1.0), # 10 MeanderReach + Color(0.549, 0.600, 0.451, 1.0), # 11 BraidedPlain + Color(0.502, 0.549, 0.302, 1.0), # 12 ValleyFloor + Color(0.549, 0.451, 0.302, 1.0), # 13 MountainPass + Color(0.800, 0.820, 0.851, 1.0), # 14 Alpine + Color(0.451, 0.149, 0.122, 1.0), # 15 Volcanic + Color(0.251, 0.451, 0.400, 1.0), # 16 Wetland +] + +## Elevation lightness modulation (D-226 T-1124 amendment §5): one +## `0.7 + 0.3*(elev_q/100)` multiply per cell — relief read without a second +## draw call, hue=type / lightness=elevation. +const DISTRICT_WINDOW_ELEV_LIGHTNESS_BASE: float = 0.7 +const DISTRICT_WINDOW_ELEV_LIGHTNESS_RANGE: float = 0.3 + +## T-1138 — vegetation green-family ramp (D-226 T-1124 amendment §5). +## VegetationClass discriminants (server/src/atlas/district_profile.rs, +## T-1126): 0 Absent, 1 Barren, 2 Scrub, 3 Forest, 4 RiparianScrub, +## 5 RiparianThicket, 6 Marine. Marine is handled by the caller (transparent — +## see vegetation_color() below), not a table entry, since "transparent" is +## not a color decision but a "don't draw" decision. +const COLOR_VEGETATION_ABSENT: Color = Color(0.35, 0.32, 0.28, 0.55) # airless/no branch — dim neutral +const COLOR_VEGETATION_BARREN: Color = Color(0.55, 0.50, 0.38, 0.55) # sparse — dry olive-tan +const COLOR_VEGETATION_SCRUB: Color = Color(0.45, 0.58, 0.32, 0.65) # transitional — olive-green +const COLOR_VEGETATION_FOREST: Color = Color(0.20, 0.50, 0.24, 0.75) # closed-canopy — deep green +# Riparian bands read as a saturated variant of their base class (D-226 T-1124 +# amendment §3's exhaustive-disposition mandate — every VegetationClass +# variant needs SOME reading, not just the three density-ladder rungs). +const COLOR_VEGETATION_RIPARIAN_SCRUB: Color = Color(0.35, 0.65, 0.45, 0.80) # scrub + water = teal-green +const COLOR_VEGETATION_RIPARIAN_THICKET: Color = Color(0.15, 0.55, 0.38, 0.85) # forest + water = teal-dark-green +const VEGETATION_MARINE: int = 6 # T-1126 — Marine renders transparent, see vegetation_color() + +## T-1138 — glaciation ice-tint MODIFIER endpoint + per-grade alpha (D-226 +## T-1124 amendment §5, porting aliveness_probe.rs's apply_ice_tint() +## unchanged in mechanism). GlaciationGrade discriminants (T-1127): +## 0 None, 1 Light, 2 Moderate, 3 Heavy, 4 IceCap. +## +## The amendment's own prose summarizes the gate as "glaciation_grade >= +## Light"; the REFERENCE implementation it names or explicitly asks to be +## ported (apply_ice_tint, aliveness_probe.rs:602) returns the base color +## UNCHANGED for None *and* Light, with its own code comment explaining why: +## grade 1 is glacial-erosion signatures (U-valleys, moraines — landform +## history visible on coasts as warm as +5C mean), not ice cover; visible ice +## starts at grade >= Moderate, which is what D-239 §5 itself gates glacial +## forms on. This table follows the port (the load-bearing instruction), +## not the summary. GRADE_LIGHT is kept as an explicit key mapped to 0.0 — +## not "absent from the dict" — so a caller iterating grades sees the +## "no tint, and here is why" decision instead of an implicit fallback. +const GLACIATION_ICE_WHITE: Color = Color(0.894, 0.941, 0.980, 1.0) # 228,240,250 / 255 +const GLACIATION_TINT_ALPHA: Dictionary = { + 0: 0.0, # None + 1: 0.0, # Light — erosion signatures only, not visible ice (see doc above) + 2: 0.30, # Moderate + 3: 0.50, # Heavy + 4: 0.70, # IceCap +} + static func morphology_color(zone: int) -> Color: if zone >= 0 and zone < MORPHOLOGY_COLORS.size(): @@ -162,3 +238,71 @@ static func quarter_notch_kind(district_type: String) -> String: return district_type.to_lower() _: return "plain" + + +## T-1138 — the regional-window base layer's hue read: MORPHOLOGY_RGB_OPAQUE +## looked up by MorphologyZone discriminant, out-of-palette falls back to +## magenta (matches aliveness_probe.rs's own out-of-palette sentinel — a +## palette/enum drift bug should be LOUD, not silently grey). +static func district_window_morphology_color(zone: int) -> Color: + if zone >= 0 and zone < MORPHOLOGY_RGB_OPAQUE.size(): + return MORPHOLOGY_RGB_OPAQUE[zone] + return Color(1.0, 0.0, 1.0, 1.0) + + +## Lightness modulation by elev_q (D-226 T-1124 amendment §5): multiply RGB by +## `0.7 + 0.3*(elev_q/100)`, alpha untouched. elev_q is clamped to [0, 100] +## before the multiply so an out-of-range value (shouldn't happen — server +## already clamps per the district_grid precedent) can't push lightness +## outside [0.7, 1.0]. +static func district_window_elevation_lightness(base: Color, elev_q: int) -> Color: + var clamped: int = clampi(elev_q, 0, 100) + var lightness: float = ( + DISTRICT_WINDOW_ELEV_LIGHTNESS_BASE + + DISTRICT_WINDOW_ELEV_LIGHTNESS_RANGE * (float(clamped) / 100.0) + ) + return Color(base.r * lightness, base.g * lightness, base.b * lightness, base.a) + + +## Vegetation green-family ramp (D-226 T-1124 amendment §5). Marine (6) +## returns Color.TRANSPARENT — "lets the morphology water-blue show through" +## per the amendment; the caller must skip the draw_rect entirely on a +## transparent result rather than drawing a zero-alpha rect (cheaper, and +## avoids relying on alpha blending to do the "don't draw" work). Every other +## discriminant (including out-of-range, e.g. a future VegetationClass +## variant this table hasn't caught up to yet) falls back to the Absent +## reading rather than a magenta sentinel — vegetation is deliberately a +## SOFTER failure mode than morphology (an unrecognized vegetation class is +## "no distinguishable vegetation signal", not a palette/enum drift bug of +## the same severity as an unrecognized terrain zone). +static func vegetation_color(vegetation_class: int) -> Color: + match vegetation_class: + VEGETATION_MARINE: + return Color.TRANSPARENT + 1: + return COLOR_VEGETATION_BARREN + 2: + return COLOR_VEGETATION_SCRUB + 3: + return COLOR_VEGETATION_FOREST + 4: + return COLOR_VEGETATION_RIPARIAN_SCRUB + 5: + return COLOR_VEGETATION_RIPARIAN_THICKET + _: + return COLOR_VEGETATION_ABSENT + + +## Glaciation ice-tint MODIFIER (D-226 T-1124 amendment §5, porting +## aliveness_probe.rs's apply_ice_tint()) — blends `base` toward glacial +## ice-white by the per-grade alpha in GLACIATION_TINT_ALPHA. Grades None/Light +## return `base` unchanged (alpha 0.0 lerp is a no-op, but the explicit +## lookup-then-lerp keeps this one code path for every grade rather than an +## early-return special case, matching the port's single lerp_rgb call site). +## Out-of-range grade values are treated as None (no tint) — the same "softer +## failure than morphology" reasoning as vegetation_color() above. +static func glaciation_tint(base: Color, glaciation_grade: int) -> Color: + var alpha: float = float(GLACIATION_TINT_ALPHA.get(glaciation_grade, 0.0)) + if alpha <= 0.0: + return base + return base.lerp(GLACIATION_ICE_WHITE, alpha) diff --git a/client/ui/implant/apps/atlas/atlas_viewer.gd b/client/ui/implant/apps/atlas/atlas_viewer.gd index 44cdfc668..c08e299c3 100644 --- a/client/ui/implant/apps/atlas/atlas_viewer.gd +++ b/client/ui/implant/apps/atlas/atlas_viewer.gd @@ -1,35 +1,30 @@ class_name AtlasViewer extends Control -## Atlas regional viewer — heightmap PNG with pan/zoom + marker overlay (#835, D-191). +## Atlas regional viewer — heightmap PNG with marker overlay (#835, D-191). ## ## Lives as a child of RegionalScreen, shown when the atlas nav stack is at -## "regional". Receives body/system context via show_body(). Emits back_pressed -## and economics_link_requested so RegionalScreen can route them. +## "regional". Receives body/system context via show_body(). Emits back_pressed, +## economics_link_requested, and district_descend_requested so RegionalScreen +## can route them. ## ## Design notes: -## - Heightmap texture is drawn on a Node2D _canvas child. Pan = _canvas.position, -## zoom = _canvas.scale. MarkerOverlay is a child of _canvas so markers auto- -## follow the same transform. +## - Heightmap texture is drawn on a Node2D _canvas child. MarkerOverlay is a +## child of _canvas so markers auto-follow the same transform. ## - markers.json schema (D-191 §8): cities, roads, railroads, pois, plus rivers, ## oceans, mountain_ranges with `center: [row, col]` and optional names. ## - Empty markers case (server #832/#833 not yet shipped): bare heightmap renders ## fine, no sidebar opens, overlays draw nothing. ## - Overlays (#836) plug into _overlay_visibility dict and _draw_overlays(). -## -## Navigation: -## Mouse drag pan the map -## Mouse wheel zoom in / out (centered on cursor) -## Click city open city data panel -## R reset view -## Esc back to body entry +## - T-1138: view is FIXED (set_view() is capture-API-only); descent screen has the reticle math. +## Navigation: Hover reticle · Click descend · Click city data (wins) · R reset(no-op) · Esc back signal back_pressed signal economics_link_requested(system_id: String) +signal district_descend_requested(district_center: Vector2i) # T-1138 const MIN_ZOOM: float = 0.5 const MAX_ZOOM: float = 8.0 -const ZOOM_STEP: float = 1.15 const PANEL_WIDTH: float = 320.0 const PANEL_MARGIN: float = 16.0 @@ -37,6 +32,8 @@ const PANEL_MARGIN: float = 16.0 # wrapping overlay bar must not overlap. const OVERLAY_BAR_HEADER_RESERVE: float = 360.0 +const AtlasDescendGeometry := preload("res://ui/implant/apps/atlas/atlas_descend_geometry.gd") # T-1138 + # ── Colors ──────────────────────────────────────────────────────────────────── const COLOR_BG: Color = Color("#0d1117") const COLOR_HEIGHTMAP_TINT: Color = Color(0.85, 0.88, 0.95, 1.0) @@ -215,16 +212,15 @@ var _tex_h: float = 512.0 # if the bridge wasn't connected yet when _load_markers first asked. var _city_names_pending_body: String = "" -# ── Pan/zoom state ──────────────────────────────────────────────────────────── +# ── View state (T-1138: FIXED — set only by _fit_to_view()/set_view()) ───── var _view_offset: Vector2 = Vector2.ZERO var _view_zoom: float = 1.0 -var _dragging: bool = false -var _drag_start_mouse: Vector2 -var _drag_start_offset: Vector2 # ── Selection ───────────────────────────────────────────────────────────────── var _selected_city: Dictionary = {} var _hovered_city: Dictionary = {} +var _hover_screen_pos: Vector2 = Vector2.ZERO # T-1138 descent reticle cursor tracking +var _hover_active: bool = false # ── Overlay visibility (#836 plugs in here) ─────────────────────────────────── ## Runtime state derived from OVERLAY_DEFS in _ready() — always-on overlays @@ -366,14 +362,9 @@ func get_view_offset() -> Vector2: return _view_offset -## Programmatic view control (T-1120 — added for the Atlas screenshot capture -## harness, which needs deterministic zoom/pan without simulating mouse wheel -## events). Mirrors _zoom_at()/_fit_to_view()'s clamp-then-_apply_transform -## shape: zoom is clamped to [MIN_ZOOM, MAX_ZOOM] exactly like every other -## mutator (_zoom_at, _fit_to_view), so this can't push the view out of the -## range the rest of the viewer assumes. Offset is caller-supplied verbatim — -## same as _fit_to_view()'s computed centering offset, there's no meaningful -## clamp for a pan translation. +## Programmatic view control (T-1120 capture harness) — survives T-1138's +## removal of user drag-pan/wheel-zoom; the harness still overrides the FIXED +## view deterministically. Clamps zoom to [MIN_ZOOM, MAX_ZOOM] like _fit_to_view(). func set_view(zoom: float, offset: Vector2) -> void: _view_zoom = clampf(zoom, MIN_ZOOM, MAX_ZOOM) _view_offset = offset @@ -630,17 +621,6 @@ func _apply_transform() -> void: _overlay_node.queue_redraw() -func _zoom_at(mouse_pos: Vector2, factor: float) -> void: - var new_zoom: float = clampf(_view_zoom * factor, MIN_ZOOM, MAX_ZOOM) - if is_equal_approx(new_zoom, _view_zoom): - return - # Keep the texture point under cursor fixed while zooming - var local_before: Vector2 = (mouse_pos - _view_offset) / _view_zoom - _view_zoom = new_zoom - _view_offset = mouse_pos - local_before * _view_zoom - _apply_transform() - - ## Convert grid coordinates (from markers.json) to canvas-space (texture pixels). func grid_to_canvas(grid_point: Vector2) -> Vector2: if _grid_w <= 0.0 or _grid_h <= 0.0: @@ -665,6 +645,26 @@ func screen_to_canvas(screen_point: Vector2) -> Vector2: func _draw() -> void: draw_rect(Rect2(Vector2.ZERO, get_rect().size), COLOR_BG) + if _hover_active and _heightmap_texture != null: + _draw_descend_reticle() + + +## T-1138 NOT-TO-SCALE reticle (§5's open design point). Draw calls only — +## geometry/rationale in atlas_descend_geometry.gd (draw_line must run on `self`). +func _draw_descend_reticle() -> void: + var center: Vector2 = _hover_screen_pos + for seg: Array in AtlasDescendGeometry.reticle_segments(center): + draw_line(seg[0], seg[1], AtlasDescendGeometry.COLOR_DESCEND_RETICLE, 1.5) + var label: Dictionary = AtlasDescendGeometry.reticle_label(center) + draw_string( + ThemeDB.fallback_font, + label["position"], + label["text"], + HORIZONTAL_ALIGNMENT_LEFT, + -1, + 10, + AtlasDescendGeometry.COLOR_DESCEND_RETICLE + ) func _build_screen_header() -> void: @@ -686,7 +686,7 @@ func _refresh_screen_header() -> void: var body_name: String = _dict_str(_body, "proper_name", _dict_str(_body, "body_id", "—")) var sys_name: String = _dict_str(_system, "proper_name", _dict_str(_system, "system_id", "—")) var title: String = "ATLAS — %s · %s" % [body_name.to_upper(), sys_name.to_upper()] - var hint: String = "drag pan · wheel zoom · r reset · click city data · esc back" + var hint: String = "click descend · click city data · esc back" _screen_header.set_content(title, hint) @@ -734,27 +734,13 @@ func _gui_input(event: InputEvent) -> void: if event is InputEventMouseButton: var mb := event as InputEventMouseButton - if mb.button_index == MOUSE_BUTTON_WHEEL_UP and mb.pressed: - _zoom_at(mb.position, ZOOM_STEP) - elif mb.button_index == MOUSE_BUTTON_WHEEL_DOWN and mb.pressed: - _zoom_at(mb.position, 1.0 / ZOOM_STEP) - elif mb.button_index == MOUSE_BUTTON_LEFT: - if mb.pressed: - if not _try_click_city(mb.position): - _dragging = true - _drag_start_mouse = mb.position - _drag_start_offset = _view_offset - else: - _dragging = false + if mb.button_index == MOUSE_BUTTON_LEFT and mb.pressed: + if not _try_click_city(mb.position): + _descend_at(mb.position) elif event is InputEventMouseMotion: if _is_over_ui((event as InputEventMouseMotion).global_position): return - var mm := event as InputEventMouseMotion - if _dragging: - _view_offset = _drag_start_offset + (mm.position - _drag_start_mouse) - _apply_transform() - else: - _update_hover(mm.position) + _update_hover((event as InputEventMouseMotion).position) func _handle_key(event: InputEventKey) -> void: @@ -770,7 +756,7 @@ func _handle_key(event: InputEventKey) -> void: _fit_to_view() -func _try_click_city(screen_pos: Vector2) -> bool: +func _try_click_city(screen_pos: Vector2) -> bool: # T-1138: a city's hit-radius wins over descent var city: Dictionary = _find_city_at(screen_pos) if city.is_empty(): return false @@ -781,11 +767,17 @@ func _try_click_city(screen_pos: Vector2) -> bool: return true +func _descend_at(screen_pos: Vector2) -> void: # T-1138: every point maps to a DistrictPos + district_descend_requested.emit(_district_pos_at(screen_pos)) + + func _update_hover(screen_pos: Vector2) -> void: var new_hover: Dictionary = _find_city_at(screen_pos) if new_hover != _hovered_city: _hovered_city = new_hover - _overlay_node.queue_redraw() + _hover_screen_pos = screen_pos + _hover_active = true + _overlay_node.queue_redraw() func _find_city_at(screen_pos: Vector2) -> Dictionary: @@ -817,6 +809,12 @@ func city_canvas_pos(city: Dictionary) -> Vector2: return Vector2.ZERO +func _district_pos_at(screen_pos: Vector2) -> Vector2i: # T-1138, geometry: atlas_descend_geometry.gd + var canvas_pt: Vector2 = screen_to_canvas(screen_pos) + var radius_km: float = float(_body.get("body_radius_km", 0.0)) + return AtlasDescendGeometry.district_pos_at(canvas_pt, _tex_w, _tex_h, radius_km) + + # ============================================================================= # City data panel (sidebar) # ============================================================================= @@ -996,3 +994,6 @@ func _notification(what: int) -> void: _position_overlay_bar() if _legend_panel: _legend_panel.reposition() + elif what == NOTIFICATION_MOUSE_EXIT and _hover_active: + _hover_active = false # T-1138: hide the reticle when the cursor leaves + _overlay_node.queue_redraw() diff --git a/client/ui/implant/apps/atlas/atlas_window_cache.gd b/client/ui/implant/apps/atlas/atlas_window_cache.gd new file mode 100644 index 000000000..0d36ec498 --- /dev/null +++ b/client/ui/implant/apps/atlas/atlas_window_cache.gd @@ -0,0 +1,79 @@ +extends RefCounted + +## Client-side LRU cache for DistrictWindowLayer responses (T-1138, D-226 +## T-1124 amendment §4 "Client cache policy"). +## +## Keyed on (body_id, center, n) — D-227's determinism guarantee (same seed + +## body + position -> same derived output, always) means a previously-fetched +## window is valid FOREVER for that body+seed. This is an LRU-evict-only +## cache: no freshness check, no TTL, no invalidation path at all. The only +## reason an entry ever leaves is capacity pressure. +## +## Godot's Dictionary preserves insertion order, so "move to the end on +## touch, evict from the front on overflow" is the whole LRU implementation — +## no separate linked-list/counter bookkeeping needed. +## +## Consumed via explicit load() by path (no class_name), matching +## atlas_overlay_bar.gd/atlas_legend_panel.gd (review #8 precedent +## elsewhere in this app): the owner constructs one instance and holds it, +## same shape as those two. + +const DEFAULT_MAX_ENTRIES: int = 24 + +var _max_entries: int = DEFAULT_MAX_ENTRIES +var _entries: Dictionary = {} # key String -> DistrictWindowLayer Dictionary + + +func _init(max_entries: int = DEFAULT_MAX_ENTRIES) -> void: + _max_entries = maxi(1, max_entries) + + +## Build the cache key from the three fields D-227 makes sufficient: +## body_id (which world+body), center (a [row, col] pair or Vector2i), and n +## (window side length). String-keyed rather than a nested Dictionary/Array +## key — Godot Dictionary keys compare by value for primitives but a +## consistent stringification sidesteps any Vector2i-vs-Array identity +## mismatch between what a caller happens to hand in. +static func make_key(body_id: String, center: Vector2i, n: int) -> String: + return "%s:%d,%d:%d" % [body_id, center.x, center.y, n] + + +## True if a window is already cached for this exact (body, center, n). +func has(body_id: String, center: Vector2i, n: int) -> bool: + return _entries.has(make_key(body_id, center, n)) + + +## Fetch a cached window, touching it (move-to-most-recently-used). Returns +## null on a miss — callers must not confuse this with a real "None" server +## response, which is a different concept (§1: an as-yet-underived window is +## carried as `district_window: None` inside a `Ready` AtlasLayerResponse, +## not a cache state). +func get_window(body_id: String, center: Vector2i, n: int) -> Variant: + var key := make_key(body_id, center, n) + if not _entries.has(key): + return null + var value: Variant = _entries[key] + # Touch: erase + re-insert moves the key to the end (most-recently-used). + _entries.erase(key) + _entries[key] = value + return value + + +## Store a window, evicting the least-recently-used entry(ies) if over +## capacity. Overwriting an existing key also counts as a touch. +func put(body_id: String, center: Vector2i, n: int, window: Dictionary) -> void: + var key := make_key(body_id, center, n) + if _entries.has(key): + _entries.erase(key) + _entries[key] = window + while _entries.size() > _max_entries: + var oldest_key: String = _entries.keys()[0] + _entries.erase(oldest_key) + + +func size() -> int: + return _entries.size() + + +func clear() -> void: + _entries.clear() diff --git a/client/ui/implant/apps/atlas/atlas_window_legend.gd b/client/ui/implant/apps/atlas/atlas_window_legend.gd new file mode 100644 index 000000000..d98c426ec --- /dev/null +++ b/client/ui/implant/apps/atlas/atlas_window_legend.gd @@ -0,0 +1,134 @@ +extends ImplantPanel + +## Legend for AtlasWindowViewer's regional-window overlays (T-1138, D-226 +## T-1124 amendment §5). Mirrors atlas_legend_panel.gd's data-driven shape — +## one spec entry per overlay id, refresh() shows only the active ones — but +## scoped to the district-window screen's OWN toggle set (gen_dw_temp/ +## gen_dw_moisture/gen_dw_veg) plus the two always-on layers that need a key +## even though they have no toggle id of their own: the morphology base +## (folded to ~5 family rows, per §5's "not everything earns permanent screen +## space" instinct) and the glaciation ice-tint modifier. +## +## No `class_name` on purpose, matching atlas_legend_panel.gd (review #8 +## precedent): the owner (AtlasWindowViewer) passes itself to _init(). + +const PANEL_MARGIN: float = 16.0 +const LEGEND_PANEL_WIDTH: float = 260.0 + +const AtlasOverlayColors := preload("res://ui/implant/apps/atlas/atlas_overlay_colors.gd") + +## The morphology base layer folds its 17 zones into ~5 family rows (§5: +## "mirroring T-1112's 'not everything earns permanent screen space' +## discipline") — the full 17-zone mapping stays in the city-click sidebar's +## reach, not duplicated here. Representative hue per family, picked from +## MORPHOLOGY_RGB_OPAQUE's own entries rather than a fresh set of colors. +const MORPHOLOGY_FAMILY_ROWS: Array = [ + {"label": "water", "zones": [0, 1]}, # OpenOcean, Lake + {"label": "coastal / transition", "zones": [2, 3, 4, 5, 6, 7]}, # TidalFlat..Estuarine + {"label": "plains / river", "zones": [8, 9, 10, 11, 12]}, # AlluvialPlain..ValleyFloor + {"label": "upland", "zones": [13, 14]}, # MountainPass, Alpine + {"label": "volcanic / wetland", "zones": [15, 16]}, # Volcanic, Wetland +] + +const GLACIATION_ROWS: Array = [ + {"grade": 0, "label": "none"}, + {"grade": 1, "label": "light (erosion signatures — no tint)"}, + {"grade": 2, "label": "moderate"}, + {"grade": 3, "label": "heavy"}, + {"grade": 4, "label": "ice cap"}, +] + +var _viewer = null # AtlasWindowViewer (untyped to avoid cyclic ref) + + +func _init(viewer_ref = null) -> void: + _viewer = viewer_ref + custom_minimum_size.x = LEGEND_PANEL_WIDTH + mouse_filter = Control.MOUSE_FILTER_IGNORE + visible = false + + +func reposition() -> void: + position = Vector2(PANEL_MARGIN, 60.0) + + +## Always shows the base-layer key (morphology + elevation reading, always +## on) plus glaciation (always-on modifier), then whichever toggle overlay is +## currently active, if any. +func refresh() -> void: + if _viewer == null: + return + clear() + visible = true + + add_component(ImplantHeader.new("REGIONAL LEGEND", "district window · 2.048 km/cell")) + add_component(ImplantSeparator.new()) + + _add_morphology_section() + add_component(ImplantSeparator.new()) + _add_glaciation_section() + + var active_id: String = _active_toggle_id() + if not active_id.is_empty(): + add_component(ImplantSeparator.new()) + _add_toggle_section(active_id) + + reposition() + + +func _add_morphology_section() -> void: + add_component( + ImplantTextBlock.new("TERRAIN — hue = type, lightness = elevation (always on)") + ) + for row: Dictionary in MORPHOLOGY_FAMILY_ROWS: + var zones: Array = row.get("zones", []) + var swatch: Color = ( + AtlasOverlayColors.district_window_morphology_color(zones[0]) if not zones.is_empty() else Color.TRANSPARENT + ) + var text: String = "▦ %s" % str(row.get("label", "")) + add_component(ImplantDataRow.new(text, swatch)) + + +func _add_glaciation_section() -> void: + add_component(ImplantTextBlock.new("ICE TINT — always-on modifier over any layer")) + for row: Dictionary in GLACIATION_ROWS: + var swatch: Color = AtlasOverlayColors.glaciation_tint( + Color(0.3, 0.3, 0.3, 1.0), int(row.get("grade", 0)) + ) + var text: String = "▦ %s" % str(row.get("label", "")) + add_component(ImplantDataRow.new(text, swatch)) + + +func _add_toggle_section(overlay_id: String) -> void: + match overlay_id: + "gen_dw_temp": + add_component(ImplantTextBlock.new("TEMPERATURE — cold->hot ramp (region colorizer, reused)")) + add_component( + ImplantDataRow.new("▦ cold", AtlasOverlayColors.COLOR_REGION_TEMP_COLD) + ) + add_component(ImplantDataRow.new("▦ hot", AtlasOverlayColors.COLOR_REGION_TEMP_HOT)) + add_component(ImplantDataRow.new("▦ airless — no reading (skipped)", Color.TRANSPARENT)) + "gen_dw_moisture": + add_component(ImplantTextBlock.new("MOISTURE — dry->wet ramp")) + add_component(ImplantDataRow.new("▦ dry", Color(0.78, 0.62, 0.35, 1.0))) + add_component(ImplantDataRow.new("▦ wet", Color(0.25, 0.72, 0.65, 1.0))) + "gen_dw_veg": + add_component(ImplantTextBlock.new("VEGETATION — green-family ramp")) + add_component(ImplantDataRow.new("▦ barren", AtlasOverlayColors.COLOR_VEGETATION_BARREN)) + add_component(ImplantDataRow.new("▦ scrub", AtlasOverlayColors.COLOR_VEGETATION_SCRUB)) + add_component(ImplantDataRow.new("▦ forest", AtlasOverlayColors.COLOR_VEGETATION_FOREST)) + add_component( + ImplantDataRow.new( + "▦ riparian band", AtlasOverlayColors.COLOR_VEGETATION_RIPARIAN_THICKET + ) + ) + add_component( + ImplantDataRow.new("▦ marine — transparent (shows water below)", Color.TRANSPARENT) + ) + + +func _active_toggle_id() -> String: + for overlay_id in ["gen_dw_temp", "gen_dw_moisture", "gen_dw_veg"]: + if _viewer.is_overlay_visible(overlay_id): + return overlay_id + return "" diff --git a/client/ui/implant/apps/atlas/atlas_window_overlay.gd b/client/ui/implant/apps/atlas/atlas_window_overlay.gd new file mode 100644 index 000000000..70aff7689 --- /dev/null +++ b/client/ui/implant/apps/atlas/atlas_window_overlay.gd @@ -0,0 +1,158 @@ +class_name AtlasWindowOverlay +extends Node2D + +## Draws the DistrictWindowLayer composite for AtlasWindowViewer (T-1138, +## D-226 T-1124 amendment §5). Child of AtlasWindowViewer._canvas so it +## inherits the pan transform (zoom is client-side texture zoom on the +## already-held composite, §5 — never a re-fetch). +## +## Draw order (bottom to top), matching the amendment's compositing model: +## 1. Base layer — morphology hue, lightness-modulated by elev_q. Always on, +## no toggle id (§5: "it IS this screen's terrain layer"). +## 2. Toggle overlays (mutually independent, at most one drawn per cell — +## each REPLACES the base read for that cell rather than blending, so +## switching between temp/moisture/veg never fights the base hue): +## gen_dw_temp / gen_dw_moisture / gen_dw_veg. +## 3. Glaciation ice-tint MODIFIER — composited over whichever layer is +## showing (base or a toggle), always-on, not a toggle id of its own. +## +## Reads window data via viewer.get_district_window() (a Dictionary or null) — this +## overlay draws nothing until the viewer has a window (border-fade during +## the wait is the VIEWER's job, drawn separately underneath this node, not +## here — this node is purely "draw the composite when there is one"). + +const AtlasOverlayColors := preload("res://ui/implant/apps/atlas/atlas_overlay_colors.gd") +const REGION_TEMP_NONE_DC: int = AtlasOverlayColors.REGION_TEMP_NONE_DC + +## Moisture ramp reuses SUB_BIOME_COLORS' dry-sand->wet-teal ENDPOINTS (§5) — +## not the categorical lookup itself (that's keyed by sub-biome NAME, not a +## 0-100 quantity). Endpoints pulled from the existing dry/wet entries in that +## table: Desert (arid/dry) and TropicalWet (wet/coastal). +const COLOR_MOISTURE_DRY: Color = Color(0.78, 0.62, 0.35, 1.0) # sand — matches SUB_BIOME_COLORS.Desert +const COLOR_MOISTURE_WET: Color = Color(0.25, 0.72, 0.65, 1.0) # teal — matches SUB_BIOME_COLORS.TropicalWet + +var viewer = null # AtlasWindowViewer (untyped to avoid cyclic ref) + + +func _draw() -> void: + if viewer == null: + return + var window: Variant = viewer.get_district_window() + if not window is Dictionary: + return + var w: Dictionary = window + var n: int = int(w.get("n", 0)) + if n <= 0: + return + + var morphology: Variant = w.get("morphology") + var elev_q: Variant = w.get("elev_q") + if not (morphology is PackedByteArray or morphology is Array): + return + + var cell_px: float = viewer.get_cell_pixel_size() + var active_toggle: String = _active_toggle_overlay() + var glaciation: Variant = w.get("glaciation") + + for row in range(n): + for col in range(n): + var i: int = row * n + col + if i >= morphology.size(): + continue + var cell_color: Color = _cell_color(w, i, int(morphology[i]), elev_q, active_toggle) + if cell_color.a <= 0.0: + continue # Marine-transparent or otherwise "don't draw" (cheaper than a 0-alpha rect) + cell_color = _apply_glaciation(cell_color, glaciation, i) + # +0.5 overdraw avoids hairline seams between adjacent cells — + # same idiom as _draw_gen_district/_draw_gen_region_grid. + draw_rect(Rect2(col * cell_px, row * cell_px, cell_px + 0.5, cell_px + 0.5), cell_color) + + +## Which of the three mutually-exclusive toggle overlays (if any) is active. +## At most one draws — §5 does not describe blending two toggles together, +## and doing so would fight the "one colorizer, one read" legibility goal the +## whole layer design optimizes for. First-match-wins on ties (should never +## happen — the overlay bar toggles independently, but this keeps the draw +## deterministic instead of implicitly depending on dictionary iteration +## order if more than one somehow ends up true). +func _active_toggle_overlay() -> String: + if viewer.is_overlay_visible("gen_dw_temp"): + return "gen_dw_temp" + if viewer.is_overlay_visible("gen_dw_moisture"): + return "gen_dw_moisture" + if viewer.is_overlay_visible("gen_dw_veg"): + return "gen_dw_veg" + return "" + + +func _cell_color( + w: Dictionary, i: int, morphology_zone: int, elev_q: Variant, active_toggle: String +) -> Color: + match active_toggle: + "gen_dw_temp": + return _temp_cell_color(w.get("temp_dc"), i) + "gen_dw_moisture": + return _moisture_cell_color(w.get("moisture_q"), i) + "gen_dw_veg": + return _veg_cell_color(w.get("vegetation"), i) + _: + return _base_cell_color(morphology_zone, elev_q, i) + + +## Base layer: morphology hue, lightness-modulated by elev_q (§5's one +## `0.7 + 0.3*(elev_q/100)` multiply per cell). +func _base_cell_color(morphology_zone: int, elev_q: Variant, i: int) -> Color: + var base: Color = AtlasOverlayColors.district_window_morphology_color(morphology_zone) + var eq: int = _dense_int(elev_q, i, 50) + return AtlasOverlayColors.district_window_elevation_lightness(base, eq) + + +## gen_dw_temp: reuses T-1118's region_temp_color() EXACTLY — same i16 +## deci-°C domain, same REGION_TEMP_NONE_DC sentinel disposition (skip the +## cell entirely, matching _draw_gen_region_grid's airless treatment) — one +## colorizer across both zoom levels, per the amendment's consistency ruling. +func _temp_cell_color(temp_dc: Variant, i: int) -> Color: + if temp_dc == null: + return Color.TRANSPARENT + var t: int = _dense_int(temp_dc, i, REGION_TEMP_NONE_DC) + if t == REGION_TEMP_NONE_DC: + return Color.TRANSPARENT # airless — no reading, skip the cell (matches region-grid precedent) + return AtlasOverlayColors.region_temp_color(t) + + +## gen_dw_moisture: dry-sand -> wet-teal ramp over the existing SUB_BIOME_COLORS +## endpoints (§5). +func _moisture_cell_color(moisture_q: Variant, i: int) -> Color: + if moisture_q == null: + return Color.TRANSPARENT + var m: int = clampi(_dense_int(moisture_q, i, 50), 0, 100) + return COLOR_MOISTURE_DRY.lerp(COLOR_MOISTURE_WET, float(m) / 100.0) + + +## gen_dw_veg: green-family ramp, Marine transparent (§3/§5 — non-negotiable +## per the amendment; see atlas_overlay_colors.gd's vegetation_color() doc). +func _veg_cell_color(vegetation: Variant, i: int) -> Color: + if vegetation == null: + return Color.TRANSPARENT + return AtlasOverlayColors.vegetation_color(_dense_int(vegetation, i, 0)) + + +## Glaciation: an always-on MODIFIER (never a toggle id), composited over +## whichever layer is currently showing — the base or one of the three +## toggles (§5). +func _apply_glaciation(cell_color: Color, glaciation: Variant, i: int) -> Color: + if glaciation == null: + return cell_color + var grade: int = _dense_int(glaciation, i, 0) + return AtlasOverlayColors.glaciation_tint(cell_color, grade) + + +## Reads element `i` from a dense numeric array field regardless of whether +## the messagepack decode produced a PackedByteArray (u8 fields) or a plain +## Array (i16 temp_dc — rmp_serde without serde_bytes, matching the existing +## region_grid _dense_int precedent in test_atlas_overlays.gd, now needed at +## RUNTIME here too, not just in a test helper). +static func _dense_int(arr: Variant, i: int, fallback: int) -> int: + if (arr is Array or arr is PackedByteArray) and i < arr.size(): + return int(arr[i]) + return fallback diff --git a/client/ui/implant/apps/atlas/atlas_window_request.gd b/client/ui/implant/apps/atlas/atlas_window_request.gd new file mode 100644 index 000000000..c37ef8002 --- /dev/null +++ b/client/ui/implant/apps/atlas/atlas_window_request.gd @@ -0,0 +1,182 @@ +extends Node + +## District-window request orchestration for AtlasWindowViewer (T-1138, D-226 +## T-1124 amendment §1/§4). Owns the cache, the pan-triggered re-request +## policy, the post-drag-release debounce, and the retry loop for the +## queue-based background derive (PR #185 finding: a window response arrives +## on a LATER TICK, not synchronously — the exact same "None until derived, +## re-poll" contract atlas_generation_proxy.gd's Layer1 path already handles, +## reused here rather than re-invented). +## +## This script has no `class_name` on purpose, matching every other +## viewer-owned helper in this cluster (atlas_overlay_bar.gd/ +## atlas_legend_panel.gd/atlas_generation_proxy.gd, review #8 precedent): the +## owner (AtlasWindowViewer) passes itself to _init(), and a `class_name` + +## required-arg _init() combo is a Godot editor footgun. `extends Node` (not +## RefCounted) because it needs get_tree() for the debounce/retry timers — +## added as a child via +## load("res://ui/implant/apps/atlas/atlas_window_request.gd").new(self). +## +## §4 policy fixed here (the constants + the debounce, NOT the pan-edge +## detection — that's the viewer's job, since it owns the screen-to-district +## geometry): +## - DISTRICT_WINDOW_DEFAULT_N = 32 (client's interactive default, half the +## server's DISTRICT_WINDOW_MAX_N = 64 hard cap — §4 pins both numbers; +## the cap itself is a server-side clamp this client never needs to +## duplicate, only stay under so a request is never silently clamped in +## a way the client didn't expect). +## - 150ms post-drag-release debounce — long enough to collapse a +## flick-and-resettle into one request, short enough that a deliberate +## single pan-and-stop never feels delayed (§4/§5 wording, identical). +## - Cache-hit is instant (no request at all) — §4's "D-227 makes exact- +## repeat the common case for Esc-then-re-enter and pan-back" is what +## makes this the common path, not the minority one. + +signal window_ready(window: Dictionary) # emitted on a cache hit OR a fresh Ready response + +const AtlasWindowCache := preload("res://ui/implant/apps/atlas/atlas_window_cache.gd") + +const DISTRICT_WINDOW_DEFAULT_N: int = 32 +const DEBOUNCE_DELAY: float = 0.15 # 150ms, §4/§5 +const RETRY_DELAY: float = 0.5 # matches atlas_generation_proxy.gd's GEN_RETRY_DELAY +const MAX_RETRIES: int = 20 # ~10s ceiling, matches atlas_generation_proxy.gd's GEN_MAX_RETRIES + +var _owner = null # AtlasWindowViewer (untyped to avoid cyclic ref) +var _cache = null # AtlasWindowCache +var _body_id: String = "" +var _center: Vector2i = Vector2i.ZERO +var _n: int = DISTRICT_WINDOW_DEFAULT_N +var _pending: bool = false +var _retries: int = 0 +var _debounce_timer: Timer = null + + +func _init(owner_ref = null) -> void: + _owner = owner_ref + _cache = AtlasWindowCache.new() + + +func _ready() -> void: + _debounce_timer = Timer.new() + _debounce_timer.name = "DebounceTimer" + _debounce_timer.one_shot = true + _debounce_timer.wait_time = DEBOUNCE_DELAY + _debounce_timer.timeout.connect(_on_debounce_timeout) + add_child(_debounce_timer) + + +## Reset for a fresh entry into the regional window mode (new body/center) — +## clears in-flight retry bookkeeping but NOT the cache (D-227: a cached +## window is valid forever regardless of which body/center the viewer is +## currently showing; clearing on every entry would throw away exactly the +## Esc-then-re-enter hit §4 promises). +func reset() -> void: + _pending = false + _retries = 0 + if _debounce_timer: + _debounce_timer.stop() + + +## Entry point + pan re-request: request the window centered on `center` +## (a DistrictPos-equivalent Vector2i) for `body_id`. Cache hit -> immediate +## synchronous window_ready emit, no network traffic at all. Cache miss -> +## fire the request now (the caller — either the initial entry or a +## debounce-fired pan — has already decided this call SHOULD fire; the 150ms +## debounce itself lives in request_debounced() below, not here, so this +## function is also the one entry-mechanic click-through uses directly with +## no debounce at all, matching §5's "first window" contract). +func request_now(body_id: String, center: Vector2i, n: int = DISTRICT_WINDOW_DEFAULT_N) -> void: + _body_id = body_id + _center = center + _n = n + _debounce_timer.stop() # a direct request supersedes any pending debounced one + + var cached: Variant = _cache.get_window(body_id, center, n) + if cached != null: + _pending = false + _retries = 0 + window_ready.emit(cached) + return + + _pending = true + _retries = 0 + SimBridge.request_atlas_layers(body_id, "Topography", center, n) + + +## Pan-triggered re-request (§4/§5: "150ms after the last drag-release, not +## per-drag-frame"). The viewer calls this on every pan-edge-crossing +## candidate; only the LAST call within the debounce window actually fires +## (Timer.start() on an already-running one-shot timer restarts it — Godot's +## documented behavior — so a flick-and-resettle collapses to one request). +func request_debounced(body_id: String, center: Vector2i, n: int = DISTRICT_WINDOW_DEFAULT_N) -> void: + _body_id = body_id + _center = center + _n = n + _debounce_timer.start() + + +func _on_debounce_timeout() -> void: + request_now(_body_id, _center, _n) + + +## Handle an AtlasLayerResponse (routed by the owning viewer from its own +## SimBridge.atlas_layers_received subscription — this object has no signal +## connection of its own, matching atlas_generation_proxy.gd's on_response() +## shape). Ignores responses for a stale body/center/n (the player panned or +## navigated away while a request was in flight) — the echoed center/n IS the +## staleness guard (§2), compared here against what THIS object most recently +## asked for. +func on_response(response: Dictionary) -> void: + if str(response.get("body_id", "")) != _body_id: + return + if str(response.get("status", "")) != "Ready": + return # Pending/NotFound/Error on the WHOLE response — not a window signal either way + var window: Variant = response.get("district_window") + if window == null: + # §1: an as-yet-underived window rides as `district_window: None` inside + # a Ready response — this is the "still generating" signal, not an + # error. Re-poll until the background derive lands or the retry + # ceiling is hit (queue-based serving, PR #185 — the response lands + # on a LATER tick, never this same round-trip). + if not _pending: + return + if _retries < MAX_RETRIES: + _retries += 1 + _schedule_retry() + else: + _pending = false # gave up — caller's border-fade / empty state persists + return + + var w: Dictionary = window + var echoed_center := _vec_from_center(w.get("center", [0, 0])) + var echoed_n := int(w.get("n", 0)) + if echoed_center != _center or echoed_n != _n: + return # stale — answers a window we've since panned away from (§2) + + _pending = false + _retries = 0 + _cache.put(_body_id, _center, _n, w) + window_ready.emit(w) + + +func _schedule_retry() -> void: + var timer := get_tree().create_timer(RETRY_DELAY) + timer.timeout.connect( + func() -> void: + if _pending: + SimBridge.request_atlas_layers(_body_id, "Topography", _center, _n) + ) + + +func is_pending() -> bool: + return _pending + + +func get_cache() -> Variant: + return _cache + + +static func _vec_from_center(center: Variant) -> Vector2i: + if center is Array and center.size() >= 2: + return Vector2i(int(center[0]), int(center[1])) + return Vector2i.ZERO diff --git a/client/ui/implant/apps/atlas/atlas_window_viewer.gd b/client/ui/implant/apps/atlas/atlas_window_viewer.gd new file mode 100644 index 000000000..a6f0bdf65 --- /dev/null +++ b/client/ui/implant/apps/atlas/atlas_window_viewer.gd @@ -0,0 +1,497 @@ +class_name AtlasWindowViewer +extends Control + +## Regional district-resolution window viewer (T-1138, D-226 T-1124 +## amendment). Entered via a click-through from the planetary AtlasViewer +## (the 2026-07-21 §5 entry revision — NOT a zoom-threshold LOD swap). +## Renders a DistrictWindowLayer composite: morphology base layer lightness- +## modulated by elev_q, three switchable climate/vegetation overlays, and an +## always-on glaciation ice-tint modifier (drawing itself is +## AtlasWindowOverlay's job — this Control owns input, request orchestration, +## chrome, and the pan/zoom transform). +## +## Design notes (mirroring AtlasViewer's own split, D-226 §5): +## - _canvas (Node2D) holds AtlasWindowOverlay; pan = _canvas.position, zoom +## = _canvas.scale — the SAME transform idiom as the planetary viewer. +## - Zoom is ALWAYS client-side on the already-held composite (§5: "the +## composite is a texture the client zooms client-side... from already- +## held data") — it NEVER triggers a re-request. Only a pan past the held +## window's edge does (§4/§5). +## - _window_request (atlas_window_request.gd) owns the cache/debounce/ +## retry — this Control decides WHEN to call it (pan-edge detection, +## entry), never talks to SimBridge directly itself. +## +## Navigation: +## Mouse drag pan within/across the window +## Mouse wheel zoom the held composite (client-side only, never refetches) +## Esc back to the planetary view + +signal back_pressed + +const PANEL_MARGIN: float = 16.0 +const OVERLAY_BAR_HEADER_RESERVE: float = 360.0 + +const MIN_ZOOM: float = 0.5 +const MAX_ZOOM: float = 8.0 +const ZOOM_STEP: float = 1.15 + +## Pixel size of one district cell at zoom=1.0 — a fixed on-screen scale +## (unlike AtlasViewer's heightmap, there is no source texture dictating a +## native pixel size; this constant IS the native size). 16px/cell at n=64 +## gives a ~1024px-wide composite before zoom, comfortably inside a +## 1280x720+ viewport at the DEFAULT_N=32 interactive default (512px) too. +const CELL_PIXEL_SIZE: float = 16.0 + +const COLOR_BG: Color = Color("#0d1117") +## Border-fade target (§5 "what renders during the wait"): the underlying +## whole-body heightmap's own background tint, so the newly-exposed edge +## reads as "real data seen through", not a placeholder block. Reuses +## AtlasViewer's own COLOR_HEIGHTMAP_TINT-adjacent dim value rather than +## inventing a new one — this IS a dimmer/less-certain read of the same +## planetary data, not a different visual language. +const COLOR_BORDER_FADE: Color = Color(0.20, 0.24, 0.30, 0.55) + +## D-243: 2,048 m per district side. +const DISTRICT_M: float = 2048.0 + +const AtlasWindowRequest := preload("res://ui/implant/apps/atlas/atlas_window_request.gd") + +# ── Overlay definitions (T-1138 — reuses atlas_overlay_bar.gd/ +# atlas_legend_panel.gd's existing duck-typed viewer interface: both call +# only get_overlay_defs()/is_overlay_visible()/set_overlay_visible(), so +# this Control is a drop-in "viewer" for either component without +# subclassing AtlasViewer). Glaciation is deliberately NOT here — it is an +# always-on modifier per §5, not a toggle id. +const OVERLAY_DEFS: Array = [ + { + "id": "gen_dw_temp", + "label": "TMP", + "group": "toggle", + "tooltip": "Temperature — region-ramp colorizer, reused from the planetary climate overlay." + }, + { + "id": "gen_dw_moisture", + "label": "MST", + "group": "toggle", + "tooltip": "Moisture — dry-to-wet ramp." + }, + { + "id": "gen_dw_veg", + "label": "VEG", + "group": "toggle", + "tooltip": "Vegetation — green-family ramp. Marine reads transparent (open water)." + }, +] + +# ── Context (set by enter()) ────────────────────────────────────────────── +var _body: Dictionary = {} +var _system: Dictionary = {} +var _implant_theme = null + +# ── Held window + geometry ──────────────────────────────────────────────── +var _window: Variant = null # current DistrictWindowLayer Dictionary, or null while waiting +var _held_center: Vector2i = Vector2i.ZERO +var _held_n: int = 32 + +# ── Pan/zoom state (mirrors AtlasViewer's own fields exactly) ──────────── +var _view_offset: Vector2 = Vector2.ZERO +var _view_zoom: float = 1.0 +var _dragging: bool = false +var _drag_start_mouse: Vector2 +var _drag_start_offset: Vector2 + +# ── Overlay visibility ───────────────────────────────────────────────────── +var _overlay_visibility: Dictionary = {} + +# ── Child nodes ──────────────────────────────────────────────────────────── +var _canvas: Node2D = null +var _overlay_node: AtlasWindowOverlay = null +var _screen_header: ImplantHeader = null +var _overlay_bar = null +var _legend_panel = null +var _window_request = null # AtlasWindowRequest + + +func _ready() -> void: + anchor_right = 1.0 + anchor_bottom = 1.0 + grow_horizontal = Control.GROW_DIRECTION_BOTH + grow_vertical = Control.GROW_DIRECTION_BOTH + mouse_filter = Control.MOUSE_FILTER_STOP + focus_mode = Control.FOCUS_ALL + + _implant_theme = load("res://ui/implant/default_implant.tres") + + for def: Dictionary in OVERLAY_DEFS: + _overlay_visibility[def["id"]] = false + + _canvas = Node2D.new() + _canvas.name = "WindowCanvas" + add_child(_canvas) + + _overlay_node = AtlasWindowOverlay.new() + _overlay_node.name = "WindowOverlay" + _overlay_node.viewer = self + _canvas.add_child(_overlay_node) + + _window_request = AtlasWindowRequest.new(self) + _window_request.name = "WindowRequest" + add_child(_window_request) + _window_request.window_ready.connect(_on_window_ready) + + _build_screen_header() + _build_overlay_bar() + _build_legend_panel() + + SimBridge.atlas_layers_received.connect(_on_atlas_layers_received) + + +func _exit_tree() -> void: + if SimBridge.atlas_layers_received.is_connected(_on_atlas_layers_received): + SimBridge.atlas_layers_received.disconnect(_on_atlas_layers_received) + + +## Enter the window screen centered on `district_center` (a DistrictPos- +## equivalent Vector2i, from the planetary click-through's derived position — +## §5's "pan center read as click point"). n defaults to the client's +## interactive default (32), half the server's hard cap. +func enter( + body: Dictionary, + system: Dictionary, + district_center: Vector2i, + n: int = AtlasWindowRequest.DISTRICT_WINDOW_DEFAULT_N +) -> void: + _body = body + _system = system + _held_center = district_center + _held_n = n + _window = null + _view_zoom = 1.0 + _view_offset = Vector2.ZERO + _apply_transform() + _window_request.reset() + _window_request.request_now(_dict_str(_body, "body_id", ""), district_center, n) + _refresh_screen_header() + grab_focus() + queue_redraw() + _overlay_node.queue_redraw() + + +func leave() -> void: + pass + + +## Named get_district_window(), NOT get_window() — Node already defines +## get_window() -> Window (the containing OS window); shadowing it with an +## incompatible return type is a Godot parse error (confirmed the hard way). +func get_district_window() -> Variant: + return _window + + +## District-cell pixel size at zoom=1.0 — AtlasWindowOverlay reads this +## rather than hardcoding CELL_PIXEL_SIZE itself, so the viewer stays the +## single source of geometry truth (same "viewer owns the transform, overlay +## only draws" split as AtlasViewer/AtlasMarkerOverlay). +func get_cell_pixel_size() -> float: + return CELL_PIXEL_SIZE + + +func is_overlay_visible(overlay_id: String) -> bool: + return bool(_overlay_visibility.get(overlay_id, false)) + + +func set_overlay_visible(overlay_id: String, visible_state: bool) -> void: + if not _overlay_visibility.has(overlay_id): + push_warning("AtlasWindowViewer: unknown overlay id '%s'" % overlay_id) + return + _overlay_visibility[overlay_id] = visible_state + _overlay_node.queue_redraw() + _legend_panel.refresh() + + +func get_overlay_defs() -> Array: + return OVERLAY_DEFS + + +# ============================================================================= +# Window response routing +# ============================================================================= + + +func _on_atlas_layers_received(response: Dictionary) -> void: + _window_request.on_response(response) + + +func _on_window_ready(window: Dictionary) -> void: + # Only adopt the window if it still matches what THIS viewer is currently + # showing — AtlasWindowRequest already filtered by its own last-asked + # (center, n) via the echo (§2), but a cache-hit path can fire + # synchronously from enter() before _held_center is what the signal + # handler expects in a re-entrant call; comparing again here is cheap and + # removes any ordering assumption between enter()'s two calls. + var w_center := _vec_from_center(window.get("center", [0, 0])) + var w_n := int(window.get("n", 0)) + if w_center != _held_center or w_n != _held_n: + return + _window = window + _refresh_screen_header() + queue_redraw() + _overlay_node.queue_redraw() + + +# ============================================================================= +# View transform (mirrors AtlasViewer's own — pan is real, zoom is client-side +# only and NEVER triggers a re-request per §5) +# ============================================================================= + + +func _apply_transform() -> void: + _canvas.position = _view_offset + _canvas.scale = Vector2(_view_zoom, _view_zoom) + queue_redraw() + _overlay_node.queue_redraw() + + +func _zoom_at(mouse_pos: Vector2, factor: float) -> void: + var new_zoom: float = clampf(_view_zoom * factor, MIN_ZOOM, MAX_ZOOM) + if is_equal_approx(new_zoom, _view_zoom): + return + var local_before: Vector2 = (mouse_pos - _view_offset) / _view_zoom + _view_zoom = new_zoom + _view_offset = mouse_pos - local_before * _view_zoom + _apply_transform() + + +## Programmatic view control (T-1120 capture-API parity — must survive on +## every viewer this app exposes, per the ticket's explicit note, even one +## that never got user pan/zoom to begin with on the OTHER seam this ticket +## removes it from). +func get_view_zoom() -> float: + return _view_zoom + + +func get_view_offset() -> Vector2: + return _view_offset + + +func set_view(zoom: float, offset: Vector2) -> void: + _view_zoom = clampf(zoom, MIN_ZOOM, MAX_ZOOM) + _view_offset = offset + _apply_transform() + + +# ============================================================================= +# Pan-edge re-request (§4/§5): re-request ONLY when the view pans past the +# held window's edge; zoom never refetches. +# ============================================================================= + + +## After a drag delta, check whether the screen-center now maps to a +## DistrictPos outside the held window's extent — if so, float a NEW window +## centered on that point (§5 "windows float on the pan center... not +## grid-snapped") via the debounced request path. +func _maybe_refloat_window() -> void: + if _held_n <= 0: + return + var screen_center: Vector2 = size * 0.5 + var canvas_pt: Vector2 = (screen_center - _view_offset) / _view_zoom + var cell: Vector2 = canvas_pt / CELL_PIXEL_SIZE + # cell is in [0, _held_n) local window space when centered — half-window + # offset from _held_center converts back to absolute district space. + var half: float = float(_held_n) / 2.0 + var abs_col: float = float(_held_center.x) - half + cell.x + var abs_row: float = float(_held_center.y) - half + cell.y + var new_center := Vector2i(roundi(abs_col), roundi(abs_row)) + if new_center == _held_center: + return + # Edge-crossing check: only re-request if the screen-center point has + # actually left the CURRENTLY HELD window's extent — a pan that stays + # inside the window (even if the nominal "nearest DistrictPos to center" + # ticked over by one cell near a boundary) must not spam a request every + # frame. §4: "re-requests only when a pan carries the view past the held + # window's edge." + var local_col: float = abs_col - float(_held_center.x) + half + var local_row: float = abs_row - float(_held_center.y) + half + var inside: bool = ( + local_col >= 0.0 + and local_col < float(_held_n) + and local_row >= 0.0 + and local_row < float(_held_n) + ) + if inside: + return + _held_center = new_center + _window_request.request_debounced(_dict_str(_body, "body_id", ""), new_center, _held_n) + + +# ============================================================================= +# Drawing (background + border-fade + header) +# ============================================================================= + + +func _draw() -> void: + draw_rect(Rect2(Vector2.ZERO, get_rect().size), COLOR_BG) + if _window == null: + # §5 "what renders during the wait": a border-fade to the underlying + # whole-body context rather than black/a spinner. This viewer has no + # resident whole-body texture of its own (that lives on AtlasViewer, + # which this screen has navigated away from) — the honest available + # substitute is a dim fade wash over the held composite's last-known + # extent, reusing _gen_pending_indicator (via the request object's own + # is_pending()) for the "still working" cue rather than new dressing. + _draw_border_fade() + + +func _draw_border_fade() -> void: + if not _window_request or not _window_request.is_pending(): + return + var extent: float = float(_held_n) * CELL_PIXEL_SIZE * _view_zoom + var top_left: Vector2 = _view_offset + draw_rect(Rect2(top_left, Vector2(extent, extent)), COLOR_BORDER_FADE) + + +func _build_screen_header() -> void: + _screen_header = ImplantHeader.new() + _screen_header.position = Vector2(PANEL_MARGIN, 16.0) + _screen_header.custom_minimum_size.x = 320.0 + _screen_header.mouse_filter = Control.MOUSE_FILTER_IGNORE + add_child(_screen_header) + if _implant_theme: + _screen_header.apply_implant_theme(_implant_theme) + + +## D-169/D-170 implant chrome (§5): location label (nearest settlement when +## the window is over/near one, else a coordinate/region label — the window +## is NOT settlement-anchored) + extent-in-real-units subtitle, e.g. +## "4.1 x 4.1 km . 2.0 km/cell". +func _refresh_screen_header() -> void: + if _screen_header == null: + return + var location_label: String = _location_label() + var extent_km: float = float(_held_n) * DISTRICT_M / 1000.0 + var extent_line: String = "%.1f x %.1f km · %.1f km/cell" % [ + extent_km, extent_km, DISTRICT_M / 1000.0 + ] + var title: String = "REGIONAL — %s" % location_label.to_upper() + _screen_header.set_content(title, extent_line) + + +## Coordinate/region label — no settlement join exists at this layer yet +## (the district window carries no settlement data of its own; that lives on +## the planetary gen_l3_settlements overlay, a different screen). This is +## deliberately the coordinate fallback branch always, until a future ticket +## wires a settlement-proximity join — recorded as an open follow-up, not +## silently guessed at. +func _location_label() -> String: + return "district (%d, %d)" % [_held_center.x, _held_center.y] + + +# ============================================================================= +# Input +# ============================================================================= + + +## No city panel / sidebar in this mode (yet) — the window carries no +## settlement join of its own (see _location_label's doc), so there is +## nothing to hit-test against and this always reads false. Wired into +## _gui_input exactly where AtlasViewer's own _is_over_ui is (same guard +## shape) so a future sidebar addition only needs to change THIS function's +## body, not every call site. +func _is_over_ui(_pos: Vector2) -> bool: + return false + + +func _gui_input(event: InputEvent) -> void: + if event is InputEventKey and event.pressed and not event.is_echo(): + _handle_key(event as InputEventKey) + return + + if ( + event is InputEventMouseButton + and _is_over_ui((event as InputEventMouseButton).global_position) + ): + return + + if event is InputEventMouseButton: + var mb := event as InputEventMouseButton + if mb.button_index == MOUSE_BUTTON_WHEEL_UP and mb.pressed: + _zoom_at(mb.position, ZOOM_STEP) + elif mb.button_index == MOUSE_BUTTON_WHEEL_DOWN and mb.pressed: + _zoom_at(mb.position, 1.0 / ZOOM_STEP) + elif mb.button_index == MOUSE_BUTTON_LEFT: + if mb.pressed: + _dragging = true + _drag_start_mouse = mb.position + _drag_start_offset = _view_offset + else: + _dragging = false + elif event is InputEventMouseMotion: + var mm := event as InputEventMouseMotion + if _dragging: + _view_offset = _drag_start_offset + (mm.position - _drag_start_mouse) + _apply_transform() + _maybe_refloat_window() + + +func _handle_key(event: InputEventKey) -> void: + if event.keycode == KEY_ESCAPE: + back_pressed.emit() + + +# ============================================================================= +# Overlay bar / legend (reuses atlas_overlay_bar.gd/atlas_legend_panel.gd — +# both call only get_overlay_defs()/is_overlay_visible()/set_overlay_visible(), +# so this Control is a drop-in viewer for either component) +# ============================================================================= + + +func _build_overlay_bar() -> void: + var BarScript := load("res://ui/implant/apps/atlas/atlas_overlay_bar.gd") + _overlay_bar = BarScript.new(self) + _overlay_bar.name = "WindowOverlayBar" + add_child(_overlay_bar) + _position_overlay_bar() + + +func _position_overlay_bar() -> void: + var sz: Vector2 = get_rect().size + if sz == Vector2.ZERO: + sz = Vector2(1280.0, 720.0) + var avail_w: float = maxf(sz.x - OVERLAY_BAR_HEADER_RESERVE - PANEL_MARGIN * 2.0, 200.0) + _overlay_bar.position = Vector2(sz.x - avail_w - PANEL_MARGIN, PANEL_MARGIN) + _overlay_bar.size = Vector2(avail_w, 0.0) + + +func _build_legend_panel() -> void: + var LegendScript := load("res://ui/implant/apps/atlas/atlas_window_legend.gd") + _legend_panel = LegendScript.new(self) + _legend_panel.name = "WindowLegend" + _legend_panel.theme_resource = _implant_theme + add_child(_legend_panel) + _legend_panel.refresh() + + +func _notification(what: int) -> void: + if what == NOTIFICATION_RESIZED: + if _overlay_bar: + _position_overlay_bar() + if _legend_panel: + _legend_panel.reposition() + + +## Safely extract a string field from a dict, falling back when missing or +## null (matches atlas_viewer.gd's own _dict_str verbatim). +static func _dict_str(d: Dictionary, key: String, fallback: String) -> String: + var v: Variant = d.get(key) + if v == null: + return fallback + var s: String = str(v) + if s.is_empty(): + return fallback + return s + + +static func _vec_from_center(center: Variant) -> Vector2i: + if center is Array and center.size() >= 2: + return Vector2i(int(center[0]), int(center[1])) + return Vector2i.ZERO diff --git a/client/ui/implant/apps/atlas/screens/district_screen.gd b/client/ui/implant/apps/atlas/screens/district_screen.gd new file mode 100644 index 000000000..1b009ef06 --- /dev/null +++ b/client/ui/implant/apps/atlas/screens/district_screen.gd @@ -0,0 +1,40 @@ +class_name DistrictScreen +extends Control +## Regional district-window viewer screen for AtlasApp (T-1138, D-226 T-1124 +## amendment). Thin wrapper around AtlasWindowViewer, mirroring +## RegionalScreen's own shape exactly — enter/leave are the nav interface. +## +## Entered via a click-through from AtlasViewer (the "regional" screen), +## carrying the derived DistrictPos the player clicked (§5's entry-revision: +## "pan center read as click point"). Esc goes back to "regional" (the +## planetary heightmap for the same body) — a nav.pop(), not a fresh push, so +## the planetary view's own pan/zoom-removed FIXED state is exactly where the +## player left it. + +signal back_requested + +var _viewer: AtlasWindowViewer = null + + +func _ready() -> void: + mouse_filter = Control.MOUSE_FILTER_STOP + set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT) + _viewer = AtlasWindowViewer.new() + _viewer.name = "AtlasWindowViewer" + add_child(_viewer) + _viewer.back_pressed.connect(_on_viewer_back) + + +func enter(payload: Dictionary) -> void: + var body: Dictionary = payload.get("body", {}) + var system: Dictionary = payload.get("system", {}) + var center: Vector2i = payload.get("district_center", Vector2i.ZERO) + _viewer.enter(body, system, center) + + +func leave() -> void: + pass + + +func _on_viewer_back() -> void: + back_requested.emit() diff --git a/client/ui/implant/apps/atlas/screens/regional_screen.gd b/client/ui/implant/apps/atlas/screens/regional_screen.gd index b0d6bdd49..b32a54848 100644 --- a/client/ui/implant/apps/atlas/screens/regional_screen.gd +++ b/client/ui/implant/apps/atlas/screens/regional_screen.gd @@ -5,6 +5,7 @@ extends Control signal back_requested signal economics_link_requested(system_id: String) +signal district_descend_requested(district_center: Vector2i) # T-1138, forwarded from AtlasViewer var _viewer: AtlasViewer = null @@ -17,6 +18,7 @@ func _ready() -> void: add_child(_viewer) _viewer.back_pressed.connect(_on_viewer_back) _viewer.economics_link_requested.connect(_on_viewer_economics_link) + _viewer.district_descend_requested.connect(_on_viewer_district_descend) func enter(payload: Dictionary) -> void: @@ -35,3 +37,7 @@ func _on_viewer_back() -> void: func _on_viewer_economics_link(system_id: String) -> void: economics_link_requested.emit(system_id) + + +func _on_viewer_district_descend(district_center: Vector2i) -> void: + district_descend_requested.emit(district_center)