HudMessage

From ZDoom Wiki
Jump to navigation Jump to search

void HudMessage (text; int type, int id, int color, fixed x, fixed y, fixed holdTime [, fixed alpha]);
void HudMessage (text; HUDMSG_FADEOUT, int id, int color, fixed x, fixed y, fixed holdTime, fixed fadetime [, fixed alpha]);
void HudMessage (text; HUDMSG_TYPEON, int id, int color, fixed x, fixed y, fixed holdTime, fixed typetime, fixed fadetime [, fixed alpha]);
void HudMessage (text; HUDMSG_FADEINOUT, int id, int color, fixed x, fixed y, fixed holdTime, fixed inTime, fixed outTime [, fixed alpha]);

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.

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

Parameters

  • Type
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. Additionally you can use use various flags, listed below.
  • Id
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. This is usually used to remove hudmessages manually or "move" them around (using a script). Messages with lower ids will overlap those with higher ids. Negative Ids (-1, -2, -3, etc) will work as well. Acceptable values are -2147483648 to 2147483647.
  • Color
The color of the message text. There are a number of predefined colors, listed below.
Color name Color Color name Color Color name Color Notes
██ CR_BLACK ██ CR_DARKRED ██ CR_ORANGE
  • CR_YELLOW is meant to replicate the
    yellow font in Heretic and Hexen, where
    letters have a gray border.
  • CR_GREY and CR_DARKGREY can be used
    instead of CR_GRAY and CR_DARKGRAY.
  • To use the font graphics' original colors,
    use CR_UNTRANSLATED.
██ CR_BLUE ██ CR_FIRE ██ CR_PURPLE
██ CR_BRICK ██ CR_GOLD ██ CR_RED
██ CR_BROWN ██ CR_GRAY ██ CR_SAPPHIRE
██ CR_CREAM ██ CR_GREEN ██ CR_TAN
██ CR_CYAN ██ CR_ICE ██ CR_TEAL
██ CR_DARKBROWN ██ CR_LIGHTBLUE ██ CR_WHITE
██ CR_DARKGRAY ██ CR_OLIVE ██ CR_YELLOW
██ CR_DARKGREEN
You can also specify the color as a string (including custom colors defined in the text colors lump); if you do so you must also add HUDMSG_COLORSTRING to the type with a binary OR ( '|' ). For example, if you define a color called 'NeonRainbowSmoothie', you could use it like this:
hudmessage(s:"test"; HUDMSG_PLAIN | HUDMSG_COLORSTRING, 0, "NeonRainbowSmoothie", 0.5, 0.5, 1.0);
  • x and y
The position of the hudmessage to be rendered on the screen in fixed point coordinates.
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.
[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
Note: The coordinate meanings are changed completely after using the SetHudSize function. Please see the Coordinate Behavior section for instructions on how to position text messages and images after the hud size has been set.


  • HoldTime
How many seconds the message stays on screen in fixed point. Use a floating point number with a decimal to obey actual seconds. If using HUDMSG_PLAIN, a HoldTime of 0 will cause the message to stay forever, or until the same ID is re-used. To get the shortest time possible for the message to stay on the screen (1 tic), use the formula 1.0 / 35 + 1 (or simply 1873 as an integer).
  • Alpha
Optionally, an alpha value can be specified for the message. This is a fixed point value ranging from 0 (totally invisible) to 1.0 (totally opaque), defaulting to 1.0 if omitted. Additionally, additive blending is possible by combining one of the four message types using the pipe character "|" with HUDMSG_ADDBLEND.
Note that to effectively use an alpha value, you need to explicitly add the HUDMSG_ALPHA flag. This is to preserve compatibility with mods predating the addition of the alpha feature but which mistakenly specified additional, then unused, parameters.

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
..., 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.

Type flags

The following can be used in conjunction with the other types and flags by using the pipe character "|".

  • HUDMSG_ADDBLEND
The message is rendered with additive blending. This can be combined with an alpha value.
  • HUDMSG_LOG
The message is logged to the console.
  • HUDMSG_ALPHA
The message uses the alpha parameter.
  • HUDMSG_NOWRAP
Wrapping is disabled for this message.

Visibility flags

The following can be used in conjunction with one of the four message types above by using the pipe character "|" to determine whether the message is shown depending on the currently active view:

  • HUDMSG_NOTWITH3DVIEW
This message does not appear when the 3D view is active.
  • HUDMSG_NOTWITHFULLMAP
This message does not appear when the fullscreen automap is active.
  • HUDMSG_NOTWITHOVERLAYMAP
This message does not appear when the overlay automap is active.

These flags may be combined, so for example: HUDMSG_NOTWITHFULLMAP | HUDMSG_NOTWITHOVERLAYMAP would prevent the message from appearing if any form of automap is active.

HUD layers

The following can be used in conjunction with one of the four message types above by using the pipe character "|" to determine where the message is rendered when it comes to the HUD layers:

  • HUDMSG_LAYER_OVERHUD
This is the default and standard behavior. The message appear on top of most HUD elements. This definition is only included for completeness' sake; you do not need to explicitly use it.
  • HUDMSG_LAYER_UNDERHUD
The message appears underneath other HUD elements, such as the status bar.
  • HUDMSG_LAYER_OVERMAP
The message appears on top of the fullscreen automap.


Combining one of the above with type flags is possible. For instance, HUDMSG_NOTWITHFULLMAP | HUDMSG_NOTWITHOVERLAYMAP | HUDMSG_LAYER_UNDERHUD would render the message under the status bar and only when the 3D view is active.

Note that these are not flags, thus can't be combined with each other, so for example HUDMSG_LAYER_UNDERHUD | HUDMSG_LAYER_OVERHUD is not valid.

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. It is also worth noting that images displayed will scale if used in conjunction with SetHudSize. For instance, an image taken with dimensions 320 x 200 will be shrunk in half if SetHudSize is set to 640 x 400

The image lump name must be 8 characters or less 

script 02 (void)
{
	SetFont("PICTURE");
	HudMessage(s:"A"; HUDMSG_PLAIN, 0, 0, 0.1, 0.8, 3.7);
}
Retrieved from "https://zdoom.org/w/index.php?title=HudMessage&oldid=48530"