191 lines
8.1 KiB
GDScript
191 lines
8.1 KiB
GDScript
## 卷轴视口承载件（level-map.md 布局决策 5——关卡画面选路屏）：画布宿主与裁切、平移状态
|
||
## 与 clamp、锚点跟随与平滑滚动、指引件（屏缘渐隐带＋平移提示 chip）。
|
||
## 纯呈现态：平移位置零核心写、不进存档（重进本屏按锚点规则重新定位）；跟随只随停点切换/
|
||
## 兑付回图发生（零自动推进）。拖拽/滚轮判定留画布 _gui_input（事件流同源——悬停/选路同源），
|
||
## 本件只管裁切/offset/clamp/跟随/指引；画布包络＝画布实际尺寸（open_choices 拟合后同帧收敛）。
|
||
class_name LevelMapViewport
|
||
extends Control
|
||
|
||
const SCROLL_DUR := 0.3 # 平滑滚动时长（布局决策 5 provisional 0.3s 单段缓动）
|
||
const FADE_BAND_W := 70.0 # 屏缘渐隐带宽（布局决策 5／像素级判据②）
|
||
const CHIP_SIZE := Vector2(240, 30) # 平移提示 chip（像素级判据③——图区底部居中）
|
||
const CHIP_CORNER := 6 # chip 圆角（布局决策 5）
|
||
const CHIP_BOTTOM_GAP := 24.0 # chip 距视口底缘（效果图档同族取值）
|
||
const CHIP_TEXT := "◄ 拖拽画布 / 滚轮平移 ►" # 14px（FS_HINT 档——布局决策 5）
|
||
const EDGE_EPS := 0.5 # 包络边界判定容差（浮点平移累积）
|
||
|
||
var _canvas: Control
|
||
var _anchor_provider: Callable # () -> Vector2 锚点画布坐标（screen 提供——当前节点/入口组）
|
||
var _viewport_size := Vector2.ZERO # 窗口尺寸兜底（setup 注入设计基座——实况窗口以控件 size 为准，布局晚于构造）
|
||
var _offset := Vector2.ZERO: # 画布左上角在视口件坐标系的位置（纯呈现态——直驱画布 position）
|
||
set(value):
|
||
_offset = value
|
||
if _canvas != null:
|
||
_canvas.position = _offset
|
||
var _view_tween: Tween
|
||
var _guided_visible := false # 指引件可见态（画布超窗才暗示——浅图无平移余量即隐藏）
|
||
|
||
|
||
## 一次交齐注入（code-conventions §1.6 拆分交接：画布宿主、锚点来源、窗口兜底尺寸）
|
||
func setup(canvas: Control, anchor_provider: Callable, viewport_size: Vector2) -> void:
|
||
_canvas = canvas
|
||
_anchor_provider = anchor_provider
|
||
_viewport_size = viewport_size
|
||
clip_contents = true
|
||
add_child(canvas)
|
||
_build_guidance()
|
||
|
||
|
||
func _notification(what: int) -> void:
|
||
# 窗口实况尺寸落定/变化即重锚（首开布局晚于 open_choices 的锚定——隐藏子树容器排序
|
||
# 首个可见帧才传播，4.7 行为；实况窗口以本件 size 为准，落定即收敛锚点）
|
||
if what == NOTIFICATION_RESIZED and _canvas != null and _anchor_provider.is_valid():
|
||
reanchor(false)
|
||
|
||
|
||
## 锚点跟随（布局决策 5：锚点居中；smooth=停点切换/兑付回图平滑滚动，减动效开＝跳终态；
|
||
## 重入先杀在飞 tween 再建新——快速连续停点切换防叠加）
|
||
func reanchor(smooth: bool) -> void:
|
||
if _canvas == null or not _anchor_provider.is_valid():
|
||
return
|
||
var target := _clamped_center_offset(_anchor_provider.call())
|
||
_kill_scroll_tween()
|
||
if not smooth or ArmedTimer.motion_still():
|
||
_offset = target
|
||
_sync_guidance()
|
||
return
|
||
_view_tween = create_tween()
|
||
_view_tween.tween_property(self, "_offset", target, UiKit.motion(SCROLL_DUR)) \
|
||
.set_trans(Tween.TRANS_CUBIC).set_ease(Tween.EASE_OUT)
|
||
_sync_guidance()
|
||
|
||
|
||
## 手动平移（画布 _gui_input 判定后调用——拖拽沿逐帧/滚轮步进；纯呈现零核心写）
|
||
func pan_by(delta: Vector2) -> void:
|
||
if _canvas == null:
|
||
return
|
||
_kill_scroll_tween()
|
||
var win := _window_size()
|
||
_offset = Vector2(
|
||
_axis_pan_offset(_offset.x, delta.x, _canvas.size.x, win.x),
|
||
_axis_pan_offset(_offset.y, delta.y, _canvas.size.y, win.y))
|
||
_sync_guidance()
|
||
|
||
|
||
## 视口中线的画布坐标（锚点居中判据投影面——浅图＝画布中心，深图＝夹紧域内当前注视点）
|
||
func viewport_center_canvas_pos() -> Vector2:
|
||
return _window_size() / 2.0 - _offset
|
||
|
||
|
||
## 视口是否钉在画布包络边界（任一超窗轴 offset 顶边——clamp 判据面）
|
||
func is_clamped_at_edge() -> bool:
|
||
var win := _window_size()
|
||
if _canvas == null:
|
||
return false
|
||
return _axis_at_edge(_offset.x, _canvas.size.x, win.x) \
|
||
or _axis_at_edge(_offset.y, _canvas.size.y, win.y)
|
||
|
||
|
||
func _kill_scroll_tween() -> void:
|
||
if _view_tween != null and _view_tween.is_valid():
|
||
_view_tween.kill()
|
||
_view_tween = null
|
||
|
||
|
||
## 单轴锚定 offset：画布不超窗＝居中分支（夹紧域退化——布局决策 5）；
|
||
## 超窗＝锚点夹紧在画布包络内，锚点落视口中线（offset = 半窗 − 锚点）
|
||
func _axis_center_offset(anchor: float, canvas_len: float, half_win: float) -> float:
|
||
if canvas_len <= half_win * 2.0:
|
||
return half_win - canvas_len / 2.0
|
||
return half_win - clampf(anchor, half_win, canvas_len - half_win)
|
||
|
||
|
||
func _clamped_center_offset(anchor: Vector2) -> Vector2:
|
||
var half := _window_size() / 2.0
|
||
return Vector2(
|
||
_axis_center_offset(anchor.x, _canvas.size.x, half.x),
|
||
_axis_center_offset(anchor.y, _canvas.size.y, half.y))
|
||
|
||
|
||
## 单轴平移收敛：居中轴零平移余量不动；超窗轴 offset 收敛在 [半窗−画布, 0]（不出露屏底空档）
|
||
func _axis_pan_offset(cur: float, delta: float, canvas_len: float, win_len: float) -> float:
|
||
if canvas_len <= win_len:
|
||
return cur
|
||
return clampf(cur + delta, win_len - canvas_len, 0.0)
|
||
|
||
|
||
func _axis_at_edge(offset: float, canvas_len: float, win_len: float) -> bool:
|
||
if canvas_len <= win_len:
|
||
return false
|
||
return offset >= -EDGE_EPS or offset <= win_len - canvas_len + EDGE_EPS
|
||
|
||
|
||
## 实况窗口优先（容器布局晚于构造——注入值只兜构造帧数学）
|
||
func _window_size() -> Vector2:
|
||
if size.x > 0.0 and size.y > 0.0:
|
||
return size
|
||
return _viewport_size
|
||
|
||
|
||
## 指引件（布局决策 5／像素级判据②③）：屏缘渐隐带盖在画布之上＋图区底部居中提示 chip；
|
||
## 可见性＝画布超窗（_sync_guidance 随锚定/平移刷新）
|
||
func _build_guidance() -> void:
|
||
var band_l := TextureRect.new()
|
||
band_l.name = "FadeL"
|
||
band_l.texture = _fade_gradient(false)
|
||
band_l.set_anchors_preset(Control.PRESET_LEFT_WIDE)
|
||
band_l.offset_right = FADE_BAND_W
|
||
band_l.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
|
||
band_l.mouse_filter = Control.MOUSE_FILTER_IGNORE
|
||
add_child(band_l)
|
||
var band_r := TextureRect.new()
|
||
band_r.name = "FadeR"
|
||
band_r.texture = _fade_gradient(true)
|
||
band_r.set_anchors_preset(Control.PRESET_RIGHT_WIDE)
|
||
band_r.offset_left = -FADE_BAND_W
|
||
band_r.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
|
||
band_r.mouse_filter = Control.MOUSE_FILTER_IGNORE
|
||
add_child(band_r)
|
||
var chip := PanelContainer.new()
|
||
chip.name = "PanHint"
|
||
chip.add_theme_stylebox_override("panel",
|
||
UiKit.panel_flat(UiKit.HP_BAR_BACK, UiKit.STONE, CHIP_CORNER, 1, Vector4(12, 5, 12, 5)))
|
||
chip.set_anchors_preset(Control.PRESET_CENTER_BOTTOM)
|
||
chip.offset_left = -CHIP_SIZE.x / 2.0
|
||
chip.offset_right = CHIP_SIZE.x / 2.0
|
||
chip.offset_top = -CHIP_SIZE.y - CHIP_BOTTOM_GAP
|
||
chip.offset_bottom = -CHIP_BOTTOM_GAP
|
||
chip.custom_minimum_size = CHIP_SIZE
|
||
chip.mouse_filter = Control.MOUSE_FILTER_IGNORE
|
||
var chip_label := UiKit.label(CHIP_TEXT, UiKit.FS_HINT, false, UiKit.WARM)
|
||
chip_label.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
|
||
chip_label.vertical_alignment = VERTICAL_ALIGNMENT_CENTER
|
||
chip.add_child(chip_label)
|
||
add_child(chip)
|
||
_sync_guidance()
|
||
|
||
|
||
## 屏缘渐隐渐变（色取屏底同族 BG_ROOT——代拍板：不透明端 0.9 单段衰减）
|
||
func _fade_gradient(transparent_at_left: bool) -> GradientTexture2D:
|
||
var grad := Gradient.new()
|
||
grad.offsets = PackedFloat32Array([0.0, 1.0])
|
||
grad.colors = PackedColorArray([Color(UiKit.BG_ROOT, 0.9), Color(UiKit.BG_ROOT, 0.0)])
|
||
var tex := GradientTexture2D.new()
|
||
tex.gradient = grad
|
||
tex.fill_from = Vector2(1, 0.5) if transparent_at_left else Vector2(0, 0.5)
|
||
tex.fill_to = Vector2(0, 0.5) if transparent_at_left else Vector2(1, 0.5)
|
||
tex.width = int(FADE_BAND_W)
|
||
return tex
|
||
|
||
|
||
func _sync_guidance() -> void:
|
||
var win := _window_size()
|
||
var over := _canvas != null and (_canvas.size.x > win.x or _canvas.size.y > win.y)
|
||
if over == _guided_visible:
|
||
return
|
||
_guided_visible = over
|
||
for nm in ["FadeL", "FadeR", "PanHint"]:
|
||
var node := get_node_or_null(NodePath(nm)) as Control
|
||
if node != null:
|
||
node.visible = over
|