Speech Bubbles news - Water mod for Half-Life 2

Today we are releasing the source code for the speech bubbles. We are not planning to release the whole source code for Water, atleast not yet, but if you have wishes to know how some certain parts of Water were made, let us know.

The speech bubbles in Water are completely generated by the HUD. The size of the bubble is calculated by how long the text is. They also support localization, to allow them to be translated to any language.

Dont forget to read Making Of Water:

You can also now download the remastered Water soundtrack by Dennis "Entru" Yaremov.

• Download from hlssmod.net
• Download from Moddb

But I digress, the speech bubbles:

Speech Bubbles

Setting it up

First you can download the four C++ files:

• mm_hud_speech_bubbles.h
• mm_hud_speech_bubbles.cpp
• util_speech_bubble.cpp
• hlss_speech_bubbles_shared.h

mm_hud_speech_bubbles.h and mm_hud_speech_bubbles.cpp are for the client side while util_speech_bubble.cpp is for the server side, and hlss_speech_bubbles_shared.h is shared.

You need to add add "StartBubble" and "NarrationBox" to your hl2_usermessages.cpp.

usermessages->Register( "SpeechBubble", -1 );
usermessages->Register( "NarrationBox", -1 );

You also need to download the materials:

• speech_bubble.vtf
• speech_bubble.vmt

They need to go to materials\vgui\ subfolder of your mod.

You need to add the speech bubble hud element to HudLayout.res in the script subfolder of your mod. Add this somewhere in the file.

For localization, you can either add your lines to your existing mod localization file which is [modname]_english.txt for english language users. Or you can create a seperate localization file for all the speech bubbles. If you have your own localization file you need to add it to the localization system either in the speech bubbles hud element or somewhere like in VGui_Startup function in vgui_int.cpp. g_pVGuiLocalize->AddFile("resource/mermaid/default_�la;nguage%.txt"); Finally you need to define what fonts you want to use for the bubble text. You can either edit mm_hud_speech_bubbles.h so that it uses some entries from ClientScheme.Res in the resource subfolder of your mod.

Or you can edit the ClientScheme.Res and add the fonts we used into the Fonts section:

How to use the bubbles

On the server side you have the four functions. You have two for the speech bubbles, and two for the narration boxes. Include hlss_speech_bubbles_shared.h to any file where you want to use the speech bubbles in.

So, to show a simple speech bubble on an NPC's head you call UTIL_SpeechBubble. The first variable is the player you want to send the bubble. If the pointer is NULL it will use the PAS filter. If your mod is a multiplayer, this might be useful since it would send it to all players who are in the proximity of the speaking entity. However, since Water was a single player mod, I didn't add an option to send the bubble to all players no matter where they are in the map. If the pointer is defined, it will send the bubble only to that player.

Next is the pointer to the speaker entity. This can be something like an NPC or the player themselves. The bubble will appear on that NPC. The attachment option defines where from the character's body the bubble's tail is coming from. Usually you want to use the "mouth" attachment, which would mean calling pSpeaker->LookupAttachment( "mouth" ). Each entity can only show one speech bubble at once, and if the entity is already showing a speech bubble, the new will either replace that one, or not show up at all.

The strBubble option should usually be a localization token refering to an entry in a localization file. You can use unlocalized lines here as well, but it is recommended you use localization. The delay determines how long the bubble should appear on the screen. In Water using the delay of 0, would make the game wait until the player has pressed a key to skip it. Since I don't cover how to make a dialogue selection menu in this tutorial, I have disabled that option for now.

The priority option tells the system how important the bubble is. If the entity the bubble is supposed to be shown on is already showing a speech bubble, and the old speech bubble has higher priority than the new one, the new one wont replace the old one. Bubbles with higher or equal priority of Medium, are also always shown, even if the entity is off screen.

How it works

You don't necessarily need to read this if you want to add the bubbles to your mod, but it helps if you want to change something in their behavior. I only cover bubbles here, but the narration boxes work pretty much the same. Since this tutorial doesn't cover how to make a dialogue selection menu either, I have commented out some of the references to it.

In short, first the server side sends a localization token to the client side with info on which entity it wants to show the bubble on and so on. The client side CHudSpeechBubbles HUD element then localizes the file, goes through it cutting it into smaller lines to fit the speech bubble shape, and adds it to the list of all speech bubbles.

The Paint function then paints all the speech bubbles and removes them if necessary.

UTIL_SpeechBubble
This is the function you call on the server side to show a speech bubble on the speaker entity. First it creates a filter, which determines which players can see the bubble. If the player pointer is NULL, it will simply use the speaker's center to determine which player's could see it using the PAS filter.

It then starts sending the usermessage SpeechBubble (as declared in hl2_usermessage.cpp) to the client. The HLSS_MESSAGE_SPEECH_BUBBLE macro defines the message. It starts by writing the entity index of the speaker entity, which will used to find the entity on the client side. After that it will send the bubble delay, priority, the token for the bubble, and the attachment index.

MsgFunc_SpeechBubble
This is the first thing that gets called on the client side. It goes through the data the server side sent, and follows the same message structure. It uses the entity index to find the pointer to the speaker entity. If the delay is negative it assumes it's supposed to remove any speech bubble from the entity rather than add a new one, and after doing so, it will stop reading the message. Other wise it will continue reading the message, and priority, token and the attachment.

It then tries to localize the token into a wchar_t buffer. If the token is not found in any localization file, it will simply show the token as it is.

If the bubble token has the $number$ character in it, the code tries to replace the number with a random number from 1 to the number before localization. For example, if the localization token sent by the server was #MM_Helper_Ask$3$, it would randomize a number between 1 and 3, so that any of the three versions of the line could show up.

AddBubble
This function checks if the speaker entity already has a speech bubble, and depending on that, adds a new one to the list of speechbubbles m_vSpeechBubbles, or edits the existing on. After this it calls ProcessLines.

ProcessLines
Here the speech bubbles are cut into several lines that are later painted seperately. It also goes through all the text and tries to replace any references to key bindings, and tries to find the name of the key the player has bound to that action. For example, if the bubble has the text %+attack% in it, the code will replace it with the name of the key the player has bound it to, which is by default MOUSE1.

First the function tries to approximate the size of the speech bubble by using it length. It then starts going through the text character by character, trying to figure out how it would fit inside the bubble shape, and cuts the lines as necessary. Finally it adds the fully processed line to the list of all speech bubbles.

Processed Bubble structere
The processed lines are listed in the UtlVector m_vSpeechBubbles, where every bubble is a single struct sSpeechBubble.

The EHANDLE m_hEnt is the entity the bubble is shown on. If the handle returns a NULL pointer, it means something has deleted the entity, and the bubble will be deleted as well. m_iAttachment defines, like previously mentioned, where in the model the bubble should appear. m_iType defines what color the bubble should be. As it is, the choices there are kind of limited, so you can add more choices there if you want.

m_iAlingment defines what direction the speech bubble's tail was pointing the last time the speech bubble was painted. m_iLettersReached is how many characters of the bubble should be shown. m_flNextGetLetter is when the next letter should be shown. The UtlVector m_vSpeechBubblesLines is a list of the speech bubbles lines.

Paint
The Paint function goes through all the bubbles and sees which ones it should paint, which ones not, and which ones it should remove. After that it does the same for narration boxes. For both of them it first checks if it should remove any of the bubbles.

With the bubbles it does a couple of things to check if the bubble should be drawn. It checks if the entity is off screen or if the speaker entity is visible. It also checks the distance of the attachment from the main view origin. If the distance is bigger than 1536 the bubble wont get drawn. In Water we didn't want the crabs' idle speech bubbles to be shown if the player was above water, so we also added a check to see if the main view origin is on the other side of the water surface than the attachment position.

The alignment of the bubble depends, if the bubble is near the edges of the screen, and direction the mouth attachment is pointing. The code also takes into consideration the alignment the bubble had previous round, so that the bubble wont suddenly change direction when the attachment moves even slightly.

Remember to vote us on the Mod Of The Year awards!

Download Water now

If you haven't yet played Water, you can download the installer, or use Desura, or unpack the .zip file to SourceMods so that the mod folder is called "water". You will have to have Source SDK Base 2007 installed on your Steam account. You can install Source SDK Base 2007 by accessing the Tools section in your Games Library. You need to have a Source engine game like Half-Life 2, Counter-Strike Source, or Portal to have Source SDK Base 2007 available.

Additionally if you the version of Water you downloaded is 1.0.2 or lower, download 1.0.3 Patch. The current installer is 1.0.3. If you have any problems with installing the patch, or anything else, go to the Water Bugs & Problems page.