图标

用名称调用图标

控件从不持有图片。它只询问名称，画什么由当前使用的图标集决定 —— 换一套图标集，所有图标随之改变，一行代码都不用改。

GoStyle.icon_button(GoIconSet.SETTINGS, open_settings)   # a button
slot.icon_name = GoGameIcons.BACKPACK                     # a quick slot
var mark := GoUi.icons().node(&"cloud_rain", 24)          # a bare Control, any size

GoUi.icons() 就是当前使用的图标集。画不出的名称会变成一个保留位置的空框，调试构建中会给出警告，所以缺一个图标也不会让整行错位。

查找图标

gohud 自带的全部图形。按名称或外观搜索，按图标集或分组筛选，选中图标即可复制名称。

名称和搜索词在任何语言中都保持英文 —— 因为它们就是你在代码里输入的内容。

四套图标集，一条查找路径

每套图标集都响应同一个调用。大的图标集叠加在当前图标集之上使用。

GoUi.add_icons(GoIconLibrary.icon_set())   # the library — and the game set under it
GoUi.add_icons(GoGameIcons.icon_set())     # or the game set alone

图标库回退到游戏图标集，游戏图标集再回退到默认图标集，因此一行代码就能绘制 1,271 个名称。图标集以路径记录图形，只在某个名称第一次被绘制时才读取文件 —— 添加图标库读取的是一张路径表（桌面端约 30 ms），而不是 1,000 张纹理。

名称的查找顺序

所有图标集遵循同一顺序，所以你能预知哪个图形胜出。

1. 先看所有图标集自己的图形 —— 当前图标集，然后是每个附加图标集，再逐层查看它们的回退。图标集自己的图形指纹理、路径或图标字体字形。
2. 如果都画不出，就尝试别名：gear 指向 settings，x 指向 close。只跳转一次。
3. 仍然没有：一个保留位置的空框。

正因为这个顺序，在中世纪预设上添加图标库后，雕刻风格的剑依然在最上层 —— 中世纪图标集自己的图形会先于任何回退被找到。

GoUi.use_preset(GoThemePresets.MEDIEVAL_DARK)
GoUi.add_icons(GoIconLibrary.icon_set())

GoUi.icons().texture(&"sword")      # the medieval engraving — its own drawing comes first
GoUi.icons().texture(&"rocket")     # from the game set
GoUi.icons().canonical(&"gear")     # &"settings" — an alias

预设、你的图标集和附加图标集

画什么由三处决定。

使用你自己的图形

覆盖几个名称、添加整个文件夹，或接入图标字体 —— 调用代码保持不变。

# Override a few names — everything else still comes from the set in use
var mine := GoIconSet.new()
mine.fallback = GoUi.icons()
mine.textures = {GoIconSet.CLOSE: preload("res://art/close.svg")}
GoUi.config.icons = mine

# A folder of drawings — file name = icon name, each read when first drawn
GoUi.config.icons = GoIconSet.from_folder("res://art/icons", GoUi.icons())

• 在 24×24 网格上用白色描边绘制。颜色通过 modulate 施加，而它只能变暗 —— 黑色的图形在任何主题下都保持黑色。
• 将 SVG 导入为 DPITexture，这样在 64 dp 的背包格子里也依然清晰。
• 在从右到左书写的语言中，图标也不会镜像。只有 back 和 forward 会改变方向，而它们由名称来选择。
• 图标字体同样可用：填写 font 和 codepoints 即可，其余不变。

名称、分组与搜索

自带图标集遵循的规则，以及查找名称的调用。

• 使用 lower_snake_case，先写所画之物，状态放在后面：volume_off、battery_charging、arrow_bar_left。
• 不加分组前缀。分组是数据，所以无论归入哪个分组，名称都不变。
• 图标库的名称就是把 Tabler 名称中的连字符换成下划线：tabler.io 上的 cloud-rain 在这里是 cloud_rain。gohud 原本已有的图形，其 Tabler 名称作为别名指向它（shopping_cart → cart）。
• 同义词是别名，而不是第二个图形。

search()

var icons := GoUi.icons()
icons.search("arrow left", 5)       # best matches first: back, arrow_bar_left …
icons.search("rain")                # cloud_rain, then drawings tagged "rain"

group_names() · names_in_group()

icons.group_names()                 # every group key, in lookup order
icons.names_in_group(&"weather")    # one group, in display order — every set's share of it
icons.group_title(&"weather")       # "Weather & sky"

canonical() · has_icon()

icons.canonical(&"gear")            # &"settings"
icons.canonical(&"treasure_chest")  # &"chest" — Tabler's name for a game drawing
icons.has_icon(&"cloud_rain")       # true once the library is added — nothing is loaded to answer

图形的来源

全部采用 MIT 许可。声明以 THIRD_PARTY_NOTICES.md 的形式随 ZIP 一起分发。

如果接入他人的图标，请在 GoIconSet.attribution 中写明来源 —— 商用图标字体只放在你的游戏里，不要放进你公开的分支。