Modding the HUD -- a diary/discussion

[Rayanth]

This thread is being created to track my progress in a quest to Mod Civ4's Heads Up Display -- the user Interface / HUD. Please feel free to post comments/suggestions/questions/encouragements, as this is an ongoing project and feedback will be greatly welcomed.


OK, SO i've been spending a lot of time on this, and here are my notes I've taken as I've gone along.

At first, just to see that the HUD *was* moddable, I replaced /resource/Civ4/HUD/HUD_bottom.tga with a version that was just solid red.
First lesson: HUD Changes require a Civ4 restart to take effect.
second lesson: this was VERy visible in the game, giving me the courage to continue.

I decided on a new color. Cyan was the pick, with a somewhat darker-than-normal shade so it wouldn't look ungodly bright.

I then had some Photoshop learning to do. After a while I determined the best way to change the color without ruining the shading was through PS's Hue/Saturation Modify option. I looke dup the HSB for both the original color and the cyan i was replacing it with, and calculated the difference. This difference was the number plugged in to the HSB sliders to make the shift. After testing on a visible file, I saved this adjustment so I could just load it on every file without adjusting sliders every time.

For the record: HSD = Hue/Saturation/Brightness(lightness).

Side-track:
There are several ways to get a color on a computer. the most popular is RGB - the Red Green Blue values. Another is CMYK, which is more common when printing the image is important, as CMYK is what printers use. CMYK is CYan/Magenta/Yellow/blacK -- the colors of ink that make up the printed color.
The final method is more complicated - Hue, Saturation, Brightness. If you plot the color wheel on a circle, and shade the results from the inside out (Center Point being pure white, outside arc being pure color) you get every shade of color. Brightness affects this by dimming the Pure color. Hue is measured in degrees, Saturation in % distance from center, Brightness in ... something. % brightness of original color maybe? Anyway, if you pick the radius of the color, then Saturation, and shift the brightness, you get a color (incidentally it can be converted to RGB easily, the advantage is that it's easy to determine the mathematical difference in colors with HSB).

For example, the brighter shade of tan used in Civ4's original HUD Scheme is RGB: 249/223/191. It is HSB: 33/23/98.
The Cyan I was replacing it with was RGB 0/118/163. HSB 197/100/64.

The difference in RGB isn't easily adjustable... it requires finding a formula to shift each shade level. HSB accounts for that... the DIFFERENCE in HSB is +164/+77/-34. Plug these numbers directly into the hue/Sat sliders and presto! you've shifted the color, shading entirely intact! Now you can save this change to a file, and load it for every file you need to adjust, making the process super quick and simple!

I proceeded to run this filter on every file in /HUD. the result was pretty clear, a very different HUD coloration but using the same files! In the main game screen it looked awesome... with a few minor things i didn't notice until later. However, once I entered a City screen my heart sank a little... the City Header was still tan, but the rest of the screen was the new blue... what gives?

Turns out that the HUD pulls files from all THREE /Resource/Civ4 folders. The city screen files were found in /Civ4, but affected other parts of the game (loading screens' Slider bars, for example) as well. It became clear at this point that you cannot just modify the in-game HUD, you gotta modify ALL of the HUD.

At this point my research turned towards the elusive /Resource/Theme folder. This folder contains .thm files which were entirely greek to me at first. It turns out that Firaxis chose to use a 3rd-party tool to build their HUD, and these .thm files are like Markup Language files to describe the HUD layout. Best yet, they included the image file names to load in each spot! I could find all of the relevant IN-game .thm files and modify them to use copies of the relevant files so that the changes could be made to only affect in-game. OR, I could look further and see if there was a way to make a sort of switch, so the user (or game itself) could /change/ the theme on startup. Both methods had clear advantages and disadvantages.

Sadly, upon the end of tonight's research, I have concluded that the path to the Theme is hardcoded into the game itself. I cannot find any mention of the Theme in any python or XML file, nor in the .ini... This has the following impacts:

Any HUD change will affect ALL games, since it is not a CustomAsset subfolder. Mod-specific custom HUDs will not be possible (for instance, for your space-based Mod you can't do a space-looking HUD, because it will force the user to change the HUD for all their other games to that as well... while a mod-specific custom HUD would be awesome for flavor reasons, it just can't be done)

So the path to now follow is:
- Very carefully examine the .thm files to understand their markup language ( to my knowledge this is not documented anywhere, the 3rd party utility they used is fairly new).
- Determine all of the .thm files used during actual gameplay
- Pick a single folder for in-game HUDs to draw their graphics from. (likely /Resource/Civ4/HUD)
- Find all references to files NOT in that directory from the in-game HUD .thm files found in step 2.
- Copy these files to the HUD directory, and change the .thm reference accordingly.
- Begin editing the HUD files, so that gameplay interface is graphically different.
- Test, Test, TEST

A few notes to sign off this post:
1) I apologize, I'm long-winded. Please bear with me and you'll eventually figure out where I'm going =)
2) For a user to download and implement a HUD mod, they will be forced to mod the HUD for all of their games, until Firaxis finds it in their hearts to let us add new Themes, or put it in CustomAssets, or something.
3) In order to download a HUD mod, the user will need: First, back up old HUD (25 megs), basically make a safe copy of the entire/Resource Directory. Second, Replace all of the .thm Theme files. Third, replace all of the /Resource/Civ4/HUD images (and any other images that were changed by the HUD mod creator)
4) Restart Civ4 for the changes to take place.

 

[Rayanth]

A screenie of the Cyan Test HUD Mod:

(Bear in mind the entire HUD was originally Tan)

 

[Rayanth]

Also, I should note that Civ4 HUD uses a layered scheme. The Shading is often provided by a seperate image that consists of the shading mask. The shading mask is simply a null-background file containing Black where shading is desired. Black's OPACITY is set to varying percentages, higher percent = darker shade. This is not ALWAYS the case, but is frequent. Shading Masks should NOT be modified if you are simply changing the color of the HUD. If you are /replacing/ the HUD with all new graphics for a whole new look, modifying the Shading Masks will be a MUST.

One other thing I'm trying to find out is where the background color is set. You know, the dark blue that fills in all of the large sections.

 

[Rayanth]

I'm making significant progress in deciphering the .thm markup language. It's an interesting network of includes and defines and stuff, but it's becoming clear. Unfortunately many things rely on definitions in Civ4_Common.thm, for instance the background color of the major sections of the in-game HUD as well as message boxes throughout loading screens, and other stuff... this means, once again, that changing that color for in-game purposes will affect other things as well.

So rebuilding the .thm structure will be a MUST, if my goal of modding only the in-game HUD is to come to full realization. I want the loading screens and all that to remain jsut as they are, but the in-game HUD to take on a whole new look.

There's two paths that I'll be jumping between to do this - One will be to unravel all of the .thm files to see everything that affects in-game HUD stuff. Then finding references that lead to shared-resources and modifying them appropriately. THe other will be to look at major resources and change them to see what else they are used for.

An example of how I am doing this, is when trying to find what affects the background color in the major sections of the game screens. I traced the color back to a definition in Civ4_Common.thm, and changed its RGBO values to something drastically different, leaving the remainder of the HUD as they were out-of-the-box. The background color is normally dark blu so i went with bright red. The differences were astounding -- clearly I had found the right thing, but it also affected all of the loading screens, before even entiring the game. Because of this, I will have to create a seperate color definition for the in-game background colors, and change all references to use it.

 

[GIDustin]

Interesting finds. I imagine that when you are done you will post a fully documented tutorial on how to change the HUD?

I will keep checking back. If you need any help, let me know.

 

[Rayanth]

Interesting finds. I imagine that when you are done you will post a fully documented tutorial on how to change the HUD?

I will keep checking back. If you need any help, let me know.

I Intend to post both a tutorial and a working, completely different HUD for download =)

I don't need any help as of yet, right now it's still in the deciphering stages... I'm not a fantastic artist though, so when I get to that stage I might need some assistance.

 

[Rayanth]

After modding the wrong file for 3 hours, and sudenly noticing the mistake, I am now quite capable of reading the .thm files -- the markup language is pretty simple once you get used to it, and i can trace inheritance with ease. There are details I need to figure out, such as what certain commands mean, but overall it's now just a matter of trial and error, and "change this to see what happens".

I am currently in the process of breaking the HUD away from shared resources by making it use its own copy. I'm defaulting images to the /Resource/Civ4/HUD directory, and creating additional Hud handles for the .thm definitions (such as panel background colors)

 

[Rayanth]

Didn't get very far today, spent time answering questions regarding the Button Color-Change i posted in Tutorials, and trying to determine once and for all whether Themes *could* be made mod-specific (to date, I'm still under the distinct impression that they cannot -- There is still some testing I can do, but I'm so convinced right now, that it's almost pointless.)

I have managed to fully mod the background color of the panels. Once I figured out yesterday that I was modding the wrong file for 3 hours (I was changing my original backup, instead of the game copy ), It all became quite clear and easy. I am working towards a new theme for my changes, and things are coming together fairly well.

There's still a couple of things I don't understand in the core .thm files, however, and those are my current focus. I'm sure they tie in with python pretty heavily, but I haven't bothered to check into the python scripts to find my answers yet. I may look there next...

 

[Rayanth]

I've been tracking all of the changes I make, so I can backtrack to see what I've changed recently in case somethign goes horribly wrong. Also I'm making notes of what I've tested, so if i have to restore originals, I know what I can safely re-implement without starting completely from scratch.

I will begin posting these logs along with my regular updates.

Today I made more progress in changing the background color of the panels in the game. That is to say, everywhere there is a panel in the HUD with a dark blue background, I am changing to a dark green background. The green doesn't look half bad with the original tan border stuff, so it's a nice start to the HUD I have envisioned in the end. (I will eventually replace the tan things too, and have to write my own shading filters as a result... a full makeover is in the works)

There are a few panels I may have missed - I've changed everything I see frequently during my settler/tiny/one-opponent mod-test game. I have changed a few other things that I suspect *might* be visible at some point, such as Diplomacy Screen backgrounds... which I have only partially tested. A similar change was made to what appears to be the diplomacy screens for Multiplayer, but I don't play multiplayer, someone else will eventually have the honor of testing that for me =)

My ChangeLog to date consists of :

Changing File Civ4Theme_Common.thm -- Line 204
Insert NEW line 205 (immediately after GColor .BG) :
-----------------------------------------------------
GColor .HudBG =GColor( 25,123, 48,217): GFC_Control_Color; //Set for dynamic color change


CHANGE the following lines to use .HudBG instead of .BG:
Civ4Theme_HUD.thm:
------------------
Line 170 -- Top Center Panel BG
Line 207 -- Bottom Center Panel BG
Line 244 -- Top Right Panel BG
Line 281 -- Top Left Panel BG
Line 318 -- Bottom Right Panel BG
Line 355 -- Bottom Left Panel BG
Tested fine.

Civ4Theme_Custom.thm:
---------------------
Line 1129 -- City Top Panel BG
Line 1163 -- City Right Panel BG
Line 1197 -- City Left Panel BG
Tested fine.
Line 1985 -- Diplomacy Panel MP BG (NOT TESTED)

Following are single-player diplomacy panel: (NOT FULLY TESTED)
Line 2047 -- Center Top BG
Line 2082 -- Bottom BG
Line 2110 -- Sides Top BG

Line 2172 to see what it belongs to -- suspect Civpedia.
Turns out this affects the bottom panel at main menu and load screens, as well as Civpedia.
This means I'll have to find where Civpedia loads the bottom bar, and replace it with a copy of the bottom bar with the color changed.
-- Actually it's worse. This is the bottom bar for ALL full-screen advisor screens as well... a LOT of screens rely on this....
-- This is likely to be the same with Line 2138 as well, then... the accompanying Top Bar Panel BG.

 

[davbenbak]

Might be a silly question but...is there a way to close the minimap? There are really only a few areas of the hud that I find important. The rest are just eye candy that slows down the graphics as far as I'm concerned. All I could find was an all or nothing kind or option "alt-I".

 

[weakciv]

try ctl-I. it is for a minimised interface. alt-i is turning off the interface

 

[Jon Shafer]

Great work Rayanth, this is the kind of thing that people will be very thankful for later.

 

[Rayanth]

Great work Rayanth, this is the kind of thing that people will be very thankful for later.

Thanks Trip, if only someone would get back to me on the possibility of making the HUD a dynamic setting in Mods in a future patch =)

I Did try out your suggestion and put a HUD in the Mod/res folder, but that is a replacement of /assets/res, not /resources. Needless to say, it didn't work -- and I suspect nothing will, until one of you Devs explicitly makes it moddable.

If nothing else, will the SDK be able to change this?

 

[Gogf]

I was playing around with the tan to try to make it look more civ-ish:

 

[MeteorPunch]

Just the post I've been looking for.

Does anyone here know what numbers to use for simply a "clear" HUD? I want more visibility on the screen.

 

[Gogf]

Just make the last number (the 217) a 0 . That should make the opacity of the HUD 0.

 

[Rayanth]

Just the post I've been looking for.

Does anyone here know what numbers to use for simply a "clear" HUD? I want more visibility on the screen.

or you can use the existing commands: Alt-I and Ctrl-I to hide the HUD completely (the same command shows it again when you need it)

 

[Gogf]

Rayanth's method is probably a better idea. With my method, there will be lots of free-floating text that will be very hard to read.

 

[Rayanth]

11/05/2005
----------
Today's work focused on playing Star Wars Battlefront 2, and determining the GRectMargin syntax -- what the heck coordinate system is it *using*? My method of testing this is to mod, pixel by pixel, one of the files that gets stretched. I'm trying to determine exactly how the coordinates in the GRectMargin are layed out, and what their reference point is. For some reason, they appear to be rather understandable in the X dimension, but Y's almost seem inside-out. More testing is necessary as of writing this sentence...

Alright, I've got it. Example Syntax: GRectMargin(16,1,156,26);
This coordinate system is listed in (X1, Y1, X2, Y2)
X1: Pixels In from the left edge of the image
Y1: Pixels in from the top of the image
X2: Pixels in from the right edge of the image
Y2: Pixels in from the bottom of the image
0 means no pixels at all, 1 is the first pixel in (the one on the edge), 2 is the one after it, etc.

What this all means? it's defining an inner rectangle, which is the rectangle that gets stretched to fit the panel. This is a bit more complicated than it sounds, and is worthy of a mini-tutorial on its own.

Due to this stretching, and my plans for the HUD, I am now entering a stage where I have a lot of Photoshop learning to do. I will still be fiddling with core bits of the markup language, as well as trying to find whether the panel *sizes* are set in python somewhere or something, but you might be seeing my posts taper off slightly. (I'm also taking a step up to full-time at work, so I won't have quite as much free time to work on this)

 

[Psyringe]

Hello Rayanth,

I just found this thread and immediately bookmarked it. Great work you're doing here. This thread might be laying the groundworks for many future Civ4 UI modding projects - keep up the good work!