gui_using_fonts.rst 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738
  1. .. _doc_gui_using_fonts:
  2. Using Fonts
  3. ===========
  4. Godot allows you to set specific fonts for different UI nodes.
  5. There are three different places where you can setup font usage.
  6. The first is the theme editor. Choose the node you want to set the
  7. font for and select the font tab. The second is in the inspector
  8. for control nodes under **Theme Overrides > Fonts**. Lastly, in
  9. the inspector settings for themes under **Default Font**.
  10. .. note::
  11. Since Godot 4.0, font sizes are no longer defined in the font itself but are
  12. instead defined in the node that uses the font. This is done in the
  13. **Theme Overrides > Font Sizes** section of the inspector.
  14. This allows changing the font size without having to duplicate the font
  15. resource for every different font size.
  16. There are 2 kinds of font files: *dynamic* (TTF/OTF/WOFF/WOFF2 formats) and
  17. *bitmap* (BMFont ``.fnt`` format or monospaced image). Dynamic fonts are the
  18. most commonly used option, as they can be resized and still look crisp at higher
  19. sizes. Thanks to their vector-based nature, they can also contain a lot more
  20. glyphs while keeping a reasonable file size compared to bitmap fonts. Dynamic
  21. fonts also support some advanced features that bitmap fonts cannot support, such
  22. as *ligatures* (several characters transforming into a single different design).
  23. .. tip::
  24. You can find freely licensed font files on websites such as `Google Fonts
  25. <https://fonts.google.com/>`__ and `Font Library
  26. <https://fontlibrary.org/>`__.
  27. Fonts are covered by copyright. Double-check the license of a font before
  28. using it, as not all fonts allow commercial use without purchasing a license.
  29. Dynamic fonts
  30. -------------
  31. Godot supports the following dynamic font formats:
  32. - TrueType Font or Collection (``.ttf``, ``.ttc``)
  33. - OpenType Font or Collection (``.otf``, ``.otc``)
  34. - Web Open Font Format 1 (``.woff``)
  35. - Web Open Font Format 2 (``.woff2``, since Godot 4.0)
  36. While ``.woff`` and especially ``.woff2`` tend to result in smaller file sizes,
  37. there is no universally "better" font format. In most situations, it's
  38. recommended to use the font format that was shipped on the font developer's
  39. website.
  40. Bitmap fonts
  41. ------------
  42. Godot supports the BMFont (``.fnt``) bitmap font format. This is a format created
  43. by the `BMFont <https://www.angelcode.com/products/bmfont/>`__ program. Many
  44. BMFont-compatible programs also exist, like `BMGlyph <https://www.bmglyph.com/>`__.
  45. Alternatively, you can import any image to be used as a bitmap font. This is
  46. only supported for **monospaced** fonts (fonts where each character has the same
  47. width). To do so, select the image in the FileSystem dock, go to the
  48. Import dock, change its import type to **Font Data (Monospace Image Font)** then
  49. click **Reimport**:
  50. .. figure:: img/using_fonts_bitmap_font_from_image_import_options.webp
  51. :align: center
  52. :alt: Changing import type to Font Data (Monospace Image Font)
  53. Changing import type to **Font Data (Monospace Image Font)**
  54. The font's character set layout can be in any order, but orders that match
  55. standard Unicode are recommended as they'll require far less configuration to
  56. import. For example, the bitmap font below contains
  57. `ASCII <https://en.wikipedia.org/wiki/ASCII>`__ characters and follows standard ASCII ordering:
  58. .. figure:: img/using_fonts_monospace_bitmap_font_example.webp
  59. :align: center
  60. :alt: Bitmap font example
  61. Credit: `LibreQuake <https://github.com/MissLav/LibreQuake/blob/master/lq1/gfx-wad/CONCHARS.png>`__
  62. (scaled and cropped to exclude extended range)
  63. The following import options can be used to import the above font image
  64. successfully:
  65. .. figure:: img/using_fonts_bitmap_font_from_image_example_configuration.webp
  66. :align: center
  67. :alt: Import options to use for the above example font
  68. Import options to use for the above example font
  69. The **Character Ranges** option is an array that maps each position on the image
  70. (in tile coordinates, not pixels). The font atlas is traversed from left to
  71. right and top to bottom. Characters can be specified with decimal numbers
  72. (``127``), hexadecimal numbers (``0x007f``) or between *single* quotes
  73. (``'~'``). Ranges can be specified with a hyphen between characters.
  74. For instance, ``0-127`` (or ``0x0000-0x007f``) denotes the full ASCII range.
  75. As another example, ``' '-'~'`` is equivalent to ``32-127`` and denotes the range
  76. of *printable* (visible) ASCII characters.
  77. Make sure the **Character Ranges** option doesn't exceed the number of
  78. **Columns** × **Rows** defined. Otherwise, the font will fail to import.
  79. Loading a font file
  80. -------------------
  81. To load a font file (dynamic or bitmap), use the resource dropdown's
  82. **Quick Load** or **Load** option next to a font property, then navigate to the
  83. font file in question:
  84. .. figure:: img/using_fonts_load_font.webp
  85. :align: center
  86. Loading a font file
  87. You can also drag-and-drop a font file from the FileSystem dock to the inspector
  88. property that accepts a Font resource.
  89. Advanced font features
  90. ----------------------
  91. .. _doc_using_fonts_antialiasing:
  92. Antialiasing
  93. ^^^^^^^^^^^^
  94. You can adjust how the font should be smoothed out when rendering by adjusting
  95. *antialiasing* and *hinting*. These are different properties, with different use
  96. cases.
  97. Antialiasing controls how glyph edges should be smoothed out when rasterizing
  98. the font. The default antialiasing method (**Grayscale**) works well on every
  99. display technology. However, at small sizes, grayscale antialiasing may result
  100. in fonts looking blurry.
  101. The antialiasing sharpness can be improved by using LCD subpixel optimization,
  102. which exploits the subpixel patterns of most LCD displays by offsetting the font
  103. antialiasing on a per-channel basis (red/green/blue). The downside is that this
  104. can introduce "fringing" on edges, especially on display technologies that don't
  105. use standard RGB subpixels (such as OLED displays).
  106. In most games, it's recommended to stick to the default **Grayscale**
  107. antialiasing. For non-game applications, LCD subpixel optimization is worth
  108. exploring.
  109. .. figure:: img/using_fonts_antialiasing_comparison.webp
  110. :align: center
  111. :alt: Font antialiasing comparison
  112. From top to bottom: Disabled, Grayscale, LCD Subpixel (RGB)
  113. .. note::
  114. Antialiasing cannot be changed on :ref:`MSDF-rendered fonts <doc_using_fonts_msdf>`
  115. – these are always rendered with grayscale antialiasing.
  116. .. _doc_using_fonts_hinting:
  117. Hinting
  118. ^^^^^^^
  119. Hinting controls how aggressively glyph edges should be snapped to pixels when
  120. rasterizing the font. **None** results in the smoothest appearance, which can
  121. make the font look blurry at small sizes. **Light** (default) is sharper by
  122. snapping glyph edges to pixels on the Y axis only, while **Full** is even sharper
  123. by snapping glyph edges to pixels on both X and Y axes. Depending on personal
  124. preference, you may prefer using one hinting mode over the other.
  125. .. figure:: img/using_fonts_hinting_comparison.webp
  126. :align: center
  127. :alt: Font hinting comparison
  128. From top to bottom: None, Light, Full hinting
  129. .. note::
  130. If changing the hinting mode has no visible effect after clicking
  131. **Reimport**, it's usually because the font doesn't include hinting
  132. instructions. This can be resolved by looking for a version of the font file
  133. that includes hinting instructions, or enabling **Force Autohinter** in the
  134. Import dock. This will use `FreeType <https://freetype.org/>`__'s autohinter
  135. to automatically add hinting instructions to the imported font.
  136. .. _doc_using_fonts_subpixel_positioning:
  137. Subpixel positioning
  138. ^^^^^^^^^^^^^^^^^^^^
  139. Subpixel positioning can be adjusted. This is a `FreeType <https://freetype.org/>`__
  140. feature that allows glyphs to be rendered more closely to their intended form.
  141. The default setting of **Auto** automatically enables subpixel positioning at
  142. small sizes, but disables it at large font sizes to improve rasterization
  143. performance.
  144. You can force the subpixel positioning mode to **Disabled**, **One half of a
  145. pixel** or **One quarter of a pixel**. **One quarter of a pixel** provides the
  146. best quality, at the cost of longer rasterization times.
  147. Changing antialiasing, hinting and subpixel positioning has the most visible
  148. effect at smaller font sizes.
  149. .. _doc_using_fonts_mipmaps:
  150. Mipmaps
  151. ^^^^^^^
  152. By default, fonts do not have mipmaps generated to reduce memory usage and speed
  153. up rasterization. However, this can cause downscaled fonts to become grainy. This
  154. can be especially noticeable with :ref:`doc_3d_text` that doesn't have **Fixed
  155. Size** enabled. This can also occur when displaying text with a traditional rasterized
  156. (non-:ref:`MSDF <doc_using_fonts_msdf>`) font in a Control node that has its scale
  157. lower than ``(1, 1)``.
  158. After selecting a font in the FileSystem dock, you can enable the **Mipmaps** in
  159. the Import dock to improve downscaled font rendering appearance.
  160. Mipmaps can be enabled on MSDF fonts as well. This can improve font rencering
  161. quality a little at smaller-than-default sizes, but MSDF fonts are already
  162. resistant to graininess out of the box.
  163. .. _doc_using_fonts_msdf:
  164. MSDF font rendering
  165. ^^^^^^^^^^^^^^^^^^^
  166. Multi-channel signed distance field (MSDF) font rendering allows rendering fonts
  167. at any size, without having to re-rasterize them when their size changes.
  168. MSDF font rendering has 2 upsides over traditional font rasterization, which
  169. Godot uses by default:
  170. - The font will always look crisp, even at huge sizes.
  171. - There is less stuttering when rendering characters *at large font sizes* for
  172. the first time, as there is no rasterization performed.
  173. The downsides of MSDF font rendering are:
  174. - Higher baseline cost for font rendering. This is usually not noticeable on
  175. desktop platforms, but it can have an impact on low-end mobile devices.
  176. - Fonts at small sizes will not look as clear as rasterized fonts, due to the
  177. lack of hinting.
  178. - Rendering new glyphs for the first time *at small font sizes* may be more
  179. expensive compared to traditional rasterized fonts.
  180. :ref:`doc_using_fonts_font_prerendering` can be used to alleviate this.
  181. - LCD subpixel optimization cannot be enabled for MSDF fonts.
  182. - Fonts with self-intersecting outlines will not render correctly in MSDF mode.
  183. If you notice rendering issues on fonts downloaded from websites such as
  184. `Google Fonts <https://fonts.google.com>`__, try downloading the font from the
  185. font author's official website instead.
  186. Using emoji
  187. ^^^^^^^^^^^
  188. Godot has limited support for emoji fonts:
  189. - CBDT/CBLC (embedded PNGs) and SVG emoji fonts are supported.
  190. - COLR/CPAL emoji fonts (custom vector format) are **not** supported.
  191. For Godot to be able to display emoji, the font used (or one of its
  192. :ref:`fallbacks <doc_using_fonts_font_fallbacks>`) needs to include them.
  193. Otherwise, emoji won't be displayed and placeholder "tofu" characters will
  194. appear instead:
  195. .. figure:: img/using_fonts_emoji_placeholder_characters.webp
  196. :align: center
  197. :alt: Default appearance when trying to use emoji in a label
  198. Default appearance when trying to use emoji in a label
  199. After adding a font to display emoji such as
  200. `Noto Color Emoji <https://fonts.google.com/noto/specimen/Noto+Color+Emoji>`__,
  201. you get the expected result:
  202. .. figure:: img/using_fonts_emoji_correct_characters.webp
  203. :align: center
  204. :alt: Correct appearance after adding an emoji font to the label
  205. Correct appearance after adding an emoji font to the label
  206. To use a regular font alongside emoji, it's recommended to specify a
  207. :ref:`fallback font <doc_using_fonts_font_fallbacks>` that points to the
  208. emoji font in the regular font's advanced import options. If you wish to use
  209. the default project font while displaying emoji, leave the **Base Font**
  210. property in FontVariation empty while adding a font fallback pointing to the
  211. emoji font:
  212. .. tip::
  213. Emoji fonts are quite large in size, so you may want to :ref:`load a system
  214. font <doc_using_fonts_system_fonts>` to provide emoji glyphs rather than
  215. bundling it with your project. This allows providing full emoji support in
  216. your project without increasing the size of its exported PCK. The downside
  217. is that emoji will look different depending on the platform, and loading
  218. system fonts is not supported on all platforms.
  219. It's possible to use a system font as a fallback font too.
  220. Using icon fonts
  221. ^^^^^^^^^^^^^^^^
  222. Tools like `Fontello <https://fontello.com/>`__ can be used to generate font
  223. files containing vectors imported from SVG files. This can be used to render
  224. custom vector elements as part of your text, or to create extruded 3D icons
  225. with :ref:`doc_3d_text` and TextMesh.
  226. .. note::
  227. Fontello currently does not support creating multicolored fonts (which Godot
  228. can render). As of November 2022, support for multicolored fonts in icon
  229. font generation tools remains scarce.
  230. Depending on your use cases, this may lead to better results compared to using
  231. the ``img`` tag in :ref:`RichTextLabel <doc_bbcode_in_richtextlabel>`. Unlike
  232. bitmap images (including SVGs which are rasterized on import by Godot),
  233. true vector data can be resized to any size without losing quality.
  234. After downloading the generated font file, load it in your Godot project then
  235. specify it as a custom font for a Label, RichTextLabel or Label3D node. Switch
  236. over to the Fontello web interface, then copy the character by selecting it then
  237. pressing :kbd:`Ctrl + C` (:kbd:`Cmd + C` on macOS). Paste the character in the
  238. **Text** property of your Label node. The character will appear as a placeholder
  239. glyph in the inspector, but it should appear correctly in the 2D/3D viewport.
  240. To use an icon font alongside a traditional font in the same Control, you can
  241. specify the icon font as a :ref:`fallback <doc_using_fonts_font_fallbacks>`.
  242. This works because icon fonts use the Unicode *private use area*, which is
  243. reserved for use by custom fonts and doesn't contain standard glyphs by design.
  244. .. note::
  245. Several modern icon fonts such as `Font Awesome 6 <https://fontawesome.com/download>`__
  246. have a desktop variant that uses *ligatures* to specify icons. This allows you to
  247. specify icons by entering their name directly in the **Text** property of any
  248. node that can display fonts. Once the icon's name is fully entered as text
  249. (such as ``house``), it will be replaced by the icon.
  250. While easier to use, this approach cannot be used with font fallbacks as the main
  251. font's characters will take priority over the fallback font's ligatures.
  252. .. _doc_using_fonts_font_fallbacks:
  253. Font fallbacks
  254. ^^^^^^^^^^^^^^
  255. Godot supports defining one or more fallbacks when the main font lacks a glyph
  256. to be displayed. There are 2 main use cases for defining font fallbacks:
  257. - Use a font that only supports Latin character sets, but use another font to
  258. be able to display text another character set such as Cyrillic.
  259. - Use a font to render text, and another font to render emoji or icons.
  260. Open the Advanced Import Settings dialog by double-clicking the font file in the
  261. FileSystem dock. You can also select the font in the FileSystem dock, go to the
  262. Import dock then choose **Advanced…** at the bottom:
  263. .. figure:: img/using_fonts_advanced_import_settings.webp
  264. :align: center
  265. Import dock
  266. In the dialog that appears, look for **Fallbacks** section
  267. on the sidebar on the right, click the **Array[Font] (size 0)** text to expand
  268. the property, then click **Add Element**:
  269. .. figure:: img/using_fonts_font_fallbacks_add.webp
  270. :align: center
  271. Adding font fallback
  272. Click the dropdown arrow on the new element, then choose a font file using the
  273. **Quick Load** or **Load** options:
  274. .. figure:: img/using_fonts_font_fallbacks_load.webp
  275. :align: center
  276. Loading font fallback
  277. It is possible to add fallback fonts while using the default project font. To do
  278. so, leave the **Base Font** property empty while adding one or more font
  279. fallbacks.
  280. .. note::
  281. Font fallbacks can also be defined on a local basis similar to
  282. :ref:`doc_using_fonts_opentype_font_features`, but this is not covered here
  283. for brevity reasons.
  284. .. _doc_using_fonts_variable_fonts:
  285. Variable fonts
  286. ^^^^^^^^^^^^^^
  287. Godot has full support for `variable fonts <https://variablefonts.io/>`__, which
  288. allow you to use a single font file to represent various font weights and styles
  289. (regular, bold, italic, …). This must be supported by the font file you're using.
  290. To use a variable font, create a :ref:`class_FontVariation` resource in the
  291. location where you intend to use the font, then load a font file within the
  292. FontVariation resource:
  293. .. figure:: img/using_fonts_font_variation_create.webp
  294. :align: center
  295. Creating a FontVariation resource
  296. .. figure:: img/using_fonts_font_variation_load.webp
  297. :align: center
  298. Loading a font file into the FontVariation resource
  299. Scroll down to the FontVariation's **Variation** section, then click the
  300. **Variation Coordinates** text to expand the list of axes that can be adjusted:
  301. .. figure:: img/using_fonts_font_variation_variable_font.webp
  302. :align: center
  303. List of variation axes
  304. The set of axes you can adjust depends on the font loaded. Some variable fonts
  305. only support one axis of adjustment (typically *weight* or *slant*), while
  306. others may support multiple axes of adjustment.
  307. For example, here's the `Inter V <https://rsms.me/inter/>`__ font with a
  308. *weight* of ``900`` and a *slant* of ``-10``:
  309. .. figure:: img/using_fonts_font_variation_variable_font_example.webp
  310. :align: center
  311. Variable font example (Inter V)
  312. .. tip::
  313. While variable font axis names and scales aren't standardized, some common
  314. conventions are usually followed by font designers. For instance, the
  315. *weight* axis typically uses ``400`` as the "regular" font weight and
  316. ``700`` as the "bold" font weight.
  317. You can save the FontVariation to a ``.tres`` resource file to reuse it in other
  318. places:
  319. .. figure:: img/using_fonts_font_variation_save_to_file.webp
  320. :align: center
  321. Saving FontVariation to an external resource file
  322. .. _doc_using_fonts_opentype_font_features:
  323. OpenType font features
  324. ^^^^^^^^^^^^^^^^^^^^^^
  325. Godot supports enabling OpenType font features, which are a standardized way to
  326. define alternate characters that can be toggled without having to swap font
  327. files entirely. Despite being named OpenType font features, these are also
  328. supported in TrueType (``.ttf``) and WOFF/WOFF2 font files.
  329. Support for OpenType features highly depends on the font used. Some fonts don't
  330. support any OpenType features, while other fonts can support dozens of
  331. toggleable features.
  332. There are 2 ways to use OpenType font featutres:
  333. **Globally on a font file**
  334. Open the Advanced Import Settings dialog by double-clicking the font file in the
  335. FileSystem dock. You can also select the font in the FileSystem dock, go to the
  336. Import dock then choose **Advanced…** at the bottom:
  337. .. figure:: img/using_fonts_advanced_import_settings.webp
  338. :align: center
  339. Import dock
  340. In the dialog that appears, look for the **Metadata Overrides > OpenType
  341. Features** section on the sidebar on the right, click the
  342. **Features (0 of N set)** text to expand the property, then click
  343. **Add Feature**:
  344. .. figure:: img/using_fonts_advanced_import_settings_opentype_features.webp
  345. :align: center
  346. OpenType feature overrides in Advanced Import Settings
  347. **In a specific font usage (FontVariation)**
  348. To use a font feature, create a FontVariation resource like you would do for a
  349. :ref:`variable font <doc_using_fonts_variable_fonts>`, then load a font file
  350. within the FontVariation resource:
  351. .. figure:: img/using_fonts_font_variation_create.webp
  352. :align: center
  353. Creating a FontVariation resource
  354. .. figure:: img/using_fonts_font_variation_load.webp
  355. :align: center
  356. Loading a font file into a FontVariation resource
  357. Scroll down to the FontVariation's **OpenType Features** section, click the
  358. **Features (0 of N set)** text to expand the property, then click **Add Feature**
  359. and select the desired feature in the dropdown:
  360. .. figure:: img/using_fonts_font_variation_opentype_features.webp
  361. :align: center
  362. Specifying OpenType features in a FontVariation resource
  363. For example, here's the `Inter <https://rsms.me/inter/>`__ font without the
  364. *Slashed Zero* feature (top), then with the *Slashed Zero* OpenType feature enabled
  365. (bottom):
  366. .. figure:: img/using_fonts_font_variation_slashed_zero.webp
  367. :align: center
  368. OpenType feature comparison (Inter)
  369. .. _doc_using_fonts_system_fonts:
  370. System fonts
  371. ^^^^^^^^^^^^
  372. .. warning::
  373. Loading system fonts is only supported on Windows, macOS and Linux.
  374. System fonts are a different type of resource compared to imported fonts. They
  375. are never actually imported into the project, but are loaded at run-time. This
  376. has 2 benefits:
  377. - The fonts are not included within the exported PCK file, leading to a smaller
  378. file size for the exported project.
  379. - Since fonts are not included with the exported project, this avoids licensing
  380. issues that would occur if proprietary system fonts were distributed alongside
  381. the project.
  382. Create a SystemFont resource in the location where you desire to use the system font:
  383. .. figure:: img/using_fonts_system_font_create.webp
  384. :align: center
  385. Creating a SystemFont resource
  386. .. figure:: img/using_fonts_system_font_specify.webp
  387. :align: center
  388. Specifying a font name to use in a SystemFont resource
  389. You can either specify one or more font names explicitly (such as ``Arial``), or
  390. specify the name of a font *alias* that maps to a "standard" default font for
  391. the system:
  392. +----------------+-----------------+----------------+-------------------------+
  393. | Font alias | Windows | macOS/iOS | Linux |
  394. +================+=================+================+=========================+
  395. | ``sans-serif`` | Arial | Helvetica | *Handled by fontconfig* |
  396. +----------------+-----------------+----------------+-------------------------+
  397. | ``serif`` | Times New Roman | Times | *Handled by fontconfig* |
  398. +----------------+-----------------+----------------+-------------------------+
  399. | ``monospace`` | Courier New | Courier | *Handled by fontconfig* |
  400. +----------------+-----------------+----------------+-------------------------+
  401. | ``cursive`` | Comic Sans MS | Apple Chancery | *Handled by fontconfig* |
  402. +----------------+-----------------+----------------+-------------------------+
  403. | ``fantasy`` | Gabriola | Papyrus | *Handled by fontconfig* |
  404. +----------------+-----------------+----------------+-------------------------+
  405. If specifying more than one font, the first font that is found on the system
  406. will be used (from top to bottom). Font names and aliases are case-insensitive
  407. on all platforms.
  408. Like for font variations, you can save the SystemFont arrangement to a resource
  409. file to reuse it in other places.
  410. .. note::
  411. Unlike Windows and macOS/iOS, the set of default fonts shipped on Linux
  412. depends on the distribution. This means that on different Linux
  413. distributions, different fonts may be displayed for a given system font name
  414. or alias.
  415. .. _doc_using_fonts_font_prerendering:
  416. Font prerendering
  417. ^^^^^^^^^^^^^^^^^
  418. When using traditional rasterized fonts, Godot caches glyphs on a per-font and
  419. per-size basis. This reduces stuttering, but it can still occur the first time a
  420. glyph is displayed when running the project. This can be especially noticeable
  421. at higher font sizes or on mobile devices.
  422. When using MSDF fonts, they only need to be rasterized once to a special signed
  423. distance field texture. This means caching can be done purely on a per-font
  424. basis, without taking the font size into consideration. However, the initial
  425. rendering of MSDF fonts is slower compared to a traditional rasterized font at a
  426. medium size.
  427. To avoid stuttering issues related to font rendering, it is possible to
  428. *prerender* certain glyphs. This can be done for all glyphs you intend to use
  429. (for optimal results), or only for common glyphs that are most likely to appear
  430. during gameplay (to reduce file size). Glyphs that aren't pre-rendered will be
  431. rasterizd on-the-fly as usual.
  432. .. note::
  433. In both cases (traditional and MSDF), font rasterization is done on the CPU.
  434. This means that the GPU performance doesn't affect how long it takes for fonts
  435. to be rasterized.
  436. Open the Advanced Import Settings dialog by double-clicking the font file in the
  437. FileSystem dock. You can also select the font in the FileSystem dock, go to the
  438. Import dock then choose **Advanced…** at the bottom:
  439. .. figure:: img/using_fonts_advanced_import_settings.webp
  440. :align: center
  441. Import dock
  442. Move to the **Pre-render Configurations** tab of the Advanced Import Settings dialog,
  443. then add a configuration by clicking the "plus" symbol:
  444. .. figure:: img/using_fonts_advanced_import_settings_prerender_new_configuration.webp
  445. :align: center
  446. :alt: Adding a new prerendering configuration in the Advanced Import Settings dialog
  447. Adding a new prerendering configuration in the Advanced Import Settings dialog
  448. After adding a configuration, make sure it is selected by clicking its name
  449. once. You can also rename the configuration by double-clicking it.
  450. There are 2 ways to add glyphs to be prerendered to a given configuration. It is
  451. possible to use both approaches in a cumulative manner:
  452. **Using text from translations**
  453. For most projects, this approach is the most convenient to use, as it
  454. automatically sources text from your language translations. The downside is that
  455. it can only be used if your project supports
  456. :ref:`internationalization <doc_internationalizing_games>`. Otherwise, stick to
  457. the "Using custom text" approach described below.
  458. After adding translations to the Project Settings, use the
  459. **Glyphs from the Translations** tab to check translations by double-clicking them,
  460. then click **Shape All Strings in the Translations and Add Glyphs** at the bottom:
  461. .. figure:: img/using_fonts_advanced_import_settings_prerender_translation.webp
  462. :align: center
  463. :alt: Enabling prerendering in the Advanced Import Settings dialog with the Glyphs from the Translations tab
  464. Enabling prerendering in the Advanced Import Settings dialog with the **Glyphs from the Translations** tab
  465. .. note::
  466. The list of prerendered glyphs is not automatically updated when
  467. translations are updated, so you need to repeat this process if your
  468. translations have changed significantly.
  469. **Using custom text**
  470. While it requires manually specifying text that will appear in the game, this is
  471. the most efficient approach for games which don't feature user text input. This
  472. approach is worth exploring for mobile games to reduce the file size of the
  473. distributed app.
  474. To use existing text as a baseline for prerendering, go to the **Glyphs from the
  475. Text** sub-tab of the Advanced Import Settings dialog, enter text in the window
  476. on the right, then click **Shape Text and Add Glyphs** at the bottom of the
  477. dialog:
  478. .. figure:: img/using_fonts_advanced_import_settings_prerender_text.webp
  479. :align: center
  480. :alt: Enabling prerendering in the Advanced Import Settings dialog, Glyphs from the Text tab
  481. Enabling prerendering in the Advanced Import Settings dialog with the **Glyphs from the Text** tab
  482. .. tip::
  483. If your project supports :ref:`internationalization <doc_internationalizing_games>`,
  484. you can paste the contents of your CSV or PO files in the above box to quickly
  485. prerender all possible characters that may be rendered during gameplay
  486. (excluding user-provided or non-translatable strings).
  487. **By enabling character sets**
  488. The second method requires less configuration and fewer updates if your game's
  489. text changes, and is more suited to text-heavy games or multiplayer games with
  490. chat. On the other hand, it may cause glyphs that never show up in the game to
  491. be prerendered, which is less efficient in terms of file size.
  492. To use existing text as a baseline for prerendering, go to the **Glyphs from the
  493. Character Map** sub-tab of the Advanced Import Settings dialog, then
  494. *dobule-click* character sets to be enabled on the right:
  495. .. figure:: img/using_fonts_advanced_import_settings_prerender_character_map.webp
  496. :align: center
  497. :alt: Enabling prerendering in the Advanced Import Settings dialog, Glyphs from the Character Map tab
  498. Enabling prerendering in the Advanced Import Settings dialog with the **Glyphs from the Character Map** tab
  499. To ensure full prerendering, the character sets you need to enable depend on
  500. which languages are supported in your game. For English, only **Basic Latin**
  501. needs to be enabled. Enabling **Latin-1 Supplement** as well allows fully
  502. covering many more languages, such as French, German and Spanish. For Russian,
  503. **Cyrillic** needs to be enabled, and so on.
  504. Default project font properties
  505. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  506. In the **GUI > Theme** section of the advanced Project Settings, you can choose
  507. how the default font should be rendered:
  508. - **Default Font Antialiasing:** Controls the
  509. :ref:`antialiasing <doc_using_fonts_antialiasing>` method used
  510. for the default project font.
  511. - **Default Font Hinting:** Controls the
  512. :ref:`hinting <doc_using_fonts_hinting>` method used for
  513. the default project font.
  514. - **Default Font Subpixel Positioning:** Controls the
  515. :ref:`subpixel positioning <doc_using_fonts_subpixel_positioning>`
  516. method for the default project font.
  517. - **Default Font Multichannel Signed Distance Field:** If ``true``, makes the
  518. default project font use `MSDF font rendering <doc_using_fonts_msdf>` instead
  519. of traditional rasterization.
  520. - **Default Font Generate Mipmaps:** If ``true``, enables
  521. :ref:`mipmap <doc_using_fonts_mipmaps>` generation and
  522. usage for the default project font.
  523. .. note::
  524. These project settings *only* affect the default project font (the one that
  525. is hardcoded in the engine binary).
  526. Custom fonts' properties are governed by their respective import options
  527. instead. You can use the **Import Defaults** section of the Project Settings
  528. dialog to override default import options for custom fonts.