编辑器发布设置
本文只记录 FairyGUI 编辑器侧真实存在的发布属性与设置文件结构，作为发布相关功能开发时的依据。本文只按编辑器真实属性组织内容。
项目设置 sidecar
工程设置目录支持以下五个 JSON 文件：
| 文件 | 正式设置字段 |
|---|---|
Publish.json | publish |
Common.json | common |
Adaptation.json | adaptation |
CustomProperties.json | customProperties，保存 JSON 对象 |
i18n.json | i18n，其中 langFiles 保存语言文件的 name 与 path |
五类设置在工程读写与 UAM 往返中保持完整的嵌套 JSON 数据。CustomProperties.json 与 i18n.json 是可选文件；源工程不存在对应设置时，规范化和写回不会自行创建它们。updateProjectSettings 以完整设置快照更新工程设置，相同快照以 project_settings_unchanged 拒绝；从快照删除可选字段时，写回会删除已有 sidecar，并要求文件系统提供 unlink()。
设置文件与层级
编辑器发布设置至少分为两层：
| 层级 | 编辑器对象 | 作用 |
|---|---|---|
| 全局发布设置 | GlobalPublishSettings | 记录项目级默认发布参数，序列化到 settings/Publish.json |
| 包级发布设置 | PublishSettings | 记录单个包的发布参数、图集列表和排除列表 |
settings/Publish.json 真实属性
顶层属性
以下是 GlobalPublishSettings 中可见的真实发布属性：
| 属性 | 含义 |
|---|---|
path | 发布输出目录 |
branchPath | 分支发布路径 |
fileExtension | 发布文件扩展名 |
packageCount | 默认包数量 |
compressDesc | 是否压缩描述数据 |
binaryFormat | 是否使用二进制发布格式 |
jpegQuality | JPEG 质量 |
compressPNG | 是否压缩 PNG |
allowGenCode | 是否允许生成代码 |
codePath | 代码输出路径 |
classNamePrefix | 类名前缀 |
memberNamePrefix | 成员名前缀 |
packageName | 代码生成使用的包名 |
ignoreNoname | 是否忽略无名对象 |
getMemberByName | 是否按名称获取成员 |
codeType | 代码生成类型 |
includeHighResolution | 高分辨率资源包含位掩码 |
branchProcessing | 分支处理模式 |
atlasMaxSize | 图集最大尺寸 |
atlasPaging | 是否分页 |
atlasSizeOption | 图集尺寸策略 |
atlasForceSquare | 是否强制正方形 |
atlasAllowRotation | 是否允许旋转 |
atlasTrimImage | 是否裁边 |
codeGeneration
Publish.json 中的代码生成子对象包含以下真实属性：
| 属性 | 含义 |
|---|---|
allowGenCode | 是否允许生成代码 |
codePath | 代码输出路径 |
classNamePrefix | 类名前缀 |
memberNamePrefix | 成员名前缀 |
packageName | 目标包名 / 命名空间 |
ignoreNoname | 是否忽略无名对象 |
getMemberByName | 是否生成按名称获取成员逻辑 |
codeType | 代码类型 |
atlasSetting
Publish.json 中的图集子对象包含以下真实属性：
| 属性 | 含义 |
|---|---|
maxSize | 图集最大尺寸 |
paging | 是否允许多页图集 |
sizeOption | 图集尺寸策略 |
forceSquare | 是否强制方图 |
allowRotation | 是否允许旋转 |
trimImage | 是否裁边 |
说明：
- 编辑器
GlobalPublishSettings里还存在atlasMaxSize、atlasPaging、atlasSizeOption、atlasForceSquare、atlasAllowRotation、atlasTrimImage这些运行时字段，它们对应Publish.json里的atlasSetting子对象。 extractAlpha不属于全局Publish.json的真实属性；它在包级图集设置里出现。
SVG 图像发布
当 package.xml 的 image 资源指向 .svg，并声明了正的 width 和 height 时，发布会先按这两个声明尺寸栅格化，再执行可选裁边和图集合成。发布物只包含 PNG 图集；sprite 的原始尺寸保持为工程声明值。
浏览器发布会在栅格化前执行与 UAM source validation 共用的结构化 XML 校验，并拒绝脚本、事件属性、外部资源引用、DTD/实体、样式、非标准命名空间或带前缀元素，以及超出尺寸或复杂度上限的 SVG。createImageBitmap 无法解码已验证 SVG 时，会使用 HTMLImageElement 与 Blob URL 回退；Blob URL 在成功和失败路径都会释放。宿主同时缺少可用 DOM 图像解码能力时，发布失败且不写出产物。
包级发布设置真实属性
PublishSettings 代表单个包的发布设置，真实属性如下：
| 属性 | 含义 |
|---|---|
path | 包级发布路径 |
fileName | 发布文件名 |
branchPath | 包级分支路径 |
packageCount | 包级输出数量 |
genCode | 是否为该包生成代码 |
codePath | 该包代码输出路径 |
useGlobalAtlasSettings | 是否使用全局图集设置 |
atlasList | 包级图集设置列表 |
excludedList | 发布排除列表 |
说明：
PublishSettings不是settings/Publish.json的顶层结构，而是单个包发布配置对象。- 包级设置里可以单独定义图集列表，也可以指定使用全局图集设置。
- 工程
package.xml中的publish节点正式支持name、path、branchPath、packageCount、genCode、codePath、maxAtlasSize、sizeOption、square、rotation、multiPage、extractAlpha、maxAtlasIndex、excluded，以及稀疏的包级图集子节点<atlas name="Default" index="0" compression="true"/>。缺少maxAtlasSize表示使用全局图集设置；maxAtlasIndex默认是10，图集子节点只记录实际命名或启用压缩的槽位。 - 工程
package.xml的packageDescription根节点正式支持compressPNG、jpegQuality与派生的hasFavorites；未设置的图片压缩选项保持省略，hasFavorites仅在包内存在收藏资源或资源文件夹时写为true。UAM 同时承载根节点压缩值与完整包级 publish 快照，lift/materialize 不会丢失这些字段。 <publish><atlas>是工程源配置，与发布/二进制读取后Package.listAtlases()中的生成 atlas 分离；ProjectWriter 只从源配置写回<publish><atlas>，不会把生成 atlas 反写到package.xml。
updatePackageSettings 使用包含 compressPNG、jpegQuality 和完整 publish 的单包快照，删除字段通过提交新的完整快照表达；相同快照以 package_settings_unchanged 拒绝。包名和输出路径必须是安全的相对路径，JPEG 质量范围是 1–100，包级 atlas 最大尺寸范围是 1–16384，maxAtlasIndex 范围是 0–255；稀疏 atlas 索引必须唯一且不超过该上限。excludedResourceIds 保存 CSV-safe 的资源 ID，可以保留当前工程中不存在的 ID，读取与写回不会把它误判为悬空引用。
发布时，显式调用参数优先于包级 atlas 设置，包级设置在 useGlobal=false 时优先于全局发布设置；extractAlpha 与 maxAtlasIndex 始终读取包级正式值。包级设置控制最大尺寸、pot / npot / mof、正方形、旋转和分页，Layabox 目标强制禁用旋转。excludedResourceIds 从发布闭包移除对应资源；Unity 的 extractAlpha 输出无 alpha 的主图集与 !a.png alpha 图集。
组件 XML 的列表清理与属性覆盖
组件根扩展、ComboBox 组件实例和 List/Tree 显示节点使用正式的 autoClearItems 布尔属性；缺省值为 false，仅在启用时写出。组件实例与静态列表项的有序 <property target="..." propertyId="..." value="..."/> 子节点由 UAM 正式属性承载，读取、物化、保存和重新加载均保持原顺序与原始字符串值，包括前后空白、纯空白和空字符串。target 必须非空，propertyId 必须是非负安全整数，value 必须存在；无效输入在物化或写回前拒绝。
发布投影会执行清理语义：Loader / Loader3D 的 clearOnPublish 清空 URL，文本的 autoClearText 清空内容，List / Tree 的 autoClearItems 和 ComboBox 实例的 instanceAutoClearItems 清空静态项；资源闭包按清理后的值收集引用，工程源模型保持不变。
组件根的 designImage、designImageForTest、pageController、showSound 和 hideSound 作为正式 authoring 属性读写；designImageAlpha 缺省为 50。设计图必须引用 image 资源，出场/退场音效必须引用 sound 资源，pageController 必须指向本组件控制器。Label、ComboBox 和 ProgressBar 组件实例的音效覆盖使用 sound 与百分比 volume，ComboBox 另以 titleColor 和 direction（auto / up / down）保存标题颜色与弹出方向。
组件根的自定义扩展 ID 使用编辑器协议拼写 customExtention；Controller page 的备注使用 <remark page="索引" value="..."/> 子节点；Loader 的错误占位开关使用 errorSign。三者均由正式属性模型、UAM 与工程 XML 读写承载，Controller page 备注不进入运行时二进制。
List/Tree 的 autoItemSize 缺省值随布局变化：single column/row 为 true，flow/pagination 为 false；只有与布局缺省值不同时才写出。Button 根扩展使用 none / dark / scale 字符串枚举保存 downEffect。Transition 使用 frameRate 保存非 24 的帧率。
组件 XML 的整数几何字段
FairyGUI 工程 XML 中由桌面编辑器按有符号 32 位整数读取的几何值，写出时统一向零截断。非有限值或截断后超出 -2147483648 至 2147483647 的值会拒绝写出。
整数几何字段包括：
- 显示节点的
xy、size、restrictSize。 - 组件根的
size、restrictSize、margin、scrollBarMargin、clipSoftness与designImageOffsetX/Y。 - List/Tree 的
margin、scrollBarMargin与clipSoftness。 gearXY的 x/y，以及gearSize的 width/height。
pivot、scale、skew、gearXY 的百分比和 gearSize 的缩放值继续保留小数。
组件根及支持 pivot 的显示标签在 anchor="true" 时保留 pivot="0,0"，零坐标不取消锚点语义。.fairy 的工程类型完整写回 Unity 至 Vision 的 13 种正式类型；未知类型在写入前拒绝。
UAM 的 XY Gear 状态与默认值使用 x/y 和可选的 px/py；启用 positionsInPercent 时，显式状态值必须提供成对的有限 px/py，比例 0.5 表示 50%。默认值 null 表示未提供默认覆盖，保存时保持省略。每个显示节点的同一种 Gear 只允许绑定一次；需要更换控制器时移除后重新添加，Display 和 Display2 可共存。
Size、Look、Color、Animation 与 FontSize Gear 同样以 defaultValue: null 表示未提供默认覆盖，不以固定状态替代。XML 的 delay 保留为 tweenDelay；关闭补间也保留非默认的 ease、duration 和 delay。组件实例的 controller 属性通过正式 UAM controllerOverrides 保留，含其控制器及页面选择。
Text/Icon Gear 按页保留未覆盖值、空字符串和普通 - 文本，默认值也区分未覆盖与显式清空。工程 XML 的 values 以 | 分隔页面；每页文本含 | 尚无已验证的官方无损表示，ProjectWriter 在任何写入前拒绝该类输出。默认值中的 | 不受此分隔限制；UAM、Document 与二进制保留完整字符串。
发布资源闭包包含组件根的 showSound / hideSound：同包未导出音效会随引用组件发布，跨包音效形成包依赖。
工程资源树元数据
package.xml 与 package_branch.xml 的 component/asset 资源节点使用 exported="true" 与 favorite="true" 记录导出和收藏状态；未导出、未收藏时省略对应属性。SWF 使用正式的 SwfResource 模型读写 <swf> 节点，并通过 UAM swf 资源保留源文件、导出状态与收藏状态。UAM 通过 resource.exported、resource.favorite 承载这些字段，公开事务分别使用幂等的 setResourceExported、setResourceFavorite 设置目标布尔值。
每个 package 通过正式的 branchNames 顺序记录自身出现的资源分支，并以 package.xml 根节点的同名 JSON 数组属性持久化。工程读取时使用该顺序建立映射；二进制发布时同一顺序定义该 package 的 branchItemIds 槽位，不能按工程根分支顺序重新推导。未显式设置包内表的 Document 调用会从实际分支资源按工程分支顺序推导后再发布。
公开事务 addBranch、renameBranch、removeBranch 维护按名称排序的工程分支注册表。重命名会原子更新资源、资源文件夹和包内分支表，但保持每个包已有槽位位置不变；删除只允许空且没有变体 ID 映射的分支。分支名必须是安全、非保留的单个路径段。编辑器当前激活分支属于本地界面状态，不在这些工程事务中修改。
ProjectWriter 会为每个工程分支保留 assets_<branch>/，并为包内空分支槽位写出空的 package_branch.xml，因此空分支和包内分支子集都能在 ProjectReader reload 后恢复。重命名或删除成功保存后，仅以非递归目录删除清理已移除的受控分支目录。
旧文件与目录清理使用存储适配器提供的现有路径身份；大小写别名解析到当前输出时不删除，大小写敏感存储仍区分不同文件。包和分支的全部图片排序提示在首次文件写入前验证，缺失、跨包、跨分支或循环锚点均拒绝写入。
资源文件夹由 package.folders 正式承载 branch / path / favorite / atlas。文件夹路径使用以 / 开头和结尾的规范形式，根目录是隐式节点；实际 assets[/_<branch>]/<包名>/ 目录是存在性的事实来源，<folder> 节点只写入需要持久化的收藏或图集元数据。setResourceFolderFavorite 可更新既有主分支或资源分支文件夹的收藏状态，且单个操作只修改 selector 指定的文件夹；需要匹配编辑器的后代收藏行为时，调用方应在同一事务中显式提交后代文件夹与资源收藏操作。公开事务 addResourceFolder、renameResourceFolder、moveResourceFolder、removeResourceFolder 只操作空文件夹；父目录必须存在，根目录、路径冲突和非空操作会在提交前拒绝。浏览器存储适配器须提供非递归 rmdir，保存成功后才清理被移除的空目录。
setResourceFolderAtlas 以规范 branch + path selector 更新既有文件夹的 source Atlas 槽位。空字符串清除覆盖；非空值必须是 0..maxAtlasIndex 范围内且没有前导零的十进制字符串，Atlas 名称不作为引用值。addResourceFolder.atlas 使用相同校验，未显式配置 package publish 时上限默认为 10。同一事务需要扩大上限时，必须先提交 updatePackageSettings，再提交文件夹 Atlas 操作；相同赋值以 resource_folder_atlas_unchanged 拒绝。
主 package.xml 的 packageDescription@hasFavorites 由包内资源与资源文件夹的收藏状态派生，不作为独立可编辑状态。收藏状态只影响编辑器工程数据，不进入运行时二进制发布协议。
工程图片资源属性
package.xml 与 package_branch.xml 的 image 资源属性由 UAM resource.image 完整快照承载，包括纹理集模式、质量选项与自定义质量、平滑、边缘复制、缩放模式、九宫格和 tile-grid 位掩码。公开事务 setImageResourceProps 只替换这份正式属性快照，不修改图片 source bytes；非图片 selector、不完整快照、非法缩放模式、九宫格或位掩码会在写回前被拒绝。
图片 source bytes 通过 replaceResourceBytes 更新时，当前只支持 PNG 与常见 8-bit Huffman JPEG。preflight 会检查 PNG 的 chunk CRC、zlib/scanline 边界和容器顺序；JPEG 除检查 quantization/Huffman table、frame/scan 顺序及编码约束外，还会完成像素解码。两者都会核对实际格式与操作时、最终文件扩展名；畸形或不匹配返回 invalid_resource_bytes，SVG、WebP、GIF、PSD、TGA 等未支持格式返回 unsupported_resource_mutation。浏览器 backend 通过 applyUamTransactionAsync 在包内 Web Worker 中执行相同的严格校验，browser 环境误用同步入口会直接拒绝而不会在主线程扫描或解码。消费端 bundler 必须把公开入口 @openfairygui/core/image-validation-worker 再打成与主 bundle 相邻的 self-contained ESM image-validation-worker.js；仅重打主入口或只复制 worker 文件不会带上其解码 chunk。Worker 无响应会在 10 秒后终止。浏览器 source 上限为 8 MiB，decoded raster 上限为 8,388,608 pixels；Node/CLI 同步校验的 source/PNG decoded bytes 上限为 128 MiB，JPEG 严格解码另限 8,388,608 pixels 与 64 MiB。
有效替换会从 bytes 派生新的 raster 宽高，并在同一内存 transaction 中原子投影到 UAM 与 Document。后续 Node Backend Save 在同级 staging 中完成全工程写回，并仅在全部成功后切换目录；浏览器 storage 是否具备同等级别的文件系统原子性由 adapter 的 runProjectWriteTransaction 能力决定。ProjectReader 在请求 hydrateResourceBytes 时以可解析且字段合法的 PNG IHDR / JPEG SOF header 覆盖陈旧 XML 尺寸，不在批量水合时扫描完整容器或重复执行像素解码；SVG 继续使用工程声明尺寸。
工程 MovieClip 资源属性与 JTA 事务
package.xml 与 package_branch.xml 的 movieclip 资源使用 atlas 记录纹理集模式，并使用 smoothing 记录平滑设置。缺少 smoothing 时按 true 读取；写回时仅为非默认值输出 smoothing="false"。MovieClip 资源使用正式的 UamMovieClipResource.movieClip 快照承载 interval、repeatDelay、swing、smoothing 和逐帧矩形/附加延迟/sprite id，不读取旧式 metadata 属性袋。
ProjectReader 水合 JTA v100-v102 时，以 source bytes 派生尺寸、播放 timing 与帧列表；fps === 0 按 24 归一，负值无效，毫秒字段使用整数截断。无法解析派生模型时仍保留原始 source bytes 和 XML 属性。JTA 不携带的 smoothing 继续以 XML/UAM 为事实来源。
addResource、包含 MovieClip 的 addPackage 与 replaceResourceBytes 会先完成有边界的 JTA 解析，再在同一个原子 transaction 中替换 bytes 和重建模型。解析失败统一返回 invalid_movie_clip_jta；UAM project、backend revision/dirty 与 storage 均保持不变。MovieClip 不经过图片 raster worker，所以 Browser 与 Node 使用相同的 Core parser 和派生规则。Save/reload 与 inverse/save/reload 都从持久化的 JTA source 重建同一模型。
当前发布输出路径解析
发布时显式传入的输出目录优先于设置文件。未传入时，当前选择顺序如下：
- 活跃分支发布的包级
branchPath，再到全局branchPath。 - 包级
path。 - 全局
path。
选中的相对路径以工程根目录为基准；若以上都未配置，发布不会隐式选择输出目录。
工程及包级 path / branchPath 先以发布名称替换 {publish_file_name}（不含扩展名），再按 CustomProperties.json 的属性顺序替换 {变量名}，最后解析相对路径。未知变量保持原样；显式 output 作为调用方路径直接使用。工程及包级 codePath 同样展开自定义变量。
浏览器 Laya 发布在显式 output 下不会使用工程或包内的桌面输出路径；显式 branch、packages、compressed 与 atlas 也保持调用参数优先。未显式覆盖时，持久化的压缩、图集和安全文件扩展名设置直接驱动输出。当前浏览器宿主不提供代码生成；全局允许且任一选中包启用 genCode 时，发布会在 Canvas 检查和文件写入前以 unsupported_publish_setting（含 setting 与 path）拒绝。失败结果的 files 只包含已经完成 writeFileRaw 的文件，因此 success=false 且列表非空表示内置输出已部分写入；需要原子发布的宿主必须提供事务式或 staging 输出文件系统。
当前发布完整性要求
位图字体在资源筛选前读取所属分支的 .fnt，由纹理及字形图片建立发布依赖闭包，包含未显式导出的图片；合并分支时字形引用同步映射到发布 ID。assets_<branch> 字体不读取主分支同名 .fnt。TTF/TTC/OTF 是引擎字体：文本写入字体资源名称，不生成空位图 Font 项，也不因该字体 URL 增加包依赖。
同一 Document 重复发布时，图集成功生成后替换旧 Atlas/Sprite，生成失败保留之前完整的图集。发布集合由资源导出状态和依赖重新计算，之前生成的 Sprite 不构成新的发布依据。
这些要求是 OpenFairyGUI 当前发布执行时的能力边界，不是新增的编辑器设置字段：
| 条件 | 当前行为 |
|---|---|
| 已解析到发布输出目录 | 必须提供输出文件系统；缺失时不会把流程当作发布成功 |
| 有需要封包的图像或动画帧 | 必须提供 raster encoder、源资源路径和 atlas 输出目录 |
| 图集装箱、图像读取或合成失败 | 中止发布，不生成带透明空洞或缺页的成功结果 |
| 发布集合包含 MovieClip | 按 JTA 长度表读取 PNG / JPEG（可混合）纹理；重复 texture index 复用首次引用帧的 sprite，-1 表示空帧。所有选中包会先完成 JTA 解析、严格 PNG/JPEG 校验、引用纹理完整解码与规范化缓存；越界索引、被引用的空纹理、未支持格式、截断数据或解码失败会在创建任何 OpenFairyGUI 内置输出目录或写入内置发布文件前中止整次发布 |
SoundResource、MiscResource、SpineResource、DragonBonesResource 及其依赖复制失败 | 中止发布，不把缺失的 runtime 资源降级为 warning |
未请求任何输出目录时，低层 publish() 可以只计算 layout；这不是文件发布，也不会写出二进制或资源文件。标准 Node 工作流应使用 publishNode()。
标准 Node adapter 在显式传入 output 时，会先把该目录复制到同级 staging 目录，完整发布成功后再以目录切换提交；内置 runtime 输出或 onPublishEnd 失败时，原输出目录保持不变。按工程/包设置解析出的多个输出目录、自定义低层文件系统、输出目录外的 codegen，以及插件通过 basePath 或其他路径产生的副作用不在这项目录级保证内，应由宿主或插件提供自己的 staging/回滚策略。
publishNode() 成功返回 { files: [{ path, size }] }，记录内置文件系统与图集 writer 实际写入的文件，路径为提交后的绝对路径、size 为字节数；测量在暂存目录提交前完成。清单包含经 publish 文件系统写入的代码，不含旧目录未改动文件、删除项或插件绕开该文件系统的任意 I/O。失败仍抛错，不返回成功清单。CLI publish --json 直接包装这一结果，不自行推测输出文件名；机器输出与退出码见可运行示例。文件命名与二进制协议未因此改变。
代码生成的当前实现范围
OpenFairyGUI 当前已经把“代码生成”接入现有 publish 流程，但实现范围仍是正式收口的一条首发口径，不是编辑器全部模板矩阵。
| 条件 | 当前行为 |
|---|---|
全局 codeGeneration.allowGenCode=false | 不生成代码 |
包级 publish@genCode=false 或未开启 | 该包不生成代码 |
包级 publish@codePath 有值 | 优先使用包级代码输出路径 |
包级 publish@codePath 为空 | 回退到全局 codeGeneration.codePath |
Unity 项目，且 codeType 为空字符串 | 生成 Unity 风格 .cs 代码 |
| Laya / Cocos Creator 项目 | 生成共享的 fgui TypeScript 代码 |
| 其他项目类型 | 当前未实现，跳过生成 |
当前正式落地的代码生成口径如下：
包名、组件名和成员名中的汉字转为逐字拼音，ASCII 名称保持原有大小写规则；多音字采用词典默认读音。组件按 ID 排序后分配名称；同一包内重名或仅大小写不同的类名依次加 _2、_3，并避开 Binder 名称。成员名冲突也分配唯一后缀。引用类型、文件名和 Binder 使用同一组最终类名。
| Lane | 输出项 | 当前行为 |
|---|---|---|
Unity + 空 codeType | 输出目录 | codePath/<规范化包名>/ |
Unity + 空 codeType | 组件类 | 每个导出组件生成一个 .cs 类文件 |
Unity + 空 codeType | Binder | 每个包生成一个 包名Binder.cs |
Unity + 空 codeType | 清理规则 | 只清理当前包输出目录下、带 FairyGUI 自动生成标记的旧 .cs 文件 |
共享 fgui TypeScript 模式（Layabox / Cocos Creator） | 输出目录 | codePath/<规范化包名>/ |
共享 fgui TypeScript 模式（Layabox / Cocos Creator） | 组件类 | 每个导出组件生成一个 .ts 类文件 |
共享 fgui TypeScript 模式（Layabox / Cocos Creator） | Binder | 每个包生成一个 包名Binder.ts |
共享 fgui TypeScript 模式（Layabox / Cocos Creator） | 运行时口径 | 使用 fgui 与 UIObjectFactory.setExtension(...) |
共享 fgui TypeScript 模式（Layabox / Cocos Creator） | 清理规则 | 只清理当前包输出目录下、带 FairyGUI 自动生成标记的旧 .ts 文件 |
说明：
- 这里描述的是 OpenFairyGUI 当前已实现行为，不等同于 FairyGUI 编辑器所有项目类型 /
codeType模板都已支持。 - 这里的
fguiTypeScript 代码生成口径已经不再依赖codeType字段分流；Layabox 与 Cocos Creator 共用 TS 模板，Cocos Creator 生成文件会显式导入fairygui-cc，Layabox 继续使用宿主提供的全局fgui。 publish流程也支持 OpenFairyGUI publish 插件接管代码生成。插件目录、生命周期、失败降级，以及与 FairyGUI 编辑器插件的关系见 Publish 插件。
包级图集设置真实属性
AtlasSettings 是单个图集项的真实属性对象：
| 属性 | 含义 |
|---|---|
name | 图集名称 |
compression | 是否压缩 |
extractAlpha | 是否提取 alpha |
packSettings | 打包参数对象 |
其中 packSettings 由 PackSettings 承载，编辑器通过它控制更细的打包行为。
默认值
以下默认值来自编辑器 GlobalPublishSettings.read() 的真实行为：
| 属性 | 默认值 / 规则 |
|---|---|
path | 空字符串 |
branchPath | 空字符串 |
packageCount | 2 |
compressDesc | true |
binaryFormat | true |
includeHighResolution | 0 |
branchProcessing | 0 |
classNamePrefix | UI_ |
memberNamePrefix | m_ |
ignoreNoname | false |
codeType | 空字符串 |
allowGenCode | true |
atlasSetting.maxSize | 2048 |
atlasSetting.paging | true |
atlasSetting.sizeOption | pot |
atlasSetting.forceSquare | false |
atlasSetting.allowRotation | false |
atlasSetting.trimImage | 项目版本号 >= 500 时默认 true，否则使用旧默认逻辑 |
jpegQuality | 80 |
fileExtension 的当前实现规则
fileExtension 在 OpenFairyGUI 当前实现中不是完整复刻编辑器全部项目类型矩阵，而是基于已落地的发布逻辑生效。当前正式行为如下：
| 场景 | 结果 |
|---|---|
| Unity 项目 | 固定为 bytes |
Cocos Creator 项目，且 Publish.json 显式设置了 fileExtension | 使用设置值 |
Cocos Creator 项目，且 Publish.json 未显式设置 fileExtension | 默认使用 bin |
其他非 Unity 项目，且 Publish.json 显式设置了 fileExtension | 使用设置值 |
其他非 Unity 项目，且 Publish.json 未显式设置 fileExtension | 回退为 fui |
CLI 显式目标覆盖
ofgui publish --project-type layabox 表示按 Layabox 目标发布，而不只是修改工程类型字段。命令会在读取工程设置后应用以下目标规则：
- 描述文件扩展名使用
fui - atlas 禁止旋转，确保产物可由当前 FairyGUI-Layabox 运行时正确消费
includeHighResolution、压缩、atlas 尺寸、分页和裁边等 Layabox 支持的设置继续使用工程配置。未提供 --project-type 时，仍遵循上表的工程设置规则。
Unity 与 Cocos Creator 运行时不解压二进制描述文件，因此这两个目标始终输出未压缩数据。若 API 或 CLI 对它们显式请求 compressed=true / --compressed，发布会直接报错；工程中持久化的 compressDesc 不会覆盖该目标约束。Layabox 继续使用工程中的压缩设置。
当前仓库已正式覆盖的非 Unity 二进制发布口径包括：
- Layabox：样例工程使用
binaryFormat=true和fileExtension="fui"，发布结果为包名.fui - Cocos Creator：未显式设置
fileExtension时默认发布为包名.bin
编辑器文档中其他项目类型的默认扩展名矩阵，目前不应直接视为 OpenFairyGUI 已实现行为；若仓库尚未实现对应项目类型发布规则，应从当前实现文档中删除，或明确标注为“未实现”。
fileExtension 的编辑器参考矩阵
下面这张表保留的是 FairyGUI 编辑器侧的项目类型规则，用作后续实现对齐时的参考索引；它不代表当前 OpenFairyGUI 已全部实现这些项目类型的发布行为。
| 项目类型 | 结果 |
|---|---|
| Unity | 固定为 bytes |
| Cocos2dx / Vision | binaryFormat=true 时为 fui，否则为 bytes |
| Cry / Monogame / Corona | 固定为 fui |
| CocosCreator | 未显式设置时默认 bin |
| H5 项目 | 未显式设置时默认 fui |
| 其他项目 | 未显式设置时默认 zip |
高分辨率与分支相关属性
| 属性 | 含义 |
|---|---|
includeHighResolution | 位掩码字段，用于表示是否包含 2x / 3x / 4x 资源 |
branchProcessing | 分支处理模式 |
branchPath | 分支输出路径 |
seperatedAtlasForBranch | 分支 atlas 是否单独输出 |
includeHighResolution 可以理解为 2x、3x、4x 资源开关对应的位掩码字段：@2x=1、@3x=2、@4x=4。
发布流程只发现并链接工程中已经存在的同路径、同分支、同类型 @2x / @3x / @4x 资源，例如 icon.png 对应 icon@2x.png。它们会作为独立 image / movieclip package item 写入，再由基础 item 的 high-resolution 列表引用；发布期不会主动把原始位图缩放或放大生成高分辨率资源。
branchProcessing 当前可见语义如下：
| 值 | 编辑器行为 |
|---|---|
0 | 主干包含所有分支，发布结果保留主干与全部分支内容，输出路径使用 path |
1 | 主干合并活跃分支，发布结果只保留主干与当前活跃分支合并后的内容；主干输出到 path，非主干分支输出到 branchPath/<branch>（若 branchPath 有值） |
seperatedAtlasForBranch 当前可见语义如下：
| 条件 | 编辑器行为 |
|---|---|
branchProcessing=0 且 seperatedAtlasForBranch=false | 主干与分支资源可以进入同一组 atlas 页 |
branchProcessing=0 且 seperatedAtlasForBranch=true | 主干 atlas 与分支 atlas 分开输出；分支 atlas 文件名带 _branchName 后缀，例如 atlas0_dev.png |
branchProcessing=1 | 发布结果已完成分支合并，seperatedAtlasForBranch 不再单独生效 |
编辑器写回行为
编辑器在写回 Publish.json 时，当前规则包括：
| 项目 | 写回规则 |
|---|---|
branchPath | 仅在有值时写出 |
fileExtension | 仅项目支持自定义扩展名时写出 |
includeHighResolution | 仅大于 0 时写出 |
branchProcessing | 仅大于 0 时写出 |
atlasSetting.maxSize | 非 2048 时写出 |
atlasSetting.paging | 为 true 时写出 |
atlasSetting.forceSquare | 为 true 时写出 |
atlasSetting.allowRotation | 为 true 时写出 |
atlasSetting.trimImage | 为 true 时写出 |
compressPNG / jpegQuality | 仅项目不支持 atlas 时写出 |
工程写回联动边界
组件 XML 往返保留受支持的属性值和有序子节点，不承诺保留源文本的属性排列。属性排列不承载语义；Gear、relation、扩展覆盖及列表条目等子节点仍按各自协议顺序处理。
恢复工程中的图片可省略 package.xml 的 width、height，以免把发布资源推导尺寸当作原工程显式声明；图片重建仍保留可用尺寸。该省略规则不改变普通工程中已声明尺寸的写回。
恢复生成的字体纹理和字形图片在相同包与分支中跟随对应字体，纹理先于字形，同类图片按资源 ID 顺序排列；这不改变资源的 ID、引用或图片内容。
工程根 .fairy 文件的 projectDescription.id / type / version 统一通过 XML 属性渲染器写出；引号、 尖括号、换行和 & 等字符会转义，并在再次读取时还原为原属性值，不会形成额外 XML 属性。
发布设置不改变 component.xml 的 authoring 属性语义。工程读写会独立保留组件根属性、根组件 customProperty 定义，以及组件引用的 Button、Label、ComboBox、ProgressBar、Slider、 ScrollBar 实例扩展覆盖；对应 XML 协议见 Project XML 属性协议。
列表与树节点的布局、渲染顺序、滚动区域、静态条目和树行为属性也按该 XML 协议独立读写； 其中 renderOrder="arch" 使用 apex 记录顶点子项，树节点通过 treeView、indent 和 clickToExpand 保留树行为。
文档边界
| 项目 | 约束 |
|---|---|
| 本文关注点 | 只记录编辑器真实属性、默认值和序列化规则 |
| 不写内容 | 不引入项目内部类型、字段映射或实现细节 |
| 文档边界 | 本页只描述编辑器设置协议本身，不描述具体项目如何消费这些属性 |