godot-docs/classes/class_dynamicfont.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/3.6/doc/classes/DynamicFont.xml.

.. _class_DynamicFont:

DynamicFont
===========

**Inherits:** :ref:`Font<class_Font>` **<** :ref:`Resource<class_Resource>` **<** :ref:`Reference<class_Reference>` **<** :ref:`Object<class_Object>`

DynamicFont renders vector font files at runtime.

.. rst-class:: classref-introduction-group

Description
-----------

DynamicFont renders vector font files dynamically at runtime instead of using a prerendered texture atlas like :ref:`BitmapFont<class_BitmapFont>`. This trades the faster loading time of :ref:`BitmapFont<class_BitmapFont>`\ s for the ability to change font parameters like size and spacing during runtime. :ref:`DynamicFontData<class_DynamicFontData>` is used for referencing the font file paths. DynamicFont also supports defining one or more fallback fonts, which will be used when displaying a character not supported by the main font.

DynamicFont uses the `FreeType <https://www.freetype.org/>`__ library for rasterization. Supported formats are TrueType (``.ttf``), OpenType (``.otf``), Web Open Font Format 1 (``.woff``), and  Web Open Font Format 2 (``.woff2``).

::

    var dynamic_font = DynamicFont.new()
    dynamic_font.font_data = load("res://BarlowCondensed-Bold.ttf")
    dynamic_font.size = 64
    $"Label".set("custom_fonts/font", dynamic_font)

\ **Note:** DynamicFont doesn't support features such as kerning, right-to-left typesetting, ligatures, text shaping, variable fonts and optional font features yet. If you wish to "bake" an optional font feature into a TTF font file, you can use `FontForge <https://fontforge.org/>`__ to do so. In FontForge, use **File > Generate Fonts**, click **Options**, choose the desired features then generate the font.

.. rst-class:: classref-introduction-group

Tutorials
---------

- `3D Voxel Demo <https://godotengine.org/asset-library/asset/676>`__

.. rst-class:: classref-reftable-group

Properties
----------

.. table::
   :widths: auto

   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`int<class_int>`                         | :ref:`extra_spacing_bottom<class_DynamicFont_property_extra_spacing_bottom>` | ``0``                   |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`int<class_int>`                         | :ref:`extra_spacing_char<class_DynamicFont_property_extra_spacing_char>`     | ``0``                   |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`int<class_int>`                         | :ref:`extra_spacing_space<class_DynamicFont_property_extra_spacing_space>`   | ``0``                   |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`int<class_int>`                         | :ref:`extra_spacing_top<class_DynamicFont_property_extra_spacing_top>`       | ``0``                   |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`DynamicFontData<class_DynamicFontData>` | :ref:`font_data<class_DynamicFont_property_font_data>`                       |                         |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`Color<class_Color>`                     | :ref:`outline_color<class_DynamicFont_property_outline_color>`               | ``Color( 1, 1, 1, 1 )`` |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`int<class_int>`                         | :ref:`outline_size<class_DynamicFont_property_outline_size>`                 | ``0``                   |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`int<class_int>`                         | :ref:`size<class_DynamicFont_property_size>`                                 | ``16``                  |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`bool<class_bool>`                       | :ref:`use_filter<class_DynamicFont_property_use_filter>`                     | ``false``               |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+
   | :ref:`bool<class_bool>`                       | :ref:`use_mipmaps<class_DynamicFont_property_use_mipmaps>`                   | ``false``               |
   +-----------------------------------------------+------------------------------------------------------------------------------+-------------------------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                          | :ref:`add_fallback<class_DynamicFont_method_add_fallback>` **(** :ref:`DynamicFontData<class_DynamicFontData>` data **)**                            |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`String<class_String>`                   | :ref:`get_available_chars<class_DynamicFont_method_get_available_chars>` **(** **)** |const|                                                         |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`DynamicFontData<class_DynamicFontData>` | :ref:`get_fallback<class_DynamicFont_method_get_fallback>` **(** :ref:`int<class_int>` idx **)** |const|                                             |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                         | :ref:`get_fallback_count<class_DynamicFont_method_get_fallback_count>` **(** **)** |const|                                                           |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                         | :ref:`get_spacing<class_DynamicFont_method_get_spacing>` **(** :ref:`int<class_int>` type **)** |const|                                              |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                          | :ref:`remove_fallback<class_DynamicFont_method_remove_fallback>` **(** :ref:`int<class_int>` idx **)**                                               |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                          | :ref:`set_fallback<class_DynamicFont_method_set_fallback>` **(** :ref:`int<class_int>` idx, :ref:`DynamicFontData<class_DynamicFontData>` data **)** |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                          | :ref:`set_spacing<class_DynamicFont_method_set_spacing>` **(** :ref:`int<class_int>` type, :ref:`int<class_int>` value **)**                         |
   +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Enumerations
------------

.. _enum_DynamicFont_SpacingType:

.. rst-class:: classref-enumeration

enum **SpacingType**:

.. _class_DynamicFont_constant_SPACING_TOP:

.. rst-class:: classref-enumeration-constant

:ref:`SpacingType<enum_DynamicFont_SpacingType>` **SPACING_TOP** = ``0``

Spacing at the top.

.. _class_DynamicFont_constant_SPACING_BOTTOM:

.. rst-class:: classref-enumeration-constant

:ref:`SpacingType<enum_DynamicFont_SpacingType>` **SPACING_BOTTOM** = ``1``

Spacing at the bottom.

.. _class_DynamicFont_constant_SPACING_CHAR:

.. rst-class:: classref-enumeration-constant

:ref:`SpacingType<enum_DynamicFont_SpacingType>` **SPACING_CHAR** = ``2``

Spacing for each character.

.. _class_DynamicFont_constant_SPACING_SPACE:

.. rst-class:: classref-enumeration-constant

:ref:`SpacingType<enum_DynamicFont_SpacingType>` **SPACING_SPACE** = ``3``

Spacing for the space character.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Property Descriptions
---------------------

.. _class_DynamicFont_property_extra_spacing_bottom:

.. rst-class:: classref-property

:ref:`int<class_int>` **extra_spacing_bottom** = ``0``

.. rst-class:: classref-property-setget

- void **set_spacing** **(** :ref:`int<class_int>` type, :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_spacing** **(** :ref:`int<class_int>` type **)** |const|

Extra spacing at the bottom in pixels.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_extra_spacing_char:

.. rst-class:: classref-property

:ref:`int<class_int>` **extra_spacing_char** = ``0``

.. rst-class:: classref-property-setget

- void **set_spacing** **(** :ref:`int<class_int>` type, :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_spacing** **(** :ref:`int<class_int>` type **)** |const|

Extra spacing for each character in pixels.

This can be a negative number to make the distance between characters smaller.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_extra_spacing_space:

.. rst-class:: classref-property

:ref:`int<class_int>` **extra_spacing_space** = ``0``

.. rst-class:: classref-property-setget

- void **set_spacing** **(** :ref:`int<class_int>` type, :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_spacing** **(** :ref:`int<class_int>` type **)** |const|

Extra spacing for the space character (in addition to :ref:`extra_spacing_char<class_DynamicFont_property_extra_spacing_char>`) in pixels.

This can be a negative number to make the distance between words smaller.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_extra_spacing_top:

.. rst-class:: classref-property

:ref:`int<class_int>` **extra_spacing_top** = ``0``

.. rst-class:: classref-property-setget

- void **set_spacing** **(** :ref:`int<class_int>` type, :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_spacing** **(** :ref:`int<class_int>` type **)** |const|

Extra spacing at the top in pixels.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_font_data:

.. rst-class:: classref-property

:ref:`DynamicFontData<class_DynamicFontData>` **font_data**

.. rst-class:: classref-property-setget

- void **set_font_data** **(** :ref:`DynamicFontData<class_DynamicFontData>` value **)**
- :ref:`DynamicFontData<class_DynamicFontData>` **get_font_data** **(** **)**

The font data.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_outline_color:

.. rst-class:: classref-property

:ref:`Color<class_Color>` **outline_color** = ``Color( 1, 1, 1, 1 )``

.. rst-class:: classref-property-setget

- void **set_outline_color** **(** :ref:`Color<class_Color>` value **)**
- :ref:`Color<class_Color>` **get_outline_color** **(** **)**

The font outline's color.

\ **Note:** It's recommended to leave this at the default value so that you can adjust it in individual controls. For example, if the outline is made black here, it won't be possible to change its color using a Label's font outline modulate theme item.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_outline_size:

.. rst-class:: classref-property

:ref:`int<class_int>` **outline_size** = ``0``

.. rst-class:: classref-property-setget

- void **set_outline_size** **(** :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_outline_size** **(** **)**

The font outline's thickness in pixels (not relative to the font size).

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_size:

.. rst-class:: classref-property

:ref:`int<class_int>` **size** = ``16``

.. rst-class:: classref-property-setget

- void **set_size** **(** :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_size** **(** **)**

The font size in pixels.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_use_filter:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **use_filter** = ``false``

.. rst-class:: classref-property-setget

- void **set_use_filter** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_use_filter** **(** **)**

If ``true``, filtering is used. This makes the font blurry instead of pixelated when scaling it if font oversampling is disabled or ineffective. It's recommended to enable this when using the font in a control whose size changes over time, unless a pixel art aesthetic is desired.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_property_use_mipmaps:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **use_mipmaps** = ``false``

.. rst-class:: classref-property-setget

- void **set_use_mipmaps** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_use_mipmaps** **(** **)**

If ``true``, mipmapping is used. This improves the font's appearance when downscaling it if font oversampling is disabled or ineffective.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Method Descriptions
-------------------

.. _class_DynamicFont_method_add_fallback:

.. rst-class:: classref-method

void **add_fallback** **(** :ref:`DynamicFontData<class_DynamicFontData>` data **)**

Adds a fallback font.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_method_get_available_chars:

.. rst-class:: classref-method

:ref:`String<class_String>` **get_available_chars** **(** **)** |const|

Returns a string containing all the characters available in the main and all the fallback fonts.

If a given character is included in more than one font, it appears only once in the returned string.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_method_get_fallback:

.. rst-class:: classref-method

:ref:`DynamicFontData<class_DynamicFontData>` **get_fallback** **(** :ref:`int<class_int>` idx **)** |const|

Returns the fallback font at index ``idx``.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_method_get_fallback_count:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_fallback_count** **(** **)** |const|

Returns the number of fallback fonts.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_method_get_spacing:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_spacing** **(** :ref:`int<class_int>` type **)** |const|

Returns the spacing for the given ``type`` (see :ref:`SpacingType<enum_DynamicFont_SpacingType>`).

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_method_remove_fallback:

.. rst-class:: classref-method

void **remove_fallback** **(** :ref:`int<class_int>` idx **)**

Removes the fallback font at index ``idx``.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_method_set_fallback:

.. rst-class:: classref-method

void **set_fallback** **(** :ref:`int<class_int>` idx, :ref:`DynamicFontData<class_DynamicFontData>` data **)**

Sets the fallback font at index ``idx``.

.. rst-class:: classref-item-separator

----

.. _class_DynamicFont_method_set_spacing:

.. rst-class:: classref-method

void **set_spacing** **(** :ref:`int<class_int>` type, :ref:`int<class_int>` value **)**

Sets the spacing for ``type`` (see :ref:`SpacingType<enum_DynamicFont_SpacingType>`) to ``value`` in pixels (not relative to the font size).

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`