Case study 5: Customizing the HUD

From Open Surge Wiki
Jump to: navigation, search
Stub
This article is a stub. This typically means the article is a placeholder for more content to come. Knowledgeable users are encouraged to help expand the article.

Overview

Customizing the HUD (also known as Heads-Up Display) can be either very easy or moderately hard depending on a series of factors:

  • The kind of visual indicators you need (lives, score, etc)
  • The look and feel of such indicators (text-only, text and graphics, only graphics)
  • Where do the indicators get their values from (from a $_globalvariable, engine function(), etc)
  • How they are positioned on-screen, and how they relate between them.

Looks simple enough. Knowing this beforehand will save you lots of time and allow you to focus on the really important features of your HUD objects.

FIRST CASE: Simple Clock

The first case shows a simple text-based HUD object:

object ".hud_clock"
{
    requires 0.2.0
    always_active
    detach_from_camera

    state "main"
    {
        hide
        set_zindex 1.1
        set_absolute_position 188 224
        let "$hour = date_hour()"
        let "$minute = date_min()"
        textout "default" 0 0 "$hour : $minute"
        on_level_cleared "cleared"
    }

    state "cleared"
    {
        destroy
    }
}

In order to learn how to display this HUD, please read: startup objects

So, let's go for a quick analysis: (you can learn more about the commands using the API Reference)

Object properties

requires 0.2.0

This command informs the engine that this object depends on functions that only exist from version 0.2.0

always_active

This command is a must-have in any HUD object. It tells the engine the object must NOT be deactivated unless destroyed.

detach_from_camera

This is the command every HUD object must contain. It makes the object set its position counting from the top left corner of the screen instead of from the top left corner of the level. This means that if the screen moves, your object will move with the camera, as if they are linked. The screen area, as of now, measures 320 x 240, so, for any HUD object to be seen, it's position must be lower than this values.

Commands

hide

Hide, yes. Why would we hide a HUD object? All objects without animation, show up a large "?" in the game and editor, and text objects do not need animations. Don't worry, the text will be always visible until you change to a state with no text at all, OR destroy the object.

set_zindex 1.1

As you may already know, or not, a Z-index greater than 1 hides the object from the editor. And we don't want HUD objects clogging up our editor, do we?

set_absolute_position 188 224

This command positions the object in the specified coordinates (X=188 Y=224), but as you may remember, this object is DETACHED FROM CAMERA, so any number you put here, must be smaller than the screen size for your object to be seen in-game.

let "$hour = date_hour()"

Assigns date_hour() to a variable called $hour.

let "$minute = date_min()"

Assigns date_min() to a variable called $minute.

textout "default" 0 0 "$hour : $minute"

The amazing thing of TEXTOUT is that it can print variables. In this case date_hour() and date_min() are fetched from your computer's clock, so this object will always tell you what time is it rather accurately :)

on_level_cleared "destroy"

Not really necessary, but a good precaution, is to destroy your HUD objects when a level is cleared, since they are created again when you start a new one, provided you have added them to the startup script. You may also have noticed, there is NO "destroy" state in the example. So yes, the object will crash as it is, if you clear the level.