fix(game): 崩溃修复（卸载区块实体冻结）+ 立面光照、掉落可见、打击感、水下效果、空手拳头、血条左/饥饿右

- 崩溃（index out of range）：实体所在区块卸载后失去碰撞支撑无限下坠到负坐标，光查询越界 panic——WorldView 增 ChunkLoaded，未加载区块实体冻结； chunk 光查询加越界防御（双保险） - 立面光照：mesh 每面取**邻格**光照（原版光照模型）——此前用方块自身光照（sky=0）导致悬崖/矿洞立面全黑（泥土竖向黑色根因） - 掉落可见：生成后 1 秒拾取延迟 + 图标加大到 0.45 - 打击感：攻击命中音（block.hit）+ 实体受击白闪（uTint）+ 手持挥动动画 - 水下效果：相机入水蓝色叠加（渲染.md §8 水体） - 空手显示肤色拳头（白羊毛 × 肤色 tint），持方块正常显示 - HUD 布局：血条左下、饥饿右下（经典布局）
2026-08-16 20:59:28 +08:00
parent 5da460c9a2
commit 9e2f5a6186
16 changed files with 223 additions and 36 deletions
--- a/internal/chunk/chunk.go
+++ b/internal/chunk/chunk.go
@@ -79,17 +79,38 @@ func (c *Chunk) FillAll(s block.State) {
 	}
 }

-// SkyLight 读取天空光（4-bit，0–15）。
-func (c *Chunk) SkyLight(x, y, z int) uint8 { return nibble(c.sky, Index(x, y, z)) }
+// SkyLight 读取天空光（4-bit，0–15；越界返回 0——实体在未加载区块
+// 下落时查询负数坐标不应崩溃，区块管理.md §6 防御）。
+func (c *Chunk) SkyLight(x, y, z int) uint8 {
+	if x < 0 || x >= SizeX || y < 0 || y >= Height || z < 0 || z >= SizeZ {
+		return 0
+	}
+	return nibble(c.sky, Index(x, y, z))
+}

-// SetSkyLight 写入天空光。
-func (c *Chunk) SetSkyLight(x, y, z int, v uint8) { setNibble(c.sky, Index(x, y, z), v) }
+// SetSkyLight 写入天空光（越界忽略）。
+func (c *Chunk) SetSkyLight(x, y, z int, v uint8) {
+	if x < 0 || x >= SizeX || y < 0 || y >= Height || z < 0 || z >= SizeZ {
+		return
+	}
+	setNibble(c.sky, Index(x, y, z), v)
+}

-// BlockLight 读取方块光（4-bit，0–15）。
-func (c *Chunk) BlockLight(x, y, z int) uint8 { return nibble(c.blockLt, Index(x, y, z)) }
+// BlockLight 读取方块光（4-bit，0–15；越界返回 0）。
+func (c *Chunk) BlockLight(x, y, z int) uint8 {
+	if x < 0 || x >= SizeX || y < 0 || y >= Height || z < 0 || z >= SizeZ {
+		return 0
+	}
+	return nibble(c.blockLt, Index(x, y, z))
+}

-// SetBlockLight 写入方块光。
-func (c *Chunk) SetBlockLight(x, y, z int, v uint8) { setNibble(c.blockLt, Index(x, y, z), v) }
+// SetBlockLight 写入方块光（越界忽略）。
+func (c *Chunk) SetBlockLight(x, y, z int, v uint8) {
+	if x < 0 || x >= SizeX || y < 0 || y >= Height || z < 0 || z >= SizeZ {
+		return
+	}
+	setNibble(c.blockLt, Index(x, y, z), v)
+}

 // nibble 读取半字节（偶数索引 → 低 4 位，奇数索引 → 高 4 位）。
 func nibble(arr []uint8, idx int) uint8 {
--- a/internal/entity/drops.go
+++ b/internal/entity/drops.go
@@ -3,6 +3,7 @@ package entity

 import (
 	"math"
+	"time"
 )

 // 掉落物参数（实体系统.md §5）。
@@ -13,10 +14,14 @@ const (
 	dropPerChunk   = 32  // 每区块掉落物上限
 )

+// dropPickupDelay 生成后可拾取延迟（测试可置 0）。
+var dropPickupDelay = time.Second
+
 // Drop 掉落物实体数据。
 type Drop struct {
 	Item  string
 	Count int
+	Born  time.Time // 生成时刻（1 秒内不可拾取，掉落可见期）
 }

 // SpawnDrop 生成掉落物：同物品近距合并（上限 dropStackMax）；超上限丢弃。
@@ -48,7 +53,7 @@ func (m *Manager) SpawnDrop(itemName string, count int, x, y, z float64) {
 	}
 	m.next++
 	e := &Entity{ID: m.next, Kind: KindItemDrop, Pos: [3]float64{x, y, z}, Health: 1,
-		Data: &Drop{Item: itemName, Count: count}}
+		Data: &Drop{Item: itemName, Count: count, Born: time.Now()}}
 	e.Vel = [3]float64{(rand01(e.ID) - 0.5) * 2, 4, (rand01(e.ID>>16) - 0.5) * 2} // 弹出初速度
 	m.entities[e.ID] = e
 	m.drops[itemName] = e
@@ -62,6 +67,7 @@ func rand01(seed ID) float64 {
 }

 // PickupNearby 拾取玩家附近掉落物，返回拾取的物品列表（实体系统.md §5 拾取）。
+// 生成后 1 秒内不可拾取（掉落可见期，与原版一致）。
 func (m *Manager) PickupNearby(px, py, pz float64) []Drop {
 	var out []Drop
 	for _, e := range m.List() {
@@ -72,6 +78,9 @@ func (m *Manager) PickupNearby(px, py, pz float64) []Drop {
 		if !ok {
 			continue
 		}
+		if time.Since(d.Born) < dropPickupDelay {
+			continue // 新鲜掉落：可拾取延迟（掉落可见）
+		}
 		dx, dy, dz := e.Pos[0]-px, e.Pos[1]-py, e.Pos[2]-pz
 		if dx*dx+dy*dy+dz*dz < dropPickupDist*dropPickupDist {
 			e.Dead = true
--- a/internal/entity/entity.go
+++ b/internal/entity/entity.go
@@ -33,6 +33,9 @@ type WorldView interface {
 	Block(x, y, z int32) block.State
 	SkyLight(x, y, z int32) uint8
 	BlockLight(x, y, z int32) uint8
+	// ChunkLoaded 实体所在区块是否已加载（卸载区块冻结实体——
+	// 否则实体失去碰撞支撑会无限下坠到负数坐标，见 实体系统.md §2）
+	ChunkLoaded(x, z int32) bool
 }

 // Entity 实体。
@@ -45,6 +48,9 @@ type Entity struct {
 	Health float64
 	Dead   bool

+	// HitFlash 受击白闪剩余秒数（客户端渲染用，打击反馈）
+	HitFlash float64
+
 	// AI 状态（实体系统.md §3 状态机）
 	state      uint8
 	decisionIn float64 // 下次决策倒计时（限频）
@@ -116,12 +122,19 @@ func (m *Manager) List() []*Entity {
 	return out
 }

-// Tick 每 tick 更新全部实体（激活区块内；冻结区由调用方过滤）。
+// Tick 每 tick 更新全部实体（激活区块内；冻结区跳过，实体系统.md §2
+// ——未加载区块无碰撞支撑，实体继续 tick 会无限下坠并越界崩溃）。
 func (m *Manager) Tick(dt float64, w WorldView, playerPos [3]float64) {
 	for _, e := range m.List() {
 		if e.Dead {
 			continue
 		}
+		if !w.ChunkLoaded(int32(e.Pos[0]), int32(e.Pos[2])) {
+			continue // 区块卸载：冻结
+		}
+		if e.HitFlash > 0 {
+			e.HitFlash -= dt // 受击白闪衰减
+		}
 		switch e.Kind {
 		case KindZombie:
 			e.tickZombie(dt, w, playerPos)
--- a/internal/entity/entity_test.go
+++ b/internal/entity/entity_test.go
@@ -17,6 +17,7 @@ func (flatWorld) Solid(x, y, z int32) bool        { return y < 63 }
 func (flatWorld) Block(x, y, z int32) block.State { return block.Air }
 func (flatWorld) SkyLight(x, y, z int32) uint8    { return 15 }
 func (flatWorld) BlockLight(x, y, z int32) uint8  { return 0 }
+func (flatWorld) ChunkLoaded(x, z int32) bool     { return true }

 // TestZombieChase 僵尸追玩家（僵尸与敌对生物.md §2）。
 func TestZombieChase(t *testing.T) {
@@ -64,6 +65,8 @@ func TestAnimalWander(t *testing.T) {

 // TestDropMerge 掉落物合并（实体系统.md §5）。
 func TestDropMerge(t *testing.T) {
+	dropPickupDelay = 0 // 测试跳过拾取延迟
+	defer func() { dropPickupDelay = time.Second }()
 	m := NewManager()
 	m.SpawnDrop("cobblestone", 5, 0.5, 64, 0.5)
 	m.SpawnDrop("cobblestone", 5, 0.6, 64, 0.5) // 距离 <1 → 合并
--- a/internal/game/game.go
+++ b/internal/game/game.go
@@ -125,6 +125,9 @@ func (s *Session) BeginBreak() {
 	s.breakTarget = h
 	s.breaking = true
 	s.breakProg = 0
+	if s.Sound != nil {
+		s.Sound("block.hit", float64(h.X)+0.5, float64(h.Y)+0.5, float64(h.Z)+0.5)
+	}
 	if s.Creative {
 		s.BreakNow()
 	}
@@ -190,6 +193,7 @@ func (s *Session) Attack() bool {
 		return false
 	}
 	e.Health -= 2
+	e.HitFlash = 0.15 // 受击白闪（打击反馈，客户端渲染）
 	// 击退（沿视线水平方向）
 	f := s.Cam.Forward()
 	e.Vel[0] += f[0] * 4
--- a/internal/game/game_test.go
+++ b/internal/game/game_test.go
@@ -331,6 +331,11 @@ func TestBlockDropVanilla(t *testing.T) {
 	for s.breaking {
 		s.Tick(1.0 / 20)
 	}
+	// 掉落有 1 秒真实时间拾取延迟（Born 为墙钟时间）：等待后 tick 触发拾取
+	time.Sleep(1100 * time.Millisecond)
+	for i := 0; i < 2; i++ {
+		s.Tick(1.0 / 20)
+	}
 	after := 0
 	for _, st := range s.Inv.Slots {
 		if st.Name == "dirt" {
--- a/internal/mesh/mesh.go
+++ b/internal/mesh/mesh.go
@@ -48,13 +48,18 @@ type ChunkMesh struct {
 // Neighbor 邻居方块查询（跨区块面剔除用，区块管理.md §6）。
 type Neighbor func(x, y, z int32) block.State

+// Light 邻居光照查询（面光照用：每个面取**邻格**的光照等级——
+// 方块自身 sky=0，用自身光照会让所有立面全黑（悬崖/矿洞立面黑色根因）。
+type Light func(x, y, z int32) (sky, blk uint8)
+
 // UVFunc 纹理键 → 图集 UV（归一化坐标，含 inset）。
 type UVFunc func(texKey string) (u0, v0, u1, v1 float32, ok bool)

 // Builder 网格构建器。
 type Builder struct {
-	reg *block.Registry
-	uv  UVFunc
+	reg   *block.Registry
+	uv    UVFunc
+	light Light // 面光照查询（邻格光照；nil 回退自身光照）
 }

 // NewBuilder 创建构建器。
@@ -62,6 +67,9 @@ func NewBuilder(reg *block.Registry, uv UVFunc) *Builder {
 	return &Builder{reg: reg, uv: uv}
 }

+// SetLight 设置面光照查询（每个面取邻格光照，光照.md 顶点光照）。
+func (b *Builder) SetLight(fn Light) { b.light = fn }
+
 // face 一个面的 4 个角偏移与朝向。
 type faceDef struct {
 	dir     [3]int32
@@ -114,7 +122,6 @@ func (b *Builder) Build(c *chunk.Chunk, nb Neighbor) *ChunkMesh {
 				wx := int32(x) + c.CX*16
 				wy := int32(y)
 				wz := int32(z) + c.CZ*16
-				sky, blk := c.SkyLight(x, y, z), c.BlockLight(x, y, z)

 				for fi, f := range faces {
 					nx := wx + f.dir[0]
@@ -129,6 +136,14 @@ func (b *Builder) Build(c *chunk.Chunk, nb Neighbor) *ChunkMesh {
 						b.reg.IsTranslucent(neighbor) == b.reg.IsTranslucent(s) && b.reg.IsTranslucent(s) {
 						continue
 					}
+					// 面光照：取**邻格**的光照（原版光照模型）——方块自身 sky=0，
+					// 用自身光照会让悬崖/矿洞立面全黑
+					sky, blk := uint8(0), uint8(0)
+					if b.light != nil {
+						sky, blk = b.light(nx, ny, nz)
+					} else {
+						sky, blk = c.SkyLight(x, y, z), c.BlockLight(x, y, z)
+					}
 					texKey := b.reg.Texture(s, faceTexture[fi])
 					u0, v0, u1, v1, ok := b.uv(texKey)
 					if !ok {
--- a/internal/render/entity_gl.go
+++ b/internal/render/entity_gl.go
@@ -71,7 +71,8 @@ func (r *Renderer) ensureBillQuad() {
 }

 // DrawBillboard 在 (x,y,z)（脚底）绘制 h 高 × w 宽的实体广告牌，贴图 uv。
-func (r *Renderer) DrawBillboard(x, y, z float32, h, w float32, uv [4]float32) {
+// flash=true 时整体白闪（受击反馈，打击感）。
+func (r *Renderer) DrawBillboard(x, y, z float32, h, w float32, uv [4]float32, flash bool) {
 	if r.entityTex == 0 {
 		return
 	}
@@ -88,6 +89,12 @@ func (r *Renderer) DrawBillboard(x, y, z float32, h, w float32, uv [4]float32) {
 	gl.Uniform3f(offLoc, x, y, z)
 	cutLoc := gl.GetUniformLocation(r.prog, gl.Str("uCutout\x00"))
 	gl.Uniform1f(cutLoc, 0)
+	tintLoc := gl.GetUniformLocation(r.prog, gl.Str("uTint\x00"))
+	if flash {
+		gl.Uniform4f(tintLoc, 2.5, 2.5, 2.5, 1) // 受击白闪
+	} else {
+		gl.Uniform4f(tintLoc, 1, 1, 1, 1)
+	}
 	// 相机基向量（视图矩阵列 0/1 即世界系下的 right/up）
 	rightLoc := gl.GetUniformLocation(r.prog, gl.Str("uCamRight\x00"))
 	upLoc := gl.GetUniformLocation(r.prog, gl.Str("uCamUp\x00"))
--- a/internal/render/mesh_gl.go
+++ b/internal/render/mesh_gl.go
@@ -110,6 +110,8 @@ func (r *Renderer) DrawChunks(get func(i int) (int32, int32), n int) {
 	uvMaxLoc := gl.GetUniformLocation(r.prog, gl.Str("uUVMax\x00"))
 	gl.Uniform2f(uvMinLoc, 0, 0) // 区块顶点 UV 直接使用
 	gl.Uniform2f(uvMaxLoc, 1, 1)
+	tintLoc := gl.GetUniformLocation(r.prog, gl.Str("uTint\x00"))
+	gl.Uniform4f(tintLoc, 1, 1, 1, 1) // 区块无颜色乘数

 	// pass 1+2：不透明与 cutout（alpha test，不排序）
 	gl.Uniform1f(cutLoc, 0)
--- a/internal/render/overlay_gl.go
+++ b/internal/render/overlay_gl.go
@@ -150,6 +150,8 @@ func (r *Renderer) DrawCrackOverlay(x, y, z float32, stage int) {
 	uvMaxLoc := gl.GetUniformLocation(r.prog, gl.Str("uUVMax\x00"))
 	gl.Uniform2f(uvMinLoc, 0, 0)
 	gl.Uniform2f(uvMaxLoc, 1, 1)
+	tintLoc := gl.GetUniformLocation(r.prog, gl.Str("uTint\x00"))
+	gl.Uniform4f(tintLoc, 1, 1, 1, 1)

 	gl.Enable(gl.POLYGON_OFFSET_FILL)
 	gl.PolygonOffset(-1, -1)
@@ -206,8 +208,8 @@ func (r *Renderer) ClearHand() {
 	}
 }

-// DrawHand 绘制手持方块（顶点已是视图空间，仅乘投影矩阵）。
-func (r *Renderer) DrawHand() {
+// DrawHand 绘制手持方块（顶点已是视图空间，仅乘投影矩阵；tint 肤色乘数）。
+func (r *Renderer) DrawHand(tint [3]float32) {
 	if r.handVao == 0 {
 		return
 	}
@@ -226,6 +228,8 @@ func (r *Renderer) DrawHand() {
 	uvMaxLoc := gl.GetUniformLocation(r.prog, gl.Str("uUVMax\x00"))
 	gl.Uniform2f(uvMinLoc, 0, 0)
 	gl.Uniform2f(uvMaxLoc, 1, 1)
+	tintLoc := gl.GetUniformLocation(r.prog, gl.Str("uTint\x00"))
+	gl.Uniform4f(tintLoc, tint[0], tint[1], tint[2], 1)
 	gl.BindVertexArray(r.handVao)
 	gl.DrawElements(gl.TRIANGLES, 36, gl.UNSIGNED_INT, gl.PtrOffset(0))
 	gl.BindVertexArray(0)
--- a/internal/render/renderer.go
+++ b/internal/render/renderer.go
@@ -250,12 +250,14 @@ void main() {
 `

 // chunkFragSrc 默认方块片元着色器：cutout 剔除 + 光照亮度混合。
+// uTint 颜色乘数（实体受击白闪/手持肤色，默认 1,1,1,1）。
 const chunkFragSrc = `
 #version 330 core
 in vec2 vUV;
 in vec2 vLight;
 uniform sampler2D uTex;
 uniform float uCutout;   // 1=alpha test（树叶/玻璃），0=普通/半透明
+uniform vec4 uTint;
 out vec4 fragColor;
 void main() {
    vec4 c = texture(uTex, vUV);
@@ -263,6 +265,6 @@ void main() {
    float sky = vLight.x / 15.0;
    float blk = vLight.y / 15.0;
    float b = max(sky, blk * 0.9 + 0.06);
-    fragColor = vec4(c.rgb * b, c.a);
+    fragColor = vec4(c.rgb * b * uTint.rgb, c.a);
 }
 `
--- a/internal/ui/hud.go
+++ b/internal/ui/hud.go
@@ -40,6 +40,9 @@ type HUD struct {
 	// 小地图（左上角，UI还原.md §3.5）
 	minimapTex uint32

+	// 水下渲染（渲染.md §8 水体效果：蓝色叠加）
+	underwater bool
+
 	// 逻辑分辨率与缩放（UI还原.md §3.1：427×240 基准 × 整数缩放）
 	baseW, baseH float32
 	scale        float32
@@ -82,11 +85,19 @@ func (h *HUD) SetTarget(tex uint32, w, hgt float32) {
 // SetMinimap 设置小地图纹理（渲染线程注入；tex=0 清除）。
 func (h *HUD) SetMinimap(tex uint32) { h.minimapTex = tex }

+// SetUnderwater 设置水下状态（蓝色叠加与雾效）。
+func (h *HUD) SetUnderwater(b bool) { h.underwater = b }
+
 // Draw 每帧绘制 HUD（调用方已 Begin）。
 func (h *HUD) Draw(r *Renderer) {
 	w, hgt := float32(r.w), float32(r.h)
 	s := h.scale

+	// 水下效果：蓝色叠加（渲染.md §8 水体）
+	if h.underwater {
+		r.DrawRect(0, 0, w, hgt, [4]float32{0.05, 0.2, 0.45, 0.42})
+	}
+
 	// 准星（原版 crosshair.png 15×15，UI还原.md §3.4）
 	cx, cy := w/2, hgt/2
 	if h.haveSprites {
@@ -147,11 +158,12 @@ func (h *HUD) Draw(r *Renderer) {
 		}
 	}

-	// 饥饿：10 鸡腿（原版 food_full，生命行下方）
+	// 饥饿：10 鸡腿（原版 food_full，屏幕**右下**——血条左、饥饿右的经典布局）
 	food := 20 // 饥饿值（饥饿系统后置，恒定 20）
 	fy := hgt - 39*s
+	fx := w/2 + 11*s // 与左侧生命行镜像对称（w/2+11 .. w/2+91）
 	for i := 0; i < 10; i++ {
-		x := hx + float32(i)*8*s
+		x := fx + float32(i)*8*s
 		switch {
 		case food >= (i+1)*2:
 			if h.haveSprites {
--- a/internal/world/world.go
+++ b/internal/world/world.go
@@ -204,6 +204,39 @@ func (w *World) BlockUnlocked(x, y, z int32) block.State {
 // VillageAt 返回 (x,z) 附近的村庄中心（村民生成定位，村民系统.md §2）。
 func (w *World) VillageAt(x, z int32) ([2]int32, bool) { return w.gen.VillageAt(x, z) }

+// ChunkLoaded 区块是否已加载（entity.WorldView 接口：卸载区块冻结实体）。
+func (w *World) ChunkLoaded(x, z int32) bool {
+	w.mu.RLock()
+	_, ok := w.chunks[coordKey(coord.ChunkCoord(x), coord.ChunkCoord(z))]
+	w.mu.RUnlock()
+	return ok
+}
+
+// SkyLightUnlocked 无锁读天空光（仅在 WithReadLock 回调内调用，mesh 构建面光照用；
+// 未加载区块返回 15——面朝向未加载区时按天空亮度处理）。
+func (w *World) SkyLightUnlocked(x, y, z int32) uint8 {
+	if y < 0 || y >= chunk.Height {
+		return 15
+	}
+	ch := w.chunks[coordKey(coord.ChunkCoord(x), coord.ChunkCoord(z))]
+	if ch == nil {
+		return 15
+	}
+	return ch.SkyLight(int(coord.LocalCoord(x)), int(y), int(coord.LocalCoord(z)))
+}
+
+// BlockLightUnlocked 无锁读方块光（仅在 WithReadLock 回调内调用；未加载返回 0）。
+func (w *World) BlockLightUnlocked(x, y, z int32) uint8 {
+	if y < 0 || y >= chunk.Height {
+		return 0
+	}
+	ch := w.chunks[coordKey(coord.ChunkCoord(x), coord.ChunkCoord(z))]
+	if ch == nil {
+		return 0
+	}
+	return ch.BlockLight(int(coord.LocalCoord(x)), int(y), int(coord.LocalCoord(z)))
+}
+
 // SetBlock 世界级写方块（含火把光源联动，方块交互与动画.md §9）：
 // 放置光源 → 初始化亮度 + BFS；移除光源 → relight 重算。
 func (w *World) SetBlock(x, y, z int32, s block.State) {