1. 项目概述为什么我们要深挖一个INI文件如果你在UE5里用过Paper2D插件不管是做2D横版游戏、UI动效还是简单的精灵动画大概率都接触过那些Sprite、Flipbook之类的资产。但不知道你有没有好奇过当你创建一个新的Paper2D精灵时引擎背后那些默认的网格体密度、碰撞精度、导入设置是从哪来的为什么有时候导入的序列图帧率不对或者碰撞生成得奇奇怪怪这些看似“默认”的行为其实都藏在一个不起眼但至关重要的配置文件里BasePaper2D.ini。这个文件是Paper2D插件的“出厂设置”总纲。它不像.cpp或.h文件那样充满逻辑也不像蓝图那样直观可视但它定义了整个2D工作流的基石。很多开发者遇到Paper2D相关的问题比如导入的像素画边缘有白边、碰撞体生成过于耗性能、或者动画播放不流畅翻遍项目设置和编辑器菜单也找不到根因其源头往往就在这个INI文件的配置项里。直接修改引擎源码是重型操作而理解并合理调整这个INI文件则是一种更轻量、更安全的“微调”手段。我最初注意到这个文件是在为一个横版动作游戏优化资源导入流程时。团队的美术同学抱怨他们精心绘制的像素角色导入后自动生成的碰撞体总是多出一圈“空气墙”导致角色感觉浮空。我们检查了所有Sprite的设置都没问题。最后我抱着试试看的心态翻开了引擎目录下的BasePaper2D.ini才在DefaultCollisionDomain和CollisionThickness等参数上找到了答案。那次经历让我意识到读懂这个配置文件就等于拿到了优化Paper2D工作流、甚至解决一些疑难杂症的“后门钥匙”。今天我就带你一起像读代码一样逐行解读BasePaper2D.ini的源码。我们不止看它“是什么”更要弄明白每个配置项“为什么”这么设计以及在实际项目中“怎么用”和“怎么改”。无论你是想深度定制2D导入管线还是单纯想解决手头的一个Paper2D小麻烦这篇文章都能给你提供清晰的路径。2. BasePaper2D.ini文件定位与结构总览2.1 文件在哪里多重配置的优先级之谜首先我们得找到它。在UE5的引擎源码目录中BasePaper2D.ini的典型路径是[YourEnginePath]\Engine\Plugins\2D\Paper2D\Config\。注意这里说的是引擎源码或安装目录下的“基础”配置文件。它定义了Paper2D插件的默认行为。但是直接修改引擎目录下的文件是极其不推荐的因为引擎更新会覆盖你的修改并且会影响所有使用该引擎的项目。UE的配置系统遵循一套覆盖优先级规则理解这个规则是安全定制的前提引擎默认配置 (BasePaper2D.ini)位于引擎插件目录提供最基础的默认值。这是我们的“源码”解读对象。引擎覆盖配置 (DefaultPaper2D.ini)位于[YourEnginePath]\Engine\Config\。你可以在这里放置针对该引擎版本的、项目无关的覆盖设置。它的优先级高于Base文件。项目默认配置 (DefaultPaper2D.ini)位于你项目的Config\文件夹根目录。这里定义的配置会覆盖引擎级别的设置并且只影响当前项目。这是最常用、最安全的定制位置。项目平台/用户配置如DefaultPaper2D.ini的平台覆盖版本或编辑器的用户设置优先级更高但使用场景较少。实操心得99%的情况下你的定制都应该发生在项目的Config\DefaultPaper2D.ini里。如果这个文件不存在就自己创建一个。这样做的好处是配置与项目绑定可以纳入版本控制并且完全不影响引擎本身或其他项目。在开始解读具体条目前先在项目里创建好这个文件。2.2 文件结构解析章节化的配置哲学用文本编辑器打开BasePaper2D.ini你会发现它遵循标准的INI文件格式由一个个用方括号[]括起来的“节”Section组成。每个节下包含若干“键值”KeyValue对。Paper2D的配置主要围绕几个核心功能模块展开[/Script/Paper2D.PaperRuntimeSettings] ... (运行时行为相关设置) [/Script/Paper2D.PaperImporterSettings] ... (资源导入相关设置) [/Script/Paper2D.PaperEditorSettings] ... (编辑器特有行为设置)这种以/Script/开头的节名是UE将配置与特定C类绑定的方式。例如/Script/Paper2D.PaperRuntimeSettings里的所有配置项最终都会影响UPaperRuntimeSettings这个类的默认属性值。这意味着你的任何修改都是在覆盖这些C类对象的默认构造参数。为什么这么设计这体现了UE配置系统的灵活性。它允许开发者在不重新编译引擎或插件代码的情况下通过文本文件来调整深层行为。对于Paper2D这样的插件美术、策划甚至技术美术都可以通过修改易懂的INI文件来调整工作流而不必求助于程序员修改C代码。3. 核心配置节深度解读与实战应用接下来我们进入核心部分逐节拆解关键配置项。我会为每个重要参数解释其含义、默认值背后的考量以及你在什么情况下需要调整它。3.1 [/Script/Paper2D.PaperRuntimeSettings] - 定义运行时行为这个节下的配置影响游戏运行时的2D渲染和物理行为。修改后通常需要重启编辑器或游戏才能生效。bEnableSpriteAtlasGroups(默认: True)这个布尔值控制是否启用Sprite图集组Sprite Atlas Group系统。图集组是Paper2D用于合批绘制、优化性能的高级功能。当它为True时引擎会尝试将多个精灵纹理打包到更大的图集纹理中减少Draw Call。为什么需要它在移动平台或需要绘制大量2D精灵的场景中每个精灵单独绘制一次一个Draw Call是性能杀手。启用图集后多个精灵可以合并到一次绘制中。什么时候关闭如果你的项目精灵数量很少或者每个精灵都巨大且独特图集化可能带来不必要的内存开销巨大的图集纹理和复杂度。在开发初期进行性能剖析时可以尝试关闭它以对比性能。实操要点保持默认的True即可。真正的优化在于合理设置图集组的大小和策略这通常在各个Sprite资产或材质中配置。bEnableTerrainSplineEditing(默认: True)启用Paper2D地形样条编辑。这是用于创建2D可变形地形如《雷曼》中的可拉伸土地的工具。什么时候关闭如果你的项目是纯粹的硬表面横版过关或RPG完全用不到可变形地形可以设置为False以节省微小的运行时开销和编辑器UI复杂度。bResizeSpriteDataToMatchTextures(默认: False)一个历史遗留兼容性选项。如果为True当精灵的源纹理尺寸发生变化时会尝试自动调整精灵的几何数据如网格、碰撞体以匹配。强烈建议保持False。自动调整几何数据很容易导致不可预知的后果比如精心调整的碰撞体形状错乱。纹理尺寸变更应该是一个需要人工检查的手动过程。DefaultPixelPerUU(默认: 1.0)这是极其重要的一个参数。它定义了“每Unreal单位对应多少个像素”Pixels Per Unreal Unit。简单说它建立了2D美术资源像素与3D世界空间UU的换算关系。默认值1.0意味着什么一个100x100像素的精灵导入后在世界中的尺寸默认是100x100 Unreal单位。在UE中1个Unreal单位通常被视为1厘米。所以这个100像素的精灵默认就有1米见方这可能非常大如何调整你需要根据你的游戏风格和美术资源决定。对于像素风游戏你可能希望一个角色精灵比如32x64像素在游戏中高度约为1.6米64 UU。那么你的DefaultPixelPerUU可以设为1.064像素64UU0.64米这里需要计算。更常见的做法是如果你希望精灵的“像素”与屏幕“像素”有更直观的对应比如像素完美渲染可能会设置为0.01100像素1UU1厘米或0.110像素1UU1厘米然后在相机和材质中做进一步调整。这个值需要在项目初期和美术统一约定一旦确定尽量不要中途更改否则所有已导入资产的尺寸都会变化。bOverrideDefaultSpriteMaterial(默认: False) 和DefaultMaskedMaterial/DefaultOpaqueMaterial是否覆盖默认的精灵材质以及指定覆盖用的材质路径。应用场景Paper2D默认使用内置的SpriteMaterial。如果你的项目有统一的、自定义的着色器需求比如所有精灵都需要某种特定的颜色混合模式、顶点动画或后期效果可以创建一个自定义材质在这里指定其路径例如/Game/MyMaterials/MySpriteMaterial.MySpriteMaterial并将bOverrideDefaultSpriteMaterial设为True。注意事项你指定的材质必须继承自Paper2D相关的材质父类如MaterialInstance的父材质是M_Sprite以确保其拥有精灵材质必需的参数如Sprite Texture。3.2 [/Script/Paper2D.PaperImporterSettings] - 掌控导入管道这个节的配置决定了当你从外部如PNG、PSD文件导入资源到Paper2D资产Sprite, Flipbook等时引擎默认采取的行为。这是问题的高发区也是优化工作流的关键。TexturePageSize(默认: 2048)当导入精灵或创建图集时纹理页Texture Page的默认最大尺寸宽度和高度。值必须是2的幂次方如512, 1024, 2048, 4096。性能与内存权衡较大的尺寸如4096可以容纳更多精灵减少图集数量但会显著增加GPU内存占用并且某些低端移动设备可能不支持大于2048的纹理。较小的尺寸如512内存友好但可能导致图集碎片化需要更多张图集增加Draw Call。选型建议对于现代PC和主机2048或4096是安全的。对于移动端特别是低端安卓设备建议从1024开始测试。你可以在项目设置中为不同平台配置覆盖值。bOverrideTextureCompression(默认: False) 和DefaultTextureCompressionSettings是否覆盖纹理压缩设置。Paper2D精灵的纹理默认使用TC_EditorIcon一种低质量的压缩这对于需要清晰显示的精灵尤其是像素画通常不合适。踩过的坑像素画导入后边缘模糊、出现色带很可能就是压缩导致的。最佳实践对于需要保持锐利边缘的像素艺术强烈建议设置bOverrideTextureCompressionTrue DefaultTextureCompressionSettingsTC_EditorIcon等等TC_EditorIcon不就是默认的吗这里容易混淆。实际上对于像素画你应该使用无压缩或矢量位移VectorDisplacement压缩后者在某些情况下能更好地保留细节。更常见的做法是在导入后在每个Sprite纹理资产的属性里手动将压缩设置为TC_EditorIcon它其实是一种简单的格式并非高质量或TC_HDR不压缩RGB。但通过INI统一设置更高效。你可以尝试设置为TC_Default然后在项目渲染设置中调整默认压缩。更精准的控制需要在纹理资产导入后单独设置其Compression Settings为UserInterface2D (RGBA)这通常需要在引擎的纹理编辑器中完成INI层面难以直接指定。DefaultPixelsPerUnit(默认: 1.0) 与DefaultMeshSubdivisions(默认: 1)这两个参数共同决定了精灵默认的网格密度。DefaultPixelsPerUnit和运行时的DefaultPixelPerUU概念类似但作用于导入时的网格生成。它表示“多少个像素对应网格的一个细分单位”。值越小网格越密。DefaultMeshSubdivisions网格的细分次数。为1时一个矩形精灵生成2x2的网格4个顶点。增加此值会生成更密的网格如2会生成3x3网格。为什么需要网格Paper2D精灵不是简单的四边形它是由三角网格构成的。这对于顶点动画、变形如弯曲的纸片效果以及某些光照效果是必需的。如何设置对于绝大多数静态精灵保持12x2网格就足够了这是性能最优的。只有当你计划对精灵进行复杂的顶点着色器变形时才需要增加细分例如制作一个可以弯曲的鞭子或飘动的旗帜。增加细分会显著增加顶点数影响性能。DefaultCollisionDomain(默认:TDCM_ConvexDecomposition)定义精灵自动生成碰撞体时使用的默认算法。这是解决文章开头“空气墙”问题的关键。TDCM_ConvexDecomposition凸包分解。引擎会尝试将精灵的透明轮廓分解成多个凸多边形。这是默认值因为它能生成相对准确且物理引擎Chaos高效处理的碰撞体。TDCM_AlphaTestGridAlpha测试网格。根据纹理的Alpha通道生成一个精确到像素的网格碰撞。这是最精确的能完美贴合精灵轮廓但性能开销最大碰撞体非常复杂。TDCM_ConvexHull凸包。生成一个包裹整个精灵轮廓的单一凸多边形。这是性能最好的但也是最不精确的会忽略所有凹进去的部分比如一个“C”形的精灵凸包会把它补成一个“O”形。TDCM_None不生成碰撞。选择策略精确碰撞如平台边缘、子弹命中对于小尺寸、形状复杂的精灵如角色使用TDCM_AlphaTestGrid但要注意控制CollisionThresholdAlpha阈值和MaxCollisionMeshVertices最大顶点数避免过于复杂。性能优先如背景装饰物使用TDCM_ConvexHull或TDCM_None。平衡之选通用TDCM_ConvexDecomposition并通过调整MaxCollisionMeshVertices和HullCount来控制精度和性能。这也是默认值的原因。CollisionThickness(默认: 10.0)为生成的2D碰撞体添加一个“厚度”使其在3D空间中成为一个有深度的“薄板”实际上是一个极扁的棱柱。单位是Unreal单位。“空气墙”问题的元凶如果你发现2D碰撞体在Z轴深度方向上也有体积导致角色在“面前”就被挡住就是因为这个值太大了。对于纯2D游戏所有物体在同一Z平面这个值应该设置得非常小比如0.1或1.0。调整建议在项目的DefaultPaper2D.ini中将其设置为一个很小的值例如CollisionThickness1.0。这能确保碰撞体在2D平面上有效同时在3D空间里几乎不占深度。MaxCollisionMeshVertices(默认: 50) 与HullCount(默认: 4)这两个参数用于控制TDCM_ConvexDecomposition算法的精度和复杂度。MaxCollisionMeshVertices限制生成的所有凸包碰撞体的总顶点数。顶点数越多形状越精确但物理计算开销越大。HullCount限制凸包分解的最大数量。算法会尝试用指定数量的凸包来近似精灵形状。调优技巧如果自动生成的碰撞体形状怪异或缺失部分可以尝试适当增加这两个值例如分别增加到100和8。但务必在性能可接受范围内。通常可以先增加HullCount如果形状仍不理想再增加MaxCollisionMeshVertices。使用编辑器的碰撞体预览功能在Sprite编辑器中实时查看调整效果。3.3 [/Script/Paper2D.PaperEditorSettings] - 优化编辑器体验这部分配置主要影响Paper2D资源在虚幻编辑器中的编辑和显示行为。bShowGridInSpriteEditor(默认: True)是否在Sprite编辑器中显示像素网格。对于像素美术工作者这个网格是精准对齐像素、查看UV拉伸的必备工具。建议保持开启。如果你觉得网格线干扰视线可以在Sprite编辑器窗口的视图选项里临时关闭而不是修改全局配置。DefaultBackgroundColor(默认:(R0.05,G0.05,B0.05,A1.0))Sprite编辑器、Flipbook编辑器等视图的默认背景色。接近黑色的深灰色是默认选择因为它能很好地突出显示大多数精灵且不刺眼。个性化定制如果你的美术资源主色调是深色可以将其调亮如(R0.2,G0.2,B0.2,A1.0)以获得更好的对比度。颜色值范围是0.0到1.0。bPickBestMaterialWhenCreatingSprite(默认: True)当通过纹理资产右键菜单创建精灵时是否尝试自动选择“最佳”材质实例。工作机制如果开启编辑器会检查纹理的Alpha通道。如果Alpha通道基本全不透明它会尝试使用不透明Opaque材质如果Alpha通道变化丰富则使用遮罩Masked材质。潜在问题这个“自动选择”有时会出错特别是对于带有复杂Alpha边缘如毛发的纹理它可能错误地判断为不透明。我的习惯我通常将其设置为False然后在创建精灵后手动指定材质。这样可以获得完全的控制权避免后续材质切换带来的意外。4. 实战定制项目专属的Paper2D配置理解了各个参数的含义我们现在来动手为你的项目创建一个定制化的DefaultPaper2D.ini。假设我们正在开发一款像素风格的2D横版游戏。步骤1在项目根目录创建文件在你的UE5项目文件夹内找到或创建Config文件夹在其中新建一个文本文件命名为DefaultPaper2D.ini。步骤2编写定制化配置将以下内容填入文件并附上详细注释说明你的设计决策; MyProject/Config/DefaultPaper2D.ini ; 专为 [我的像素横版游戏] 定制的Paper2D配置 ; 创建于2023年10月27日 ; 作者你的名字 [/Script/Paper2D.PaperRuntimeSettings] ; 启用图集组以优化运行时Draw Call bEnableSpriteAtlasGroupsTrue ; 我们的游戏不需要可变形地形关闭以简化 bEnableTerrainSplineEditingFalse ; 永不自动调整精灵数据避免意外 bResizeSpriteDataToMatchTexturesFalse ; !!!核心比例设定约定美术资源1像素 世界中的1厘米 (1UU)。 ; 因此一个32像素高的角色在游戏中就是0.32米高符合横版游戏常见比例。 ; 计算我们希望 1像素 0.01米 (1厘米) - 1 UU 1厘米 (UE默认)。 ; 所以 PixelPerUU 期望的1像素对应的UU数 0.01。 ; 但注意这里设置的是运行时比例。导入比例在下面单独设置。 DefaultPixelPerUU0.01 ; 不覆盖默认材质我们使用引擎标准的Sprite材质必要时创建材质实例 bOverrideDefaultSpriteMaterialFalse [/Script/Paper2D.PaperImporterSettings] ; 移动端目标平台纹理页大小设为1024以兼容低端设备 TexturePageSize1024 ; 尝试覆盖压缩设置以减少像素画模糊具体效果需测试可能需要配合纹理资产单独设置 bOverrideTextureCompressionTrue ; 使用TC_HDR无压缩RGB来最大程度保留像素画色彩和边缘。注意这会增加内存。 ; 另一种选择是 TC_EditorIcon但TC_HDR通常质量更好。 DefaultTextureCompressionSettingsTC_HDR ; 导入网格密度像素游戏通常不需要细分网格保持12x2网格最优 DefaultPixelsPerUnit1.0 DefaultMeshSubdivisions1 ; 碰撞生成使用凸包分解作为平衡选择 DefaultCollisionDomainTDCM_ConvexDecomposition ; !!!关键将碰撞厚度设为极小值避免产生Z轴深度上的“空气墙” CollisionThickness0.5 ; 提高凸包分解的精度上限以生成更贴合角色轮廓的碰撞体 MaxCollisionMeshVertices80 HullCount6 ; 导入时也使用与运行时一致的比例1像素0.01米 ; 注意这个参数在Base文件中可能不直接存在但比例一致性理念很重要。 ; 实际的导入尺寸由纹理的像素尺寸和下面可能存在的导入比例共同决定。 ; 我们主要依靠美术在制作资源时遵循统一的像素密度规范。 [/Script/Paper2D.PaperEditorSettings] ; 在精灵编辑器中显示像素网格方便美术对齐 bShowGridInSpriteEditorTrue ; 使用稍亮的背景色因为我们的像素画常有黑色轮廓 DefaultBackgroundColor(R0.15,G0.15,B0.15,A1.0) ; 关闭自动材质选择由人工指定保证一致性 bPickBestMaterialWhenCreatingSpriteFalse步骤3验证配置生效保存DefaultPaper2D.ini文件。关闭并重新启动虚幻编辑器对于PaperRuntimeSettings的修改重启是必要的。打开或新建一个Paper2D精灵资产。检查其属性例如查看其Render Geometry下的Pixels Per Unit是否与你预期的导入工作流一致在Sprite编辑器中查看碰撞体厚度是否变薄尝试导入一张新的PNG图片观察其默认的纹理压缩设置、碰撞生成算法是否符合你的配置。5. 常见问题排查与高级技巧即使配置得当在实际使用中仍会遇到各种问题。这里记录一些典型问题的排查思路和解决方法。5.1 导入的精灵尺寸不对症状在PS里是32x32像素导入UE后在3D视口中巨大无比或太小。排查步骤检查INI配置确认DefaultPixelPerUU运行时和导入时理解的比例设置。记住精灵在世界中的最终尺寸 (纹理像素宽度 /PixelsPerUnit) *DefaultPixelPerUU。你需要理清这两个参数的关系。在Sprite资产的详细信息面板中直接修改Pixels Per Unit属性是最直接的。检查纹理资产本身在内容浏览器中选中导入的纹理查看其详细信息。确保其LODGroup设置正确Texture2D并且没有意外的缩放。检查精灵组件如果精灵是通过PaperSpriteComponent放置在场景中检查该组件上的Relative Scale或World Scale是否为1。5.2 像素画边缘模糊或有颜色渗透症状清晰的像素画导入后边缘出现模糊或相邻颜色“渗”过来。排查与解决纹理压缩这是首要怀疑对象。按照前文所述在项目INI中尝试覆盖压缩为TC_HDR或者更有效的是在纹理资产上手动设置双击打开纹理资产。在细节面板找到Compression部分。将Compression Settings改为UserInterface2D (RGBA)。这个设置专门为需要锐利显示的2D UI和精灵设计禁用了一些会导致模糊的压缩过滤。将Mip Gen Settings改为NoMipmaps。像素画通常不需要多级渐远纹理Mipmaps关闭它可以避免缩小时的模糊。采样器过滤在精灵所使用的材质中检查对纹理采样的Texture Sample节点。确保其Sampler Type设置为Color并且Filter可以尝试从默认的Trilinear改为Nearest最近邻过滤这能保证放大时也是硬边缘的像素。但注意Nearest在缩小时可能产生锯齿。DDS格式考虑如果可能让美术提供.dds格式的纹理并在导入时选择正确的无压缩格式如DXT1/3/5或BC7有时比引擎后处理压缩更可控。5.3 自动生成的碰撞体形状怪异或性能差症状碰撞体不能准确贴合精灵形状或者物理模拟时帧率下降明显。优化策略分而治之不要对所有精灵使用同一套碰撞设置。为不同用途的精灵定义不同的预设。高精度角色/敌人在它们的纹理导入后单独在Sprite编辑器中将碰撞域Collision Domain设为Alpha Test Grid并仔细调整Alpha Threshold如0.1确保轮廓抓取得当。同时设置一个合理的Max Vertices如150。背景元素直接设为Convex Hull或None。通用道具使用Convex Decomposition并采用项目INI中的默认中等精度设置。手动编辑碰撞几何体对于形状特别重要且自动生成不满意的精灵如一个带有凹槽的钥匙Paper2D编辑器提供了手动绘制多边形碰撞体的工具。虽然耗时但一劳永逸且性能最优顶点数最少。使用简单形状替代很多情况下一个精确的复杂碰撞体并非必需。用一个胶囊体Capsule或盒子Box来近似角色碰撞用多个简单凸包来近似一个复杂形状在性能和开发效率上往往是更好的选择。5.4 Flipbook动画播放卡顿或帧率不对症状序列帧动画播放不流畅或者感觉比预期快/慢。排查要点检查帧率Frames Per Second在Flipbook资产中确保Frames Per Second设置正确。这个值决定了每秒播放多少张图。15、24、30是常见值。不要和纹理的导入帧率混淆。检查关键帧间隔Flipbook的播放是基于时间的而不是每帧更新。在性能开销大的场景如果游戏帧率DeltaTime波动大可能导致动画计时不准。可以考虑在Tick更新动画逻辑时使用一个独立的、累积的时间变量而不是直接依赖每帧的DeltaTime。合批与渲染性能确保Flipbook使用的精灵位于同一个图集Atlas中。如果每一帧的纹理都来自不同的图集或纹理资源会导致渲染状态频繁切换造成卡顿。使用Sprite Atlas Group工具将Flipbook所需的所有帧打包到一张大图上。深入BasePaper2D.ini的过程就像拿到了一张Paper2D插件的地图。它不会直接教你如何绘制精美的精灵或编写复杂的动画蓝图但它指明了所有默认行为的源头和调整这些行为的开关。这份掌控感能让你在遇到Paper2D相关问题时不再停留在表面调整而是能直击根源进行配置。最好的学习方式就是在理解这些参数后为你当前的项目创建一份量身定制的DefaultPaper2D.ini并在实际导入资源、创建碰撞、播放动画的过程中反复观察和调整。你会发现许多曾经令人头疼的“小毛病”其实只是某个默认值不适合你的项目而已。 UE5 Paper2D插件INI文件深度解析：从默认配置到项目定制优化
1. 项目概述为什么我们要深挖一个INI文件如果你在UE5里用过Paper2D插件不管是做2D横版游戏、UI动效还是简单的精灵动画大概率都接触过那些Sprite、Flipbook之类的资产。但不知道你有没有好奇过当你创建一个新的Paper2D精灵时引擎背后那些默认的网格体密度、碰撞精度、导入设置是从哪来的为什么有时候导入的序列图帧率不对或者碰撞生成得奇奇怪怪这些看似“默认”的行为其实都藏在一个不起眼但至关重要的配置文件里BasePaper2D.ini。这个文件是Paper2D插件的“出厂设置”总纲。它不像.cpp或.h文件那样充满逻辑也不像蓝图那样直观可视但它定义了整个2D工作流的基石。很多开发者遇到Paper2D相关的问题比如导入的像素画边缘有白边、碰撞体生成过于耗性能、或者动画播放不流畅翻遍项目设置和编辑器菜单也找不到根因其源头往往就在这个INI文件的配置项里。直接修改引擎源码是重型操作而理解并合理调整这个INI文件则是一种更轻量、更安全的“微调”手段。我最初注意到这个文件是在为一个横版动作游戏优化资源导入流程时。团队的美术同学抱怨他们精心绘制的像素角色导入后自动生成的碰撞体总是多出一圈“空气墙”导致角色感觉浮空。我们检查了所有Sprite的设置都没问题。最后我抱着试试看的心态翻开了引擎目录下的BasePaper2D.ini才在DefaultCollisionDomain和CollisionThickness等参数上找到了答案。那次经历让我意识到读懂这个配置文件就等于拿到了优化Paper2D工作流、甚至解决一些疑难杂症的“后门钥匙”。今天我就带你一起像读代码一样逐行解读BasePaper2D.ini的源码。我们不止看它“是什么”更要弄明白每个配置项“为什么”这么设计以及在实际项目中“怎么用”和“怎么改”。无论你是想深度定制2D导入管线还是单纯想解决手头的一个Paper2D小麻烦这篇文章都能给你提供清晰的路径。2. BasePaper2D.ini文件定位与结构总览2.1 文件在哪里多重配置的优先级之谜首先我们得找到它。在UE5的引擎源码目录中BasePaper2D.ini的典型路径是[YourEnginePath]\Engine\Plugins\2D\Paper2D\Config\。注意这里说的是引擎源码或安装目录下的“基础”配置文件。它定义了Paper2D插件的默认行为。但是直接修改引擎目录下的文件是极其不推荐的因为引擎更新会覆盖你的修改并且会影响所有使用该引擎的项目。UE的配置系统遵循一套覆盖优先级规则理解这个规则是安全定制的前提引擎默认配置 (BasePaper2D.ini)位于引擎插件目录提供最基础的默认值。这是我们的“源码”解读对象。引擎覆盖配置 (DefaultPaper2D.ini)位于[YourEnginePath]\Engine\Config\。你可以在这里放置针对该引擎版本的、项目无关的覆盖设置。它的优先级高于Base文件。项目默认配置 (DefaultPaper2D.ini)位于你项目的Config\文件夹根目录。这里定义的配置会覆盖引擎级别的设置并且只影响当前项目。这是最常用、最安全的定制位置。项目平台/用户配置如DefaultPaper2D.ini的平台覆盖版本或编辑器的用户设置优先级更高但使用场景较少。实操心得99%的情况下你的定制都应该发生在项目的Config\DefaultPaper2D.ini里。如果这个文件不存在就自己创建一个。这样做的好处是配置与项目绑定可以纳入版本控制并且完全不影响引擎本身或其他项目。在开始解读具体条目前先在项目里创建好这个文件。2.2 文件结构解析章节化的配置哲学用文本编辑器打开BasePaper2D.ini你会发现它遵循标准的INI文件格式由一个个用方括号[]括起来的“节”Section组成。每个节下包含若干“键值”KeyValue对。Paper2D的配置主要围绕几个核心功能模块展开[/Script/Paper2D.PaperRuntimeSettings] ... (运行时行为相关设置) [/Script/Paper2D.PaperImporterSettings] ... (资源导入相关设置) [/Script/Paper2D.PaperEditorSettings] ... (编辑器特有行为设置)这种以/Script/开头的节名是UE将配置与特定C类绑定的方式。例如/Script/Paper2D.PaperRuntimeSettings里的所有配置项最终都会影响UPaperRuntimeSettings这个类的默认属性值。这意味着你的任何修改都是在覆盖这些C类对象的默认构造参数。为什么这么设计这体现了UE配置系统的灵活性。它允许开发者在不重新编译引擎或插件代码的情况下通过文本文件来调整深层行为。对于Paper2D这样的插件美术、策划甚至技术美术都可以通过修改易懂的INI文件来调整工作流而不必求助于程序员修改C代码。3. 核心配置节深度解读与实战应用接下来我们进入核心部分逐节拆解关键配置项。我会为每个重要参数解释其含义、默认值背后的考量以及你在什么情况下需要调整它。3.1 [/Script/Paper2D.PaperRuntimeSettings] - 定义运行时行为这个节下的配置影响游戏运行时的2D渲染和物理行为。修改后通常需要重启编辑器或游戏才能生效。bEnableSpriteAtlasGroups(默认: True)这个布尔值控制是否启用Sprite图集组Sprite Atlas Group系统。图集组是Paper2D用于合批绘制、优化性能的高级功能。当它为True时引擎会尝试将多个精灵纹理打包到更大的图集纹理中减少Draw Call。为什么需要它在移动平台或需要绘制大量2D精灵的场景中每个精灵单独绘制一次一个Draw Call是性能杀手。启用图集后多个精灵可以合并到一次绘制中。什么时候关闭如果你的项目精灵数量很少或者每个精灵都巨大且独特图集化可能带来不必要的内存开销巨大的图集纹理和复杂度。在开发初期进行性能剖析时可以尝试关闭它以对比性能。实操要点保持默认的True即可。真正的优化在于合理设置图集组的大小和策略这通常在各个Sprite资产或材质中配置。bEnableTerrainSplineEditing(默认: True)启用Paper2D地形样条编辑。这是用于创建2D可变形地形如《雷曼》中的可拉伸土地的工具。什么时候关闭如果你的项目是纯粹的硬表面横版过关或RPG完全用不到可变形地形可以设置为False以节省微小的运行时开销和编辑器UI复杂度。bResizeSpriteDataToMatchTextures(默认: False)一个历史遗留兼容性选项。如果为True当精灵的源纹理尺寸发生变化时会尝试自动调整精灵的几何数据如网格、碰撞体以匹配。强烈建议保持False。自动调整几何数据很容易导致不可预知的后果比如精心调整的碰撞体形状错乱。纹理尺寸变更应该是一个需要人工检查的手动过程。DefaultPixelPerUU(默认: 1.0)这是极其重要的一个参数。它定义了“每Unreal单位对应多少个像素”Pixels Per Unreal Unit。简单说它建立了2D美术资源像素与3D世界空间UU的换算关系。默认值1.0意味着什么一个100x100像素的精灵导入后在世界中的尺寸默认是100x100 Unreal单位。在UE中1个Unreal单位通常被视为1厘米。所以这个100像素的精灵默认就有1米见方这可能非常大如何调整你需要根据你的游戏风格和美术资源决定。对于像素风游戏你可能希望一个角色精灵比如32x64像素在游戏中高度约为1.6米64 UU。那么你的DefaultPixelPerUU可以设为1.064像素64UU0.64米这里需要计算。更常见的做法是如果你希望精灵的“像素”与屏幕“像素”有更直观的对应比如像素完美渲染可能会设置为0.01100像素1UU1厘米或0.110像素1UU1厘米然后在相机和材质中做进一步调整。这个值需要在项目初期和美术统一约定一旦确定尽量不要中途更改否则所有已导入资产的尺寸都会变化。bOverrideDefaultSpriteMaterial(默认: False) 和DefaultMaskedMaterial/DefaultOpaqueMaterial是否覆盖默认的精灵材质以及指定覆盖用的材质路径。应用场景Paper2D默认使用内置的SpriteMaterial。如果你的项目有统一的、自定义的着色器需求比如所有精灵都需要某种特定的颜色混合模式、顶点动画或后期效果可以创建一个自定义材质在这里指定其路径例如/Game/MyMaterials/MySpriteMaterial.MySpriteMaterial并将bOverrideDefaultSpriteMaterial设为True。注意事项你指定的材质必须继承自Paper2D相关的材质父类如MaterialInstance的父材质是M_Sprite以确保其拥有精灵材质必需的参数如Sprite Texture。3.2 [/Script/Paper2D.PaperImporterSettings] - 掌控导入管道这个节的配置决定了当你从外部如PNG、PSD文件导入资源到Paper2D资产Sprite, Flipbook等时引擎默认采取的行为。这是问题的高发区也是优化工作流的关键。TexturePageSize(默认: 2048)当导入精灵或创建图集时纹理页Texture Page的默认最大尺寸宽度和高度。值必须是2的幂次方如512, 1024, 2048, 4096。性能与内存权衡较大的尺寸如4096可以容纳更多精灵减少图集数量但会显著增加GPU内存占用并且某些低端移动设备可能不支持大于2048的纹理。较小的尺寸如512内存友好但可能导致图集碎片化需要更多张图集增加Draw Call。选型建议对于现代PC和主机2048或4096是安全的。对于移动端特别是低端安卓设备建议从1024开始测试。你可以在项目设置中为不同平台配置覆盖值。bOverrideTextureCompression(默认: False) 和DefaultTextureCompressionSettings是否覆盖纹理压缩设置。Paper2D精灵的纹理默认使用TC_EditorIcon一种低质量的压缩这对于需要清晰显示的精灵尤其是像素画通常不合适。踩过的坑像素画导入后边缘模糊、出现色带很可能就是压缩导致的。最佳实践对于需要保持锐利边缘的像素艺术强烈建议设置bOverrideTextureCompressionTrue DefaultTextureCompressionSettingsTC_EditorIcon等等TC_EditorIcon不就是默认的吗这里容易混淆。实际上对于像素画你应该使用无压缩或矢量位移VectorDisplacement压缩后者在某些情况下能更好地保留细节。更常见的做法是在导入后在每个Sprite纹理资产的属性里手动将压缩设置为TC_EditorIcon它其实是一种简单的格式并非高质量或TC_HDR不压缩RGB。但通过INI统一设置更高效。你可以尝试设置为TC_Default然后在项目渲染设置中调整默认压缩。更精准的控制需要在纹理资产导入后单独设置其Compression Settings为UserInterface2D (RGBA)这通常需要在引擎的纹理编辑器中完成INI层面难以直接指定。DefaultPixelsPerUnit(默认: 1.0) 与DefaultMeshSubdivisions(默认: 1)这两个参数共同决定了精灵默认的网格密度。DefaultPixelsPerUnit和运行时的DefaultPixelPerUU概念类似但作用于导入时的网格生成。它表示“多少个像素对应网格的一个细分单位”。值越小网格越密。DefaultMeshSubdivisions网格的细分次数。为1时一个矩形精灵生成2x2的网格4个顶点。增加此值会生成更密的网格如2会生成3x3网格。为什么需要网格Paper2D精灵不是简单的四边形它是由三角网格构成的。这对于顶点动画、变形如弯曲的纸片效果以及某些光照效果是必需的。如何设置对于绝大多数静态精灵保持12x2网格就足够了这是性能最优的。只有当你计划对精灵进行复杂的顶点着色器变形时才需要增加细分例如制作一个可以弯曲的鞭子或飘动的旗帜。增加细分会显著增加顶点数影响性能。DefaultCollisionDomain(默认:TDCM_ConvexDecomposition)定义精灵自动生成碰撞体时使用的默认算法。这是解决文章开头“空气墙”问题的关键。TDCM_ConvexDecomposition凸包分解。引擎会尝试将精灵的透明轮廓分解成多个凸多边形。这是默认值因为它能生成相对准确且物理引擎Chaos高效处理的碰撞体。TDCM_AlphaTestGridAlpha测试网格。根据纹理的Alpha通道生成一个精确到像素的网格碰撞。这是最精确的能完美贴合精灵轮廓但性能开销最大碰撞体非常复杂。TDCM_ConvexHull凸包。生成一个包裹整个精灵轮廓的单一凸多边形。这是性能最好的但也是最不精确的会忽略所有凹进去的部分比如一个“C”形的精灵凸包会把它补成一个“O”形。TDCM_None不生成碰撞。选择策略精确碰撞如平台边缘、子弹命中对于小尺寸、形状复杂的精灵如角色使用TDCM_AlphaTestGrid但要注意控制CollisionThresholdAlpha阈值和MaxCollisionMeshVertices最大顶点数避免过于复杂。性能优先如背景装饰物使用TDCM_ConvexHull或TDCM_None。平衡之选通用TDCM_ConvexDecomposition并通过调整MaxCollisionMeshVertices和HullCount来控制精度和性能。这也是默认值的原因。CollisionThickness(默认: 10.0)为生成的2D碰撞体添加一个“厚度”使其在3D空间中成为一个有深度的“薄板”实际上是一个极扁的棱柱。单位是Unreal单位。“空气墙”问题的元凶如果你发现2D碰撞体在Z轴深度方向上也有体积导致角色在“面前”就被挡住就是因为这个值太大了。对于纯2D游戏所有物体在同一Z平面这个值应该设置得非常小比如0.1或1.0。调整建议在项目的DefaultPaper2D.ini中将其设置为一个很小的值例如CollisionThickness1.0。这能确保碰撞体在2D平面上有效同时在3D空间里几乎不占深度。MaxCollisionMeshVertices(默认: 50) 与HullCount(默认: 4)这两个参数用于控制TDCM_ConvexDecomposition算法的精度和复杂度。MaxCollisionMeshVertices限制生成的所有凸包碰撞体的总顶点数。顶点数越多形状越精确但物理计算开销越大。HullCount限制凸包分解的最大数量。算法会尝试用指定数量的凸包来近似精灵形状。调优技巧如果自动生成的碰撞体形状怪异或缺失部分可以尝试适当增加这两个值例如分别增加到100和8。但务必在性能可接受范围内。通常可以先增加HullCount如果形状仍不理想再增加MaxCollisionMeshVertices。使用编辑器的碰撞体预览功能在Sprite编辑器中实时查看调整效果。3.3 [/Script/Paper2D.PaperEditorSettings] - 优化编辑器体验这部分配置主要影响Paper2D资源在虚幻编辑器中的编辑和显示行为。bShowGridInSpriteEditor(默认: True)是否在Sprite编辑器中显示像素网格。对于像素美术工作者这个网格是精准对齐像素、查看UV拉伸的必备工具。建议保持开启。如果你觉得网格线干扰视线可以在Sprite编辑器窗口的视图选项里临时关闭而不是修改全局配置。DefaultBackgroundColor(默认:(R0.05,G0.05,B0.05,A1.0))Sprite编辑器、Flipbook编辑器等视图的默认背景色。接近黑色的深灰色是默认选择因为它能很好地突出显示大多数精灵且不刺眼。个性化定制如果你的美术资源主色调是深色可以将其调亮如(R0.2,G0.2,B0.2,A1.0)以获得更好的对比度。颜色值范围是0.0到1.0。bPickBestMaterialWhenCreatingSprite(默认: True)当通过纹理资产右键菜单创建精灵时是否尝试自动选择“最佳”材质实例。工作机制如果开启编辑器会检查纹理的Alpha通道。如果Alpha通道基本全不透明它会尝试使用不透明Opaque材质如果Alpha通道变化丰富则使用遮罩Masked材质。潜在问题这个“自动选择”有时会出错特别是对于带有复杂Alpha边缘如毛发的纹理它可能错误地判断为不透明。我的习惯我通常将其设置为False然后在创建精灵后手动指定材质。这样可以获得完全的控制权避免后续材质切换带来的意外。4. 实战定制项目专属的Paper2D配置理解了各个参数的含义我们现在来动手为你的项目创建一个定制化的DefaultPaper2D.ini。假设我们正在开发一款像素风格的2D横版游戏。步骤1在项目根目录创建文件在你的UE5项目文件夹内找到或创建Config文件夹在其中新建一个文本文件命名为DefaultPaper2D.ini。步骤2编写定制化配置将以下内容填入文件并附上详细注释说明你的设计决策; MyProject/Config/DefaultPaper2D.ini ; 专为 [我的像素横版游戏] 定制的Paper2D配置 ; 创建于2023年10月27日 ; 作者你的名字 [/Script/Paper2D.PaperRuntimeSettings] ; 启用图集组以优化运行时Draw Call bEnableSpriteAtlasGroupsTrue ; 我们的游戏不需要可变形地形关闭以简化 bEnableTerrainSplineEditingFalse ; 永不自动调整精灵数据避免意外 bResizeSpriteDataToMatchTexturesFalse ; !!!核心比例设定约定美术资源1像素 世界中的1厘米 (1UU)。 ; 因此一个32像素高的角色在游戏中就是0.32米高符合横版游戏常见比例。 ; 计算我们希望 1像素 0.01米 (1厘米) - 1 UU 1厘米 (UE默认)。 ; 所以 PixelPerUU 期望的1像素对应的UU数 0.01。 ; 但注意这里设置的是运行时比例。导入比例在下面单独设置。 DefaultPixelPerUU0.01 ; 不覆盖默认材质我们使用引擎标准的Sprite材质必要时创建材质实例 bOverrideDefaultSpriteMaterialFalse [/Script/Paper2D.PaperImporterSettings] ; 移动端目标平台纹理页大小设为1024以兼容低端设备 TexturePageSize1024 ; 尝试覆盖压缩设置以减少像素画模糊具体效果需测试可能需要配合纹理资产单独设置 bOverrideTextureCompressionTrue ; 使用TC_HDR无压缩RGB来最大程度保留像素画色彩和边缘。注意这会增加内存。 ; 另一种选择是 TC_EditorIcon但TC_HDR通常质量更好。 DefaultTextureCompressionSettingsTC_HDR ; 导入网格密度像素游戏通常不需要细分网格保持12x2网格最优 DefaultPixelsPerUnit1.0 DefaultMeshSubdivisions1 ; 碰撞生成使用凸包分解作为平衡选择 DefaultCollisionDomainTDCM_ConvexDecomposition ; !!!关键将碰撞厚度设为极小值避免产生Z轴深度上的“空气墙” CollisionThickness0.5 ; 提高凸包分解的精度上限以生成更贴合角色轮廓的碰撞体 MaxCollisionMeshVertices80 HullCount6 ; 导入时也使用与运行时一致的比例1像素0.01米 ; 注意这个参数在Base文件中可能不直接存在但比例一致性理念很重要。 ; 实际的导入尺寸由纹理的像素尺寸和下面可能存在的导入比例共同决定。 ; 我们主要依靠美术在制作资源时遵循统一的像素密度规范。 [/Script/Paper2D.PaperEditorSettings] ; 在精灵编辑器中显示像素网格方便美术对齐 bShowGridInSpriteEditorTrue ; 使用稍亮的背景色因为我们的像素画常有黑色轮廓 DefaultBackgroundColor(R0.15,G0.15,B0.15,A1.0) ; 关闭自动材质选择由人工指定保证一致性 bPickBestMaterialWhenCreatingSpriteFalse步骤3验证配置生效保存DefaultPaper2D.ini文件。关闭并重新启动虚幻编辑器对于PaperRuntimeSettings的修改重启是必要的。打开或新建一个Paper2D精灵资产。检查其属性例如查看其Render Geometry下的Pixels Per Unit是否与你预期的导入工作流一致在Sprite编辑器中查看碰撞体厚度是否变薄尝试导入一张新的PNG图片观察其默认的纹理压缩设置、碰撞生成算法是否符合你的配置。5. 常见问题排查与高级技巧即使配置得当在实际使用中仍会遇到各种问题。这里记录一些典型问题的排查思路和解决方法。5.1 导入的精灵尺寸不对症状在PS里是32x32像素导入UE后在3D视口中巨大无比或太小。排查步骤检查INI配置确认DefaultPixelPerUU运行时和导入时理解的比例设置。记住精灵在世界中的最终尺寸 (纹理像素宽度 /PixelsPerUnit) *DefaultPixelPerUU。你需要理清这两个参数的关系。在Sprite资产的详细信息面板中直接修改Pixels Per Unit属性是最直接的。检查纹理资产本身在内容浏览器中选中导入的纹理查看其详细信息。确保其LODGroup设置正确Texture2D并且没有意外的缩放。检查精灵组件如果精灵是通过PaperSpriteComponent放置在场景中检查该组件上的Relative Scale或World Scale是否为1。5.2 像素画边缘模糊或有颜色渗透症状清晰的像素画导入后边缘出现模糊或相邻颜色“渗”过来。排查与解决纹理压缩这是首要怀疑对象。按照前文所述在项目INI中尝试覆盖压缩为TC_HDR或者更有效的是在纹理资产上手动设置双击打开纹理资产。在细节面板找到Compression部分。将Compression Settings改为UserInterface2D (RGBA)。这个设置专门为需要锐利显示的2D UI和精灵设计禁用了一些会导致模糊的压缩过滤。将Mip Gen Settings改为NoMipmaps。像素画通常不需要多级渐远纹理Mipmaps关闭它可以避免缩小时的模糊。采样器过滤在精灵所使用的材质中检查对纹理采样的Texture Sample节点。确保其Sampler Type设置为Color并且Filter可以尝试从默认的Trilinear改为Nearest最近邻过滤这能保证放大时也是硬边缘的像素。但注意Nearest在缩小时可能产生锯齿。DDS格式考虑如果可能让美术提供.dds格式的纹理并在导入时选择正确的无压缩格式如DXT1/3/5或BC7有时比引擎后处理压缩更可控。5.3 自动生成的碰撞体形状怪异或性能差症状碰撞体不能准确贴合精灵形状或者物理模拟时帧率下降明显。优化策略分而治之不要对所有精灵使用同一套碰撞设置。为不同用途的精灵定义不同的预设。高精度角色/敌人在它们的纹理导入后单独在Sprite编辑器中将碰撞域Collision Domain设为Alpha Test Grid并仔细调整Alpha Threshold如0.1确保轮廓抓取得当。同时设置一个合理的Max Vertices如150。背景元素直接设为Convex Hull或None。通用道具使用Convex Decomposition并采用项目INI中的默认中等精度设置。手动编辑碰撞几何体对于形状特别重要且自动生成不满意的精灵如一个带有凹槽的钥匙Paper2D编辑器提供了手动绘制多边形碰撞体的工具。虽然耗时但一劳永逸且性能最优顶点数最少。使用简单形状替代很多情况下一个精确的复杂碰撞体并非必需。用一个胶囊体Capsule或盒子Box来近似角色碰撞用多个简单凸包来近似一个复杂形状在性能和开发效率上往往是更好的选择。5.4 Flipbook动画播放卡顿或帧率不对症状序列帧动画播放不流畅或者感觉比预期快/慢。排查要点检查帧率Frames Per Second在Flipbook资产中确保Frames Per Second设置正确。这个值决定了每秒播放多少张图。15、24、30是常见值。不要和纹理的导入帧率混淆。检查关键帧间隔Flipbook的播放是基于时间的而不是每帧更新。在性能开销大的场景如果游戏帧率DeltaTime波动大可能导致动画计时不准。可以考虑在Tick更新动画逻辑时使用一个独立的、累积的时间变量而不是直接依赖每帧的DeltaTime。合批与渲染性能确保Flipbook使用的精灵位于同一个图集Atlas中。如果每一帧的纹理都来自不同的图集或纹理资源会导致渲染状态频繁切换造成卡顿。使用Sprite Atlas Group工具将Flipbook所需的所有帧打包到一张大图上。深入BasePaper2D.ini的过程就像拿到了一张Paper2D插件的地图。它不会直接教你如何绘制精美的精灵或编写复杂的动画蓝图但它指明了所有默认行为的源头和调整这些行为的开关。这份掌控感能让你在遇到Paper2D相关问题时不再停留在表面调整而是能直击根源进行配置。最好的学习方式就是在理解这些参数后为你当前的项目创建一份量身定制的DefaultPaper2D.ini并在实际导入资源、创建碰撞、播放动画的过程中反复观察和调整。你会发现许多曾经令人头疼的“小毛病”其实只是某个默认值不适合你的项目而已。