HudMessage

From ZDoom Wiki

hudmessage (text; int type, int id, int color, fixed x, fixed y, fixed holdTime, ...);

Usage

Hudmessage works like Print, except it offers more flexibility. The 'text' parameter is in the Print specification, as used with Print or PrintBold. A semicolon separates it from the rest of the function's parameters, because a print specification can build a big string from littler comma-separated parts.

'Type' is the type of message to create; currently, there are 4 different ways to display a message: HUDMSG_PLAIN, HUDMSG_FADEOUT, HUDMSG_TYPEON and HUDMSG_FADEINOUT. Messages types other than HUDMSG_PLAIN also take additional parameters listed below.

By default HudMessages will not appear in the console (unlike Print and PrintBold). This can be remedied by ORing the HudMessage type with HUDMSG_LOG. For instance if you have a simple hud message: hudmessage(s:"test\n"; HUDMSG_PLAIN, 0, CR_GOLD, 0.5, 0.5, 1.0); and want the text to appear in the console (so the user can read it later if need be) then you would simply change it to hudmessage(s:"test\n"; HUDMSG_PLAIN | HUDMSG_LOG, 0, CR_GOLD, 0.5, 0.5, 1.0);

'Id' is an identifier for the message. If a message with a non-zero id is displayed, then another with that same id is displayed, the first message will be removed before displaying the second. Messages with lower id's will overlap those with higer id's.

'Color' is the color of the message text. Putting a 0 will render the text in color CR_BRICK. For a full list of colors, see the defines section below.

X and y specify the location of the message on the screen. Values for x are in the ranges:

• [0.0, 1.0]: Position between left and right edge valid box locations
• [-1.0, 0.0): Position between left and right edge of screen
• (1.0, 2.0]: Same as [0.0,1.0], but center each line inside box
• [-2.0, 1.0): Same as [-1.0,0.0), but center each line inside box

Valid values for y are:

• [ 0.0, 1.0]: Position between top and bottom of valid box locations
• [-1.0, 0.0): Position between top and bottom edge of screen

You can think of each message being inside a box. The difference between positive and negative values for these parameters is that positive values position the box the message is in on the screen, and negative values position the left/top edge of the box the message is in.

'HoldTime' is how long the message stays on screen, in seconds. If using HUDMSG_PLAIN, a HoldTime of 0 will cause the message to stay forever, or until the same ID is re-used.

Note that x, y, and holdtime are all fixed point values, not ints. If you use a decimal point, acc will automatically convert the number to fixed point for you. (Meaning that if you use a value such as 1.0, acc will treat it as if you had used 65536.) You can use FixedDiv and FixedMul to divide and multiply fixed point numbers, just like with the source code.

You can also use HudMessage together with SetFont to print images instead of text.

Additional Type Parameters

Note that you cannot specify an infinite (0) HoldTime when using any of these message types.

HUDMSG_FADEOUT

..., fixed fadetime);

Fadetime is the time, in seconds, that the message takes to fade out after its holdtime is up.

HUDMSG_TYPEON

..., fixed typetime, fixed fadetime);

Typetime is the time, in seconds, that it takes each character of the message to appear on the screen. After every character has been "typed," the message waits for holdtime seconds and then fades out for fadetime seconds.

HUDMSG_FADEINOUT (Added 2.0.93)

..., fixed inTime, fixed outTime);

inTime is the time, in seconds, that the message takes to fade in. The message then stays for the duration of its holdTime, then fades out using the duration specified in outTime.

Defines

Here are the values defined in zdefs.acs relating to HudMessage:

#define CR_UNTRANSLATED -1 
#define CR_BRICK 0 
#define CR_TAN 1 
#define CR_GRAY 2 
#define CR_GREY 2 
#define CR_GREEN 3 
#define CR_BROWN 4 
#define CR_GOLD 5 
#define CR_RED 6 
#define CR_BLUE 7 
#define CR_ORANGE 8 
#define CR_WHITE 9 
#define CR_YELLOW 10 
#define CR_BLACK 12 
#define CR_LIGHTBLUE 13 
#define CR_CREAM 14 
#define CR_OLIVE 15 
#define CR_DARKGREEN 16 
#define CR_DARKRED 17 
#define CR_DARKBROWN 18 
#define CR_PURPLE 19 
#define CR_DARKGRAY 20 
#define CR_DARKGREY 20
#define HUDMSG_PLAIN 0 
#define HUDMSG_FADEOUT 1 
#define HUDMSG_TYPEON 2
#define HUDMSG_FADEINOUT 3

Examples

Examples of x and y positions

• (0.5,0.0) positions the message at the middle top of the screen.
• (0.0,0.5) positions the message at the middle left of the screen.
• (-0.25,0.0) positions the left edge of the message 1/4 of the way across the screen at the top.
• (1.5,0.5) centers the box on the screen, and also centers each line inside the box.

Example scripts

This script gives a goal using the standard large font which is seen for the level names. The goal tells the player to destroy a certain number of a certain object. The amount and object type are decided by the parameters to this script; so giving parameters 5 and 0 would tell the player to destroy 5 generators. The text types on to the screen and fades out, and also stays on the console.

str goals[3] = {"generators", "altars", "teleporters"};

script 10 (int amount, int goaltype)
{
	SetFont("BIGFONT");
	HudMessage(s:"You must find ",
		d:amount, s:" ", l:goals[goaltype],
		s:"\nand destroy them.";
		HUDMSG_TYPEON | HUDMSG_LOG, 0, CR_TAN, 1.5, 0.8, 5.0,
		0.05, 2.0);
}

This demonstrates that the message to display can be built of smaller strings and also variables. \n is the new-line character. SetFont is used to change the font.

Another example is a damage counter, which stays on screen reporting the damage the player has until they are healed.

script 1 (void)
{
	int health = GetActorProperty(0, APROP_HEALTH);
	
	while(health < 100)
	{
		HudMessage(s:"You have ",
			d:(100 - health),
			s:" damage!";
		HUDMSG_PLAIN, 1, CR_RED, 0.1, 0.9, 1.0);
		
		Delay(1);
		
		health = GetActorProperty(0, APROP_HEALTH);
	}
	
	HudMessage(s:"You are in good health.";
		HUDMSG_PLAIN, 1, CR_RED, 0.1, 0.9, 5.0);
}

First this sets the player's health to a variable and loops whilst the health is less than 100 (i.e. whilst they are damaged). The current damage is displayed, before a frame's delay and then checking the health again. After the player is healed (health == 100) the while loop exits and a final message reports that the player is healed.

Note that the messages have an ID number of 1. If they were to lack an ID number, each health message would be written over the previous causing it to look very glitchy. The ID number prevents this from happening.

An example of a moving text:

script 1 (void)
{
   SetFont("BIGFONT");
   
   // Vary the x coordinate
   for(int x = 0.0; x < 0.5; x += 0.01)
   {
      // Show the message at our x coord
      HudMessage(s:"You got pommed\nby the appler";
         0, 1, CR_TAN, x, 0.4, 2.0);
      // Slight delay
      Delay(1);
   }
   
   // Display the message once again at the final x coordinate
   HudMessage(s:"You got pommed\nby the appler";
      0, 1, CR_TAN, x, 0.4, 2.0);
}

This uses a for loop to change the value of x so that it scrolls across the screen. It starts at (0.0, 0.4) which means the text will be placed at the left hand edge, slightly above the center line. It finishes at (0.5, 0.4) which is just above the absolute center of the screen.

Displaying images

HudMessage can be used in conjunction with SetFont to display graphic lumps. Pass the name of a graphic lump as a parameter of SetFont, and use HudMessage with a capital 'A' to display the graphic.

script 02 (void)
{
	SetFont("PICTURE");
	HudMessage(s:"A"; HUDMSG_PLAIN, 0, 0, 0.1, 0.8, 3.7);
}