[mjn.mixael]

The Mainhall Basics
Mainhall boot camp!

With this tutorial, I'm going to walk you through the basics of setting up a very simple mainhall menu. This won't cover 3D or full hangar mainhalls exactly, but the principals will apply exactly the same. I'm not going to walk you through the design process either. I'm going to assume that you have it mostly completed and are ready to try and get it working in FSO. Simply make sure you have a background and six buttons or clickable areas. Make sure that your buttons are on separate layers than your background in your source files.

Here's my design.


Now, the first thing you need to know is this has to be done at 1024x768 resolution. No more and no less. This is a limit of FSO and there's no getting around that right now. (You could do 640x480, but I'll talk about that a bit later.) This is no longer true.

Flatten your image (buttons and all) and save it as a .png. This will actually just be a temporary file, but it will help us get things setup correctly. Now save out each of your buttons or clickable areas with a transparent background.

Here's my temporary BG...

.. and an example of a button.


The Mask
The Jim Carey kind?

The next thing we need to create is the menu mask. This is an image that tells FSO what button your mouse is hovering over. It's actually a rather clever system. Let me explain how it works. The mask needs to be an indexed .pcx file. An indexed PCX file saves color information to index numbers rather than pixels. Then each pixel is assigned an index number. When the image is reproduced on screen, the program gets the index number from the pixel and then displays the color associated with that index. It's a good form of 'compression' for images that have very few colors. But that's not really how FSO uses it. FSO will monitor the index of the pixel the mouse is currently hovering over and take appropriate action based on that.

So here's what you need to know to create one. FSO really only cares about the first 6 indexes. (Ignore the RGB values for now.)

• Exit Button [255,255,255]
• Barracks Button [254,254,254]
• Ready Room Button [253,253,253]
• Tech Room Button [252,252,252]
• Options Button [251,251,251]
• Campaign Button [250,250,250]

These are hardcoded and can't be changed. In the newest version of FSO you can set the mask value in the mainhall.tbl, but we'll use the default set for this tutorial. So what you'll do is assign colors to indexes 1-6. (The methods will differ depending on your image program of choice, so I recommend you Google search instructions on indexed image palettes.) This image also needs to be the same resolution as your mainhall background. You will then paint with the color for Index 1 over the area and shape for the Exit button (or clickable area). Paint with the color for Index 2 over your Barracks button. Do this for all six buttons. I follow the scheme of the retail masks, so I paint over black with nearly white colors. I've included the RGB values next to each button that retail uses in the list above.

My mask looks like this.


You can also open the mask in the Example Download below and examine the RGB values compared to the index palette to see how I did it.

File Setup
With confusing EFFs

So we've got a temporary background file, 6 button files and a mask. We are almost set. FSO expects the buttons to be animated and we need to cater to that. I recommend keeping an organized naming scheme for your buttons. In the example I named each one 'But-REGION.png' where 'region' is replaced with things like 'ReadyRoom'. But we need to take it a step further because of the animation code. You'll need to add '_0000' to the end of the name before the extension. So I have 'But-ReadyRoom_0000.png'. Do this for all 6 buttons. With that completed, we need to create an EFF file. Open a program like Notepad and copy the following into it.

Code: [Select]

$Type: png
$Frames: 1
$FPS: 15
Then save it as 'YOURBUTTONNAME.eff'. For example, I have 'But-ReadyRoom.eff'. Note how I did not include the numbers. That is because of how EFFs work. EFFs are more like mini tables that give FSO information about animation frames. It gets the root name of the images from the EFF name (then it automatically tacks on '_####' starting with 0000 and ending with the last frame as designated in the $Frames entry. It gets the image type from $Type and the frames per second from $FPS. The type should match your image type and we are using PNG. Our button is unanimated, so we only have one frame. Do this for all 6 of your buttons. You should now have 14 files ready to go. Make a mod folder and create data/interface and data/tables. Copy all 14 of those files into data/interface.

The Table In The Digital Flesh
Not your pr0n either!

Now we need a mainhall.tbl and it will be easier to start with one that already exists, so let's use the retail one. I've linked it here to make it easy on you.

Scroll down until you find ';; Main hall 1 (Vasudan)'. Delete that and everything below it except '#end'. That will just simplify the table to one mainhall entry. Note that in one entry there are definitions for a 640 resolution mainhall and a 1024 resolution mainhall. If you want, you can resize and recreate your mainhall for the 640 res as well, but very few people will ever see that. I prefer to just leave the 640 Aquitaine stuff so that FSO won't crash for the one person who plays on that low of a resolution. Remember that you can't delete the 640 res definitions. It must be there or FSO will scream bloody murder. From here on out we will focus just on the 1024 section which begins with ';; GR_1024'. The note no longer applies to newer FSO versions.

At this point you may want to keep a tab open to the mainhall.tbl Wiki page. But I won't be going over the 3.6.15 flagged changes as those are currently only in Antipodes builds (as is modular mainhall.tbl ability).

Go ahead and make sure your table is saved in your mod folder data/tables as 'mainhall.tbl'. Again, we will be only working under the ';;GR_1024' section.

Make the following changes...

• +Bitmap: should link to your temporary background image file.
• +Mask: should link to your mask file.
• Replace your +Num Intercom Sounds: section with the following as we'll cover that later.

Code: [Select]

+Num Intercom Sounds: 1
+Intercom delay: 8000 15000
+Intercom sound: 1
+Intercom pan: 0.0

• +Num Misc Animations: should be zero as we don't have any. Comment out or remove the rest of the lines until +Num Door Animations:.

Under +Num Door Animations: 6 you should see six +Door anim: entries. These link to the clickable areas in this order: Exit, Barracks, Ready Room, Tech Room, Options, and Campaign. That order can't be changed. So replace all the entries there with the names of your button EFF files. Mine looks like this.

Code: [Select]

+Door anim: But-Quit ;; door anim 1 exit
+Door anim: But-Barracks ;; door anim 2 barracks
+Door anim: But-ReadyRoom ;; door anim 3 ready room
+Door anim: But-TechRoom ;; door anim 4 tech room
+Door anim: But-Options ;; door anim 5 options
+Door anim: But-Campaign ;; door anim 6 campaign
We aren't going to change anything else for now. Select this mod folder and run FSO. You should see your temporary background image and all of your buttons, but they will be all over the place.



Your temporary background likely also included images for your buttons and so you might see duplicates as well. I've circled the red for what is on the background image in my example. The actual buttons are circled in blue.



You can also check that your mask works by mousing over where your buttons should be. You should see text show up on the bottom of the screen letting you know what 'button' you could click. If the game did not load your buttons or background correctly, check for spelling in the mainhall.tbl. Be sure not to include file extensions in the table either. If the mask didn't work properly, you may have your indexes setup incorrectly and will need to tweak it with your image program.

Here's where to look to check if your mask is working.


Let's return to the table, so exit FSO and return to the +Door anim: entries. I need to take a moment to explain how the mainhall.tbl works. Remember that this works for all areas of the mainhall.tbl not just the door area. Notice how each set of +XXXXXXX flags has six versions. They each correspond to the door entry above in the same order. So the first +Door coords: works with the first +Door anim: in the same way that the fifth +Door pan: works with the fifth +Door anim: entry. Understanding this is key to understanding the mainhall.tbl.

With that in mind, we need to position our buttons correctly. They get their positions from their +Door coords: entry, as you may have guessed. There are four sets of numbers here. The first two are the X & Y position of the button as measured from the top left corner of the screen, to the top left corner of the button image. The second two numbers are the X & Y for where the mouse cursor will be placed when the player right clicks. Typically it should be set in the center of the button. These are also measured from top left of the screen.

There's no easy way to do this. You'll have to make some educated guesses and run FSO to check. Then make some adjustments and check them again. You could also do the pixel math. I know my buttons are 204 pixels wide and that the Ready Room button is in the exact center. So it's X position will be 512 (center of 1024) minus 102 (half the image width). Concurrently, it's cursor X position is going to be screen center or 512. I guessed on the height for the Ready Room, but once I got that I knew that all the other buttons (except my Exit button) will have the same Y and cursor Y positions. I did some other math/educated guesses to finally get the buttons lined up. This is why you created the temporary background image that still had the buttons. With that you could line them up where the needed to be to also correspond to the mainhall mask. When this is done, you can replace your temporary background file with a final version that is saved without the buttons on it. Here's mine.



And here we are in FSO with all the buttons lined up properly.



Making It More Awesome
Just add MjnMixael!

This is a perfectly usable mainhall. It's got all the basics and it works properly. But let's customize it a bit. Let's begin with the sound effects. You may have noticed that when you mouse over your buttons you hear the classic 'door open' and 'door close' sound effects. Let's change that to the FS beep. The sounds you use here must be in the sounds.tbl in the interface section which you can read about on the Wiki. I already know that the beep I want is sound index 0 and that sound index 1 is empty.

FSO plays sounds for 'doors' on mouseon (when the cursor hovers of the area) and mouseoff (when the cursor leaves the area). Find +Door sounds: and you'll see that they all have two numbers. These correspond to the sound indexes. The first is mouseon and the second is mouseoff. I want the beep when the player hovers over the button and no sound when the cursor leaves, so I'll change them to 0 and 1. You can see this in the mainhall.tbl I included in the download below.

If you try it now, you'll get the beep, but it will be panned differently (left/right) for each button. Back in the table is +Door pan: where -1.0 is totally left, 0.0 is center, and 1.0 is totally right. I changed the entries for each button to match where they are on the screen. You can do the same or just set them all to 0.0 (center).

I hope you saved the source files for your 6 buttons, because now we are going to add a simple animation that you can do with any image editor. Open your button and do something like highlight the wording or make the button a brighter color.

I changed..

to'


Save that as your button name, but with '_0001' instead of '_0000'. Change your EFF file to have two frames instead of one. (Edit $Frames.) I also changed $FPS to 120 so that the buttons might be a little more responsive. The first frame of the two-frame animation is what is shown by default. FSO will play the animation and hold on the last frame when the mouse hovers over that button. Since we only have two frames, it will be a simple On/Off. I did this for all 6 buttons.

NOTE: If you are using .ani instead of .eff you need to use ANIBuilder to create or ANIs as a mainhall .ani and it will set the proper keyframes for you. You could also use my ANI Toolkit. More information on ANIs versus EFFs can be found here.

Let's also change the music. Scroll up to find the music entry. It currently says 'Aquitaine'. This references a music entry in the music.tbl. You can change your music table if you wish. For simplicity, I saved my music as Aquitaine.wav so I don't have to do that and placed it in data/music.

Misc(ellaneous) Anim(ation)s
I've got nothin.

This is looking quite nice at this point. But I'm going to go just a bit further and add a misc anim. Misc anims are the animations that are constantly playing. They are how the cranes moved in FS1's Bastion mainhall, or how the welder could create sparks in FS1's Galatea mainhall. In most cases, you won't be able to create these without some sort of animating program like After Effects. I'll move through this next section somewhat quickly. Be sure to reference the mainhall.tbl Wiki page to fully understand each mainhall entry.

I happen to have an animated SOC logo that I'm going to use. I saved it as an EFF just like before. I changed +Num Misc Animations: to 1 and added its file name to +Misc anim. I set it's +Misc Anim Delay: to -1 0 0 so that it plays right on mainhall load. +Misc anim coords: is just like +Door coords:, so I set it to be in the right place. I set it's +Misc anim mode: to 0 (loop). I don't want it to have sounds, so I set the sounds and trigger to 0. I also resaved my BG image to not have the SOC logo on it. (Now it's just the stars and green nebula, nothing else.)

Like so.


The animation is about 110 frames long, which is just over 7 seconds at 15 FPS. It loops constantly and it actually seems quite busy, so I'm going to change it to a timed animation.

In the mainhall.tbl I set its +Misc anim mode: to 2 (timed) and I set it's delay to -1 8000 10000 (min delay is 8 seconds, max is 10 seconds). When I loaded up the mainhall, the first thing I noticed was that the logo was missing! After about 8 seconds, it popped on screen, did it's animation, then disappeared. This is a good lesson. Misc anims are not like door animations (with one exception that I'll mention in a minute). They will be on screen ONLY during the time that they are playing. Since a looped animation is always playing, this was not an issue. Timed anims are different. So fix this, I once again added the SOC logo to the background and made sure that the Misc Anim position matched it (like we did with the buttons).

The one exception is a Misc anim that is set to mode 1. Mode 1 is hold, Which basically means that the animation will indefinitely hold on the last frame forever. The retail FS2 mainhall uses this for the guy that rides down the elevator.

This Guy.


However, my logo animation is still quite repetitive. It's the same animation every few seconds. SCP once added a feature that my 3D mainhalls use extensively. Basically, with this feature you can create variations of animations that will only play one at a time!

Currently my misc anim has a light shine from right to left, then left to right across the logo. To save time, I simply cut it in half making 3 total misc anims. (One where it goes from right to left and back, another where it only goes from right to left, and the last one where it goes from left to right.)

I added all of these to the mainhall.tbl just like the first misc anim. They are set to timed mode and have a delay. Next we will add '+Misc anim group:' just under +Misc anim for all three entries. (See the included mainhall.tbl in the download for an example.) How this works is that misc anims are grouped by number where -1 is not a group. I set all 3 to group number 1 so they are in the same group. If you run FSO and watch for a while, you will see that it randomly plays one of the three animations every 8-10 seconds. This is a pretty powerful and flexible feature.

The misc anims in the same group, do not need to have the same delay, coords, or sounds. They do need to all be set to mode 2 (timed). I'll let your creative brain think up the possibilities here.

Intercom Sounds
Announcing an announcement!

The intercom section is very straightforward now that you understand more about the mainhall.tbl. Intercom sounds are sounds that are played randomly in the back of the sound mix. They are actually a lot like Misc Anims but without anything visual. You can have multiple Intercom sounds just like you can have multiple anims. The layout of their entries is the same. Check the mainhall.tbl Wiki page for information on each entry in this section.

Other Notes
The musical kind... but not really.

The mainhall essentially works in layers. The background is always on bottom and the doors are always on top. Misc anims are in between. Anims listed first in the mainhall table will be on top of anims below it. (actually, that might be the other way around.. I'm not 100% sure.)

Modular mainhalls are possible under Antipodes 8 with the extension -hall.

Under Antipodes 8 you can also use sound names instead of index numbers, but they still need to be present in the sounds.tbl.

At some point, I'll mention how mainhalls are assigned to campaigns.. but I'm sick of writing today.

The End
With a download.

So now we have a complete mainhall with 6 working animated buttons and an animated logo. This tutorial also applies to fully 3D mainhalls as well, but you have to do a lot more work to line all your renders up.

Example Mainhall Download

[Cyborg17]

Awesome work Mjn!  Modding is just that much easier now.  Thank you! 

[Mongoose]

Man, did not make that process easy...

[mjn.mixael]

There certainly is a steep learning curve.. but if you understand the mainhall.tbl and an image editor, you can do some pretty nice lookin menus.