DOWNLOAD TypedText 0.7.0 (beta version) MODULE PACKArchive contains modules: TypedText, TypedTextHelper and TypedTextDrawing.
DOWNLOAD Demo GameLatest source code may be found hereGit cloning address:
https://ivan-mogilko@bitbucket.org/ivan-mogilko/ags-script-modules.gitDemo Game git cloning address:
https://ivan-mogilko@bitbucket.org/ivan-mogilko/ags-script-demos.gitModule supports
AGS 3.2.1 and higherIntroductionTypedText module provides means for displaying continiously typed text, also known as typewriter style display. Letter appears by letter with certain delay in between.
A while ago I was scripting a typing text animation for a game project; later I found out that there is already
Phemar's Typewriter module, but it did not allow the kind of behavior that the project required, so I continued with my own script.
Now I found some free time to rewrite that script in a cleaner way and make an actual script module of it. But I also copied few things from Phemar's module, to make TypedText suitable for the needs of people who used Phemar's module before.
The general peculiarity of this module, and also what makes it different from existing one, is that it is based on a Type (struct), and objects of that type, instead of a Function. This leads to following effects:
1. You can have multiple typed text animations simultaneously.
2. Since objects keep their states in them, you may have both blocking and non-blocking typed texts.
3. Having an object with exposed interface (public functions and properties) make it possible to alter its behavior on fly, as well as override it, and use it to create your own custom typewriters.
Using an object may be more complicated than using a single function, and require time to study it, so I added
TypedTextHelper module with number of "helper" functions to make it easier to start using TypedText in your project. Also those functions may be just what you need if standart behavior is enough. This is why I will explain their use before going into detail about TypedText itself.
But first I need to quickly clarify on some concepts.
TypedText conceptsTypedText simulates continious text typing, letter by letter. When doing so it passes several states:
Inactive - this is when it has no text set whatsoever.
Typing text - this is when it is in process of typing text.
Waiting for reader - this is when all text was fully typed and displayed on screen, but settings demand TypedText to wait a little longer to give human an opportunity to finish reading the text.
Idling - this is when typing and waiting is complete, and TypedText is not going to do anything else.
NOTE: Helper functions, such as those that display TypedText on Overlays, rely on "waiting for reader" state to know when typed text should be removed from screen.
TypedText has a concept of the flashing caret. Depending on setup, it may flash last typed letter, or draw certain symbol behind typed text (like '_', for example).
The caret, if enabled, commences to flash whenever delay between two typed letters is greater than caret's waiting timer. This timer resets when next letter is typed. This also means that when all the text was already typed, caret will then flash endlessly (so long as TypedText is on screen).
Keeping the above in mind, TypedText relies on following parameters:
Typing delay - how many game ticks to wait after each typed letter.
Typing delay style - this concept is copied from Phemar's module, and defines delay behavior for spaces and caret-returns in the text (are they same, slower than usual or faster than usual),
Caret depiction - is the caret is depicted anyway, and how: this may be flashing last letter, or specific string drawn in the end, or even a sprite - for the advanced TypedText implementations.
Caret flash times - how long caret stays on screen and stays hidden when it flashes.
Text reading time - how much time, in game ticks, is spent on reading 1 letter: this parameter is used to calculate average reading time of a text.
Finally, extended variants of TypedText also support sound that is played whenever next letter was typed.
Using TypedTextHelperTypedTextHelper module requires TypedText module to present above it in the modules list.
It provides a number of functions to run typed text blocking or non-blocking, in a number of ways: on a
Button, on a
Label, or on an
Overlay.
Because TypedText has a significant number of parameters, many of which are supposed to stay same for the most of the time in game, I thought it would be very inconvenient to put all of those parameters into functions. Instead, TypedTextHelper has a special
preset system.
This works pretty simple actually: you setup least changing properties as a preset under certain ID, and then use that preset ID when starting typed text on Label, or Overlay; this makes all of that preset's parameters to be used for that instance of text typing.
Following are preset functions you may use:
/// Set general parameters for the specified preset
TypewriterPreset.SetGeneral(int preset, int delay_min, int delay_max, TypedDelayStyle style, int read_time = 12);
/// Set caret parameters for the specified preset
TypewriterPreset.SetCaret(int preset, int flash_on_time, int flash_off_time, TypedCaretStyle style, String caret_str, int caret_sprite = 0);
/// Set sound parameters for the specified preset
TypewriterPreset.SetSounds(int preset, AudioClip *type_sound, AudioClip *caret_sound, AudioClip *end_sound);
TypewriterPreset.SetSoundArray(int preset, AudioClip *type_sounds[], int type_sound_count,
AudioClip *caret_sound, AudioClip *end_sound);
Maximal number of presets is determined with TYPEDTEXTHELPER_MAXPRESETS constant in the module header. It is 8 by default, but you may increase it if you need more.
Maximal number of sounds that you may assign for preset and each typewriter is determined with TYPEDTEXTRENDER_MAXSOUNDS contant.
Best place to set preset's parameters is "game_start" function, but you may change them anytime by using same preset ID.
After you set up at least one preset, you may begin using helper functions. All of them are made as
extender functions, which means you first type object (Button, Label, Character) pointer name, then call the function from it, like:
// NOTE: preset is optional, and will be 0 if you don't type anything
/// Print TypedText as a text on button
SomeButton.Typewriter(String text, BlockingStyle bs, int preset = 0);
/// Print TypedText as a text on label
SomeLabel.Typewriter(String text, BlockingStyle bs, int preset = 0);
The only difference is Overlay static extender (static extenders is a new thing since AGS 3.4.0), where you do not use overlay's pointer, but just "Overlay" word:
// NOTE: preset is optional, and will be 0 if you don't type anything
/// Print TypedText as a text on created overlay
Overlay.Typewriter(int x, int y, int color, FontType font, String text, BlockingStyle bs, int preset = 0);
If you are working in pre-3.4.0, you will have to use non-extender function for overlays, called TypewriteOnOverlay, but it works essentially same, and has same parameters (except it is not called from Overlay).
If you run these functions with eBlock, they will display typed text inside of them, and return when typing (and waiting) state has finished.
If you run them with eNoBlock, they will
return back immediately, but typed text will work on a background, updated from repeatedly_execute inside the module.
You may run only one blocking typed text at the same time.
Maximal simultaneous non-blocking typed texts is determined by TYPEDTEXTHELPER_MAXTYPEWRITERS constant in the module header. It is 8 by default, but you may increase it if you need more.
Each of those helper functions return unique ID of typewriter. If you want to control that typewriter, such as detect when it stops typing, or be able to cancel it, store this ID in a variable for later. You may then use this ID with TypewriterRunners static functions and properties:
/// Get number of currently running typewriters
int TypewriterRunners.ActiveCount;
/// Get number of maximal supported typewriters that can run simultaneously
int TypewriterRunners.MaxCount;
/// Get whether given typewriter ID is currently running (use unique ID as an array index)
bool TypewriterRunners.IsActive[];
/// Get whether given typewriter ID is blocking (use unique ID as an array index)
bool TypewriterRunners.IsBlocking[];
/// Stop typewriter under given ID
void Cancel(int id);
The principal example:
int tw_id = SomeButton.Typewriter(text, eNoBlock);
<... later ...>
if (TypewriterRunners.IsActive[tw_id])
TypewriterRunners.Cancel(tw_id); // interrupt typewriter if it was still running
Using TypedText directlyIf above helper functions do not do what you like, you may create and use objects of TypedText struct, or any derived structs, directly.
TypedText struct's purpose is to calculate timing and basic state of the text. It does not draw anything on screen on its own, but calculates and tells how the text should look like at any given moment, letting you to use that information as you see fit. In other words, it tells what is happening, but does not tell you how it should look (and sound) like.
Setting up TypedText is fairly straighforward, here are its configuration properties:
/// Base delay (in ticks) between every typing event
import attribute int TypeDelay;
/// Bounds for random base delay
import attribute int TypeDelayMin;
import attribute int TypeDelayMax;
import attribute TypedDelayStyle TypeDelayStyle;
/// Time (in ticks) the caret stays shown
import attribute int CaretFlashOnTime;
/// Time (in ticks) the caret stays hidden
import attribute int CaretFlashOffTime;
/// Time (in ticks) given to read one text character
import attribute int TextReadTime;
/// Whitespace/caret-return delay style defines relation of special case
/// delays to the base type delay.
/// Idea is conforming to the Phemar's Typewriter module.
enum TypedDelayStyle
{
/// wait for the same amount of time as after regular letters
eTypedDelay_Uniform = 0,
/// wait twice as long after whitespaces
eTypedDelay_LongSpace,
/// wait twice as less after whitespaces
eTypedDelay_ShortSpace,
/// randomly choose a style every time
eTypedDelay_Mixed
};
And its control methods are:
/// Gets/sets paused state
import attribute bool Paused;
/// Clears all text and resets all timers
import void Clear();
/// Sets new string, resets all timers and commences typing
import void Start(String text);
/// Skips all the remaining typing
import void Skip();
/// Update typed text state, advancing it by single tick
import void Tick();
Since you are using TypedText yourself, you need to be continiously checking its state in repeating function:
/// Full string that has to be typed
readonly import attribute String FullString;
/// Part of string that is supposed to be shown at current time
readonly import attribute String CurrentString;
/// Part of string that was 'typed' during latest update
readonly import attribute String LastTyped;
/// Tells whether TypedText has active content to process or display
readonly import attribute bool IsActive;
/// Tells whether TypedText is in process of typing text
/// (return FALSE if either no text is set, or text is already fully typed)
readonly import attribute bool IsTextBeingTyped;
/// Tells whether TypedText is waiting for the text to be read by player
/// (return FALSE when reading timer has ran out, regardless of other states)
readonly import attribute bool IsWaitingForReader;
/// Tells whether TypedText is currently idling, either not having a content,
/// or after finishing all the required actions (typing & waiting for reader)
readonly import attribute bool IsIdle;
/// Tells whether caret should be currently displayed
readonly import attribute bool IsCaretShown;
/// Gets if the new character was just typed
readonly import attribute bool EvtCharTyped;
/// Gets if the text has just ended being typed
readonly import attribute bool EvtFinishedTyping;
One of the simpliest examples for using TypedText is this:
// in GlobalScript.asc
TypedText my_tt;
function game_start()
{
// Config typed text to your liking
my_tt.TypeDelay = 4;
my_tt.CaretFlashOnTime = 4;
my_tt.CaretFlashOffTime = 4;
}
// Calling TypeSay will start typed text
function TypeSay(string s)
{
my_tt.Start(s);
}
function repeatedly_execute()
{
if (my_tt.IsIdle)
{
my_tt.Clear(); // clear the text, stop timers ticking, etc
}
else if (my_tt.IsActive)
{
my_tt.Tick(); // update TT
String text_to_show = my_tt.CurrentString;
if (my_tt.IsCaretShown)
text_to_show = text_to_show.Append("_"); // append caret symbol to the end of the text
player.Saybackground(text_to_show); // print TT's current text as a player's background speech
}
}
Using TypewriterRender and its subtypesThere is a number of extended types provided by the module, which add bit more functionality. First is struct
TypewriterRender, which extends TypedText, and other structs extend TypewriterRender further.
As was mentioned above, TypedText does not draw anything on its own, only calculates the text's state. TypewriterRender does not do much too, but it adds few more properties and serves rather like a base class for actual visualizing:
/// Caret display style
import attribute TypedCaretStyle CaretStyle;
/// A string (or single character) that represents typewriter caret
import attribute String CaretString;
/// The only sound to play when a character is typed
import attribute AudioClip * TypeSound;
/// Array of sounds to choose at random when a character is typed
readonly import attribute AudioClip *TypeSounds[];
/// Number of typing sounds registered
readonly import attribute int TypeSoundCount;
/// Sound to play when the line break is met
import attribute AudioClip * CaretSound;
/// Sound to play when the typewriter finished typing text
import attribute AudioClip * EndSound;
/// Sets the array of sounds to play at random when character is typed
import void SetRandomTypeSounds(AudioClip *sounds[], int count);
/// Style of the caret displayed during typing
enum TypedCaretStyle
{
/// No caret display
eTypedCaret_None = 0,
/// Flash last character
eTypedCaret_LastChar,
/// Draw separate caret at the next assumed character location
eTypedCaret_Explicit
};
The actual workers are inheriting types:
TypewriterButton,
TypewriterLabel,
TypewriterOverlay. They have respective properties to set up an object they will print text on (or from which perspective), as well as their own overwritten Clear, Start and Tick methods.
Using them you will avoid necessity to draw text yourself:
// in GlobalScript.asc
TypewriterLabel my_tt_label;
function game_start()
{
my_tt_label.TypeOnLabel = lblTypewriter; // put your actual label's name here
my_tt_label.TypeDelay = 4;
my_tt_label.CaretFlashOnTime = 4;
my_tt_label.CaretFlashOffTime = 4;
my_tt_label.CaretStyle = eTypedCaret_LastChar; // make last char flash
my_tt_label.TypeSound = aTypewriterTyping; // set sound to play
}
// Calling TypeOnLabel will start typed text
function TypeOnLabel(string s)
{
my_tt_label.Start(s);
}
function repeatedly_execute()
{
if (my_tt_label.IsIdle)
my_tt_label.Clear(); // remove text when done typing & waiting for the reader
else if (my_tt_label.IsActive)
my_tt_label.Tick(); // update text
// notice that you do not need to point where to print the text anymore,
// TypewriterLabel already knows that and does printing for you
}
Using TypedTextDrawingTypedTextDrawing is an advanced struct, extending TypewriterRender, that lets you
draw typed text on DrawingSurface. This means you may have typewriter text on literally anything that can give drawing surfaces or have assigned image: room and GUI backgrounds, objects, character frames even (crazy).
Besides, TypedTextDrawing is the only one of the provided types that can
draw caret as a sprite.
TypedTextDrawing is located in its own separate module (of same name) and requires TypedText module to work (but not TypedTextHelper).
Setting TypedTextDrawing up is very similar to setting other TypedText subtypes, but you also need to set up its position on DrawingSurface, text color and font, and optionally background color.
What is more important to remember, you must explicitly call Draw function, because you need to pass DrawingSurface pointer to its drawing. It cannot store DrawingSurface once for use later, because that goes against rules of using drawing surfaces (they have to be released right after every use).
Here is some example, that draws typed text on a room's backround
// in GlobalScript.asc
TypedTextDrawing tt_draw;
DynamicSprite *roomBkg; // will keep saved room background
function game_start()
{
tt_draw.TypeDelay = 4;
tt_draw.CaretFlashOnTime = 4;
tt_draw.CaretFlashOffTime = 4;
tt_draw.CaretStyle = eTypedCaret_Explicit; // draw caret
tt_draw.CaretSprite = 1010; // put your sprite number here
tt_draw.TypeSound = aTypewriterTyping; // set sound to play
tt_draw.X = 40;
tt_draw.Y = 40;
tt_draw.Width = Room.Width - 80;
tt_draw.Height = Room.Height - 80;
tt_draw.Font = eFontText;
tt_draw.TextAlign = eAlignCentre;
}
function RestoreRoomBkg()
{
// Restore original room background
DrawingSurface *ds = Room.GetDrawingSurfaceForBackground();
ds.DrawImage(0, 0, roomBkg.Graphic);
ds.Release();
}
// Calling TypeOnDS will start typed text
function TypeOnDS(string s)
{
if (roomBkg == null)
{
roomBkg = DynamicSprite.CreateFromBackground();
}
else
{
RestoreRoomBkg();
}
tt_draw.Start(s);
}
function repeatedly_execute()
{
if (tt_draw.IsIdle)
{
tt_draw.Clear();
RestoreRoomBkg();
}
else if (tt_draw.IsActive)
{
tt_draw.Tick(); // update TT
DrawingSurface *ds = Room.GetDrawingSurfaceForBackground();
tt_draw.Draw(ds);
ds.Release();
}
}
Other script modules by me:
DragDrop moduleKeyListener