3D 基础：空间、相机、光照与材质

func transform_parts() -> void:
	# Transform3D = basis（3×3 矩阵：旋转 + 缩放）+ origin（位置）
	var t := global_transform
	var right := t.basis.x        # 物体自己的 +X（右）在世界里指向哪里
	var up := t.basis.y           # 自己的 +Y（上）
	var forward := -t.basis.z     # Godot 约定 -Z 是"前方"
	var pos := t.origin           # 等于 global_position
	# 把局部坐标转成世界坐标：先乘 basis（旋转、缩放），再加 origin（平移）
	var muzzle_local := Vector3(0.2, -0.1, -0.5)
	var muzzle_world := t * muzzle_local          # 等价于 t.basis * muzzle_local + t.origin
	var back_to_local := t.affine_inverse() * muzzle_world
	print(right, up, forward, pos, back_to_local)

func euler_examples() -> void:
	# rotation 是欧拉角（弧度），rotation_degrees 是同样的值换成度。
	# Godot 默认的旋转顺序是 YXZ：先绕 Y（偏航），再绕 X（俯仰），最后绕 Z（翻滚）。
	rotation_degrees = Vector3(-30, 45, 0)        # 抬头 30°，向左转 45°
	var b := Basis.from_euler(Vector3(deg_to_rad(-30), deg_to_rad(45), 0.0))   # 同样的朝向
	print(b.get_euler())                          # 再从 Basis 读回欧拉角
	# 相对当前朝向再转一点：rotate_y 绕父节点的 Y 轴，rotate_object_local 绕自己的轴
	rotate_y(deg_to_rad(10))
	rotate_object_local(Vector3.RIGHT, deg_to_rad(5))

## 在两个朝向之间平滑过渡：转成四元数做球面插值（slerp），不会出现万向节锁，
## 走的也是最短的弧线。直接对欧拉角做 lerp 可能会"绕远路"。
func turn_towards(target_basis: Basis, weight: float) -> void:
	var from := Quaternion(basis.orthonormalized())
	var to := Quaternion(target_basis.orthonormalized())
	basis = Basis(from.slerp(to, weight))

func face_target(target: Node3D) -> void:
	# look_at 让自己的 -Z 指向目标；第二个参数是"上"方向，不能和视线平行
	look_at(target.global_position, Vector3.UP)
	# 只想水平转身（不抬头低头）时，把目标的高度换成自己的高度
	var flat := Vector3(target.global_position.x, global_position.y, target.global_position.z)
	if not flat.is_equal_approx(global_position):
		look_at(flat, Vector3.UP)

func setup_camera(cam: Camera3D) -> void:
	cam.projection = Camera3D.PROJECTION_PERSPECTIVE
	cam.fov = 75.0                 # 垂直视野角（keep_aspect 默认是 KEEP_HEIGHT）
	cam.near = 0.05                # 近裁剪面：比它近的东西不画
	cam.far = 250.0                # 远裁剪面：near 和 far 的比值越大，深度精度越差
	# 正交相机：没有近大远小，size 是画面的高度（米），常用于等距视角和小地图
	var top_down := Camera3D.new()
	top_down.projection = Camera3D.PROJECTION_ORTHOGONAL
	top_down.size = 40.0
	# 屏幕坐标 ↔ 世界坐标：鼠标拾取、在 3D 物体头顶显示 2D 血条都要用到
	var screen_pos := cam.unproject_position(Vector3(0, 1, -5))
	var ray_dir := cam.project_ray_normal(screen_pos)
	print(screen_pos, ray_dir)
	top_down.free()

func _make_lights() -> void:
	# 太阳：DirectionalLight3D 只有方向，没有位置。旋转决定光从哪里来（光沿自身 -Z 方向照射）
	sun = DirectionalLight3D.new()
	sun.name = "Sun"
	sun.rotation_degrees = Vector3(-38, 32, 0)
	sun.light_color = Color(1.0, 0.86, 0.68)
	sun.light_energy = 1.25
	sun.shadow_enabled = shadows
	sun.shadow_blur = 1.5
	sun.shadow_bias = 0.05
	sun.shadow_normal_bias = 1.6
	sun.directional_shadow_mode = DirectionalLight3D.SHADOW_PARALLEL_2_SPLITS   # 2 级级联，比 4 级省一半绘制
	sun.directional_shadow_max_distance = 40.0     # 阴影只画到 40 米，距离越短阴影越清晰
	add_child(sun)
	# 补光：从反方向打一盏弱的冷色光，不投阴影，让背光面不至于死黑
	var fill := DirectionalLight3D.new()
	fill.name = "Fill"
	fill.rotation_degrees = Vector3(-30, -150, 0)
	fill.light_color = Color(0.55, 0.68, 1.0)
	fill.light_energy = 0.35
	fill.light_specular = 0.0
	fill.sky_mode = DirectionalLight3D.SKY_MODE_LIGHT_ONLY   # 只照亮场景，不在天空里画出第二个太阳
	add_child(fill)

## PBR 材质：albedo（底色/贴图）、metallic（金属度）、roughness（粗糙度）、normal（法线贴图）。
## 用三平面映射（triplanar）后，不管方块多大，贴图都按世界坐标平铺，不会被拉伸。
func _make_materials() -> void:
	var floor_mat := StandardMaterial3D.new()
	floor_mat.albedo_texture = load(TEX + "floor.png")
	floor_mat.roughness = 0.85
	floor_mat.uv1_triplanar = true
	floor_mat.uv1_world_triplanar = true
	floor_mat.uv1_scale = Vector3.ONE * 0.5          # 贴图一张覆盖 2m×2m
	mats.floor = floor_mat

	var wall_mat := StandardMaterial3D.new()
	wall_mat.albedo_texture = load(TEX + "wall.png")
	wall_mat.normal_enabled = true
	wall_mat.normal_texture = load(TEX + "wall_normal.png")
	wall_mat.normal_scale = 1.4
	wall_mat.roughness = 0.9
	wall_mat.uv1_triplanar = true
	wall_mat.uv1_world_triplanar = true
	wall_mat.uv1_scale = Vector3.ONE * 0.25          # 一张覆盖 4m
	mats.wall = wall_mat
	# 墙裙：同一张贴图乘上青绿色，下半截墙像刷过漆
	var paint: StandardMaterial3D = wall_mat.duplicate()
	paint.albedo_color = Color(0.36, 0.62, 0.64)
	paint.roughness = 0.7
	mats.paint = paint

	var metal := StandardMaterial3D.new()
	metal.albedo_texture = load(TEX + "metal.png")
	metal.metallic = 0.85
	metal.roughness = 0.38
	metal.uv1_triplanar = true
	metal.uv1_world_triplanar = true
	mats.metal = metal

	# 集装箱：同一张金属贴图，用 albedo_color 染成不同颜色（贴图颜色 × albedo_color）
	for tint: Array in [["teal", Color(0.35, 0.75, 0.78)], ["orange", Color(1.0, 0.55, 0.28)], ["red", Color(0.85, 0.32, 0.3)]]:
		var m: StandardMaterial3D = metal.duplicate()
		m.albedo_color = tint[1]
		m.metallic = 0.55
		m.roughness = 0.5
		mats[tint[0]] = m

	var hazard := StandardMaterial3D.new()
	hazard.albedo_texture = load(TEX + "hazard.png")
	hazard.roughness = 0.6
	hazard.uv1_triplanar = true
	hazard.uv1_world_triplanar = true
	hazard.uv1_scale = Vector3.ONE * 1.5
	mats.hazard = hazard

	var crate := StandardMaterial3D.new()
	crate.albedo_texture = load(TEX + "crate.png")
	crate.roughness = 0.8
	crate.uv1_triplanar = true                        # 物体空间三平面：每个面正好一张贴图
	crate.uv1_scale = Vector3.ONE / 1.2
	crate.uv1_offset = Vector3.ONE * 0.5
	mats.crate = crate

	var lamp := StandardMaterial3D.new()
	lamp.albedo_color = Color(1.0, 0.8, 0.5)
	lamp.emission_enabled = true                      # 自发光 + glow：灯泡周围会有一圈光晕
	lamp.emission = Color(1.0, 0.7, 0.4)
	lamp.emission_energy_multiplier = 4.0
	mats.lamp = lamp

func _make_environment() -> void:
	var sky_mat := ProceduralSkyMaterial.new()
	sky_mat.sky_top_color = Color(0.24, 0.42, 0.7)
	sky_mat.sky_horizon_color = Color(0.86, 0.76, 0.66)
	sky_mat.ground_horizon_color = Color(0.86, 0.76, 0.66)
	sky_mat.ground_bottom_color = Color(0.25, 0.23, 0.22)
	var sky := Sky.new()
	sky.sky_material = sky_mat

	env = Environment.new()
	env.background_mode = Environment.BG_SKY
	env.sky = sky
	# 环境光取自天空：朝上的面偏蓝，朝下的面偏暗，比单一颜色的环境光自然得多
	env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY
	env.ambient_light_sky_contribution = 0.5        # 一半取自天空，一半取 ambient_light_color
	env.ambient_light_color = Color(0.6, 0.52, 0.45)
	env.ambient_light_energy = 0.45
	env.reflected_light_source = Environment.REFLECTION_SOURCE_SKY
	# 色调映射：把 HDR 的亮度压到屏幕能显示的 0~1，高光不会一片死白
	env.tonemap_mode = Environment.TONE_MAPPER_ACES
	env.tonemap_exposure = 0.9
	# 雾：指数雾，远处的物体逐渐融进雾色，增加纵深感
	env.fog_enabled = fog_density > 0.0
	env.fog_mode = Environment.FOG_MODE_EXPONENTIAL
	env.fog_density = fog_density
	env.fog_light_color = Color(0.78, 0.72, 0.66)
	env.fog_sun_scatter = 0.25
	env.fog_aerial_perspective = 0.25
	env.fog_sky_affect = 0.15
	# glow：亮度超过阈值的像素向外扩散（Compatibility 下是简化版实现）
	env.glow_enabled = true
	env.glow_intensity = 0.7
	env.glow_hdr_threshold = 1.0
	var we := WorldEnvironment.new()
	we.environment = env
	add_child(we)

## 带拱门的隔墙：CSG 做布尔运算，一个方块减去一个圆柱和一个方块，就挖出了门洞。
## CSG 适合快速搭原型（白盒）。它也能自带碰撞（use_collision），但导航烘焙解析 CSG 时
## 要把网格从显卡读回来，很慢；所以这里等 CSG 算完后，把形状烘焙成一个普通的静态碰撞体。
func _build_arches() -> void:
	for s: int in [-1, 1]:
		var wall := CSGBox3D.new()
		wall.size = Vector3(0.8, 4.0, 9.0)
		wall.position = Vector3(s * 10.5, 2.0, 0)
		wall.material = mats.wall
		var door := CSGBox3D.new()
		door.operation = CSGShape3D.OPERATION_SUBTRACTION
		door.size = Vector3(2.0, 2.2, 2.8)
		door.position = Vector3(0, -0.9, 0)          # 相对墙中心：门洞底部贴地
		wall.add_child(door)
		var round_top := CSGCylinder3D.new()
		round_top.operation = CSGShape3D.OPERATION_SUBTRACTION
		round_top.radius = 1.4
		round_top.height = 2.0
		round_top.sides = 20
		round_top.rotation.z = PI / 2                # 圆柱默认沿 y 轴，转 90° 让它横穿墙体
		round_top.position = Vector3(0, 0.2, 0)
		wall.add_child(round_top)
		add_child(wall)
		_csg_walls.append(wall)


## CSG 的结果 → ConcavePolygonShape3D（三角形网格碰撞）→ 挂到一个 StaticBody3D 上。
func _csg_to_static_body(csg: CSGShape3D) -> void:
	var body := StaticBody3D.new()
	body.collision_layer = 1
	body.collision_mask = 0
	var shape := CollisionShape3D.new()
	shape.shape = csg.bake_collision_shape()
	body.add_child(shape)
	body.transform = csg.transform
	add_child(body)

## 造一个带碰撞的方块：StaticBody3D（碰撞层 1 = 世界）+ BoxShape3D + 同样大小的 BoxMesh。
func _box(pos: Vector3, size: Vector3, mat: Material, yaw := 0.0, collide := true) -> Node3D:
	var mesh := BoxMesh.new()
	mesh.size = size
	var mi := MeshInstance3D.new()
	mi.mesh = mesh
	mi.material_override = mat
	if not collide:
		mi.position = pos
		mi.rotation.y = yaw
		add_child(mi)
		return mi
	var body := StaticBody3D.new()
	body.collision_layer = 1
	body.collision_mask = 0
	var shape := CollisionShape3D.new()
	var box := BoxShape3D.new()
	box.size = size
	shape.shape = box
	body.add_child(shape)
	body.add_child(mi)
	body.position = pos
	body.rotation.y = yaw
	add_child(body)
	return body