Files

T

2026-09-03 23:06:00 +08:00

25 KiB

Raw Blame History

UI 迁移参照手册（Game_Surface_3 → YouleNexus）

Status: v1 (2026-09-03) Purpose: 记录已迁移 Layer 的 prefab 结构，作为之后脚本绑定与驱动 UI 的唯一参照。每个 prefab 的节点名、组件、坐标、spriteFrame、文本/字体均在此列出，脚本开发时无需回查 prefab JSON 或源数据。 权威源: Layer XML（projects/Game_Surface_3/save/Layer*.xml）+ gameabc_Object.json + gameabc_Image.json。

1. 全局迁移规则（实测确立）

1.1 设计分辨率与布局策略

源工程（Game_Surface_3）UI 设计分辨率：1280×720。
新工程（YouleNexus）画布：1600×720（有意设计）。
布局策略：1280×720 的 UI 在 1600×720 画布中水平居中（左右各留 160 空白），全屏背景拉伸到 1600 填满。

水平居中靠 Widget alignFlags=16（水平居中）+ _horizontalCenter = lpos.x 实现（见 1.4），不是改坐标中心。

1.2 坐标系换算（源左上角 → Cocos 中心）

源数据 X/Y 是左上角锚点（Layer XML 的 X/Y = gameabc_Object.json 的 Left/Top）：

lpos.x = X + W/2 - 640     // 相对 1280 中心
lpos.y = 360 - (Y + H/2)   // Y-up 翻转，相对 720 中心

中心取 640/360（1280×720），不是 800/360。1600 的居中由 Widget 实现。

1.3 组件类型映射

组件类型以 gameabc_Object.json 的 ObjectType 为准（CLAUDE.md 已修正旧文档 off-by-one 与 SpiritType 误用）：

ObjectType（JSON，权威）	含义	Cocos 组件
2	Sprite	cc.Sprite
4	Text	cc.Label

Layer XML 的 SpiritType 是细分类，只作参考：

SpiritType（XML）	含义
0	普通 Sprite
1	Text
3	帧 Sprite（带 `Frame` 属性；`frame_all=1` 时无多帧效果）

节点类型	alignFlags	说明
root / group / 全屏背景	45（全拉伸）	contentSize 1600×720，填满画布
固定元素	16（水平居中）+ `_horizontalCenter = lpos.x`	实现 1280 UI 在 1600 画布居中

⚠️ 校验不变量：alignFlags=16 的节点，_lpos.x 必须 === _horizontalCenter（anchor=0.5、父居中、isAbs=true 时恒成立）。引擎 align() 里 x = targetCenter + (anchorX-0.5)*width + horizontalCenter，偶发编辑器回调把 horizontalCenter 翻倍（实测 Layer613 背景 12→24）。迁移后逐节点校验，不符就用 edit_prefab_json 改回。

1.5 spriteFrame 引用

cc.Sprite._spriteFrame 必须是对象形式 {"__uuid__": "…@f9941", "__expectedType__": "cc.SpriteFrame"}。
⚠️ create_sprite 的 spriteFrameUuid 参数会把 _spriteFrame 写成裸字符串 "…@f9941"（坏引用，validate_prefab_references 报 referenceCount:0、运行时加载不到图）。正确做法：create_sprite 不传 spriteFrameUuid，用 set_component_property 设 _spriteFrame = 对象 JSON；或事后用 edit_prefab_json 修。
_type=0（SIMPLE）、_sizeMode=0（CUSTOM）+ _contentSize = 源 W/H。
⚠️ create_sprite 默认 _sizeMode=1（TRIMMED）会覆盖 contentSize，必须显式 _sizeMode=0。

1.6 全屏背景 contentSize

源 1280×720 的全屏背景（如 00011.png 纯色遮罩，图片本身仅 4×4）→ contentSize 1600×720（拉伸填满）。固定元素 contentSize = 源 W/H。

1.7 Text 对象字段映射

文本/fontSize 的权威源是 Layer XML（Property Name="FontSize" / Text 等），gameabc_Object.json 里 Text 对象只有语义名（ObjectName）+ W/H，无 fontSize/文本。

源字段（Layer XML，SpiritType=1）	cc.Label	说明
`FontSize`	`_fontSize`	字体大小保持源值，不统一
`FontColor`	`_color.r/g/b`	整数 RGB：`16777215` = `0xFFFFFF` = 白
`FontColorA`	`_color.a`	透明度
`Text`	`_string`	初始文本（常 = ObjectName 占位，运行时由脚本替换）
`LineSpace`	`_lineHeight`	当前用 `lineHeight = fontSize`（见 5.待验证）
`FontBold`	加粗	待验证映射（复杂 Layer 补齐）
`AlignHorz` / `AlignVert`	`_horizontalAlign` / `_verticalAlign`	待验证映射
`WordWrap`	`_overflow` / `_enableWrapText`	待验证映射

1.8 根节点命名

prefab 根节点名 = 文件名（如 Layer619_BackHall.prefab → 根节点 Layer619_BackHall），Cocos 约定。

1.9 九宫格（9-slice / SpiritType=5）

源 SpiritType=5 表示九宫格，边距来自 Layer XML 的 LeftEdge/TopEdge/RightEdge/BottomEdge。
Cocos 3.8 的九宫格边距不在 Sprite 组件上（cc.Sprite 只有 _type=1 SLICED 标志，无 inset 字段），而是存在图片资源 spriteFrame 的 border 字段：.meta 里 spriteFrame subMeta 的 userData.borderLeft/Top/Right/Bottom，导入后写入 library spriteFrame 的 capInsets（顺序 [left, top, right, bottom]）。
迁移步骤：① Sprite _type=1（SLICED）+ _sizeMode=0 + contentSize = 源 W/H；② 图片 spriteFrame 的 border 设为 LeftEdge/TopEdge/RightEdge/BottomEdge（改 .meta 的 4 个数值 + refresh_assets，属图片资源配置，一次设置服务所有共享该图的 Layer）。
⚠️ 图片被多 Layer 共享时，先确认各处九宫格边距一致（同一图片的边距是图片固有属性）；若不一致，需为不同边距各建 spriteFrame 副本。改 .meta 属触碰 CLAUDE.md「禁手改 .meta」边界，须先征得同意（只动 4 个非引用数值，不碰 UUID）。

2. 已迁移 prefab 清单

prefab	源 Layer	spirits	内容
`Layer614_Loading.prefab`	Loading_Layer (614)	2	载入遮罩 + 载入动画
`Layer616_Kick.prefab`	Kick_Layer (616)	3	强制下线提示 + 底 + 文字
`Layer619_BackHall.prefab`	BackHall_Layer (619)	1	Spirit465（返回大厅按钮）
`Layer613_RoomCardUpdate.prefab`	updateRoomCard_Layer (613)	3	房卡修改遮罩 + 背景 + 提示文字
`Layer615_Reconnect.prefab`	Reconnect_Layer (615)	4	掉线遮罩 + 背景 + 重连动画（多帧）+ 重连文字
`Layer10_Protol.prefab`	Protol_Layer (10)	4	协议遮罩 + 背景（九宫格）+ 内容 + 关闭按钮
`Layer612_Tips.prefab`	Tips_Layer (612)	5	提示遮罩 + 提示背景 + 提示文字（2 组：普通提示 + 九宫格提示）
`Layer620_Record.prefab`	recordLayer (620)	3	记录遮罩 + 记录背景（多帧）+ 记录动画（多帧）

图片映射（ImageFileID → spriteFrame UUID）

ImageFileID	bmp	图片实际尺寸	用途	spriteFrame UUID
11	00011.png	4×4（拉伸）	全屏遮罩	`eabf148a-fa6a-460a-be4f-8e586eb80e07@f9941`
108	00108.png	100×100	载入动画	`e966950a-fe3c-41d9-adcb-b8950fb77ae1@f9941`
87	00087.png	570×105	强制下线提示底	`c6295419-a30e-4e88-b7d7-d4099114319d@f9941`
31	00031.png	91×91	Spirit465	`8e3905be-b629-4c4d-858b-b8a76e9f7752@f9941`
54	00054.png	454×207	掉线背景	`4b04584c-c0f4-4586-8be7-05b0adca4157@f9941`
97	00097_*.png（8 帧）	64×64	重连动画（多帧）	帧 1 = `5690de47-2417-4e4c-b948-b772697cd010@f9941`
98	00098.png	171×28	重连文字（Sprite，非文本）	`837b6d75-1a66-40a0-8b7a-42dae7146c2a@f9941`
41	00041.png	115×94（九宫格）	协议背景（边框 55/45/55/45）	`3e7492cb-7ae1-4f56-806d-07096662d8fb@f9941`
95	00095.png	729×997	协议内容（滚动长图）	`998850c4-7861-4c12-8cb4-be7a7415c42a@f9941`
33	00033.png	83×84（trim 后 81×81）	关闭按钮	`eedce6d7-3ea6-434c-83e1-87d9a04b2bad@f9941`
10	00010.png	166×68（拉伸）	遮罩（Layer612 + Layer620 共用，异于通用遮罩 00011）	`dcc4530b-344b-40b6-8fbb-9fa35db6a289@f9941`
249	00249.png	100×100（九宫格）	提示九宫格按钮（边框 40/40/40/40）	`b44cf3e4-ec84-4208-a68f-ec5e30ecd593@f9941`
380	00380_*.png（6 帧）	65×174	记录动画（多帧，帧 1 落盘）	帧 1 = `1305d4c3-fc5b-4873-8ec4-e619f7514692@f9941`
381	00381.png	351×359	记录背景	`31eeca1a-3b00-4b66-b2c1-0d647d6c821c@f9941`

3. 每个 prefab 详细说明

约定：lpos = 相对父节点中心的偏移；Widget hc = _horizontalCenter；所有节点 anchorPoint = (0.5, 0.5)。

3.1 Layer619_BackHall.prefab（BackHall_Layer，返回大厅）

源 Layer00619.xml：1 spirit，GroupID=55。

Layer619_BackHall            UITransform 1600×720  Widget 45
└─ group-55                  UITransform 1600×720  Widget 45
   └─ Spirit465              UITransform 91×91    Widget 16 (hc=569.5)

节点	源字段	组件属性
Spirit465	ObjectID=465, X=1164 Y=146 W=91 H=91, ImgResID=31, Frame=1, CanClick=1	Sprite sf=`8e3905be-…@f9941` type=0 sizeMode=0；contentSize 91×91；lpos (569.5, 168.5)；Widget 16 hc=569.5

脚本驱动要点：

Spirit465 是「返回大厅」按钮（CanClick=1），XML Event 为空 → 需脚本 bind_button_click_event 绑定点击回调。

3.2 Layer614_Loading.prefab（Loading_Layer，载入遮罩）

源 Layer00614.xml：2 spirits，GroupID=40。

Layer614_Loading            UITransform 1600×720  Widget 45
└─ group-40                 UITransform 1600×720  Widget 45
   ├─ 载入遮罩              UITransform 1600×720  Widget 45
   └─ 载入动画              UITransform 150×150  Widget 16 (hc=0)

节点	源字段	组件属性
载入遮罩	ObjectID=326, X=0 Y=0 W=1280 H=720, ImgResID=11, CanClick=1	Sprite sf=`eabf148a-…@f9941` type=0 sizeMode=0；contentSize 1600×720（全屏拉伸）；lpos (0,0)；Widget 45
载入动画	ObjectID=327, X=565 Y=285 W=150 H=150, ImgResID=108, Frame=1	Sprite sf=`e966950a-…@f9941` type=0 sizeMode=0；contentSize 150×150；lpos (0,0)；Widget 16 hc=0

脚本驱动要点：

载入遮罩（CanClick=1）XML Event MouseUp=326（自引用）→ 语义为「点击关闭 loading」，脚本绑定点击回调。
载入动画 frame_all=1（单帧静态），若后续要转圈动画需脚本切 spriteFrame 或加 Animation（源为静态图）。

3.3 Layer616_Kick.prefab（Kick_Layer，强制下线提示）

源 Layer00616.xml：3 spirits，GroupID=33。

Layer616_Kick              UITransform 1600×720  Widget 45
└─ group-33                UITransform 1600×720  Widget 45
   ├─ 强制下线提示         UITransform 1600×720  Widget 45
   ├─ 强制下线提示底       UITransform 600×105  Widget 16 (hc=-1)
   └─ 强制退出提示文字     UITransform 168×28   Widget 16 (hc=-18)  [Label]

节点	源字段	组件属性
强制下线提示	ObjectID=224, X=0 Y=0 W=1280 H=720, ImgResID=11	Sprite sf=`eabf148a-…@f9941` type=0 sizeMode=0；contentSize 1600×720；lpos (0,0)；Widget 45
强制下线提示底	ObjectID=225, X=339 Y=292 W=600 H=105, ImgResID=87	Sprite sf=`c6295419-…@f9941` type=0 sizeMode=0；contentSize 600×105；lpos (-1, 15.5)；Widget 16 hc=-1
强制退出提示文字	ObjectID=227, X=538 Y=330 W=168 H=28, FontSize=16, FontColor=16777215, Text="强制退出提示文字"	Label string=`强制退出提示文字` fontSize=16 lineHeight=16 color=白(255,255,255,255)；contentSize 168×28；lpos (-18, 16)；Widget 16 hc=-18

脚本驱动要点：

强制退出提示文字（Label）是动态文本：_string 运行时由脚本替换为实际提示内容（源 Text="强制退出提示文字" 是占位）。
强制下线提示底是「提示框底图」，文字叠加其上（lpos 差 (17, 0.5)，文字略偏左下对齐底图）。

3.4 Layer613_RoomCardUpdate.prefab（updateRoomCard_Layer，房卡修改）

源 Layer00613.xml：3 spirits，GroupID=34。

Layer613_RoomCardUpdate        UITransform 1600×720  Widget 45
└─ group-34                    UITransform 1600×720  Widget 45
   ├─ 房卡修改遮罩            UITransform 1600×720  Widget 45
   ├─ 房卡修改背景            UITransform 570×105   Widget 16 (hc=12)
   └─ 房卡修改提示文字        UITransform 168×28    Widget 16 (hc=-50)  [Label]

节点	源字段	组件属性
房卡修改遮罩	ObjectID=226, X=0 Y=0 W=1280 H=720, ImgResID=11	Sprite sf=`eabf148a-…@f9941` type=0 sizeMode=0；contentSize 1600×720；lpos (0,0)；Widget 45
房卡修改背景	ObjectID=228, X=367 Y=288 W=570 H=105, ImgResID=87	Sprite sf=`c6295419-…@f9941` type=0 sizeMode=0；contentSize 570×105；lpos (12, 19.5)；Widget 16 hc=12
房卡修改提示文字	ObjectID=229, X=506 Y=324 W=168 H=28, FontSize=16, FontColor=16777215, Text="房卡修改提示文字"	Label string=`房卡修改提示文字` fontSize=16 lineHeight=16 color=白；contentSize 168×28；lpos (-50, 22)；Widget 16 hc=-50

脚本驱动要点：

房卡修改提示文字（Label）是动态文本：_string 运行时由脚本替换（源 Text="房卡修改提示文字" 是占位）。
遮罩 CanClick=1，XML Event 空 → 脚本按需 bind_button_click_event（通常「点击关闭」）。

3.5 Layer615_Reconnect.prefab（Reconnect_Layer，掉线重连）

源 Layer00615.xml：4 spirits，GroupID=35。

Layer615_Reconnect        UITransform 1600×720  Widget 45
└─ group-35               UITransform 1600×720  Widget 45
   ├─ 掉线遮罩            UITransform 1600×720  Widget 45
   ├─ 掉线背景            UITransform 454×207   Widget 16 (hc=0)
   ├─ 重连动画            UITransform 64×64     Widget 16 (hc=0)
   └─ 重连文字            UITransform 171×28    Widget 16 (hc=0.5)  [Sprite]

节点	源字段	组件属性
掉线遮罩	ObjectID=230, X=0 Y=0 W=1280 H=720, ImgResID=11, CanClick=1	Sprite sf=`eabf148a-…@f9941` type=0 sizeMode=0；contentSize 1600×720；lpos (0,0)；Widget 45
掉线背景	ObjectID=231, X=413 Y=257 W=454 H=207, ImgResID=54	Sprite sf=`4b04584c-…@f9941` type=0 sizeMode=0；contentSize 454×207；lpos (0,-0.5)；Widget 16 hc=0
重连动画	ObjectID=232, X=608 Y=293 W=64 H=64, ImgResID=97, SpiritType=3, Frame=1, FrameIndex=1	Sprite sf=`5690de47-…@f9941`（第 1 帧）type=0 sizeMode=0；contentSize 64×64；lpos (0,35)；Widget 16 hc=0
重连文字	ObjectID=255, X=555 Y=390 W=171 H=28, ImgResID=98, ObjectType=2	Sprite sf=`837b6d75-…@f9941` type=0 sizeMode=0；contentSize 171×28；lpos (0.5,-44)；Widget 16 hc=0.5

脚本驱动要点：

重连文字是 Sprite，不是 Label（ObjectType=2、ImgResID=98，源 XML SpiritType=0 无 FontSize/Text）：文字已烘焙在图片 00098.png 里，脚本无需 set string，只按需显隐/换图。
重连动画是多帧 sprite（ImgResID=97，源 SpiritType=3 + Frame=1，8 帧 00097_1~8.png）：迁移只落第 1 帧为 spriteFrame，运行时逐帧动画需脚本循环切 spriteFrame 或加 cc.Animation。
掉线遮罩 CanClick=1，XML Event 空 → 脚本按需 bind_button_click_event（通常「点击取消重连/关闭」）。

3.6 Layer10_Protol.prefab（Protol_Layer，协议弹窗）

源 Layer00010.xml：4 spirits，GroupID=37。

Layer10_Protol           UITransform 1600×720  Widget 45
└─ group-37              UITransform 1600×720  Widget 45
   ├─ 协议遮罩           UITransform 1600×720  Widget 45
   ├─ 协议背景           UITransform 820×650   Widget 16 (hc=-7)   [9-slice]
   ├─ 协议内容           UITransform 729×997   Widget 16 (hc=-5.5)
   └─ Spirit253          UITransform 83×84     Widget 16 (hc=395.5)

节点	源字段	组件属性
协议遮罩	ObjectID=250, X=0 Y=0 W=1280 H=720, ImgResID=11, CanClick=1	Sprite sf=`eabf148a-…@f9941` type=0 sizeMode=0；contentSize 1600×720；lpos (0,0)；Widget 45
协议背景	ObjectID=251, X=223 Y=30 W=820 H=650, ImgResID=41, SpiritType=5, 边距 55/45/55/45	Sprite sf=`3e7492cb-…@f9941` type=1 (SLICED) sizeMode=0；contentSize 820×650；lpos (-7,5)；Widget 16 hc=-7；spriteFrame border/capInsets=[55,45,55,45]
协议内容	ObjectID=252, X=270 Y=70 W=729 H=997, ImgResID=95	Sprite sf=`998850c4-…@f9941` type=0 sizeMode=0；contentSize 729×997；lpos (-5.5,-208.5)；Widget 16 hc=-5.5
Spirit253	ObjectID=253, X=994 Y=6 W=83 H=84, ImgResID=33, CanClick=1	Sprite sf=`eedce6d7-…@f9941` type=0 sizeMode=0；contentSize 83×84；lpos (395.5,312)；Widget 16 hc=395.5

脚本驱动要点：

协议背景是九宫格（源 SpiritType=5，边距 55/45/55/45）：Sprite _type=SLICED + spriteFrame border 已设。九宫格边距是图片 00041.png 的固有属性，10 个 Layer 共享且边距一致，已在图片资源上一次性设置。
协议内容是滚动长图（729×997，高超出 720 画布）：contentSize 用源值，lpos (-5.5,-208.5) 向下超出屏幕，运行时需脚本配合 ScrollView/Mask 滚动显示（或按需裁剪）。
Spirit253 是关闭按钮（CanClick=1，源 Name 即 "Spirit253" 未改名），XML Event 空 → 脚本 bind_button_click_event 绑定「关闭协议弹窗」。
协议遮罩 CanClick=1，XML Event 空 → 脚本按需绑定「点击遮罩关闭」。

3.7 Layer612_Tips.prefab（Tips_Layer，提示弹窗）

源 Layer00612.xml：5 spirits，2 组（GroupID=32 普通提示、GroupID=89 九宫格提示）。

Layer612_Tips             UITransform 1600×720  Widget 45
├─ group-32              UITransform 1600×720  Widget 45
│  ├─ Spirit3193         UITransform 1600×720  Widget 45
│  ├─ 提示背景           UITransform 570×105   Widget 16 (hc=-24)
│  └─ 提示文字           UITransform 84×28     Widget 16 (hc=-81)   [Label]
└─ group-89              UITransform 1600×720  Widget 45
   ├─ Spirit3012         UITransform 100×100   Widget 16 (hc=-254)  [9-slice]
   └─ Spirit3013         UITransform 84×28     Widget 16 (hc=-238)  [Label]

节点	源字段	组件属性
Spirit3193	ObjectID=3193, X=0 Y=0 W=1280 H=720, ImgResID=10, CanClick=1	Sprite sf=`dcc4530b-…@f9941` type=0 sizeMode=0；contentSize 1600×720；lpos (0,0)；Widget 45
提示背景	ObjectID=217, X=331 Y=290 W=570 H=105, ImgResID=87	Sprite sf=`c6295419-…@f9941` type=0 sizeMode=0；contentSize 570×105；lpos (-24, 17.5)；Widget 16 hc=-24
提示文字	ObjectID=218, X=517 Y=327 W=84 H=28, FontSize=16, FontColor=16777215, Text="提示文字"	Label string=`提示文字` fontSize=16 lineHeight=16 color=白；contentSize 84×28；lpos (-81, 19)；Widget 16 hc=-81
Spirit3012	ObjectID=3012, X=336 Y=289 W=100 H=100, ImgResID=249, SpiritType=5, 边距 40/40/40/40, CanClick=1	Sprite sf=`b44cf3e4-…@f9941` type=1 (SLICED) sizeMode=0；contentSize 100×100；lpos (-254, 21)；Widget 16 hc=-254；spriteFrame border/capInsets=[40,40,40,40]
Spirit3013	ObjectID=3013, X=360 Y=336 W=84 H=28, FontSize=16, FontColor=16777215, Text="提示文字"	Label string=`提示文字` fontSize=16 lineHeight=16 color=白；contentSize 84×28；lpos (-238, 10)；Widget 16 hc=-238

脚本驱动要点：

两组提示：group-32 是普通提示（遮罩 + 570×105 底 + 文字），group-89 是九宫格提示（100×100 九宫格按钮 + 文字）。两组为互斥的两种提示形态，运行时按需显隐某一 group。
提示文字（Label）是动态文本：两处 _string 都是占位 "提示文字"，运行时由脚本替换为实际提示内容。
Spirit3012 是九宫格（源 SpiritType=5 + CanDragSize=1，边距 40/40/40/40）：Sprite _type=SLICED + spriteFrame border 已设。图片 00249.png 仅被 Layer612 使用（无跨 Layer 共享），边距在图片资源上一次性设置。CanDragSize=1 表明运行时可能被脚本拉伸（九宫格保证拉伸不变形）。
遮罩图异于通用遮罩：Layer612 用 ImgResID=10（00010.png 166×68）做遮罩，不是其它 Layer 通用的 00011.png（4×4）。若后续要统一遮罩，需在脚本/来源处确认（数据源权威，不得下游兜底）。
Spirit3193（CanClick=1）、Spirit3012（CanClick=1）XML Event 空 → 脚本按需 bind_button_click_event。

3.8 Layer620_Record.prefab（recordLayer，记录）

源 Layer00620.xml：3 spirits，GroupID=101。

Layer620_Record          UITransform 1600×720  Widget 45
└─ group-101             UITransform 1600×720  Widget 45
   ├─ Spirit3126         UITransform 1600×720  Widget 45
   ├─ Spirit3127         UITransform 351×359   Widget 16 (hc=0.5)
   └─ Spirit3128         UITransform 65×174    Widget 16 (hc=96.5)

节点	源字段	组件属性
Spirit3126	ObjectID=3126, X=0 Y=0 W=1280 H=720, ImgResID=10, CanClick=1	Sprite sf=`dcc4530b-…@f9941` type=0 sizeMode=0；contentSize 1600×720；lpos (0,0)；Widget 45
Spirit3127	ObjectID=3127, X=465 Y=181 W=351 H=359, ImgResID=381, SpiritType=3, Frame=1, CanClick=1	Sprite sf=`31eeca1a-…@f9941` type=0 sizeMode=0；contentSize 351×359；lpos (0.5,-0.5)；Widget 16 hc=0.5
Spirit3128	ObjectID=3128, X=704 Y=273 W=65 H=174, ImgResID=380, SpiritType=3, Frame=1, CanClick=1	Sprite sf=`1305d4c3-…@f9941`（第 1 帧）type=0 sizeMode=0；contentSize 65×174；lpos (96.5,0)；Widget 16 hc=96.5

脚本驱动要点：

Spirit3128 是多帧 sprite（ImgResID=380，源 SpiritType=3 + Frame=1，6 帧 00380_1~6.png，每帧 65×174）：迁移只落第 1 帧为 spriteFrame，运行时逐帧动画需脚本循环切 spriteFrame 或加 cc.Animation（记录滚动/计数动画）。
Spirit3127 是记录背景（ImgResID=381 单图 351×359）：SizeCalcMode=2 + WidthCalcMode/HeightCalcMode=1（随内容自适应尺寸），但源 W/H 已给出 351×359，迁移按固定 contentSize 落盘。
三节点均 CanClick=1、XML Event 空 → 脚本按需 bind_button_click_event（Spirit3126 遮罩通常「点击关闭」）。
遮罩用 ImgResID=10（00010.png，与 Layer612 共用），非通用遮罩 00011。

4. 脚本驱动汇总

4.1 动态文本节点（脚本需 set string）

prefab	节点	初始 _string
Layer616_Kick	强制退出提示文字	"强制退出提示文字"（占位，运行时替换）
Layer612_Tips	提示文字（group-32）	"提示文字"（占位，运行时替换）
Layer612_Tips	Spirit3013（group-89）	"提示文字"（占位，运行时替换）

4.2 可点击节点（脚本需 bind 回调）

prefab	节点	源 Event	语义
Layer614_Loading	载入遮罩	MouseUp=326（自引用）	点击关闭 loading
Layer619_BackHall	Spirit465	空	返回大厅按钮
Layer615_Reconnect	掉线遮罩	空	点击取消重连/关闭（按需绑定）
Layer10_Protol	Spirit253	空	关闭协议弹窗
Layer10_Protol	协议遮罩	空	点击遮罩关闭（按需绑定）
Layer612_Tips	Spirit3193	空	提示遮罩（点击关闭，按需绑定）
Layer612_Tips	Spirit3012	空	九宫格提示按钮（点击关闭/确认，按需绑定）
Layer620_Record	Spirit3126	空	记录遮罩（点击关闭，按需绑定）
Layer620_Record	Spirit3127	空	记录背景（按需绑定）
Layer620_Record	Spirit3128	空	记录动画（按需绑定）

4.3 源 Event → Cocos 绑定映射

原工程 XML EventList（MouseDown/MouseUp/MouseMove/OnTimer）的 Value 是回调目标 ObjectID（1/空 = 无）。迁移时用 bind_button_click_event 把 Button 点击绑定到对应脚本 handler。若目标 ObjectID 指向自身，语义通常是「点击自身关闭该 Layer」。

5. 待验证事项

LineSpace → _lineHeight 映射：当前用 lineHeight = fontSize（对齐 Login_Layer 参考），但源 XML LineSpace=0 的精确语义（默认行距 vs 额外间距）待更多 Text 样本确认。
FontBold / AlignHorz / AlignVert / WordWrap → cc.Label 的完整映射：复杂 Layer（含富文本/多行/对齐文本）迁移时补齐。
FrameStyle/FrameIndex 多帧 sprite：Layer615 重连动画（ImgID=97，8 帧）是首个多帧案例，已迁移第 1 帧为 spriteFrame；运行时逐帧动画驱动（脚本切 spriteFrame 或 cc.Animation）待实现。
Option.vx/vy/vw/vh 动画物理：deferred 到 game logic 迁移。
Label 运行期 contentSize 自收紧：实测（Layer612）Label 节点的 UITransform 在运行期会把 contentSize 从源 W×H（如 84×28）自动收紧为文本包围盒（如 64×20.16，overflow=NONE 下仍发生，仅 Label、Sprite 不受影响）。视觉无影响（文本按 anchor 居中位置不变），但脚本若依赖 contentSize 做布局需注意。prefab JSON 里仍保留源 W×H（对齐「保持与原工程一致」）。

关联文档

docs/superpowers/specs/UI-手工迁移规范.md（9 步迁移流程 + 8 项验证清单）
docs/superpowers/specs/原工程数据模型.md（JSON schema + 锚点公式）
docs/superpowers/data/layer-spirit-summary.json（Layer → prefab 映射表）

25 KiB Raw Blame History Unescape Escape

UI 迁移参照手册（Game_Surface_3 → YouleNexus）

1. 全局迁移规则（实测确立）

1.1 设计分辨率与布局策略

1.2 坐标系换算（源左上角 → Cocos 中心）

1.3 组件类型映射

1.4 Widget 规则

1.5 spriteFrame 引用

1.6 全屏背景 contentSize

1.7 Text 对象字段映射

1.8 根节点命名

1.9 九宫格（9-slice / SpiritType=5）

2. 已迁移 prefab 清单

图片映射（ImageFileID → spriteFrame UUID）

3. 每个 prefab 详细说明

3.1 Layer619_BackHall.prefab（BackHall_Layer，返回大厅）

3.2 Layer614_Loading.prefab（Loading_Layer，载入遮罩）

3.3 Layer616_Kick.prefab（Kick_Layer，强制下线提示）

3.4 Layer613_RoomCardUpdate.prefab（updateRoomCard_Layer，房卡修改）

3.5 Layer615_Reconnect.prefab（Reconnect_Layer，掉线重连）

3.6 Layer10_Protol.prefab（Protol_Layer，协议弹窗）

3.7 Layer612_Tips.prefab（Tips_Layer，提示弹窗）

3.8 Layer620_Record.prefab（recordLayer，记录）

4. 脚本驱动汇总

4.1 动态文本节点（脚本需 set string）

4.2 可点击节点（脚本需 bind 回调）

4.3 源 Event → Cocos 绑定映射

5. 待验证事项

关联文档

25 KiB

Raw Blame History