定义图片资源

在游戏配置文件中，您可以使用 <ImageDef> 元素来定义图片资源。每个 <ImageDef> 元素都必须包含在顶层的 <Define> 元素之内，并遵循其通用的属性定义规则。

功能介绍

<ImageDef> 用于加载和配置游戏所需的各种图片资源，包括单张图片、切分后的子图以及调整图片加载时的各项参数。您可以通过它指定图片路径、切分方式、像素密度以及加载时的翻转行为。

参数说明

所有的参数都必须通过嵌套元素的方式进行赋值。

  • <defName> (必需，字符串)

    • 该图片定义的唯一标识符。在整个游戏配置中，此名称必须是全局唯一的，除非您有意覆盖现有定义。
    • 作为匿名定义时，此字段可以省略。

  • <label> (可选，字符串)

    • 提供一个人类可读的标签，用于更好地理解该图片定义的用途。

  • <description> (可选，字符串)

    • 提供更详细的文本描述，解释该图片定义的具体内容或特殊用途。

  • <path> (必需，字符串)

    • 指定图片资源的实际存储路径。
    • 路径前缀约定：
      • otherPackID:相对地址: 表示加载 otherPackID 包下的相对路径图片资源。
      • 空前缀: 表示加载当前定义所在包的相对路径图片资源。
      • res:相对地址: 表示加载游戏编译过程中，项目 Resources 文件夹下的图片资源。res: 前缀的优先级高于包 ID 前缀。

  • <wCount> (必需，整数)

    • 指定将图片在水平方向上切分为多少个子图。要求图片的宽度可以被 wCount 整除。

  • <hCount> (必需，整数)

    • 指定将图片在垂直方向上切分为多少个子图。要求图片的高度可以被 hCount 整除。
    • 当 wCount 或 hCount 大于 1 时，图片将被切分为多个子图。子图按照从上到下，从左到右，从 0 开始的顺序进行编号。

  • <pixelsPerUnit> (可选，整数，默认为 16)

    • 定义图片在游戏世界中绘制时的像素密度。例如，如果设置为 16，则 16 像素宽的图片在绘制时将占据 1 个单位的宽度。

  • <flipX> (可选，布尔值，默认为 false)

    • 如果设置为 true，则在加载时沿 X 轴翻转图片。
    • 重要提示： 对于多子图图片，翻转操作是在图片被切分之后进行的。defName_0 始终代表翻转前的图片左上角子图。这意味着先进行裁剪，再对每个子图进行翻转。

  • <flipY> (可选，布尔值，默认为 false)

    • 如果设置为 true，则在加载时沿 Y 轴翻转图片。
    • 重要提示： 对于多子图图片，翻转操作是在图片被切分之后进行的。defName_0 始终代表翻转前的图片左上角子图。这意味着先进行裁剪，再对每个子图进行翻转。

引用方式

  • 当其他定义需要引用某个图片资源时：
    • defName: 始终代表完整图片（无论是否被切分）。
    • defName_编号: (例如 myImage_0, myImage_5) 引用对应的子图。

示例

示例 1：定义一张单图图片

<Define>
    <ImageDef>
        <defName>PlayerSprite</defName>
        <label>玩家角色图片</label>
        <description>用于绘制玩家角色的基本图片。</description>
        <path>Textures/Player/player_base.png</path>
        <pixelsPerUnit>32</pixelsPerUnit>
        <flipX>false</flipX>
        <flipY>false</flipY>
    </ImageDef>
</Define>

在其他定义中引用此图片：

  • 引用完整图片：PlayerSprite

示例 2：定义一张切分后的图片集

假设 enemy_sheet.png 是一张 128x64 像素的图集，包含 4x2 共 8 个子图。

<Define>
    <ImageDef>
        <defName>EnemySprites</defName>
        <label>敌人动画图集</label>
        <description>包含敌人的行走和攻击动画帧。</description>
        <path>res:Sprites/Enemies/enemy_sheet.png</path>
        <wCount>4</wCount>
        <hCount>2</hCount>
        <pixelsPerUnit>16</pixelsPerUnit>
    </ImageDef>
</Define>
  • 引用完整图集：EnemySprites
  • 引用第一个子图（左上角）：EnemySprites_0
  • 引用第二个子图：EnemySprites_1
  • 引用第五个子图（第二行第一个）：EnemySprites_4

示例 3：定义一张来自其他包的图片并翻转加载

<Define>
    <ImageDef>
        <defName>FlippedBackground</defName>
        <label>翻转的背景图</label>
        <description>从UI包加载并水平翻转的背景图片。</description>
        <path>UIPack:Backgrounds/main_bg.jpg</path>
        <wCount>1</wCount>
        <hCount>1</hCount>
        <pixelsPerUnit>100</pixelsPerUnit>
        <flipX>true</flipX>
    </ImageDef>
</Define>

在其他定义中引用此图片：

  • 引用完整图片：FlippedBackground

注意事项

  • 图片切分与翻转的顺序： 务必记住，flipX 和 flipY 操作是在 wCount 和 hCount 切分操作之后进行的。这意味着即使图片被翻转，defName_0 始终指向原始图片（未翻转前）的左上角子图，然后该子图才会被独立翻转。
  • 像素整除性： 确保您的图片尺寸可以被 wCount 和 hCount 整除，否则切分可能不会按预期工作或导致错误。
  • 路径前缀优先级： res: 前缀的解析优先级最高，其次是包 ID 前缀，最后是当前包。
  • defName 唯一性： 强烈建议所有 <ImageDef> 的 defName 都是全局唯一的，以避免在加载和引用时出现混淆或不确定的行为。如果存在重复的 defName，后加载的定义将会覆盖先加载的。
  • 匿名定义： 当 ImageDef 作为其他定义的内部结构使用时，defName 可以省略，此时它将作为一个匿名的、局部可用的图片定义。在这种情况下，该图片无法通过名称在外部引用。