HUD Elements - CoD4 Unleashed Server

HUD elements allow you to display custom text, images, and UI elements on players’ screens. CoD4 Unleashed provides powerful functions to create and animate HUD elements.

Creating HUD Elements

newHudElem()

Creates a new server-wide HUD element visible to all players.

hudElem = newHudElem();
hudElem.x = 320;
hudElem.y = 240;
hudElem setText("Server Message");

Returns: HUD element object

Server HUD elements are visible to all players. Use newClientHudElem() for player-specific elements.

newClientHudElem()

Creates a HUD element visible only to a specific player.

OnPlayerSpawn() {
    hud = newClientHudElem(self);
    hud.x = 10;
    hud.y = 10;
    hud.alignX = "left";
    hud.alignY = "top";
    hud setText("Welcome " + self.name);
}

Parameters:

player - Player entity

Returns: HUD element object

HUD Element Properties

Position Properties

hud.x = 320;              // X coordinate (0-640)
hud.y = 240;              // Y coordinate (0-480)

CoD4 uses a 640x480 coordinate system regardless of actual screen resolution.

Alignment Properties

hud.alignX = "left";      // "left", "center", "right"
hud.alignY = "top";       // "top", "middle", "bottom"

Text Properties

hud.font = "objective";     // Font type
hud.fontScale = 1.5;        // Text size (1.4 - 4.6)
hud.label = &"Score: ";     // Localized label

Font Types

Font	Description	Usage
`default`	Standard game font	General text
`bigfixed`	Large monospace	Timers, scores
`smallfixed`	Small monospace	Detailed info
`objective`	Bold objective font	Important messages

Font scale must be between 1.4 and 4.6. Values outside this range will be clamped to 1.4.

Color Properties

hud.color = (1, 0, 0);     // Red
hud.color = (0, 1, 0);     // Green
hud.color = (0, 0, 1);     // Blue
hud.color = (1, 1, 1);     // White

Display Properties

hud.archived = true;          // Save across round changes
hud.hideWhenInMenu = true;    // Hide when menu open
hud.foreground = true;        // Draw in foreground
hud.sort = 1;                 // Draw order (higher = front)

Text Methods

setText()

Sets the element’s text content.

hud setText("Game Over");

Parameters:

text - String or localized string reference

setValue()

Sets a numeric value with automatic formatting.

scoreHud setValue(self.score);
timeHud setValue(getTime() / 1000);

Parameters:

value - Number to display

setTimer()

Displays a countdown timer.

timerHud setTimer(30);        // 30 second countdown

Parameters:

duration - Time in seconds

Animation Methods

moveOverTime()

Animates the element to a new position.

hud.x = -100;                 // Start off-screen
hud moveOverTime(0.5);        // 0.5 second animation
hud.x = 10;                   // End position

Parameters:

time - Animation duration in seconds (0-60)

Set the new position after calling moveOverTime(). The element animates from its current position to the newly set position.

fadeOverTime()

Animates the element’s opacity.

hud.alpha = 0;
hud fadeOverTime(1.0);
hud.alpha = 1;

Parameters:

time - Animation duration in seconds (0-60)

scaleOverTime()

Animates font size changes.

hud.fontScale = 1.4;
hud scaleOverTime(0.5, 3.0);  // Grow to size 3.0
wait 0.5;
hud scaleOverTime(0.5, 1.4);  // Shrink back

Parameters:

time - Animation duration
scale - Target font scale

Destruction

destroy()

Removes the HUD element immediately.

hud destroy();

Always destroy HUD elements when no longer needed to prevent exceeding the limit of 1024 elements.

destroyElem()

Alias for destroy().

hud destroyElem();

C API Functions

The following C functions are available through the scripting VM:

G_GetNewHudElem()

Low-level function to create HUD elements from C code.

game_hudelem_t* G_GetNewHudElem(unsigned int clientnum);

G_HudSetPosition()

Sets element position with alignment.

void G_HudSetPosition(game_hudelem_t* element, float x, float y,
                      hudscrnalign_t scrnhalign, hudscrnalign_t scrnvalign,
                      hudalign_t alignx, hudalign_t aligny);

G_HudSetFont()

Configures font properties.

void G_HudSetFont(game_hudelem_t* element, float fontscale, fonttype_t fonttype);

Font Types:

HUDFONT_DEFAULT (0)
HUDFONT_BIGFIXED (1)
HUDFONT_SMALLFIXED (2)
HUDFONT_OBJECTIVE (3)

G_HudSetColor()

Sets color and glow color.

void G_HudSetColor(game_hudelem_t* element, ucolor_t color, ucolor_t glowcolor);

G_HudSetText()

Sets display text.

void G_HudSetText(game_hudelem_t* element, const char* text);

G_HudSetMovingOverTime()

Animates position change.

void G_HudSetMovingOverTime(game_hudelem_t* element, int time, float newx, float newy);

G_HudSetFadingOverTime()

Animates color/alpha change.

void G_HudSetFadingOverTime(game_hudelem_t* element, int time, ucolor_t newcolor);

G_HudDestroy()

Destroys a HUD element.

void G_HudDestroy(game_hudelem_t* element);

Complete Examples

Kill Feed

showKillFeed(attacker, victim) {
    hud = newHudElem();
    hud.x = 10;
    hud.y = 10;
    hud.alignX = "left";
    hud.alignY = "top";
    hud.horzAlign = "left";
    hud.vertAlign = "top";
    hud.fontScale = 1.4;
    hud.alpha = 0;
    hud setText(attacker.name + " killed " + victim.name);
    
    // Fade in
    hud fadeOverTime(0.3);
    hud.alpha = 1;
    wait 0.3;
    
    // Hold
    wait 3;
    
    // Fade out
    hud fadeOverTime(0.5);
    hud.alpha = 0;
    wait 0.5;
    
    hud destroy();
}

Countdown Timer

showCountdown(duration) {
    timer = newHudElem();
    timer.x = 320;
    timer.y = 50;
    timer.alignX = "center";
    timer.alignY = "top";
    timer.horzAlign = "center";
    timer.vertAlign = "top";
    timer.font = "objective";
    timer.fontScale = 3.0;
    timer.color = (1, 1, 0);
    timer.glowColor = (1, 0.5, 0);
    timer.glowAlpha = 1;
    timer setTimer(duration);
    
    // Pulse effect in last 5 seconds
    wait (duration - 5);
    timer.color = (1, 0, 0);
    
    for (i = 0; i < 5; i++) {
        timer scaleOverTime(0.5, 4.0);
        wait 0.5;
        timer scaleOverTime(0.5, 3.0);
        wait 0.5;
    }
    
    timer destroy();
}

Player Score Display

OnPlayerSpawn() {
    self.scoreHud = newClientHudElem(self);
    self.scoreHud.x = 320;
    self.scoreHud.y = 420;
    self.scoreHud.alignX = "center";
    self.scoreHud.alignY = "bottom";
    self.scoreHud.horzAlign = "center";
    self.scoreHud.vertAlign = "bottom";
    self.scoreHud.fontScale = 1.8;
    self.scoreHud.font = "bigfixed";
    self.scoreHud.archived = true;
    self.scoreHud.label = &"Score: ";
    self.scoreHud setValue(self.score);
    
    self thread watchScore();
}

watchScore() {
    self endon("disconnect");
    
    lastScore = self.score;
    
    while (true) {
        if (self.score != lastScore) {
            self.scoreHud setValue(self.score);
            
            // Pulse on score change
            self.scoreHud scaleOverTime(0.1, 2.5);
            wait 0.1;
            self.scoreHud scaleOverTime(0.2, 1.8);
            
            lastScore = self.score;
        }
        wait 0.05;
    }
}

Welcome Message

OnPlayerConnect() {
    title = newClientHudElem(self);
    title.x = 320;
    title.y = 150;
    title.alignX = "center";
    title.alignY = "middle";
    title.horzAlign = "center";
    title.vertAlign = "middle";
    title.font = "objective";
    title.fontScale = 2.5;
    title.color = (0, 1, 0);
    title.alpha = 0;
    title setText("Welcome to the Server");
    
    subtitle = newClientHudElem(self);
    subtitle.x = 320;
    subtitle.y = 180;
    subtitle.alignX = "center";
    subtitle.alignY = "middle";
    subtitle.horzAlign = "center";
    subtitle.vertAlign = "middle";
    subtitle.fontScale = 1.6;
    subtitle.alpha = 0;
    subtitle setText(self.name);
    
    // Slide in from top
    title.y = 100;
    subtitle.y = 130;
    
    title fadeOverTime(0.5);
    title.alpha = 1;
    title moveOverTime(0.5);
    title.y = 150;
    
    subtitle fadeOverTime(0.5);
    subtitle.alpha = 1;
    subtitle moveOverTime(0.5);
    subtitle.y = 180;
    
    wait 3;
    
    // Fade out
    title fadeOverTime(0.5);
    title.alpha = 0;
    subtitle fadeOverTime(0.5);
    subtitle.alpha = 0;
    
    wait 0.5;
    
    title destroy();
    subtitle destroy();
}

Limits and Best Practices

Maximum Elements: The server supports up to 1024 HUD elements total (shared across all players and server HUD elements).

Best Practices

Always destroy unused HUD elements
Use client HUD elements for player-specific UI
Reuse elements when possible instead of creating new ones
Set archived = false for temporary elements
Limit animations to avoid performance issues
Test with multiple players to ensure element limit isn’t exceeded

Performance Tips

// Bad: Creates new element every second
while (true) {
    hud = newHudElem();
    hud setText("Time: " + getTime());
    wait 1;
    // Never destroyed!
}

// Good: Reuses same element
hud = newHudElem();
while (true) {
    hud setText("Time: " + getTime());
    wait 1;
}

Alignment Reference

Horizontal Alignment Constants

HUDALIGN_LEFT = 0
HUDALIGN_CENTER = 4
HUDALIGN_RIGHT = 8

Vertical Alignment Constants

HUDALIGN_TOP = 0
HUDALIGN_MIDDLE = 1
HUDALIGN_BOTTOM = 2

Screen Alignment Constants

HUDSCRNALIGN_LEFT = 9
HUDSCRNALIGN_CENTER = 17
HUDSCRNALIGN_RIGHT = 25

HUDSCRNALIGN_TOP = 0
HUDSCRNALIGN_MIDDLE = 1
HUDSCRNALIGN_BOTTOM = 2

GSC Scripting

Player Functions

Server Functions

Advanced

​Creating HUD Elements

​newHudElem()

​newClientHudElem()

​HUD Element Properties

​Position Properties

​Alignment Properties

​Text Properties

​Font Types

​Color Properties

​Display Properties

​Text Methods

​setText()

​setValue()

​setTimer()

​Animation Methods

​moveOverTime()

​fadeOverTime()

​scaleOverTime()

​Destruction

​destroy()

​destroyElem()

​C API Functions

​G_GetNewHudElem()

​G_HudSetPosition()

​G_HudSetFont()

​G_HudSetColor()

​G_HudSetText()

​G_HudSetMovingOverTime()

​G_HudSetFadingOverTime()

​G_HudDestroy()

​Complete Examples

​Kill Feed

​Countdown Timer

​Player Score Display

​Welcome Message

​Limits and Best Practices

​Best Practices

​Performance Tips

​Alignment Reference

​Horizontal Alignment Constants

​Vertical Alignment Constants

​Screen Alignment Constants

​See Also

Build docs developers (and LLMs) love

Creating HUD Elements

newHudElem()

newClientHudElem()

HUD Element Properties

Position Properties

Alignment Properties

Text Properties

Font Types

Color Properties

Display Properties

Text Methods

setText()

setValue()

setTimer()

Animation Methods

moveOverTime()

fadeOverTime()

scaleOverTime()

Destruction

destroy()

destroyElem()

C API Functions

G_GetNewHudElem()

G_HudSetPosition()

G_HudSetFont()

G_HudSetColor()

G_HudSetText()

G_HudSetMovingOverTime()

G_HudSetFadingOverTime()

G_HudDestroy()

Complete Examples

Kill Feed

Countdown Timer

Player Score Display

Welcome Message

Limits and Best Practices

Best Practices

Performance Tips

Alignment Reference

Horizontal Alignment Constants

Vertical Alignment Constants

Screen Alignment Constants

See Also