class_name StepCanvasProtocol ## StepCanvasRequest/StepCanvasResponse wire codec (T-1182, D-255(c)) — the ## stepped Atlas ladder's tagged-envelope carrier, executing the D-225 ## migration server/src/atlas/step_canvas.rs already ships (T-1181, PR #201). ## Split out of protocol.gd (not folded in), same rationale as ## browse_protocol.gd/atlas_map_protocol.gd — stay under gdlint's ## max-file-lines, one file per wire-shape family. ## ## `step_canvas: true` is the mandatory discriminator field — the SIXTH ## `Inbound` shape server/src/bridge/mod.rs demuxes on (star_map/city_names/ ## browse/step_canvas, plus the two field-shape-disambiguated map probes). ## ## **Wire shapes (confirmed against server/src/atlas/step_canvas.rs, the ## authoritative source over any doc drift — T-1181's IMPLEMENTATION REPORT + ## WIRE SHAPE ADDENDUM, 2026-07-25):** ## StepCanvasRequest — a map: {step_canvas: true, body_id: String, ## rung: , center: [i64, i64], extent: [u32, u32], ## min_wl_m: u32}. `rung` is a unit-variant enum, encoded as its Rust ## variant NAME verbatim (rmp_serde's bare-enum convention, same as ## granularity_v2/RoadNodeKind/CourseTerminus elsewhere on this wire). ## `center`/`extent` are meaningless for Global (server ignores extent ## entirely, center is echoed but unused) but are still sent — the ## request shape carries them unconditionally, no per-rung omission (the ## server-side struct has no Option on either field). ## StepCanvasResponse — a map: {body_id, rung, center: [i64,i64], ## extent: [u32,u32], min_wl_m: u32, status, canvas: null | EncodedStepCanvas}. ## `extent` is the server-CLAMPED echo (PR #201 review) — ALWAYS read ## this back, never assume the requested extent; `(0,0)` for Global (the ## wire extent is never read for that rung, so there is no clamped value ## to report). `status` is the same bare-string-or-{"Error":"msg"} shape ## every other status enum on this wire uses (Ready|Pending|NotFound| ## Error(String)) — decoded via the shared _decode_status_field() shape ## (duplicated here per browse_protocol.gd's own "genuinely standalone" ## precedent, not shared via a Callable). ## EncodedStepCanvas — a map: {width, height, morphology, elev_q, temp_dc, ## moisture_q, vegetation, settlement_id, glaciation, flooded_q, courses, ## cliffs}. The six PNG-per-field dense planes (morphology/elev_q/ ## moisture_q/vegetation/glaciation/flooded_q) are each a map ## {"png_bytes": [...]} — png_bytes is a Rust `Vec` with NO ## serde_bytes annotation anywhere in this codebase (confirmed: grep for ## serde_bytes across server/src returns nothing), so serde's blanket ## Vec impl serializes it via serialize_seq — a msgpack ARRAY of ## small-integer elements, NOT a `bin` blob. messagepack.gd's decoder ## therefore returns a plain GDScript Array (one int per byte), which ## this codec repacks into a PackedByteArray via the direct ## PackedByteArray(array) constructor before handing it to ## Image.load_png_from_buffer() — decode_png_field() below is the one ## place this conversion happens. temp_dc/settlement_id are the OTHER ## two dense fields, shipped raw MessagePack-native (too wide for an ## 8-bit PNG plane per EncodedTempField/EncodedSettlementField's own ## server-side doc): {"values": [...]} — i16/u32 arrays respectively, ## passed through as plain Arrays, no PackedByteArray repack (their ## per-cell domain doesn't fit a byte anyway). courses/cliffs are sparse ## MessagePack-native lists, passed through unshaped (the annotation ## layer owns interpreting RiverCourse/CliffSegment's own per-entry ## shape, matching atlas_map_protocol.gd's existing "raw passthrough, ## caller reshapes" precedent for district_window's courses field). ## Encode a StepCanvasRequest. `mp` is the loaded messagepack.gd module ## (passed in rather than reloaded here, matching every other codec in this ## cluster). `rung` is one of the six bare-string rung tags ## (StepCanvasTransport.RUNG_* constants) — sent verbatim, no client-side ## validation (the server rejects an unrecognized variant name at decode ## time per step_canvas.rs's own doc: "Unknown -> rejected, never trusted ## from the wire"). static func encode_step_canvas_request( mp, body_id: String, rung: String, center: Vector2i, extent: Vector2i, min_wl_m: int = 0 ) -> PackedByteArray: var msg := { "step_canvas": true, "body_id": body_id, "rung": rung, "center": [center.x, center.y], "extent": [extent.x, extent.y], "min_wl_m": min_wl_m, } var result = mp.encode(msg) if result.status != null: push_error("StepCanvasProtocol: encode_step_canvas_request failed: %s" % result.status) return PackedByteArray() return result.value ## Shared status-enum decode — bare string ("Ready"/"Pending"/"NotFound") or ## a single-key map ({"Error": "message"}) for the one data variant. Same ## shape browse_protocol.gd/atlas_map_protocol.gd already implement for their ## own status enums; duplicated here rather than shared via a Callable to ## keep this file genuinely standalone (browse_protocol.gd's own stated ## rationale for its copy). static func _decode_status_field(status_raw: Variant) -> Dictionary: if status_raw is String: return {"status": status_raw, "error": ""} if status_raw is Dictionary and status_raw.has("Error"): return {"status": "Error", "error": str(status_raw["Error"])} return {"status": "", "error": ""} ## Repack a decoded {"png_bytes": [...]} field into a PackedByteArray ready ## for Image.load_png_from_buffer(). `field_raw` is the raw decoded Variant ## for one of the six PNG-per-field planes — null/malformed input returns an ## empty PackedByteArray (the caller's Image decode then fails gracefully, ## same "skip the bad entry" posture the rest of this cluster uses rather ## than crashing on a malformed wire payload). static func decode_png_field(field_raw: Variant) -> PackedByteArray: if not field_raw is Dictionary: return PackedByteArray() var bytes_raw: Variant = (field_raw as Dictionary).get("png_bytes") if not bytes_raw is Array: return PackedByteArray() return PackedByteArray(bytes_raw) ## Build an EncodedStepCanvas Dictionary (GDScript-side shape) from an ## already-decoded raw value. Returns null if `raw` isn't a plausible canvas ## (missing width/height). PNG fields are repacked to PackedByteArray here ## (once, at decode time) — every downstream consumer (the terrain layer) ## works with real PackedByteArray/Image objects, never re-touches the raw ## msgpack Array shape. static func _decode_encoded_canvas(raw: Variant) -> Variant: if not raw is Dictionary: return null var d: Dictionary = raw if not d.has("width") or not d.has("height"): return null var temp_dc_raw: Variant = d.get("temp_dc") var settlement_id_raw: Variant = d.get("settlement_id") return { "width": int(d.get("width", 0)), "height": int(d.get("height", 0)), "morphology": decode_png_field(d.get("morphology")), "elev_q": decode_png_field(d.get("elev_q")), "temp_dc": (temp_dc_raw as Dictionary).get("values", []) if temp_dc_raw is Dictionary else [], "moisture_q": decode_png_field(d.get("moisture_q")), "vegetation": decode_png_field(d.get("vegetation")), "settlement_id": ( (settlement_id_raw as Dictionary).get("values", []) if settlement_id_raw is Dictionary else [] ), "glaciation": decode_png_field(d.get("glaciation")), "flooded_q": decode_png_field(d.get("flooded_q")), "courses": d.get("courses", []), "cliffs": d.get("cliffs", []), } ## Build a StepCanvasResponse Dictionary from an already-decoded raw value. ## Returns null unless it carries "rung" AND "status" — "rung" is the field ## no other decoded response on this wire has (atlas/citynames/browse all ## lack it), making it a safe, unambiguous discriminator for ## Protocol.decode_inbound()'s dispatch. static func step_canvas_response_from_raw(raw: Variant) -> Variant: if not raw is Dictionary or not raw.has("rung") or not raw.has("status"): return null var d: Dictionary = raw var decoded_status := _decode_status_field(d.get("status")) var center_raw: Variant = d.get("center", [0, 0]) var extent_raw: Variant = d.get("extent", [0, 0]) return { "body_id": str(d.get("body_id", "")), "rung": str(d.get("rung", "")), "center": _vec_from_pair(center_raw), "extent": _vec_from_pair(extent_raw), "min_wl_m": int(d.get("min_wl_m", 0)), "status": decoded_status["status"], "error": decoded_status["error"], "canvas": _decode_encoded_canvas(d.get("canvas")), } static func _vec_from_pair(pair: Variant) -> Vector2i: if pair is Array and pair.size() >= 2: return Vector2i(int(pair[0]), int(pair[1])) return Vector2i.ZERO