TextParagraph in Godot – Complete Guide

Welcome to the world of Godot 4, where bringing your gaming visions to life is just a few lines of code away. Today, we’ve set our sights on the TextParagraph class—a powerful and essential feature within this engine that can elevate your game’s text handling to new heights. Whether you’re creating dynamic storylines, engaging dialogues, or intuitive interfaces, mastering TextParagraph is your key to crafting an immersive experience for players. So, let us step into the realm of Godot 4 and discover the capabilities of the TextParagraph class together.

What is the TextParagraph Class?

The TextParagraph class is an abstraction layer over Godot’s TextServer that simplifies the management of a single paragraph of text. It encompasses features such as alignment, text direction, and inline object handling, making it a versatile tool for developers.

What is the TextParagraph Class Used For?

TextParagraph offers developers a rich set of properties and methods to efficiently control paragraph formatting, appearance, and behavior in Godot. It’s used for:

  • Customizing text alignment: Horizontally align your text with ease.
  • Setting line break rules: Decide how and where text wraps to the next line.
  • Embedding objects: Sprinkle in icons or interactive elements within your paragraph.
  • Drawing with detail: Render your text with precision, adding drop caps or outlines for stylistic flair.

Why Should I Learn It?

Getting to grips with TextParagraph means you’ll have:

  • Enhanced control: Over how text is displayed, giving your games a professional touch.
  • Adaptability: The ability to handle various writing systems and languages.
  • Creative freedom: The power to create compelling UIs with custom text features.

By mastering this class, you’ll be able to present your game’s narrative and instructions in a clear, visually appealing, and user-friendly manner—essential skills for any aspiring game developer.

CTA Small Image

Creating and Customizing a TextParagraph

To begin, let’s create a basic TextParagraph instance. Here, you’ll learn to instantiate the class and examine some simple ways to customize your text through properties.

var paragraph = TextParagraph.new()
paragraph.text = "Hello, Godot 4!"

Once created, setting the font is crucial for visibility and aesthetics. You can load a custom font and apply it to the paragraph like this:

var font = load("res://path_to_your_font.tres")

Now, let’s align the paragraph in the center of our scene. TextParagraph provides properties like ‘align’ to help achieve this:

paragraph.align = TextParagraph.ALIGN_CENTER

Additionally, to set direction of the text (useful for languages with different writing directions), use the ‘set_base_direction’ method:

# Use DIRECTION_RTL for right-to-left text

These basics give you the power to create readable text that fits nicely into your game’s interface.

Manipulating Lines and Embedding Objects

Beyond basic formatting, knowing how to manipulate lines and embed objects within your text can enrich user interfaces. Let’s see how TextParagraph enables such manipulation.

For instance, to specify the maximum width before wrapping text to a new line, set the ‘wrap_width’ property:

paragraph.wrap_width = 200

This ensures that your paragraph doesn’t stretch beyond 200 pixels, making it versatile for responsive design across devices.

Embedding objects like icons inside a paragraph is also a breeze with TextParagraph. First, create an inline object:

var inline_obj = InlineObject.new()
inline_obj.size = Vector2(10, 10) # Replace with the size of your icon

Then, embed this object within the text by using the ‘add_inline_object’ method:

paragraph.add_inline_object(0, inline_obj) # 0 is the index in the text

After the inline object is added, whenever the paragraph is rendered, there will be a placeholder at the specified index. This placeholder will then be occupied by the inline object.

Line Breaks and Text Measurement

Controlling how and where your text breaks onto the next line can greatly affect readability. Use the ‘break_policy’ property to enforce your preferred line-breaking rules:

paragraph.break_policy = TextParagraph.BREAK_MANDATORY

The ‘BREAK_MANDATORY’ policy will ensure that line breaks only occur where you explicitly include them (for instance, using the newline character ‘\n’).

Also, you might need to measure the height and width of the text block to layout other UI elements around it. Use ‘get_size’ for this:

var size = paragraph.get_size()
print("Width: ", size.x, " Height: ", size.y)

Being able to measure text is particularly important in responsive interface design, where elements must adapt to different screen sizes and resolutions.

With these code examples, you’re well on your way to becoming proficient with the TextParagraph class in Godot 4. Don’t hesitate to experiment with the different properties and methods to find the customizations that best fit your game’s unique style.Continuing our exploration of Godot 4’s TextParagraph class, let’s delve into more advanced capabilities such as applying color, decorations, and understanding performance considerations when rendering paragraphs.

Applying Color to Text
To enhance the visual appeal of your text, you may want to apply color. This is how you can set the color for the entire paragraph:

paragraph.default_color = Color(1, 1, 0, 1) # A vibrant yellow with full opacity

But what if you want to merely change the color of a specific word or line? You can use ‘add_color_override’. Here’s how:

paragraph.add_color_override(0, 5, Color(0, 1, 0, 1)) # Changes first five characters to green

Add Decorations Like Underline or Strikethrough
Decorative text features like underline or strikethrough can be significant for emphasis or design. Here’s how you can add an underline:

paragraph.add_underline(7, 12) # Underlines characters from indices 7 to 12

Similarly, for a strikethrough effect, you would use:

paragraph.add_strikethrough(7, 12) # Strikes through characters from indices 7 to 12

Rendering the TextParagraph
Rendering the text to the screen is easy with the ‘draw’ method. Incorporate it within the _draw() callback of a CanvasItem-based node:

func _draw():
    paragraph.draw(self, Vector2.ZERO)

This will render the paragraph at the top-left corner of the node.

Performance Considerations
Optimizing the performance of your game is crucial. Here are some things to keep in mind:

– Use ‘visibility_notifier’ to only process text when it’s visible on the screen.
– Avoid changing the text too often — measure changes and update them at strategic moments.
– Cache the size calculations if you need to use them frequently to layout other UI elements.

Developing a performance-conscious approach to working with TextParagraph will help ensure that your game runs smoothly.

Responsive Text Layout
Lastly, consider the importance of responsive design in your game. Here’s a code snippet to help resize a paragraph’s width based on the screen size:

func _ready():
    var screen_width = OS.window_size.x
    paragraph.wrap_width = screen_width * 0.8 # 80% of the screen width

Resizing your text containers this way ensures that your UI elements look great across different device resolutions and aspect ratios.

By now, you’re equipped with an expanded toolkit of Godot 4’s TextParagraph capabilities. Remember, the quality of the UI significantly impacts player experience. Utilize these techniques in TextParagraph to create immersive, clear, and engaging text for your games. Embrace these nuances and craft your game’s narrative and interface with polished finesse!Building upon the foundation of the earlier sections, we now take the TextParagraph class even further, exploring text animations, pagination, and the integration of user input. These advanced features can bring life and interactivity to your game’s text elements.

Animating Text
Animating text can capture the player’s attention or convey a sense of dynamism. Here’s how to change the color of a TextParagraph over time, by interpolating between colors within the _process method of a node:

func _process(delta):
    var current_color = paragraph.default_color
    var target_color = Color(1, 0, 0, 1) # Red
    var new_color = current_color.linear_interpolate(target_color, delta * 0.5)
    paragraph.default_color = new_color

Handling Pagination
When dealing with long texts, fitting them into the UI can be challenging. Pagination can help break the text into manageable page-sized chunks. Here’s how to measure text and determine where to split into pages:

# Assume we have a text string and a desired page height of 400 pixels.
var full_text = paragraph.text
var page_height = 400
var start_index = 0
var end_index = 0

while end_index  page_height:
        # Find the last line that fits within the page height and break the page there.
        end_index = paragraph.get_line_breaks(page_height).pop_back()
        var page_text = full_text.substr(start_index, end_index - start_index)
        # Do something with the page_text, like adding it to an array of pages.
        start_index = end_index
        # All the remaining text fits on a page.
        end_index = full_text.length()

Interactive Text
To create an engaging text experience, you can make it respond to user input. We can hide and reveal parts of the paragraph or interact with inline objects:

# Let's say we want to reveal the text one letter at a time.
var revealed_length = 0
func _process(delta):
    if revealed_length < paragraph.text.length():
        revealed_length += 1
        paragraph.visible_characters = revealed_length

Here’s an example of interacting with inline objects when a player hovers over or clicks them:

func _on_MouseEntered(index):
    # Change color or size when mouse enters the area of an inline object.
    paragraph.modify_inline_object(index, {"color": Color(1, 0, 0, 1)})

func _on_MouseExited(index):
    # Revert to original properties when the mouse exits.
    paragraph.modify_inline_object(index, {"color": paragraph.default_color})

And lastly, for clickable inline objects:

func _input(event):
    if event is InputEventMouseButton and event.pressed:
        var click_position = event.position
        var object_index = paragraph.get_inline_object_at_position(click_position)
        if object_index != -1:
            # Respond to the click, e.g., display a tooltip or open a link.

Customization and Final Thoughts
The Godot 4 TextParagraph class is highly customizable, and its methods allow for a wide range of effects and functionalities. Experimenting with these features in various combinations can result in a richly interactive and visually appealing text user interface.

Here’s a quick example of combining different properties for a stylized look:

# Set italic and bold style to your text.
paragraph.add_italics(0, paragraph.text.length())
paragraph.add_bold(0, paragraph.text.length())

Remember, creativity in using these tools is the key to making your game’s text stand out. Keep refining and testing your text layouts, animations, and interactions to ensure they contribute positively to the overall gameplay experience. Through thoughtful application of what you’ve learned, you can craft a narrative and interface that truly resonate with your audience.

Continue Your Game Development Journey with Godot

Your foray into the world of Godot 4 and the versatile TextParagraph class is just the beginning. To further enhance your skills and put them to practical use, continuing your learning journey is key. Our Godot Game Development Mini-Degree is the perfect next step for you. This comprehensive series offers a wide range of courses covering everything from the basics to more advanced game development concepts in Godot 4. With flexible learning options including video lessons, interactive lessons, and hands-on coding practice, you’ll be able to build a solid portfolio of real Godot projects.

Whether you’re just starting or already have some experience under your belt, our curriculum is tailored to elevate your game development skills to new levels. The Mini-Degree will guide you through creating varied game genres, mastering GDScript, and building rich gameplay experiences. You’ll gain the in-demand skills that could open doors to new career opportunities in the game development industry.

For those seeking an even broader range of content, be sure to check out our full collection of Godot courses. At Zenva, we’re committed to providing high-quality, accessible education that empowers you to go from beginner to professional. So, take the next step and continue your game development journey with us today!


You’ve taken an exciting deep dive into the TextParagraph class in Godot 4 and have seen how it can transform text into a dynamic, engaging element in your games. Remember, the tools and techniques discussed are just the tip of the iceberg; there’s a whole world of possibilities awaiting you in game development with Godot. As you continue to harness these new skills, keep experimenting, keep learning, and most importantly, keep creating the games of your dreams.

Should you be eager to advance further and master the intricacies of game development, our Godot Game Development Mini-Degree is the ideal resource to support your growth. With our curriculum, you’ll be well-equipped to tackle any game development challenge that comes your way. We at Zenva are excited to be a part of your journey and can’t wait to see what you’ll build next. Dive into our courses, and let’s create something extraordinary together!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.