GUI Scripting: Sign Text Example

This page is part of a series. See GUI Scripting Language for overview.

Introduction

This example, adapted from a 2017 response by Obsttorte to a question by UberMann, illustrates:

• How to create wall plaques from available text prefabs and a gui-surface-containing model, which is not entirely obvious.
• The minimal GUI file involved, that fetches values from spawnargs.
• Replacing the stock GUI with a customized one, to change text alignment.
• Further generalizing an entity and GUI with a gui:: parameter.

This topic deals with in-world signs that don't need to be expandable by frobbing. Similar needs are considered in Text Decals for Signs etc., but that approach treats the "Entity GUi" showing the text and the background (e.g., plaque or really anything flat) as two independent items, which can be adjusted in space relative to each other. The treatment here deals with a specific model (gui_sign_squarish01.lwo) that has an "Entity GUi" surface baked in during modeling; that surface cannot be repositioned in DR with respect to the rest of the model.

While there is a stock entityDef (atdm:readable_immobile_sign_small01) that also relies on that model, it uses a bloated GUI. So we'll ignore that entityDef here, and just use a simple off-the-shelf GUI that gets its sign text from a spawnarg instead of from an .xd file.

Setup

TDM's standard distribution includes text for signs. These are available as prefabs with various fonts through the Entity Inspector, for example:

readables/sign_text_decals/sign_text_carolingia.pfb

When you import this prefab into Dark Radiant, you will see only a blue "Entity GUI" rectangle. In the next step, you're going to throw away that rectangle, and substitute a model that contains it's own "Entity GUI". So why select the prefab in the first place? Because it's a quick trick to get these needed spawnarg exactly right:

gui		guis/readables/sign_text_decals/sign_text_carolingia.gui
gui_parm1	put text here

Next, in the Entity Inspector, select the spawnarg "model" (with dummy value "sign_text") and use "Choose Model..." to navigate to:

models/darkmod/decorative/signs/gui_sign_squarish01.lwo

Be sure to select the model whose name starts with "gui_...". DR will give you a popup warning:

Changing this entity's model to the selected value will remove all child primitives from it: sign_text

That's fine. The result is a func_static with the spawnargs needed, as shown. The final step would be to change gui_parm1's value to the real text you want on the sign.

The example sign plaque, shown in DR, with the corresponding spawnargs seen in the Entity Viewer.

The GUI

The default stock gui being referenced is:

windowDef Desktop
{
    rect 0, 0, 640, 480
    backcolor 0, 0, 0, 0

    windowDef SignText
    {
        rect 0, 0, 640,480
        backcolor 0, 0, 0, 0
        text    "gui::gui_parm1"
        font "fonts/carolingia"
        textscale 2.25
        forecolor 0, 0, 0, 0.66
        visible 1
    }
}

Editing the GUI to Change the Text Alignment

A downside of using the stock GUI is that the text is not horizontally centered on the sign. Since no text alignment property was specified, it defaults to left alignment. While you can fake the centering with spaces, for the example here, let's instead modify the GUI to change the text alignment. Begin by cloning and renaming the file (but still with the .gui extension and stored in your guis subfolder). In a text editor, add the line:

textalign 1

to the SignText block. The textalign property takes values:

0	= left alignment, the default
1	= centered
2	= right alignment.

Then in DR, change the "gui" spawnarg to point to your altered GUI file.

Generalizing: Making the Alignment a Gui:: Parameter

You can make the textalign argument a guiParm, too, so you can handle it via the spawnargs. In the Entity Inspector, add a spawnarg, with a default value of 1 (for centered). We could call it "gui_parm2", but let's be more informative:

gui_parm_text_align	 1

Then further modify your gui to:

windowDef Desktop
{
    rect 0, 0, 640, 480
    backcolor 0, 0, 0, 0

    windowDef SignText
    {
        rect 0, 0, 640,480
        backcolor 0, 0, 0, 0
        text    "gui::gui_parm1"
        font "fonts/carolingia"
        textscale 2.25
        forecolor 0, 0, 0, 0.66
        visible 1
        textalign "gui::gui_parm_text_align"
    }
}

Besides adjusting the centering, you may find you need to tweak the textscale value to fit your word choice. (If you use the method of Text Decals for Signs etc., where the overlay is not embedded in the sign, you can alternatively resize the blue "Entity GUI" patch in DR to achieve the same ends.)

If providing i18n support, you could easily enter a #str value in gui_parm1. Adjusting the textscale automatically for different languages would be more difficult.

Final Thoughts

If you want to use this sign with this font multiple places in your project, or in future projects, you could "Export Selected as Prefab" into your own .pfb file, stored whether you wish (not necessarily your FM). Subsequently, use "Import Prefabs" with "Browse Custom Paths" to fetch it. If you customized the .gui file, you'll need to remember to copy it too.

As mentioned at the outset, for the sign model being used here, a pre-existing entityDef (atdm:readable_immobile_sign_small01) is available. Why not use that here? Because its not so good for explaining how GUIs work. That entityDef inherits the complicated readables_base system, designed for frobable multipage readables that get their data from an .xd file. The ...sign_small01 entityDef does turn off the inherited frobability by default. But still, a simpler GUI that gets the text from a spawnarg is what's needed.

FYI, other entityDefs in tdm_readable.def that use models with embedded "Entity Gui" surfaces are:

• atdm:readable_immobile_paper01 and atdm:readable_mobile_paper01 use models/darkmod/readables/gui_paper01.lwo
• atdm:readable_immobile_scroll01 and atdm:readable_mobile_scroll01 use models/darkmod/readables/gui_scroll01.lwo
• atdm:readable_immobile_book_open01 and atdm:readable_mobile_book_open01 use models/darkmod/readables/gui_book_open01.lwo

All of these are frobbable by default - unlike ...sign_small01.