Super Text Mesh Documentation
        
    
    
    




Table of Contents

Features

  1. Adding Super Text Mesh to Unity
  2. Text Data File & Rich Text Tags
  3. Functions, Variables & Events
  4. Shaders & Shadows
  5. Utilities

Notes
FAQ
ChangeLog
Update Warnings
Credits


Features


1. Adding Super Text Mesh to Unity

a. Importing Super Text Mesh into Unity



Recommended minimum install.

To import Super Text Mesh into your project, either drag in the .unitypackage file, or get it from the asset store window.

Imported folders, what they do, and if you need to import them or not, alphabetically:

Additional support packages are listed under Support Packages for Other Assets.

The outline shaders take a long time to compile, so don't import them if you're in a hurry or don't want to use them.

b. Adding Super Text Mesh to a Scene



Adding as a new Game Object.

To add it as a new GameObject, you can also go "GameObject > 3D Object > Super 3D Text", to create a new Text Mesh object. This option may require a reset of Unity to appear, initially. "GameObject > UI > Super Text" is the path for adding a new UI Text object. Please do not add Super Text Mesh to your game by dragging in the prefabs from the "prefabs" folder. Those only exist so adding it from the GameObject menu can work!

To add Super Text Mesh to an existing object in your project, you can select "Add Component" on an existing GameObject and find it under "Mesh > Super Text Mesh". Even when adding it as a UI element, you can add it this way, as long as the object you're adding it to is already the child of a canvas (if it has a RectTransform).


2. Text Data File & Rich Text Tags

a. Text Data



The inspector window.

In "Assets > Clavian > SuperTextMesh > Resources", you'll find a set of files used to change the presets of all text meshes in your project. You can edit these directly here, or click on the "[T]" icon in any Super Text Mesh's inspector to edit them with a custom inspector!

This file allows customization of effects called by Super Text Mesh's rich text tags. For example, you can define a color named "1" to be called with the tag <c=1>, or a text delay to be called using <d=myDelay> so you wouldn't have to type the same number over and over to call the same effect.

b. Text Data Customization

Lots of Super Text Mesh's settings can be changed mid-strin`g with tags such as <c=red> to change text to be red, or <d=10> to insert a delay that would be equal to 10 characters being read out. Most tags can be customized in a group of assets referred to as "TextData".

All TextData files can be found within "Assets > Clavian > SuperTextMesh > Resources" and can be edited there, or by clicking the [T] icon within a Super Text Mesh component. The name of the file will determine what tag it uses (eg. A color named "Teal" would be called with <c=Teal>).

When editing in the Super Text Mesh inspector, each TextData file has a header with a button to ping the asset in the project folder, a button to delete it, and a bar where the name can be edited. At the bottom of each group is a button to create a new asset, and at the very bottom of the inspector is a button to refresh the database, incase you make assets outside of the inspector.

Waves, Jitters, and Delays all have customizable default settings. When you go to edit them, you'll notice a setting named "default". This will be the setting called by the basic version of this tag. (<w>, <j>, <d>.) These can be changed to whatever settings you want. In other words, using the <w> tag would be the same as calling <w=default>.

For autodelays and autoclips, you might want to have a delay or a clip inserted for a character that can't be saved in a file name, such as "?", "!", ".", etc. For these, use the written-out name of these characters instead: "space", "tab", "line break", "exclamation point", "question mark", "semicolon", "colon", "tilde", "period", "comma", "number sign", "percent", "ampersand", "asterix", "backslash", "forwardslash", "openbrace", "closebrace"

You can also reference quads this way! If you have a quad named "cross", then when you type <q=cross> into a mesh, it'll react to autodelays, autoclips, and sound clips named "cross".

Other aspects of Super Text Mesh, like draw animations, automatic voice clips, and master switches are also controlled with these text data files.

c. Rich Text Tags



Demonstration of some tags.

These tags can be used mid-string to change aspects of the text! Any tag that has "name" on it like "<c=name>" can be modified with the Text Data file. All tags can be closed with a tag like "</c>", for example.

Other elements of Super Text Mesh can be changed directly with tags, but these are meant to be changed with voice tags, as they are longer than standard tags. Still, you can use them in regular text, too:


3. Functions, Variables & Events

a. Public Functions

These functions can be called with code, and are useful for dialogue managers:

b. Public Variables

All public variables can be changed with code, if needed.

Text

Appearance

Position

Timing

Functionality

Audio

Bounds Variables

Raw Bounds

Defined Bounds

Text Bounds

Final Text Bounds

Unwrapped Bounds

Extra Stuff

c. UnityEvents & Delegate Events



Events from the sample scene.

Unity Events call a list of component methods via the Unity Event System.

You can tell a function to be called when a certain event happens, by dragging in the GameObject & function in the Unity editor.

On Print Event ()

Invoked when a new letter is printed by STM. Can be used to tell a textbox to resize, among other uses.

On Rebuild Event ()

Invoked when Rebuild() is called. Good for custom events, like clearing generated particles or colliders.

On Complete Event ()

Invoked when a text mesh is finished writing out text.

On Undrawn Event ()

Invoked when a text mesh finishes its undrawing animation.

Custom Event (string, STMTextInfo)

Invoked with the event tag (<e=myString> / <e2=myString>). Passes an argument that has a string, and the STMTextInfo attached to the letter. The "e" tag makes an event happen for one character, and the "e2" tag repeats that event for every character until cancelled with "</e2>". The string is the "tag" written with the event. ("myString", in this case) STMTextInfo is an internal class used by Super Text mesh that contains all kinds of data about letters in a mesh like size & position. Here's some basics of the STMTextInfo class that you can use to reposition letters:

You can check out "TextMeshData.cs" to have a look at the complete code for this class!

Using the tag (<e=helloWorld>) mid-string could be used to invoke a function like this:

void MyFunction(string myString, int letterIndex, Vector3 letterMiddle, Vector3 letterCorner){
    Debug.Log(myString); //prints "helloWorld"
    Debug.Log(letterIndex); //prints index of letter event was attached to
    Debug.Log(letterMiddle); //prints world position of letter
}

Check out "STMEventInterpreter" in the "Sample" folder, for an example of how to use this. The "TextMeshExample" scene has a few examples that use this, as well as common uses for it. Included samples show things like using STM as links and buttons, and spawning particle effects on certain letters. Check it out!

Vertex Mod (Vector3[], Vector3[], Vector3[])



Vertex Mod in action.

Not a typical event like the rest, this event is used to modify the vertices of an entire mesh. To use it, under the "Position" foldout enable "modify vertices" and the event dialogue will appear. The kind of event you'll want to call would be laid out like this:

void ChangeVertices (Vector3[] verts, Vector3[] middles, Vector3[] positions){
    for(int i = 0; i < allMeshVertices.Length / 4; i++){
        //change a letter's verts:
        verts[4 * i + 0] += Vector3.right;
        verts[4 * i + 1] += Vector3.right;
        verts[4 * i + 2] += Vector3.right;
        verts[4 * i + 3] += Vector3.right;
        //move all to the right         Debug.Log(middles[i]); //middle of this letter
        Debug.Log(positions[i]); //position of this letter
    }
}

An included example script named "STMVertexMod" shows a few basic modifications you can do to a text mesh. (In the sample scene, look for an object named "CurvedTextSample" to see it in action)

Pre Parse (STMTextContainer)

Another non-typical event like the vertex mod. Pre-parsing can be used to manually parse text before it reaches SuperTextMesh's internal parser. This can be used for things such as...

public string addToStart = "";
public void Parse(STMTextContainer x){
 x.text = addToStart + x.text;
}

Make sure when adding a new event to select "Editor and Runtime" from the event dropdown so you can see changes made in-editor.

These events all have matching Delegate Events that are invoked at the same time. If you prefer to use delegate events, the names you can subscribe to are "OnPrintEvent", "OnRebuildEvent", "OnCompleteEvent", "OnUndrawnEvent", "OnCustomEvent", "OnVertexMod", and "OnPreParse". (Note the uppercase letters)


4. Shaders & Shadows

a. Changing Shaders & Included Shaders

You can drag a new shader onto the "text shader" area to change that. The included shaders all start with the prefix "STM" for easy searching.

As of v1.8.2, all these shaders have uber shader features! Each one has a culling mode toggle (Cull Back, Cull Front, Cull Off), An option to Render On Top (Set automatically for UI shaders), a Pixel Snap toggle, a toggle to render SDF fonts properly, and for UI shaders, masking options!

b. Clues for Writing Custom Shaders

Stencil {
 Ref 0 //Customize this value
 Comp Equal //Customize the compare function
 Pass Keep
}

This code gets added just after the "blend" portion of a shader.
Ref 0 == Render Outside Mask
Ref 1 == Render Inside Mask
(Thanks, Red for finding this!)

c. Enabling Shadowcasting

To toggle Super Text Mesh's shadow casting, check out the "Shadow Casting Mode" dropdown under the "appearance" section!

d. Outlines and Dropshadows

To use outlines or drop shadows, drag the "Unlit Dropshadow", "Unlit Outline", or "Unlit DropshadowAndOutline" shaders from the "Shaders" folder into the "shader" varaible on Super Text Mesh. After this, an additional header labelled "Shader" will appear in the inspector. You can use this to set how the dropshadow and outline look!

e. SDF Fonts

To use "SDF Mode" on a shader properly, you will first have to convert an existing font to an SDF font, using an external SDF texture generator. I use SDF Toolkit Free by Catlike Coding, and this guide will involve how to set up an SDF font using this. Please consider getting the paid version to support Jasper, who let me write this up for you!

Now you have super-crisp SDF text in your game! Enjoy!

NOTE: You can also use SDF mode on normal fonts! They'll render sharp, but not as precisely as converted fonts when observed close-up. Give it a try!


5. Utilities

a. Curve Generator



The "New" button in the curve dialogue.

Within "Assets > Clavian > SuperTextMesh > Utility", you'll find a script named "STMCurveGenerator". This script is meant to generate curves that are pretty common for waves. To use it, drag it onto any Game Object in your project, then click on one of the curves to open up the curve editor. From there, you can click the gear in the bottom left to save the curve into Unity as a preset! Then you can use it again for other curve fields, like the ones on waves and jitters.

a. Change Sorting Order

In the Utility folder, there's a script names "STMChangeSortingOrder". Add the component to any object with a Super Text Mesh component on it, and you'll be able to change the sprite sorting order and the sprite sorting layer. It also works with any gameobject with a renderer.

b. Support Packages for Other Assets

There are additional tools that assist with setting up Super Text Mesh with other Unity assets that others have coded. Linking them here, but I cannot provide direct support for these.

Other assets that can be used in conjunction with Super Text Mesh, but weren't written specifically for it:


FAQ

Notes

Known Bugs

Planned Features / To Do List:


ChangeLog

v1.0

v1.1

v1.1.1

v1.2:

v1.2.1

v1.2.2

v1.3

v1.3.1

v1.4

v1.4.1

v1.4.2

v1.4.3

v1.4.4

v1.4.5

v1.4.6

v1.4.7

v1.4.8

v1.4.9

v1.4.10

v1.4.11

v1.4.12

v1.4.13

v1.5

v1.5.1

v1.5.2

v1.6

v1.6.1

v1.6.2

v1.6.3

v1.7

v1.7.1

v1.8

v1.8.1

v1.8.2

v1.8.3

v1.8.4

v1.8.5

v1.8.6

v1.8.7

v1.8.8

v1.8.9

Update Warnings

v1.3 to v1.4+:

v1.4 to v1.5+:

v1.5 to v1.6+:

v1.6 to v1.7+:

v1.7 to v1.8+


Credits

Coding and design by Kai Clavier (@KaiClavier)
Extra CSS help by Tak (@takorii)