Merge branch 'master' of https://git.yvmou.cn/yvmoux/agame

.gitignore

@@ -1,3 +1,5 @@
 # Godot 4+ specific ignores
 .godot/
 /android/
+addons/limboai/bin/~liblimboai.windows.editor.x86_64.dll
+addons/godotsteam/win64/~libgodotsteam.windows.template_debug.x86_64.dll

.workbuddy-ai/memory/2026-10-03.md

@@ -0,0 +1,133 @@
+# 2026-10-03
+
+## 修「表情糊到肚子上」：脸部矩形越界 + 加护栏
+
+用户先发了一张截图问「这是为什么」（本会话 Read 工具读不了图片文件，只能靠像素统计猜），随后说「继续」。
+直接跑 `test_run` 就复现了问题：
+
+```
+表情矩形左下角 (0.695, 0.482) 跑出了头部 UV 孤岛 [P: (0.694607, 0.681596), S: (0.301457, 0.314468)]
+（中心 (0.8455, 0.639) 大小 (0.301, 0.314)）
+```
+
+用户在 shader 里把 `face_center.y` 从 0.839 调到了 **0.639**（想「往下挪」），矩形下边落到 0.482，
+而头部孤岛底边是 0.6816 —— **矩形伸进了正下方那段孤岛（u 0.695~0.935 / v 0.293~0.674，胸腹）**，
+所以表情同时糊到了肚子上。这就是截图里那个现象。
+
+修法（`face_paint.gdshader`）：
+- 顶部新增两个常量 `FACE_UV_BOUNDS_MIN = vec2(0.6946, 0.6816)` / `FACE_UV_BOUNDS_MAX = vec2(0.9961, 0.9961)`
+  —— 就是头部孤岛的实测范围，当护栏用。
+- `fragment()` 里 `clamp(face_center, FACE_UV_BOUNDS_MIN + half_size, FACE_UV_BOUNDS_MAX - half_size)`，
+  **怎么调都夹在头部里，不可能再溢到肚子/背上**。`min/max` 包一层是为了 size 大于孤岛时不出现 lo>hi。
+- 默认值改成 `face_center = (0.8455, 0.7816)`、`face_size = (0.301, 0.20)`：
+  孤岛高 0.3145，整高时根本没法往下挪（可移动范围 = 孤岛 − 大小），收到 0.20 后中心才能落到 0.7816，
+  表情落在头部下半段，符合用户「往下移」的诉求。
+
+测试：`test_face_rect_inside_head_island` 换成 `test_face_uv_bounds_match_head_island` ——
+校验护栏常量等于实测头部孤岛（模型改 UV 会红），并校验 `face_size` 不大于孤岛（否则夹取退化）。
+`_shader_vec2()` 的匹配前缀从 `uniform vec2 X = vec2(` 放宽成 `X = vec2(`，这样 const 也能解析。
+另加一条断言：shader 里必须出现 `clamp(face_center`。
+
+验证：`test_run` **32/32**；实机跑角色选择页无 shader/脚本报错，自己截了两帧确认表情只在头部、肚子上是干净的。
+
+## 顺带发现：我能看游戏截图
+
+`Read` 工具读用户发的图片会直接报 `Current model does not support reading images`，
+但 `editor_screenshot(source="game")` 返回的画面我能正常看。以后排查画面问题可以直接自己截图对照，
+不必让用户描述。
+
+## 再往下挪一点：只能靠压高度
+
+用户要求「往下移一点」。中心 0.7816 已经等于孤岛下边界 + 半个高度，直接减小 center.y 会被 clamp 吃掉（等于没反应），
+所以改成 **`face_size.y` 0.20 → 0.17、`face_center.y` → 0.7666**（0.7666 − 0.085 = 0.6816，仍然贴着下边界）。
+自己前后各截一帧对比，表情确实整体下移了一点，代价是纵向压扁 15%。
+
+记下这条边界：**头部孤岛下边界 0.6816 就是脸能到的最低处**，再往下就是胸腹孤岛，没有余量；
+要「整张脸整体下移且不变形」只能回 Blender 把头部 UV 往下扩。
+`test_run` 32/32。
+
+## 换成「贴花」：脸终于能放到身体正中间
+
+用户接着发图说「还需要往下移，脸部应该位于中间位置」。UV 方案已经到极限（再往下就是胸腹孤岛），
+所以直接把定位方式换成**贴花**：`face_paint.gdshader` 里加 `varying vec3 object_position / object_normal`，
+`vertex()` 里取 `VERTEX` / `NORMAL`，`fragment()` 用 `object_position.xy` 定位矩形，再用
+`-normalize(object_normal).z` 筛掉背面。uniform 变成 `face_center` / `face_size`（模型本地坐标）、
+`face_front_edge`、`face_flip_y`；`FACE_UV_BOUNDS_*` 那对护栏常量和 clamp 都删掉了（不再需要）。
+好处：**和 UV 孤岛布局彻底解耦**，以后 Blender 重排 UV 也不会再把脸画歪。
+
+踩到的坑：第一版把正面判成 `+normal.z`，结果表情画到了**背上**。
+`character_select.tscn` 的 `Model` 节点和 `player.tscn` 的 `mouse` 节点都把模型转了 180°，
+**模型自己的正面是本地 -Z**。测试里钉了 `-normalize(object_normal).z` 防止再写反。
+
+调参过程（用截图迭代）：
+- 为了看正面，临时把 `character_select.gd` 的 `SPIN_SPEED` 改成 0（模型初始朝正面），**调完已还原成 0.5**。
+- 内置表情在 tile 里的墨线只占 ~70%（face_01 68.9%×74.4%、face_02 83.9%×65.4%，且居中），
+  所以 `face_size` 要按这个比例估：4.0 的矩形 → 约 2.8 单位的墨线宽度，正好对上用户截图里脸占身体 ~55% 的感觉。
+- 最终 `face_center = (0.0, 0.0)`、`face_size = (4.0, 4.0)`：实测脸落在身体正中间，模型原点就是蛋形身体的中轴。
+- 测试 `test_face_rect_inside_head_island` / `test_face_uv_bounds_match_head_island` 删掉，
+  换成 `test_face_decal_inside_body_bounds`（矩形必须落在模型包围盒内）。
+
+验证：`test_run` **32/32**；主菜单 →「开始游戏」→ 角色选择实机截图确认 预设表情1 落在身体正中间。
+
+## 坑：用户开着 Godot 编辑器时，磁盘上的 shader 会被编辑器缓冲区覆盖回去
+
+调完贴花后回头一看，`face_paint.gdshader` 变成了「我的新注释 + 旧的 `+normal.z` 代码 + `face_center.y = 0.6`」的混合体：
+我改的 `-normalize(object_normal).z` 和 `face_center.y = 0.0` 被冲掉了，而 `0.6` 这个值我从没写过。
+判断是**用户在编辑器里开着这个 shader**（缓冲区还是我第一版的内容），他改了参数并保存，把我后来的改动覆盖了。
+
+处理：用整份 `Write` 重新写回验证过的版本（`face_center = (0.0, 0.0)`、`-normalize(object_normal).z`、
+并把顶部那句「法线朝 +Z」的旧注释一并改对，避免注释和代码互相矛盾），再跑 `test_run` 32/32。
+
+**教训**：改 `.gdshader` / `.tscn` 这类编辑器可能正开着的文件之后，最好提醒用户先关掉或重开那个文件再保存；
+否则他那边一保存就会把磁盘上的新版本覆盖掉，而且不会有任何提示。
+
+## 实现：抱起物品系统（第 1 步，单机跑通）
+
+用户要求：左键抱起、长按 Q 扔出、抱起后胳膊伸出去抱住且走路会晃、胳膊可延伸、只有特定物品能抱并给个示例。
+
+新增/改动：
+- `world/items/carryable.gd`（`class_name Carryable extends RigidBody3D`，**标了 @tool**）：
+  门槛在物品自己身上 —— 进 `carryable` 组才算「可抱」。参数：`hold_offset` / `hold_rotation_deg` /
+  `freeze_while_carried` / `throw_speed_min` / `throw_speed_max`。
+  `begin_carry()` 冻结物理并**把 collision_layer 清 0**（不清会把抱着它的人顶飞）；`end_carry(v)` 恢复并给初速度；
+  `apply_hold_transform(socket)` 由持有者每帧调用，偏移/朝向由物品自己决定。
+- `world/items/carryable_box.tscn`：示例物品（0.6³ 橙箱子，RigidBody3D + Mesh + Collision + 脚本）。
+- `character/player/carry_arms.gd`（`class_name CarryArms extends Node`，也标了 @tool）：
+  抱持姿势 + 走路晃动的表现层。**动画之后叠加**（`process_priority = 100`），只动 arm_l_*/arm_r_* 六根骨骼，
+  晃动同时作用在骨骼和抱持点上，所以人和东西一起晃。
+- `player.gd`：`_find_carryable / _pick_up / _release_throw` 三个小函数；交互提示与判定同源（优先级：手上有东西 > 可抱物 > 缆上 > 可挂的缆）；抱东西时禁疾跑 + `carry_speed_scale` 降速；抱着时不给挂滑索。
+- `player.tscn`：新增 `CameraRig/CarrySocket`(Marker3D，本地 (0,-0.8,-1.0)) 和 `Body/CarryArms`。
+- `world/main.tscn`：放两个示例箱子。
+- 输入动作：`carry` = 鼠标左键、`throw_carry` = Q（`input_map_manage ensure_binding`，直接落 project.godot）。
+- `tests/test_carry.gd`：7 条（动作存在、玩家场景节点、示例物品可抱、抱起/放下冻结与恢复、贴到抱持点、投掷速度随蓄力、抱持姿势真的伸到身前）。
+
+踩到的坑：
+- **`CarryArms` 的 NodePath 少了一级**：默认写成 `mouse/MouseRig/Skeleton3D`，但节点挂在 `Body` 下，
+  应该是 `../mouse/MouseRig/Skeleton3D`；抱持点同理要 `../../CameraRig/CarrySocket`。
+  解析不到只会 push_warning，姿势完全不生效、画面看不出原因。
+- **骨骼本地轴不能猜**：一开始按骨骼本地欧拉角写，结果手是往**上后方**摆的。
+  改成「世界方向语义」——参数按世界方向理解，内部用 `rest_basis.inverse() * world * rest_basis`
+  换算到骨骼本地空间，再乘到动画姿态上。这样换模型也不会错。
+- 参数是扫出来的（临时探针一次跑 24 组 swing/tuck/roll，打印 `arm_l_03` 的全局位置）：
+  最终 `shoulder_swing_deg = 40 / tuck = 50 / roll = 0 / elbow = 15 / stretch = 1.25`
+  → 手落在模型本地 (±1.17, 0.08, 0.95)，即身前中部。
+- **非 @tool 脚本在编辑器里是 placeholder**，测试里方法调不动、`_ready` 也不跑（组也加不上）。
+  `carryable.gd` / `carry_arms.gd` 都标了 `@tool` 才跑得通；改完脚本要 `filesystem_manage(op="scan")`
+  才会重新解析（不 scan 的话测试还按旧代码跑）。
+- 顺手纠正：脸部贴花的正面是模型**本地 +Z**（尾巴在 -Z），我之前写成 `-normalize(object_normal).z` 是错的，
+  已改回 `+`，`tests/test_face.gd` 的断言也跟着反过来。
+
+验证：`test_run` **39/39**；实机跑通完整链路 —— 提示「左键 抱起」→ 左键抱起（箱子出现在身前）→
+长按 Q（提示「长按 Q 扔出 100%」）→ 松手箱子飞出去落地。
+
+**未做**：联机同步（第 2 步）。现在物品位置只有持有者本地在写，远端玩家看不到箱子被抱走 —— 需要给物品加
+`MultiplayerSynchronizer` + 跟随持有者的 authority 切换 + 抢占仲裁。
+
+## 给「抱起物品系统」出了方案（未动代码）
+
+用户要新功能：玩家抱起物品，先要方案。我在对话里给了设计，没有写文件。
+要点：`Carryable` 组件挂在物品上（组 `carryable`，照抄 Zipline 的「参数放组件、玩家只读」套路）；
+玩家侧只加 `_find_carryable/_pick_up/_drop` 三个小函数 + `CameraRig/CarrySocket` 标记点；
+交互优先级和提示文案共用一处 `_resolve_interaction()`（滑索踩过「提示亮着但按 E 没反应」的坑）；
+抱持**不 reparent**，改成 `carried_by` 状态 + 持有者每帧摆到 socket，authority 随持有者切换；
+分三步：单机跑通 → 联机仲裁/同步 → 持物动画与扔出。等用户拍板几个点（E 是否复用、要不要真物理/扔、模型有没有持物动画）。

.workbuddy-ai/memory/MEMORY.md

@@ -52,22 +52,50 @@
 
 - `face_paint.gdshader`：将 face surface 的 UV remap 到 0~1，再映射到内置图集 rect 或本地 PNG；贴图 alpha 只代表墨线覆盖率，混到 `skin_color` 上，**不写空间 `ALPHA`**（否则脸片变洞）。
 - `mouse_mouse_lambert1_BaseColor.png` 和 `mouse_表情测试.png` 的背景都精确为 RGB(137,179,255) / `#89B3FF`；表情图源 alpha 全 255，不能直接当透明度。
-- **最终做法：全身一个 shader，脸部靠 UV 矩形圈出来**。`face_paint.gdshader` 用 `body_tex`（= `mat_body` 的 BaseColor）采样全身底色，再在 `face_uv_min` / `face_uv_size` 圈出的矩形里，把表情贴图（内置图集或本地 PNG）和玩家手绘按 alpha 叠上去。透明处保持身体底色，所以**脸和周围不可能是两块不同的皮肤**。`FaceRig` 把 mat_body 的 `albedo_texture` / `albedo_color` / `roughness` / `metallic` 抄进 shader，并用 `set_surface_override_material(0, mat)`（surface 0，不再是 1）。
+- **最终做法：全身一个 shader，脸是「贴在身体正面的贴花」**。`face_paint.gdshader` 用 `body_tex`（= `mat_body` 的 BaseColor）采样全身底色，再在 `face_center` / `face_size` 圈出的矩形里，把表情贴图（内置图集或本地 PNG）和玩家手绘按 alpha 叠上去。透明处保持身体底色，所以**脸和周围不可能是两块不同的皮肤**。`FaceRig` 把 mat_body 的 `albedo_texture` / `albedo_color` / `roughness` / `metallic` 抄进 shader，并用 `set_surface_override_material(0, mat)`（surface 0，不再是 1）。
+- **贴花用模型本地坐标，不用 UV**：`varying vec3 object_position` / `object_normal` 在 `vertex()` 里取 `VERTEX` / `NORMAL`，`fragment()` 里用 `object_position.xy` 定位。**这样和 UV 孤岛怎么排无关** —— 之前用 UV 矩形时，矩形一越界就会把表情糊到肚子/背上（头部孤岛和胸腹孤岛只差 0.008），换贴花后这类问题从根上没了。
+- **模型自己的正面是本地 -Z**：`character_select.tscn` 的 `Model` 节点和 `player.tscn` 的 `mouse` 节点都把它转了 180°。所以正面遮罩写 `-normalize(object_normal).z`，**写反了表情会跑到背上**（踩过）。背面同 (x,y) 的点也会落进矩形，所以这个遮罩是必须的。
 - 不再需要 `skin_color` 当 shader 输入：`FaceRig` 反过来从身体贴图左上角取色写进 `skin_color`，只给画布和缩略图垫底用（导入贴图是压缩的，`get_pixel` 前要先 `decompress()`，否则报 "Can't get_pixel() on compressed image"）。
 - 表情遮罩用 `step()` 相乘而不是 `if`：采样留在统一控制流里，免得 mipmap 导数在分支里未定义。
 - **仍然不能写空间 `ALPHA`**：alpha 只代表墨线覆盖率，写进 ALPHA 会让面片变洞。
 - `face_atlas_transparent.png` 是我们自己的素材（从已删除的 `mouse_表情测试.png` 去蓝底、反混合出来的 1024² 副本），保留原图坐标排布；内置 ID `builtin:face_01/02` 对应各自的图集 rect。**原始表情图已随模型删除，这个副本现在是唯一来源，别删。**
-- **表情位置/大小/翻转只写在 `face_paint.gdshader` 顶部那段「调表情就改这一段」里**：`face_center`（中心，UV 单位，**往下挪就减小 .y**）、`face_size`（.x 宽 .y 高）、`face_flip_y`（默认 true）。
-  **FaceRig 故意不传这三个 uniform** —— 早期版本从 `@export` 传过去，会把 shader 里调好的值盖掉；现在 `face_rig.gd` 里没有对应的 export，测试里有一条断言禁止再传。
-- 头部孤岛实测：u 0.695~0.996（左右）、v 0.682~0.996（上下，**v 越大越靠头顶**）。贴图第 0 行在上边，所以默认必须 `face_flip_y = true`，否则表情上下颠倒（用户实测确认过）。
-- **矩形中心 ± 半个大小不能溢出头部孤岛**：正下方还有一段孤岛（u 0.695~0.935 / v 0.293~0.674），量下来是胸腹那一带，溢出去表情就会糊到肚子上。`tests/test_face.gd` 的 `test_face_rect_inside_head_island` 会直接从 shader 源码里读 `face_center` / `face_size` 再判定，**所以随手调这两个值不会被测试误报，只有溢出才会红**。
-- 两个 FaceRig 节点（`player.tscn` 的 `Player/FaceRig`、`character_select.tscn` 的预览 `FaceRig`）现在都不带表情矩形参数了 —— 值只有一份，在 shader 里。
+- **表情位置/大小/翻转只写在 `face_paint.gdshader` 顶部那段「调表情就改这一段」里**：`face_center`（中心，**模型本地坐标**，模型大约 x -3~3、y -3~3，**往下挪就减小 .y**）、`face_size`（.x 宽 .y 高，默认 4.0×4.0）、`face_front_edge`（法线朝前的阈值，调大只留最正面）、`face_flip_y`（默认 true）。
+  **FaceRig 故意不传这几个 uniform** —— 早期版本从 `@export` 传过去，会把 shader 里调好的值盖掉；现在 `face_rig.gd` 里没有对应的 export，测试里有一条断言禁止再传。
+- 贴图第 0 行在上边，而头部 UV 的 v 朝上，所以默认必须 `face_flip_y = true`，否则表情上下颠倒（用户实测确认过）。
+- 内置表情在各自图集 tile 里的墨线占比：`face_01` 68.9%×74.4%、`face_02` 83.9%×65.4%，且都居中 —— 所以 `face_size` 要按「墨线只占 tile 的七成」来估：4.0 的矩形给出约 2.8 单位的墨线宽度。
+- `test_face_decal_inside_body_bounds` 校验贴花矩形落在模型包围盒里（模型换尺度/原点会红）；`test_face_shader_has_expected_uniforms` 里钉住 `normalize(object_normal).z`（**不能带负号**，正面是本地 +Z）和 `object_position.xy`，防止有人改回 UV 方案或把正面写反。
+- 两个 FaceRig 节点（`player.tscn` 的 `Player/FaceRig`、`character_select.tscn` 的预览 `FaceRig`）都不带表情参数 —— 值只有一份，在 shader 里。
 - `FaceRig` 保存 `user://face_preset.json` 中的 expression ID 和 `user://face_paint.png` 暂存笔画；已保存的自绘表情用 `user://face_library/index.json` + 各自透明 PNG 持久化，角色选择页动态显示内置 atlas 表情和本地表情。
 - 联机当前表情同步：内置表情发送 ID；`user:` 本地表情发送当前 PNG 字节；笔画层另外发送。**不广播整份本地表情库**。
 - `FacePainter`：直接改 RGBA8 字节缓冲。画 = source-over alpha 混合，擦 = 把目标 alpha 乘掉；512² 一次 1MB，按一笔/动作同步一次。
 - 「自己画」= 空白底起手；保存到本地表情库成为独立项目，再次选择可加载。取消会恢复旧 expression ID 与笔画。
 - 界面链路：`ui/main_menu.tscn` →「开始游戏」→ `ui/character_select.tscn`（3D 预览 + 动态表情列表 + 自己画）→ `ui/paint_panel.tscn`（透明笔画层叠在肤色底上）。本地列表用 HFlow + ScrollContainer 显示。
 
+## 抱起物品（world/items/ + character/player/carry_arms.gd）
+
+- **门槛在物品自己身上**：物品根节点（RigidBody3D）挂 `Carryable`（`class_name`，进 `carryable` 组）才抱得起来，
+  玩家侧不认识任何具体物品。手感和滑索一个套路 —— `hold_offset` / `hold_rotation_deg` / `throw_speed_min/max`
+  都写在物品上，玩家只负责「找最近的、摆到抱持点、扔出去」。
+- 示例物品：`world/items/carryable_box.tscn`（0.6³ 橙箱子），世界场景里放了两个。加新物品只要挂脚本。
+- 玩家侧只有 `_find_carryable / _pick_up / _release_throw` 三个函数；**交互提示和按键判定同源**
+  （优先级：手上有东西 → 可抱物 → 缆上 → 可挂的缆），别再拆成两处。
+- 抱持**不 reparent**：`Carryable.carried_by` 记状态，持有者每物理帧 `apply_hold_transform(socket)`。
+  抱起来时冻结物理 + **collision_layer 清 0**（不清会把玩家顶飞），放下时恢复并继承初速度。
+- 输入动作：`carry` = 鼠标左键、`throw_carry` = Q（长按蓄力，松手出手）。鼠标没锁定时左键仍然只用来重新锁定视角。
+- 抱东西时禁疾跑 + `carry_speed_scale` 降速；**抱着不给挂滑索**（`_attach_zipline()` 开头直接 return）。
+- 抱持点 `CameraRig/CarrySocket`（Marker3D，本地 (0,-0.8,-1.0)）。物品位置要跟着它走。
+- `CarryArms`（挂在 `Body/CarryArms`）是**表现层**：`process_priority = 100` 保证跑在 AnimationPlayer 之后，
+  在动画姿态上**叠加**手臂旋转（只动 `arm_l_*` / `arm_r_*`），走路时胳膊和抱持点一起晃。
+  **参数按「世界方向」语义**（`rest_basis.inverse() * world * rest_basis` 换算到骨骼本地空间）——
+  直接写骨骼本地欧拉角会得到「手往上后方摆」这种莫名其妙的结果，换模型必错。
+  默认 swing 40 / tuck 50 / roll 0 / elbow 15 / stretch 1.25 → 手落在模型本地 (±1.17, 0.08, 0.95)。
+- 本地玩家第一人称藏了自己的模型（`hide_own_body`），所以**自己看不到自己的胳膊**，晃动只有别的玩家能看到；
+  想自己看就把 `hide_own_body` 关掉并把 `eye_height` 降下来。
+- **未做**：联机同步。现在物品位置只有持有者本地在写，远端看不到箱子被抱走 ——
+  要给物品加 `MultiplayerSynchronizer`、authority 随持有者切换、再加抢占仲裁。
+- 测试 `tests/test_carry.gd`：`Carryable` / `CarryArms` 都标了 `@tool`，否则编辑器里是 placeholder、
+  方法调不动、`_ready` 不跑（组也加不上）；改完脚本要 `filesystem_manage(op="scan")` 才重新解析。
+
 ## Godot 4 踩坑
 
 - **canvas 没有「擦除」混合模式**：`CanvasItemMaterial.BlendMode` 只有 mix/add/sub/mul/premult，
@@ -81,6 +109,14 @@
 
 ## Godot MCP 踩坑
 
+- **看画面**：`Read` 工具读用户发的图片文件会报 `Current model does not support reading images`，
+  但 `editor_screenshot(source="game")` 返回的游戏画面能正常看 —— 排查画面问题直接自己截图对照，
+  比让用户描述快。没有画面时也可以用像素统计（PNG 手写解码 + 粗 ASCII 图）反推布局。
+- **用户在编辑器里开着的文件会覆盖磁盘改动**：改完 `face_paint.gdshader` 后，磁盘上出现过
+  「我的新注释 + 旧的 `+normal.z` + 我从未写过的 `face_center.y = 0.6`」这种混合体 ——
+  用户在 Godot 里开着这个 shader、缓冲区是旧版本，他一保存就把我后来的改动冲掉了，而且没有任何提示。
+  所以改 `.gdshader` / `.tscn` 之后要在回复里提醒对方先关掉/重开那个文件再保存。
+
 - **数值标量经 MCP 会被字符串化**：`node_set_property` 传 `0.15` 能写进去，但回显是 `"0.15"`；
   而 `batch_execute` 里包 `{"command": "set_property", "params": {...}}` 直接报
   `INTERNAL_ERROR … handler returned malformed result`（和旧版本文档里写的正好相反，以实测为准）。
@@ -99,7 +135,9 @@
 - **非 `@tool` 脚本在编辑器里是「placeholder instance」**：`load(path).can_instantiate()` 返回 false，
   `.new()` 报 `Nonexistent function 'new' in base 'GDScript'`，`set_script` 后调方法报
   `Attempt to call a method on a placeholder instance`（`player.gd` 也一样，不是脚本本身的问题）。
-  想在 `test_run` 里验非 @tool 脚本，就临时生成一个「去掉 class_name、加上 @tool」的副本喂给测试，跑完删掉。
+  想在 `test_run` 里验非 @tool 脚本，**最省事的做法是直接给脚本加 `@tool`**（`Carryable` / `CarryArms` 就是这么办的，
+  运行时行为完全一样），其次才是临时生成一个 @tool 副本喂给测试。
+  加完要 `filesystem_manage(op="scan")` 一次，否则编辑器还在用旧的非 tool 版本，照样报 placeholder。
 - **`test_run` 的 GDScript 编译缓存是按路径的**：删掉再重建同名脚本，跑到的可能还是旧版本
   （现象：逻辑明明改了，测试却按旧逻辑失败）。要验新代码就换个文件名，或者重启编辑器。
 - **编辑器进程的 `InputMap` 只有内建动作**（`ui_accept` 有，`interact` / `jump` 没有）——

character/player/carry_arms.gd

@@ -0,0 +1,133 @@
+@tool
+class_name CarryArms
+extends Node
+## 抱东西时把两条胳膊伸出去抱住物品，走路时人和东西一起晃。
+##
+## 模型里没有「抱」这个动作片段，所以这里在动画**之后**叠加一段手臂姿态：
+## 只动 arm_l_* / arm_r_* 这几根骨骼，其余骨骼照旧交给 AnimationPlayer。
+## process_priority 设得比播放器大，保证在它写完骨骼之后才覆盖 —— 否则会被动画冲掉。
+##
+## 晃动同时作用在两条胳膊和「抱持点」上：物品每帧跟住抱持点，于是东西和人一起晃，
+## 不会出现「胳膊在晃、东西钉在手上」的穿帮。
+##
+## 控制器只负责说「抱没抱、走多快」，具体摆成什么样全由这里的参数决定。
+##
+## 标了 @tool 是为了能在编辑器里跑测试（非 @tool 脚本在编辑器里是 placeholder，方法调不动）。
+
+@export_group("接线")
+## 骨架。本节点挂在 Body 下，所以要先 .. 回到 Body
+@export var skeleton_path: NodePath = ^"../mouse/MouseRig/Skeleton3D"
+## 抱持点（Marker3D）。物品就摆在它上面：Body/CarryArms → ../../CameraRig/CarrySocket
+@export var socket_path: NodePath = ^"../../CameraRig/CarrySocket"
+
+@export_group("抱持姿势")
+## 大臂前摆（度）：把手伸到身前
+@export var shoulder_swing_deg: float = 40.0
+## 大臂内收（度）：两只手往中间合，抱住东西
+@export var shoulder_tuck_deg: float = 50.0
+## 大臂侧收（度）：绕身体前后轴转，把胳膊从上往下收到身前
+@export var shoulder_roll_deg: float = 0.0
+## 小臂弯曲（度）
+@export var elbow_deg: float = 15.0
+## 胳膊沿自身方向拉长的倍数（>1 就是「延伸」）
+@export var stretch: float = 1.25
+
+@export_group("走路晃动")
+## 胳膊晃动幅度（度）
+@export var wobble_deg: float = 8.0
+## 抱持点晃动幅度（米）。物品跟着它晃，所以别太大
+@export var wobble_socket: float = 0.035
+## 每秒晃几下
+@export var wobble_hz: float = 1.7
+## 姿态过渡速度（越大越跟手）
+@export var blend_speed: float = 8.0
+
+var _skeleton: Skeleton3D
+var _socket: Node3D
+var _socket_rest := Transform3D.IDENTITY
+## 手臂骨骼索引，按 [左大臂, 左小臂, 左手, 右大臂, 右小臂, 右手] 的顺序
+var _bones: Array[int] = []
+var _carrying := false
+## 姿态权重 0~1：抱起来时涨到 1，放下时退回 0（退回 0 之后就完全交给动画）
+var _weight := 0.0
+var _phase := 0.0
+## 当前速度 / 常规走速，用来决定晃多厉害
+var _speed_ratio := 0.0
+
+
+func _ready() -> void:
+	# 跑在 AnimationPlayer 之后，否则我们摆的骨骼会被动画覆盖
+	process_priority = 100
+	_skeleton = get_node_or_null(skeleton_path) as Skeleton3D
+	if _skeleton == null:
+		push_warning("%s 找不到骨架（%s），胳膊不会动" % [get_path(), skeleton_path])
+	_socket = get_node_or_null(socket_path) as Node3D
+	if _socket != null:
+		_socket_rest = _socket.transform
+	for bone_name in ["arm_l_01", "arm_l_02", "arm_l_03", "arm_r_01", "arm_r_02", "arm_r_03"]:
+		if _skeleton == null:
+			break
+		var index := _skeleton.find_bone(bone_name)
+		if index < 0:
+			push_warning("%s 里没有骨骼 %s，胳膊姿势会不完整" % [_skeleton.get_path(), bone_name])
+		_bones.append(index)
+
+
+## 控制器每帧告诉它「抱没抱、走多快」。speed_ratio 用「当前水平速度 / 常规走速」。
+func set_carrying(carrying: bool, speed_ratio: float) -> void:
+	_carrying = carrying
+	_speed_ratio = speed_ratio
+
+
+func _process(delta: float) -> void:
+	var target := 1.0 if _carrying else 0.0
+	_weight = move_toward(_weight, target, blend_speed * delta)
+	if _weight <= 0.0:
+		# 没抱东西：不碰骨骼也不碰抱持点，全部交回给动画
+		return
+
+	# 走得越快晃得越猛；站着不动时 phase 不推进，姿态是静的
+	var wobble_scale := clampf(_speed_ratio, 0.0, 1.5)
+	_phase += delta * TAU * wobble_hz * wobble_scale
+	var wobble := sin(_phase) * wobble_deg * wobble_scale * _weight
+
+	if _socket != null:
+		# 抱持点跟着晃，物品每帧跟住它 —— 东西和胳膊就同步了
+		var bob := sin(_phase) * wobble_socket * wobble_scale * _weight
+		_socket.transform = _socket_rest.translated_local(Vector3(0.0, bob, 0.0))
+
+	if _skeleton == null or _bones.size() < 6:
+		return
+	# 左右两组，同相位（抱着重物是两只手一起上下），内收方向相反
+	for side in 2:
+		var shoulder := _bones[side * 3]
+		var elbow := _bones[side * 3 + 1]
+		var wrist := _bones[side * 3 + 2]
+		if shoulder < 0:
+			continue
+		var mirror := -1.0 if side == 0 else 1.0
+		# 参数是**世界方向**：X 负向 = 往前摆，Y = 左右收，Z = 侧收（左右手相反）
+		_apply_bone(shoulder, Vector3(
+			-(shoulder_swing_deg + wobble),
+			shoulder_tuck_deg * mirror,
+			shoulder_roll_deg * mirror,
+		))
+		# 胳膊沿自身拉长 —— 这就是「可延伸」
+		_skeleton.set_bone_pose_scale(shoulder, Vector3(1.0, lerpf(1.0, stretch, _weight), 1.0))
+		if elbow >= 0:
+			_apply_bone(elbow, Vector3(-elbow_deg, 0.0, 0.0))
+		if wrist >= 0:
+			_apply_bone(wrist, Vector3(-elbow_deg * 0.4, 0.0, 0.0))
+
+
+## 在动画写好的姿态上再叠一个旋转。
+##
+## 传进来的角度按**世界方向**理解（往前摆 = 绕 X 轴负向），内部用骨骼自身的静止姿态
+## 把它换算到骨骼本地空间 —— 否则得先猜出每根骨骼本地轴朝哪，换个模型就全错。
+## 叠在动画姿态上是乘法，所以走路原本的摆臂不会被抹掉。
+func _apply_bone(index: int, offset_deg: Vector3) -> void:
+	var rest_basis := _skeleton.get_bone_rest(index).basis
+	var world := Basis.from_euler(offset_deg * PI / 180.0)
+	var local := rest_basis.inverse() * world * rest_basis
+	var posed := _skeleton.get_bone_pose_rotation(index)
+	_skeleton.set_bone_pose_rotation(index, posed * local.get_rotation_quaternion())

character/player/carry_arms.gd.uid

@@ -0,0 +1 @@
+uid://cca1hl0g2bku

character/player/face/face_paint.gdshader

@@ -1,23 +1,23 @@
 shader_type spatial;
-// 全身 shader：body_mesh 只有一个材质 mat_body —— 身体底色照常取它的 BaseColor，
-// 脸部不再换材质，只在这一个 shader 里把表情和手绘叠到指定 UV 矩形上。
-// 脸和周围走的是同一套材质、同一套光照，所以不会再出现独立面片的色块边界。
+// 全身 shader：body_mesh 只有一个材质 mat_body —— 身体底色照常取它的 BaseColor。
+// 脸不再靠 UV 矩形，而是「贴在身体正面上的一块贴花」：用**模型本地坐标**的 (x, y) 定位，
+// 再用「法线朝前的程度」当遮罩。
+// 这样它和 UV 孤岛怎么排完全无关 —— 表情可以放在身体正面任意位置，也不会再越界糊到肚子上。
 //
 // 贴图 alpha 只代表「墨线覆盖率」，绝不写进空间 ALPHA —— body_mesh 的面片必须保持不透明。
 
 // ================= 调表情就改这一段 =================
-// 头部那一段 UV 孤岛的实测范围：u 0.695~0.996（左右），v 0.682~0.996（上下，v 越大越靠头顶）。
-// 下面三个值就是「表情画在哪 / 多大 / 正不正」，FaceRig 不会覆盖它们，改完存盘即可。
-//
-// 表情中心点：**想往下挪就减小 .y**，往左挪就减小 .x
-uniform vec2 face_center = vec2(0.8455, 0.639);
-// 表情大小：.x 是左右宽度，.y 是上下高度（想只盖住半张脸就把 .y 改小）
-uniform vec2 face_size = vec2(0.301, 0.314);
-// 上下颠倒了就改成 false（头部 UV 的 v 朝上、贴图第 0 行在上边，所以默认要翻）
+// 中心点是**模型本地坐标**（和 mesh 顶点同一个空间，模型整体大约 x -3~3、y -3~3）。
+// 想往下挪就减小 .y，往左挪就减小 .x。
+uniform vec2 face_center = vec2(0.0, 0.6);
+// 表情大小：.x 是左右宽度，.y 是上下高度
+uniform vec2 face_size = vec2(4.0, 4.0);
+// 只在身体正面出现：朝**模型本地 +Z**（尾巴在 -Z 那一侧，所以正面是 +Z）的那面才画。
+// 调大就只留最正面的一小块，调小会往侧面包过去。
+uniform float face_front_edge : hint_range(0.0, 1.0) = 0.0;
+// 上下颠倒了就改成 false
 uniform bool face_flip_y = true;
 // ====================================================
-//
-// 中心 ± 半个大小必须整个落在上面那段 UV 孤岛里，否则表情会糊到肚子 / 背上去。
 
 uniform sampler2D body_tex : source_color, filter_linear, repeat_disable,
 		hint_default_white;
@@ -34,17 +34,32 @@ uniform vec2 base_uv_size = vec2(1.0, 1.0);
 uniform sampler2D paint_tex : source_color, filter_linear, repeat_disable,
 		hint_default_transparent;
 
+// 贴花要用「模型本地坐标」，而 fragment 里拿不到，所以从顶点阶段传过来
+varying vec3 object_position;
+varying vec3 object_normal;
+
+void vertex() {
+	object_position = VERTEX;
+	object_normal = NORMAL;
+}
+
 void fragment() {
 	// 全身底色都来自 mat_body 的 BaseColor，表情只是盖在脸上
 	vec3 albedo = texture(body_tex, UV).rgb * body_tint.rgb;
 
-	vec2 face_uv = (UV - (face_center - face_size * 0.5)) / face_size;
+	vec2 face_uv = (object_position.xy - (face_center - face_size * 0.5)) / face_size;
 	if (face_flip_y) {
 		face_uv.y = 1.0 - face_uv.y;
 	}
 	// 用 step 而不是 if：采样留在统一控制流里，免得 mipmap 的导数在分支里未定义
-	float mask = step(0.0, face_uv.x) * step(face_uv.x, 1.0)
+	float inside = step(0.0, face_uv.x) * step(face_uv.x, 1.0)
 			* step(0.0, face_uv.y) * step(face_uv.y, 1.0);
+	// 背面的点 (x, y) 和正面一样，也会落进矩形，所以要再按「朝不朝前」筛一遍。
+	// 模型正面是**本地 +Z**（尾巴在 -Z 那一侧），写成 -normal.z 表情就跑到背上去了。
+	float front = smoothstep(face_front_edge, face_front_edge + 0.3,
+			normalize(object_normal).z);
+	float mask = inside * front;
+
 	vec4 base = texture(base_tex, base_uv_min + face_uv * base_uv_size);
 	vec4 paint = texture(paint_tex, face_uv);
 	// 透明处保持身体底色 —— 所以脸和周围不可能出现底色差

character/player/player.gd

@@ -6,18 +6,25 @@ extends CharacterBody3D
 ##   Player (CharacterBody3D)          ← 只负责移动与碰撞，自身不旋转
 ##     ├─ Collision (CollisionShape3D, CapsuleShape3D)
 ##     ├─ CameraRig (Node3D)           ← 眼睛，架在 eye_height 高，承担偏航 yaw
-##     │    └─ Camera (Camera3D)       ← 承担俯仰 pitch（第一人称，没有弹簧臂）
+##     │    ├─ Camera (Camera3D)       ← 承担俯仰 pitch（第一人称，没有弹簧臂）
+##     │    └─ CarrySocket (Marker3D)  ← 抱持点：抱起来的物品就摆在这上面
 ##     ├─ Body (Node3D)                ← 视觉层，始终朝视线方向；换角色模型时挂在它下面
 ##     │    ├─ mouse (Node3D)          ← 模型（mouse.glb）：MouseRig/Skeleton3D + 各部位 MeshInstance3D
-##     │    └─ AnimationPlayer         ← 动作库 + 表现层（挂 player_animator.gd）：只读运动、只写动画
+##     │    ├─ AnimationPlayer         ← 动作库 + 表现层（挂 player_animator.gd）：只读运动、只写动画
+##     │    └─ CarryArms (Node)        ← 抱东西时的胳膊姿势 + 走路晃动（挂 carry_arms.gd）
 ##     ├─ Sync (MultiplayerSynchronizer)   ← 同步 position、Body.rotation、health、动画状态
 ##     ├─ HealthLabel (Label3D)        ← 头顶血条（节点配置，不是代码建的）
-##     └─ InteractHint (Label3D)       ← 靠近滑索时的「按 E」提示，同样在场景里配好
+##     └─ InteractHint (Label3D)       ← 交互提示，同样在场景里配好
 ##
 ## 滑索：走到缆下按 E 挂上，沿缆滑向低端，缆上按 S 刹车、空格跳离。
 ## 手感参数（速度/刹车/吸附半径）全在 Zipline 组件上，本文件只读不定义 —— 见文件末尾。
 ##
-## 操作：WASD/方向键移动，鼠标转视角，Shift 疾跑，Ctrl 蹲下（蹲着走即潜行），空格跳跃，E 滑索，Esc 释放/锁定鼠标
+## 抱起：左键抱起最近的可抱物品，长按 Q 蓄力、松手扔出去。
+## 谁能被抱由物品自己决定（挂 Carryable 脚本、进 carryable 组），手感参数同样在物品上；
+## 本文件只管「找到它、摆到抱持点、扔出去」这三件事。
+##
+## 操作：WASD/方向键移动，鼠标转视角，Shift 疾跑，Ctrl 蹲下（蹲着走即潜行），空格跳跃，
+##       E 滑索，左键抱起，长按 Q 扔出，Esc 释放/锁定鼠标
 
 ## 跳跃输入缓冲帧数（输入事件在渲染帧到达，物理帧读取，避免漏跳）
 const JUMP_BUFFER_FRAMES: int = 6
@@ -55,6 +62,18 @@ const JUMP_BUFFER_FRAMES: int = 6
 ## 起跳初速度（米/秒）
 @export var jump_velocity: float = 5.0
 
+@export_group("抱起")
+## 多远内的物品能抱起来（米）
+@export var pickup_radius: float = 3.0
+## 抱着东西时的移动速度倍率
+@export var carry_speed_scale: float = 0.6
+## 抱着东西时禁止疾跑
+@export var carry_blocks_sprint: bool = true
+## 长按 Q 蓄满力要多久（秒）
+@export var throw_charge_time: float = 0.8
+## 扔出去时额外叠上玩家自身的速度（跑着扔会飞更远）
+@export var throw_inherits_velocity: bool = true
+
 @onready var body: Node3D = $Body
 ## 眼睛分两层转：CameraRig 绕竖直轴转（yaw），Camera 原地抬头低头（pitch）。
 ## 分开是为了让 pitch 不掺进移动方向 —— 移动只用 rig 的 basis，低头看地也不会走歪。
@@ -64,6 +83,10 @@ const JUMP_BUFFER_FRAMES: int = 6
 @onready var _health_label: Label3D = $HealthLabel
 ## 滑索操作提示，同样在 player.tscn 里配好，默认隐藏
 @onready var _hint: Label3D = $InteractHint
+## 抱持点：抱起来的物品每物理帧摆到它上面
+@onready var _carry_socket: Node3D = $CameraRig/CarrySocket
+## 抱东西时的胳膊表现层（挂 carry_arms.gd）：只收「抱没抱、走多快」
+@onready var _carry_arms: CarryArms = $Body/CarryArms
 
 ## 动画状态机（挂在 Body/AnimationPlayer 上）。只把「运动结果」交给它，也只知道它会自己播动画。
 @onready var animator: PlayerAnimator = $Body/AnimationPlayer
@@ -87,6 +110,13 @@ var _zip_speed: float = 0.0
 ## 挂上瞬间「人相对缆」的偏移，随后衰减到 0 —— 吸附是滑过去的，不是瞬移
 var _zip_grab_offset: Vector3 = Vector3.ZERO
 
+## 手上抱着的物品。非 null 时每物理帧把它摆到抱持点上。
+## 只在权威端写；远端玩家的物品位置由物品自己的 Sync 复制过来。
+var _carried: Carryable = null
+## 长按 Q 的蓄力进度 0~1
+var _throw_charge: float = 0.0
+var _throw_charging: bool = false
+
 
 func _ready() -> void:
 	_report_identity()
@@ -133,6 +163,15 @@ func _unhandled_input(event: InputEvent) -> void:
 			_detach_zipline()
 		else:
 			_attach_zipline()
+	elif event.is_action_pressed("carry") and Input.mouse_mode == Input.MOUSE_MODE_CAPTURED:
+		# 鼠标没锁定时左键是用来重新锁定视角的，那种情况留给下面那个分支
+		_pick_up()
+	elif event.is_action_pressed("throw_carry"):
+		# 按住开始蓄力，松手才真正出手（见 _release_throw）
+		_throw_charging = _carried != null
+		_throw_charge = 0.0
+	elif event.is_action_released("throw_carry"):
+		_release_throw()
 	elif event.is_action_pressed("ui_cancel"):
 		set_mouse_captured(Input.mouse_mode != Input.MOUSE_MODE_CAPTURED)
 	elif event is InputEventMouseButton and event.pressed and Input.mouse_mode != Input.MOUSE_MODE_CAPTURED:
@@ -159,11 +198,37 @@ func _physics_process(delta: float) -> void:
 	if not _is_local:
 		return
 
-	# 靠近缆时给个操作提示。判定与 _attach_zipline 共用 _find_zipline()，
+	# 交互提示：**同一处判定**既决定「显示什么」又决定「按键干什么」，
 	# 免得出现「提示亮了但按 E 挂不上」这种对不上的情况。
-	_hint.visible = _zipline != null or _find_zipline() != null
-	if _hint.visible:
-		_hint.text = "空格 跳离 · E 松手" if _zipline != null else "按 E 挂上滑索"
+	# 优先级：手上有东西 > 可抱物 > 缆上 > 可挂的缆。
+	var nearby_carry := _find_carryable()
+	var nearby_zip := _find_zipline()
+	if _carried != null:
+		_hint.visible = true
+		_hint.text = "长按 Q 扔出 %d%%" % int(_throw_charge * 100.0)
+	elif nearby_carry != null:
+		_hint.visible = true
+		_hint.text = "左键 抱起"
+	elif _zipline != null:
+		_hint.visible = true
+		_hint.text = "空格 跳离 · E 松手"
+	elif nearby_zip != null:
+		_hint.visible = true
+		_hint.text = "按 E 挂上滑索"
+	else:
+		_hint.visible = false
+
+	# 抱着东西：每帧把它摆到抱持点上，并推进 Q 的蓄力。
+	# 物品的位置由持有者写 —— 远端玩家的那份由物品自己的 Sync 复制过去。
+	if _carried != null:
+		_carried.apply_hold_transform(_carry_socket)
+		if _throw_charging:
+			_throw_charge = minf(1.0, _throw_charge + delta / maxf(throw_charge_time, 0.01))
+	# 胳膊表现层只收「抱没抱、走多快」，摆成什么样是它自己的事
+	_carry_arms.set_carrying(
+		_carried != null,
+		Vector2(velocity.x, velocity.z).length() / maxf(walk_speed, 0.01),
+	)
 
 	# 挂在缆上时，下面的常规重力/输入/贴地全部让位给缆上运动
 	if _zipline != null:
@@ -196,7 +261,13 @@ func _physics_process(delta: float) -> void:
 		wish = wish.normalized()
 	# 身体朝向由 _apply_look() 跟着视线走 —— 第一人称不再朝移动方向转身
 
-	var speed := sprint_speed if Input.is_action_pressed("sprint") else walk_speed
+	var sprinting := Input.is_action_pressed("sprint")
+	# 抱着东西跑不快：禁疾跑 + 整体降速，参数在 @export 里
+	if _carried != null and carry_blocks_sprint:
+		sprinting = false
+	var speed := sprint_speed if sprinting else walk_speed
+	if _carried != null:
+		speed *= carry_speed_scale
 	if not wants_move:
 		speed = 0.0
 	var accel := acceleration if is_on_floor() else air_acceleration
@@ -212,11 +283,60 @@ func _physics_process(delta: float) -> void:
 	animator.set_motion(
 		velocity,
 		is_on_floor(),
-		Input.is_action_pressed("sprint"),
+		sprinting,
 		Input.is_action_pressed("crouch"),
 	)
 
 
+# ---------------- 抱起 ----------------
+# 三件事：找物品（_find_carryable）、抱起来（_pick_up）、扔出去（_release_throw）。
+# 谁能被抱、抱持偏移、投掷速度全在 Carryable 组件上，这里只读不定义 —— 和滑索一个套路。
+
+## 找最近能抱的物品。够不着、或者已经被人抱着的都不算。
+## 提示文案和左键共用这一套判定，避免「提示亮着却抱不起来」。
+func _find_carryable() -> Carryable:
+	var best: Carryable = null
+	var best_distance := pickup_radius
+	for node in get_tree().get_nodes_in_group(Carryable.GROUP):
+		var item := node as Carryable
+		if item == null or not item.can_be_carried():
+			continue
+		var distance := global_position.distance_to(item.global_position)
+		if distance > best_distance:
+			continue
+		best_distance = distance
+		best = item
+	return best
+
+
+## 抱起最近的可抱物品。手上已经有东西、或者正挂在缆上都不抱。
+func _pick_up() -> void:
+	if _carried != null or _zipline != null:
+		return
+	var item := _find_carryable()
+	if item == null:
+		return
+	item.begin_carry(self)
+	item.apply_hold_transform(_carry_socket)
+	_carried = item
+
+
+## 松手扔出：方向就是视线方向，速度按蓄力插值（轻点也能扔出去，只是近）。
+## 跑着扔会把自己当前的速度也叠上，所以助跑能扔更远。
+func _release_throw() -> void:
+	var item := _carried
+	_carried = null
+	_throw_charging = false
+	if item == null:
+		_throw_charge = 0.0
+		return
+	var launch := -camera.global_transform.basis.z * item.throw_speed(_throw_charge)
+	if throw_inherits_velocity:
+		launch += velocity
+	_throw_charge = 0.0
+	item.end_carry(launch)
+
+
 # ---------------- 滑索 ----------------
 # 拆成三件事：找缆（_find_zipline）、挂上（_attach_zipline）、缆上运动（_ride_zipline）。
 # 缆的几何与手感参数都在 Zipline 组件里，这里只管「人」的状态，参数只读不定义。
@@ -239,8 +359,10 @@ func _find_zipline() -> Zipline:
 	return best
 
 
-## 挂上最近的一条缆，人就近吸附到缆上最近一点。
+## 挂上最近的一条缆，人就近吸附到缆上最近一点。抱着东西时不给挂（会腾不出手）。
 func _attach_zipline() -> void:
+	if _carried != null:
+		return
 	var zip := _find_zipline()
 	if zip == null:
 		return

character/player/player.tscn

@@ -12,16 +12,18 @@
 [ext_resource type="AnimationLibrary" uid="uid://dy8a178vlbsof" path="res://character/player/assets/animations/sneak.glb" id="8_jo6ux"]
 [ext_resource type="AnimationLibrary" uid="uid://db83440o2cyr7" path="res://character/player/assets/animations/walk.glb" id="9_fkbv7"]
 [ext_resource type="Script" uid="uid://c6l2fl5jgvr1h" path="res://character/player/face/face_rig.gd" id="12_lqp71"]
+[ext_resource type="Script" uid="uid://cca1hl0g2bku" path="res://character/player/carry_arms.gd" id="13_carryarms"]
 
 [sub_resource type="CapsuleShape3D" id="CapsuleShape3D_rkbax"]
-radius = 0.4
-height = 1.8
+radius = 0.54541016
+height = 1.4063476
 
 [node name="Player" type="CharacterBody3D" unique_id=869687860]
+transform = Transform3D(0.2, 0, 0, 0, 0.2, 0, 0, 0, 0.2, 0, 0, 0)
 script = ExtResource("1_gtsfv")
 
 [node name="Collision" type="CollisionShape3D" parent="." unique_id=215132582]
-transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0.9, 0)
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0.7031738, 0)
 shape = SubResource("CapsuleShape3D_rkbax")
 
 [node name="CameraRig" type="Node3D" parent="." unique_id=1774966304]
@@ -30,6 +32,9 @@ transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1.6, 0)
 [node name="Camera" type="Camera3D" parent="CameraRig" unique_id=52294557]
 transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, -0.6066488, -0.11179829)
 
+[node name="CarrySocket" type="Marker3D" parent="CameraRig" unique_id=570180284]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, -0.8, -1)
+
 [node name="Body" type="Node3D" parent="." unique_id=394283421]
 
 [node name="mouse" parent="Body" unique_id=1995806863 instance=ExtResource("2_wu8e1")]
@@ -46,6 +51,10 @@ libraries/sneak = ExtResource("8_jo6ux")
 libraries/walk = ExtResource("9_fkbv7")
 script = ExtResource("3_g20gq")
 
+[node name="CarryArms" type="Node" parent="Body" unique_id=301629134]
+process_priority = 100
+script = ExtResource("13_carryarms")
+
 [node name="Sync" type="MultiplayerSynchronizer" parent="." unique_id=1979575210]
 replication_config = ExtResource("3_wu8e1")
 

project.godot

@@ -84,6 +84,16 @@ crouch={
 "events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":4194326,"physical_keycode":0,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
 ]
 }
+carry={
+"deadzone": 0.5,
+"events": [Object(InputEventMouseButton,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"button_mask":0,"position":Vector2(0, 0),"global_position":Vector2(0, 0),"factor":1.0,"button_index":1,"canceled":false,"pressed":false,"double_click":false,"script":null)
+]
+}
+throw_carry={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":81,"physical_keycode":0,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
 
 [physics]
 

tests/test_carry.gd

@@ -0,0 +1,152 @@
+@tool
+extends McpTestSuite
+## 回归测试：抱起物品系统的契约。
+##
+## 谁能被抱由**物品自己**决定（挂 carryable.gd + 进 carryable 组），玩家只管找/抱/扔；
+## 抱持偏移和投掷速度也写在物品上。这里盯住这几条契约，改物品或改玩家时先让测试红一次。
+
+const PLAYER_SCENE_PATH := "res://character/player/player.tscn"
+const ITEM_SCENE_PATH := "res://world/items/carryable_box.tscn"
+const CARRY_ACTION := "carry"
+const THROW_ACTION := "throw_carry"
+
+
+func suite_name() -> String:
+	return "carry"
+
+
+## 编辑器进程里的 InputMap 只有内建动作，项目动作要手动 load 一次才在
+func _ensure_input_map() -> void:
+	InputMap.load_from_project_settings()
+
+
+## 把节点塞进场景树，让 _ready() 真的跑起来；track() 负责回收
+func _into_tree(node: Node) -> Node:
+	var editor := Engine.get_singleton("EditorInterface")
+	var root: Node = null
+	if editor != null:
+		root = editor.get_edited_scene_root()
+	if root == null:
+		root = Engine.get_main_loop().root
+	root.add_child(node)
+	track(node)
+	return node
+
+
+func test_carry_actions_exist() -> void:
+	_ensure_input_map()
+	# 动作没了按键就完全没反应，而且不报错 —— 这种静默失效必须由测试兜住
+	assert_true(InputMap.has_action(CARRY_ACTION), "缺少 %s 动作，左键抱不起来" % CARRY_ACTION)
+	assert_true(InputMap.has_action(THROW_ACTION), "缺少 %s 动作，长按 Q 扔不出去" % THROW_ACTION)
+
+
+func test_player_scene_has_carry_nodes() -> void:
+	var packed := load(PLAYER_SCENE_PATH) as PackedScene
+	assert_true(packed != null, "%s 未能加载" % PLAYER_SCENE_PATH)
+	if packed == null:
+		return
+	var player := packed.instantiate()
+	track(player)
+	var socket := player.get_node_or_null("CameraRig/CarrySocket")
+	assert_true(socket is Marker3D, "CameraRig 下缺少 CarrySocket（Marker3D）—— 物品没有抱持点")
+	var arms := player.get_node_or_null("Body/CarryArms")
+	assert_true(arms != null, "Body 下缺少 CarryArms 节点")
+	if arms != null:
+		assert_true(arms.get_script() != null and str(arms.get_script().resource_path).ends_with("carry_arms.gd"),
+			"Body/CarryArms 没挂 carry_arms.gd，胳膊不会抱东西")
+
+
+func test_example_item_is_carryable() -> void:
+	var packed := load(ITEM_SCENE_PATH) as PackedScene
+	assert_true(packed != null, "%s 未能加载 —— 可抱物品的示例没了" % ITEM_SCENE_PATH)
+	if packed == null:
+		return
+	var item := packed.instantiate()
+	assert_true(item is Carryable, "示例物品根节点不是 Carryable（%s）" % item.get_class())
+	if not item is Carryable:
+		track(item)
+		return
+	var carryable := item as Carryable
+	_into_tree(carryable)
+	assert_true(carryable.is_in_group(Carryable.GROUP),
+		"可抱物品没进 %s 组，玩家就找不到它" % Carryable.GROUP)
+	assert_true(carryable.get_node_or_null("Collision") is CollisionShape3D,
+		"示例物品没有碰撞体，扔出去会穿地")
+
+
+func test_carry_freezes_body_and_restores_on_release() -> void:
+	var item := _into_tree((load(ITEM_SCENE_PATH) as PackedScene).instantiate()) as Carryable
+	assert_true(item != null, "示例物品实例化失败")
+	if item == null:
+		return
+	var layer := item.collision_layer
+	assert_true(item.can_be_carried(), "新物品应该是可以抱的")
+	var holder := Node3D.new()
+	track(holder)
+	item.begin_carry(holder)
+	assert_true(not item.can_be_carried(), "抱起来之后不该还能被别人抱走")
+	assert_true(item.freeze, "抱起来要冻结物理，否则会和抱着它的人打架")
+	assert_eq(item.collision_layer, 0, "抱起来要清掉碰撞层，否则物品会把玩家顶飞")
+	item.end_carry(Vector3(1.0, 2.0, 3.0))
+	assert_true(item.can_be_carried(), "放下之后应该又能被抱")
+	assert_true(not item.freeze, "放下要恢复物理")
+	assert_eq(item.collision_layer, layer, "放下要恢复原来的碰撞层")
+	assert_true(item.linear_velocity.is_equal_approx(Vector3(1.0, 2.0, 3.0)),
+		"放下时要继承扔出去的速度，实际 %s" % item.linear_velocity)
+
+
+func test_hold_transform_snaps_to_socket() -> void:
+	var item := _into_tree((load(ITEM_SCENE_PATH) as PackedScene).instantiate()) as Carryable
+	if item == null:
+		return
+	var socket := Marker3D.new()
+	track(socket)
+	socket.position = Vector3(1.0, 2.0, -3.0)
+	socket.rotation = Vector3(0.0, PI * 0.5, 0.0)
+	var root: Node = Engine.get_main_loop().root
+	root.add_child(socket)
+	item.apply_hold_transform(socket)
+	var expected := socket.global_position + socket.global_basis * item.hold_offset
+	assert_true(item.global_position.distance_to(expected) < 0.001,
+		"物品没摆到抱持点上：实际 %s，期望 %s" % [item.global_position, expected])
+
+
+func test_throw_speed_scales_with_charge() -> void:
+	var item := _into_tree((load(ITEM_SCENE_PATH) as PackedScene).instantiate()) as Carryable
+	if item == null:
+		return
+	assert_true(absf(item.throw_speed(0.0) - item.throw_speed_min) < 0.001,
+		"蓄力为 0 时应该是最低出手速度")
+	assert_true(absf(item.throw_speed(1.0) - item.throw_speed_max) < 0.001,
+		"蓄满时应该是最高出手速度")
+	assert_true(item.throw_speed(0.5) > item.throw_speed_min and item.throw_speed(0.5) < item.throw_speed_max,
+		"出手速度应该随蓄力单调变化")
+	assert_true(item.throw_speed(9.0) <= item.throw_speed_max, "蓄力超出范围要被夹住")
+
+
+## 抱起姿势必须真的把胳膊伸到身体**前方**（模型正面是本地 +Z，尾巴在 -Z 那一侧）。
+## 参数写反或者骨骼名写错时，这里会红 —— 光看代码看不出胳膊朝哪边伸。
+func test_carry_pose_reaches_forward() -> void:
+	var packed := load(PLAYER_SCENE_PATH) as PackedScene
+	if packed == null:
+		return
+	var player := _into_tree(packed.instantiate())
+	var arms := player.get_node_or_null("Body/CarryArms") as CarryArms
+	var skeleton := player.get_node_or_null("Body/mouse/MouseRig/Skeleton3D") as Skeleton3D
+	assert_true(arms != null and skeleton != null, "玩家场景里缺 CarryArms 或骨架")
+	if arms == null or skeleton == null:
+		return
+	var hand := skeleton.find_bone("arm_l_03")
+	assert_true(hand >= 0, "骨架里没有 arm_l_03，胳膊姿势会不完整")
+	if hand < 0:
+		return
+	var before := skeleton.get_bone_global_pose(hand).origin
+	arms.set_carrying(true, 0.0)
+	# 直接推进两次让它混合到位（测试里没有引擎帧）
+	arms._process(1.0)
+	arms._process(1.0)
+	var after := skeleton.get_bone_global_pose(hand).origin
+	assert_true(after.z > before.z + 0.5,
+		"抱起来时手要伸到身体前方：抱之前 z=%.2f，抱之后 z=%.2f" % [before.z, after.z])
+	assert_true(after.y > before.y,
+		"抱起来时手要抬到身前的高度：抱之前 y=%.2f，抱之后 y=%.2f" % [before.y, after.y])

tests/test_carry.gd.uid

@@ -0,0 +1 @@
+uid://bcvmvwwjphdf5

tests/test_face.gd

@@ -1,20 +1,19 @@
 @tool
 extends McpTestSuite
-## 回归测试：脸部那套「UV 矩形 + 预设 + 画笔」的契约。
+## 回归测试：脸部那套「贴花 + 预设 + 画笔」的契约。
 ##
-## body_mesh 只有一个材质 mat_body，脸部不再单独换材质，而是由 shader 顶部的
-## face_center / face_size 在本体 UV 上圈出表情矩形。**模型重导或改 UV 之后，脸就会画歪、
-## 被裁掉、甚至糊到肚子上，而且不报任何错** —— 所以这里把「矩形必须落在头部孤岛里」钉死，
-## 改模型时先让测试红一次。数值本身从 shader 源码里读，方便随手调。
+## body_mesh 只有一个材质 mat_body，脸是 shader 里贴在身体正面上的一块**贴花**：
+## 用模型本地坐标 (x, y) 定位、用法线朝前的程度当遮罩，所以和 UV 孤岛怎么排无关，
+## 也不会因为越界糊到肚子/背上。这里盯住：贴花参数还在、矩形大致落在模型包围盒里
+## （模型换尺度或换原点时会红）、以及 FaceRig 不许再抢着传这些 uniform。
 
 const PLAYER_SCENE_PATH := "res://character/player/player.tscn"
 const SHADER_PATH := "res://character/player/face/face_paint.gdshader"
 const PRESET_DIR := "res://character/player/face/presets"
 const BODY_MESH_PATH := "Body/mouse/MouseRig/Skeleton3D/body_mesh"
 const BODY_MATERIAL_NAME := "mat_body"
-
-## UV 是浮点，给点容差
-const EPS := 0.004
+## 模型本地坐标，给点容差
+const EPS := 0.05
 
 
 func suite_name() -> String:
@@ -29,11 +28,11 @@ func _shader_code() -> String:
 	return file.get_as_text()
 
 
-## 从 shader 源码里抓 `uniform vec2 名字 = vec2(a, b);` 的两个数。
+## 从 shader 源码里抓 `名字 = vec2(a, b);` 的两个数（uniform 和 const 都能抓）。
 func _shader_vec2(code: String, name: String) -> Vector2:
-	var marker := "uniform vec2 %s = vec2(" % name
+	var marker := "%s = vec2(" % name
 	var start := code.find(marker)
-	assert_true(start >= 0, "shader 里找不到 uniform vec2 %s 的默认值" % name)
+	assert_true(start >= 0, "shader 里找不到 %s 的 vec2 默认值" % name)
 	if start < 0:
 		return Vector2(INF, INF)
 	start += marker.length()
@@ -63,69 +62,6 @@ func _body_mesh() -> MeshInstance3D:
 	return player.get_node_or_null(BODY_MESH_PATH) as MeshInstance3D
 
 
-## 找「最高处那块 UV 孤岛」（= 头部）的 UV 范围。脸部矩形必须落在它里面。
-func _head_island_uv_rect() -> Rect2:
-	var mi := _body_mesh()
-	if mi == null:
-		return Rect2()
-	var mesh := mi.mesh as ArrayMesh
-	if mesh == null or mesh.get_surface_count() == 0:
-		return Rect2()
-	var arrays := mesh.surface_get_arrays(0)
-	var uvs := arrays[Mesh.ARRAY_TEX_UV] as PackedVector2Array
-	var verts := arrays[Mesh.ARRAY_VERTEX] as PackedVector3Array
-	var indices := PackedInt32Array()
-	if arrays[Mesh.ARRAY_INDEX] is PackedInt32Array:
-		indices = arrays[Mesh.ARRAY_INDEX]
-	if uvs.size() == 0 or indices.size() == 0:
-		return Rect2()
-	var parent := []
-	parent.resize(uvs.size())
-	for i in uvs.size():
-		parent[i] = i
-	for t in indices.size() / 3:
-		_union(parent, indices[t * 3], indices[t * 3 + 1])
-		_union(parent, indices[t * 3], indices[t * 3 + 2])
-	var groups := {}
-	for i in uvs.size():
-		var root := _find(parent, i)
-		if not groups.has(root):
-			groups[root] = []
-		groups[root].append(i)
-	var best_root := -1
-	var best_top := -INF
-	for root in groups:
-		var members: Array = groups[root]
-		var top := -INF
-		for i in members:
-			top = maxf(top, verts[i].y)
-		if top > best_top:
-			best_top = top
-			best_root = root
-	var members: Array = groups.get(best_root, [])
-	var uv_min := Vector2(INF, INF)
-	var uv_max := Vector2(-INF, -INF)
-	for i in members:
-		var uv: Vector2 = uvs[i]
-		uv_min = Vector2(minf(uv_min.x, uv.x), minf(uv_min.y, uv.y))
-		uv_max = Vector2(maxf(uv_max.x, uv.x), maxf(uv_max.y, uv.y))
-	return Rect2(uv_min, uv_max - uv_min)
-
-
-func _find(parent: Array, index: int) -> int:
-	while parent[index] != index:
-		parent[index] = parent[parent[index]]
-		index = parent[index]
-	return index
-
-
-func _union(parent: Array, a: int, b: int) -> void:
-	var root_a := _find(parent, a)
-	var root_b := _find(parent, b)
-	if root_a != root_b:
-		parent[root_b] = root_a
-
-
 func test_player_has_face_rig_wired() -> void:
 	var player := _player()
 	if player == null:
@@ -137,9 +73,9 @@ func test_player_has_face_rig_wired() -> void:
 	assert_eq(rig.surface_index, 0, "body_mesh 只剩一个材质，FaceRig 必须覆盖 surface 0")
 	assert_true(rig.get_node_or_null(rig.mesh_path) is MeshInstance3D,
 		"FaceRig.mesh_path（%s）解析不到 MeshInstance3D —— 换模型后路径要跟着改" % rig.mesh_path)
-	# 表情位置/大小只写在 shader 里；脚本一旦也传这三个 uniform，就会把调好的值盖掉
+	# 贴花参数只写在 shader 里；脚本一旦也传这几个 uniform，就会把调好的值盖掉
 	var script_text := FileAccess.open("res://character/player/face/face_rig.gd", FileAccess.READ).get_as_text()
-	for name in ["face_center", "face_size", "face_flip_y"]:
+	for name in ["face_center", "face_size", "face_flip_y", "face_front_edge"]:
 		assert_true(not script_text.contains("set_shader_parameter(\"%s\"" % name),
 			"face_rig.gd 又在传 %s 了 —— shader 顶部调好的值会被脚本覆盖" % name)
 
@@ -166,9 +102,8 @@ func test_body_mesh_has_single_material() -> void:
 		assert_true(standard.albedo_texture != null, "%s 没有 BaseColor 贴图，身体底色会变成白" % BODY_MATERIAL_NAME)
 
 
-## 脸部矩形必须整块落在头部孤岛里，否则表情会画到身体别的部位上。
-## 表情矩形（中心 ± 半个大小）必须整块落在头部孤岛里，否则表情会糊到别的部位上。
-func test_face_rect_inside_head_island() -> void:
+## 贴花矩形是模型本地坐标，必须落在模型自己的包围盒里，否则表情会飘到体外。
+func test_face_decal_inside_body_bounds() -> void:
 	var code := _shader_code()
 	if code.is_empty():
 		return
@@ -176,33 +111,38 @@ func test_face_rect_inside_head_island() -> void:
 	var size := _shader_vec2(code, "face_size")
 	if not center.is_finite() or not size.is_finite():
 		return
-	var head := _head_island_uv_rect()
-	assert_true(head.size.x > 0.0 and head.size.y > 0.0, "没算出头部 UV 孤岛 —— 模型结构变了？")
-	if head.size.x <= 0.0:
+	assert_true(size.x > 0.0 and size.y > 0.0, "face_size 必须是正数（要翻转请用 face_flip_y）")
+	var mi := _body_mesh()
+	if mi == null:
 		return
+	var bounds := mi.mesh.get_aabb()
 	var rect_min := center - size * 0.5
 	var rect_max := center + size * 0.5
-	assert_true(rect_min.x >= head.position.x - EPS and rect_min.y >= head.position.y - EPS,
-		"表情矩形左下角 %s 跑出了头部 UV 孤岛 %s（中心 %s 大小 %s）" % [rect_min, head, center, size])
-	assert_true(rect_max.x <= head.end.x + EPS and rect_max.y <= head.end.y + EPS,
-		"表情矩形右上角 %s 超出了头部 UV 孤岛 %s（中心 %s 大小 %s）—— 模型改过 UV 还是值调过头了？"
-		% [rect_max, head, center, size])
+	assert_true(rect_min.x >= bounds.position.x - EPS and rect_min.y >= bounds.position.y - EPS,
+		"贴花左下角 %s 跑到模型包围盒 %s 外面了" % [rect_min, bounds])
+	assert_true(rect_max.x <= bounds.end.x + EPS and rect_max.y <= bounds.end.y + EPS,
+		"贴花右上角 %s 跑到模型包围盒 %s 外面了 —— 模型换尺度/原点后会这样" % [rect_max, bounds])
 
 
 func test_face_shader_has_expected_uniforms() -> void:
-	var file := FileAccess.open(SHADER_PATH, FileAccess.READ)
-	assert_true(file != null, "%s 加载失败" % SHADER_PATH)
-	if file == null:
+	var code := _shader_code()
+	if code.is_empty():
 		return
-	var code := file.get_as_text()
 	for required in [
 		"body_tex", "body_tint", "surface_roughness", "surface_metallic",
-		"face_center", "face_size", "face_flip_y",
+		"face_center", "face_size", "face_front_edge", "face_flip_y",
 		"base_tex", "base_uv_min", "base_uv_size", "paint_tex",
 	]:
 		assert_true(code.contains("uniform ") and code.contains(required), "shader 少了 uniform %s" % required)
 	assert_true(code.contains("texture(body_tex, UV)"),
 		"shader 必须用 body_tex 采样全身底色，否则脸和身体不是同一块皮肤")
+	assert_true(code.contains("varying vec3 object_position") and code.contains("object_position.xy"),
+		"贴花必须用模型本地坐标定位，否则又会被 UV 孤岛边界卡住")
+	assert_true(code.contains("normalize(object_normal).z"),
+		"贴花必须按「法线朝前」筛一遍，否则背面的点也会画上表情")
+	# 模型正面是本地 +Z（尾巴在 -Z 那一侧），写成 -normalize 表情就跑到背上去了
+	assert_true(not code.contains("-normalize(object_normal).z"),
+		"正面遮罩写反了：模型正面是本地 +Z，-normalize 会让表情出现在背上")
 	assert_true(code.contains("ROUGHNESS = surface_roughness"), "shader 必须复用 mat_body 的 roughness")
 	assert_true(code.contains("METALLIC = surface_metallic"), "shader 必须复用 mat_body 的 metallic")
 	# alpha 只代表墨线覆盖率，不能写进空间 ALPHA，否则身体面片会被抠出洞

ui/character_select.gd

@@ -4,7 +4,6 @@ extends Control
 signal confirmed
 signal back_pressed
 
-const SPIN_SPEED := 0.5
 
 @onready var _model: Node3D = %Model
 @onready var _camera: Camera3D = %PreviewCamera
@@ -25,12 +24,12 @@ func _ready() -> void:
 	_paint_panel.finished.connect(_refresh_expression_list)
 	_paint_panel.cancelled.connect(_refresh_expression_list)
 	_refresh_expression_list()
+	
+	# 将模型选择180度
+	if (_model != null):
+		_model.rotate_y(PI)
 
 
-func _process(delta: float) -> void:
-	if _model != null:
-		_model.rotate_y(SPIN_SPEED * delta)
-
 
 ## 内置表情用 AtlasTexture 显示对应 UV 小格；本地表情直接显示各自 PNG。
 func _refresh_expression_list() -> void:

ui/character_select.tscn

@@ -96,7 +96,6 @@ transform = Transform3D(0.18240133, 0, 0, 0, 0.18240133, 0, 0, 0, 0.18240133, 0,
 unique_name_in_owner = true
 script = ExtResource("7_face_rig")
 mesh_path = NodePath("../Model/mouse/MouseRig/Skeleton3D/body_mesh")
-default_expression_id = "builtin:face_01"
 
 [node name="Right" type="VBoxContainer" parent="Margin/Layout" unique_id=605730650]
 layout_mode = 2
@@ -133,12 +132,12 @@ theme_override_constants/outline_size = 8
 theme_override_font_sizes/font_size = 28
 text = "脸部"
 
-[node name="PresetScroll" type="ScrollContainer" parent="Margin/Layout/Right"]
+[node name="PresetScroll" type="ScrollContainer" parent="Margin/Layout/Right" unique_id=832055416]
 custom_minimum_size = Vector2(0, 190)
 layout_mode = 2
 size_flags_vertical = 3
 
-[node name="PresetRow" type="HFlowContainer" parent="Margin/Layout/Right/PresetScroll"]
+[node name="PresetRow" type="HFlowContainer" parent="Margin/Layout/Right/PresetScroll" unique_id=1604784518]
 unique_name_in_owner = true
 layout_mode = 2
 size_flags_horizontal = 3

world/items/carryable.gd

@@ -0,0 +1,74 @@
+@tool
+class_name Carryable
+extends RigidBody3D
+## 可抱起的物品。**只有带这个脚本（并进了 carryable 组）的东西才抱得起来** —— 这就是
+## 「仅特定物品可抱」的实现方式：门槛不在玩家那边，而在物品自己身上。
+##
+## 和 Zipline 一样，手感参数放物品这一侧：不同物品可以有不同的抱持偏移、不同的投掷速度，
+## 玩家只负责「找到它、把它摆到手上、扔出去」，不定义手感。
+##
+## 用法：把这个脚本挂在物品根节点（RigidBody3D）上即可，别的什么都不用配。
+## 参考示例见 res://world/items/carryable_box.tscn。
+##
+## 标了 @tool 是为了能在编辑器里跑测试（非 @tool 脚本在编辑器里是 placeholder，方法调不动）；
+## 运行时行为完全一样。
+
+## 所有可抱物品都进这个组，玩家靠它找物品
+const GROUP: StringName = &"carryable"
+
+@export_group("抱持")
+## 被抱时相对抱持点的偏移（米）。物品大小不同，靠它对准手心
+@export var hold_offset: Vector3 = Vector3.ZERO
+## 被抱时的朝向（度）
+@export var hold_rotation_deg: Vector3 = Vector3.ZERO
+## 抱起来时冻结物理、并清掉碰撞层 —— 不清的话物品会把抱着它的人顶飞
+@export var freeze_while_carried: bool = true
+
+@export_group("投掷")
+## 长按蓄满力后的出手速度（米/秒）
+@export var throw_speed_max: float = 14.0
+## 轻点时最低出手速度（米/秒）
+@export var throw_speed_min: float = 5.0
+
+## 现在被谁抱着。空 = 没人抱
+var carried_by: Node3D = null
+
+var _saved_collision_layer: int = 1
+
+
+func _ready() -> void:
+	add_to_group(GROUP)
+	_saved_collision_layer = collision_layer
+
+
+func can_be_carried() -> bool:
+	return carried_by == null
+
+
+## 被抱起来：冻结物理、退出碰撞，之后由持有者每帧摆位置
+func begin_carry(holder: Node3D) -> void:
+	carried_by = holder
+	if freeze_while_carried:
+		freeze = true
+		collision_layer = 0
+
+
+## 放下 / 扔出：恢复物理并继承一个初速度
+func end_carry(velocity: Vector3) -> void:
+	carried_by = null
+	if freeze_while_carried:
+		freeze = false
+		collision_layer = _saved_collision_layer
+	linear_velocity = velocity
+
+
+## 把自己摆到抱持点上。持有者每物理帧调一次 —— 偏移和朝向由物品自己决定，玩家不用管。
+func apply_hold_transform(socket: Node3D) -> void:
+	var socket_basis := socket.global_basis
+	global_position = socket.global_position + socket_basis * hold_offset
+	global_basis = socket_basis * Basis.from_euler(hold_rotation_deg * PI / 180.0)
+
+
+## 按蓄力比例算出手速度（0 = 轻点，1 = 蓄满）
+func throw_speed(charge: float) -> float:
+	return lerpf(throw_speed_min, throw_speed_max, clampf(charge, 0.0, 1.0))

world/items/carryable.gd.uid

@@ -0,0 +1 @@
+uid://bdo6ee5tmvnc2

world/items/carryable_box.tscn

@@ -0,0 +1,24 @@
+[gd_scene load_steps=5 format=3]
+
+[ext_resource type="Script" path="res://world/items/carryable.gd" id="1_carryable"]
+
+[sub_resource type="BoxMesh" id="BoxMesh_body"]
+size = Vector3(0.6, 0.6, 0.6)
+
+[sub_resource type="StandardMaterial3D" id="StandardMaterial3D_box"]
+albedo_color = Color(0.92, 0.6, 0.25, 1)
+roughness = 0.7
+
+[sub_resource type="BoxShape3D" id="BoxShape3D_body"]
+size = Vector3(0.6, 0.6, 0.6)
+
+[node name="CarryableBox" type="RigidBody3D"]
+mass = 2.0
+script = ExtResource("1_carryable")
+
+[node name="Mesh" type="MeshInstance3D" parent="."]
+mesh = SubResource("BoxMesh_body")
+surface_material_override/0 = SubResource("StandardMaterial3D_box")
+
+[node name="Collision" type="CollisionShape3D" parent="."]
+shape = SubResource("BoxShape3D_body")

world/main.tscn

@@ -6,6 +6,7 @@
 [ext_resource type="PackedScene" path="res://world/ocean/sea.tscn" id="3_sea"]
 [ext_resource type="Material" path="res://world/ocean/island_mesa.tres" id="4_island"]
 [ext_resource type="PackedScene" uid="uid://12qonfnowpas" path="res://world/zipline/zipline.tscn" id="6_i1eo7"]
+[ext_resource type="PackedScene" path="res://world/items/carryable_box.tscn" id="7_carrybox"]
 
 [sub_resource type="BoxShape3D" id="BoxShape3D_hyim0"]
 size = Vector3(58, 0.5, 58)
@@ -91,3 +92,9 @@ material_override = SubResource("StandardMaterial3D_op3e8")
 mesh = SubResource("BoxMesh_vid1e")
 
 [node name="Zipline" parent="." unique_id=982324784 instance=ExtResource("6_i1eo7")]
+
+[node name="CarryableBox1" parent="." instance=ExtResource("7_carrybox")]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 2.2, 0.55, -1.6)
+
+[node name="CarryableBox2" parent="." instance=ExtResource("7_carrybox")]
+transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 3.0, 0.55, -2.4)