Theme Layout Rules & Issues

[Gandalf467]

Being new to GameEx I'm finding a lot of little nuances to it that are very different from my past experience with Mamewah...particularly around theming and options.

I'd like to try and get some questions answered around the theming system and how some things work.  These are my current observations so just looking for confirmation or responses so that I can figure out next steps,

1. Themes are nothing more than a visual layout.  There is no hard functionality tied to a theme (sort of...see questions below).
2. Some of the objects in a theme are basically fixed objects.  For example, menus or the taskbar...the size of these objects can't be manipulated using a mouse "drag and drop" kind of approach, however I have found that I can manipulate size of these objects by changing the "W" & "H" values directly in the editor panel on the left (most on this below/next).

3. If I manually manipulate the dimensions of these objects as stated above, specifically the menu, then it will cause GameEx to generate an error when it tries to load the theme.  For example, if I try to make the menu 200 Wx400 H in a theme GameEx will error out.  I suspect it is because GameEx is expecting the menu object to be designed as a horizontal menu, not a vertical menu, and when you do this it can't handle it (which would also explain why it won't let you manipulate the object dimensions using the mouse).  Is this correct?

By the way, trying to "Upload the log" options results in an error from this screen...

4. Some pieces/components have to appear in fixed locations in the layout and those same components appear to have functionality that is "hardwired" to them, but no way to obviously move them around.  For example, I haven't found a single theme that has a taskbar someplace other than the top of the theme.  If I wanted to put my taskbar elsewhere, and then tie things like "volume up/down" to that new positioning it doesn't seem like there is a way to do that.  Volume Up/Down is expected to live in a specific place in the layout, much like the MCE button, the "Back" Button, and the "Help Button".  To be visual with it...are the objects circled in red below something that can be moved to another location either horizontally or vertically...or is this the only place those objects can live?

5. I haven't found a way to tie "functions" to a keypress without selecting them from a menu (FYI...I don't want a menu on the theme...or I want a menu setup that is more like mame or mamewah where the menu "pops up" when you press a certain key).  For example, I would really like a way to trigger a ROM list update for MAME from a cabinet button push, but that doesn't seem possible.  Is this a situation where you could create a "back" menu or a menu tied to a different key that that goes to a different layout that has all of the MAME options on it??  I want to "fix" GameEx to MAME as the only option, but still be able to access the menu system via a keypress of some kind.
6. In the ThemeEditor there appears to be a "hierarchy" of objects.  For example, there is a background object, but also a Mod Background, and a Emu Background.  I'm not entirely sure how to use these vs. simply changing the background in one or more of the templates.  Is there a 'hierarchy map" for the themes that shows how each template/object relates to each other, and what the specific items are in the MEDIA library for the template that are associated with each object?
7. The MAMEWAH import option doesn't appear to work...at least not trying to import my current mamewah theme configuration (see attached).  This is the error that I receive.

8. On MAMEWAH there was a lot of granularity for information related to the ROMs that you could place on the layout including,
- Game Description
- ROM Name (+ Parent)
- Year & Manufacturer
- Screen Type
- Controller Type
- Driver Status
- Catver Category
Some of these appears to be covered through filtering mechanisms and other things, but I'm particularly interested in whether the "Controller Type" object is available in the layout system at all.  It doesn't look like that level of granularity is available but I wanted to check before I gave up on it.

Sorry if this stuff has been answered in the past.  I've been searching around the forums and have not been able to find answers to these questions.

 

mame.lay

[Draco1962]

Hi there - while there isn't a guide for Theme Editor, there is a dedicated thread here that may contain answers to some of your questions:

 

 

[u-man]

I would like to help, but there are too many (imprecise) questions. What do you want achieve? A more arcade cab related theme or a more HDTV oriented theme? Do you want something simple but individual or do you really plan to do some artist(ic) stuff etc. etc.

I will try to answer some of your questions and will start with the layering of things in the theme editor:
There is a background layer (the bottom of the bottom) and a foreground layer (on top of all layers) and anything else, is in between this "sandwich"  . The foreground layer is mostly used as a mask layer to mask out objects (i.e. rounded windows etc). Ideally the image(s) used for back & foreground are in the size of your theme (i.e. 640x480, 1920x1080 etc). Why i write this? We will come back to this later.

The "templates" box contains all (default) pages that your theme can use and each of these pages can use a different back & foreground layer, that is set in the "object" box. Which pages are really used in the theme, are setup in the GameEx setup wizard. Clicking on pages of the "templates" box can be used, to see a preview of how that page will look in the theme. Each page in the template box, has a equivalent in the "object" box and contains the elements that will be showed, if you are on that page in the theme (once running). These elements are mostly text based stuff and will only use fonts and their according options. Exceptions are Image, Image 2 and weather. Sadly we have no full control what Image 1&2 is showing. It depends on what page you are in the once running theme, what images you have in the media folder of your theme and how you have setup certain pages (i.e. MAME settings) in your GameEx setup wizard.

Hardcoded elements: AFAIK, there are only 5% hardcoded elements, maybe less. You may come to this conclusion, because there are hardcoded dependencies (especially the "naming" of certain buttons and elements) to certain elements, but how these elements look like, is really up to you.

As you see in the preview picture for the theme editor question thread of Draco1962 answer, there is a vertical menue in a theme, but the point is, it is likely made with a different theme version of the theme editor (the option where you been asked what version you want to create, if you want to start a complete new theme.)

Many text based things are dependent on how you configure GameEx (setup wizard) in the first place and some of your questions, are answered exactly there. You can only benefit from catver category, if GameEx itself, finds a catver.ini file. It must be setup (and updated) before this stuff can work. Same goes for the menue, what kind of text and options show up, must be setup before and the setup wizard has these options.

Buttons and coordinates: Some of the buttons in the "object" box, should ideally use the same properties and size of the object/picture it represents. Simply changing the width and height in the fields, will just scale the used graphic to these values and will degrade/squeeze the quality of the object/picture in the final output.

My advice is first to fully understand the GameEx setup wizard. The setup wizard has a small description for EVERY option you set there. It is the core element of how your theme will work and what options you will have. Start with a very simple theme, set it up properly and to your like. Once you are done with this, you can start to use the theme editor. Setup only MAME and use other emulators later, since we have the most options for MAME. Turn off any further options i.e. Jukebox, Daphne, Karaoke etc. and add them later to your theme. This way it is easier to understand the theme editor and you can better focus on what is happening, if you change this or that.

My advice to Draco1962 and Tom Speirs: add a wiki for a theme editor tutorial / manual. So that users can gradually fill up the manual. It is simply to much work to write a complete manual for it (at least for me).
Please Tom, make the "template" and "object" boxes SIZEABLE , this is crucial. The amount of time spending scrolling through these boxes is INSANE and very, very painful. If this is something that can be achieved easily, then please please please do it. I personally hate these boxes so much, that there is not much more passion to create a theme. 

I hope i could help at least someone.

[Gandalf467]

U-Man,

Thanks for the detailed response.  Let me give you a bit more context.  I'm trying to rebuild my Mamewah configuration, which is purely limited to MAME classic Arcade games (layout screenshot attached).

You have the ability to select a game from a list, get a snap of the game (in Artwork Image #1), and some description information about the ROM (there are a number of other objects you can place on the layout as well, but I don't use most of them).  Mamewah's menu system is more of a "popup" style menu...you can press a key to access the menu, it shows up, you leave the menu and it goes away...so it doesn't directly influence the primary goal of the interface which is to allow selection of games to play.  You can also configure Mamewah to generate a new list of ROMs from the ROM folder directly vs. using an XML file to figure it out, so updating the listing is, at the worst case, restarting Mamewah.

Although I've been able to make Mamewah work on my new setup (new machine, new O/S, new monitor, new everything) Mamewah is no longer supported, and doesn't handle the video transitions very well, thus why I started looking around for alternatives.

All of my questions are driven around trying to figure out how the system works and get back to that point.

The Theme Editor has an "Import Mamewah" option, but it doesn't work, so I'm left to figuring this stuff out.  I have been playing with different themes and playing around A LOT with the Setup Wizard to try different options and understand how some of this works, but as you can see, it has still left me with a lot of questions (the descriptions are not always helpful).

Your description of the layering is very helpful...I haven't found anything that describes it as a sandwich...thanks for that analogy.

My hardcoding question was not stated very well.  The question that I'm really driving toward is for objects like the Media controls, it seems like that always has to have a particular "format"/structure with the pause/play, back, forward, volume down, volume up buttons in specific positions, and in a specific order.  I think (although I haven't found anything that clearly states this), that as long as that is true you can put that thing anywhere on the screen and use it...but no one ever places it anywhere except in the taskbar, so not sure if that is a true statement.  The reason the ordering of the buttons is important is because GameEx expects them to be in a particular order, with a particular spacing, otherwise it doesn't know which control to manipulate when you "mouse over" the controls and push a button.  Is that true?  I think this goes back to your buttons & coordinates comment...I'm trying to figure out if there are certain functions/features that have specific coordinates they are tied to...because the layout edito r doesn't appear to restrict this in any way.

Hopefully this gives you a bit more context.  I completely agree, a guide of some kind would be super helpful.  I'm trying to go through the thread that Draco provided around the theming system, but there is a lot there and since I started at the beginning of the thread it is taking time.

Draco, any chance you can export that thread to a file of some kind that we could run through a ChatGPT session and try to turn it into a starting point for a user guide?  I'm happy to do the work, but would need the information to do it.  I can make something that will grovel through the whole thread, but it will take longer.

 

 

 

[Draco1962]

Sorry but there's no way to export the forum threads. You would basically have to copy & paste each post into a document editor.

[Draco1962]

P.S. Another thread you may be interested in - more emphasis on graphic editing relative to theme creation.

 

 

[Gandalf467]

Draco, I tried reading through the original thread you pointed me at, but the history of evolution is hard to keep track of.

So...I used AI to screen scrape the original forum thread you pointed me at and used it to process everything that it found in that thread and turn it into a Markdown document. 

Draco & u-man, I would be very interested in your feedback to help understand how good of a job the AI did in terms of summarizing how the Theme Editor works and if this could be a possible starting point for an actual user guide/document.

(Let me know if you guys would like to see this in a different format...it was a starting point.  I'm happy to set up a Github repo or other storage that contains this, and I can do this for other threads in the forum as well.)

GameEx_Theme_Editor_Usage_Summary.md

[u-man]

From what i have read, this is a really nice start up. Some stuff is a bit wrong or not actual, but i would say 70-75% of the document is pretty usable. If we go together through this document point by point and eliminate errors or wrong statements, it will be a very good starter. It will need some pictures/screenshots for some points, but i guess this will be no problem. My thumbs are up for this.

[Draco1962]

I will be glad to take a look and thanks for taking an interest.

You might want to go through the second thread I provided, scrape it, and incorporate where possible or needed. While covering some specific themes, I believe it also touches on a few techniques for moving and resizing elements within Theme Editor for more unique layouts.

[u-man]

I will start with some points  . 

## 2. : **V4 Themes** 
This strip position and font size are hardcoded and cannot be repositioned or resized via the editor.

This is not true, the only thing you cant change is, that it is a horizontal menu, but you can position it at least horizontal (X pos.). You can change font size and you have some control in that way, that you can decide what options it is showing by using the GameEx setup wizard. Also you can resize the menu "box/field", but the borders could "cutoff" the menu text that is displayed, if you are using too small width values. Moreover even if you cutoff the text, the options will still be there, just not visible, which can be irritating for a user.
 

## 6. Backgrounds and Foregrounds

I think it would be good here to add some points: The .png format is the best and recommended format for pictures. Lossless compression including a full working Alpha channel (for transparencies). You can also use other formats like .bmp or .jpg for example. AFAIK you can use "animated" foregrounds too, but in most cases, it will not make sense to do so. For example if you use a "animated" foreground that has the same size like the theme, then it would cover every element on screen, making them invisible for the user. The biggest problem here is, that .avi codecs that provide a Alpha channel for transparencies are taxing the cpu so hard, that GameEx cant work without a huge slo-mo effect and becoming barely usable. The solution here, would be a option where we can setup and specify a seperate Alpha channel (i.e. a grayscaled .png file) just for the foreground layer, but this is something, that only Tom Speirs can answer.

- Image files in the `media` and `logos` folders do **not** need to be resized to match theme resolution — GameEx scales them automatically.

This is true, but i would not recommend doing this at all. Anything where (up)scaling is involved, decreases the image quality of the (scaled) object. Always try to use original width and height values. Downscaling is ok, but can produce a too sharp/crisp image.

## 8. Selector Bar
- The bar is built from a sequence of **PNG frames** (at least 15 frames are standard; some themes use 20). Frames can also be BMP format.

The sequence is hardcoded to 15 frames, if there are themes that have 20 frames, then only the first 15 will be used. Again recommendation is to use .png, because BMP has no compression and will tax the cpu more. 

- The frames animate by cycling through the sequence.

The frames are not cycling, they go forth and back to create a loop. Cycling would mean, if frame 15 is reached, it starts with frame 1 again. This is not the case for the selector bar.
 

## 12. Transparency / Color Key

While this whole section might be true, i would not recommend to use it at all. The quality of the color key is very bad. Images with color key will have jaggy edges. This is really obsolete and legacy. Sadly the theme editor itself, does not preview transparencies (alpha channel from a .png file) correctly, they will look jaggy too, but only in the theme editor and not in the final theme.

## 13. Changing Theme Resolution

I would add a note here: You should try to avoid this, as it involves a lot of work to achieve the same quality level as before doing this and the amount of time spending on updating object coordinates is HUGE. Not to mention that font sizes needs to be changed too. Always plan the theme resolution beforehand, in fact it should be the very first thing you do, before even start working on a theme. If you plan to use the theme with different resolutions, then work with the highest resolution you plan to use. So you can use these image files to create the other (lower) resolutions.
 

## 15. Weather Display
- Per-page weather control (e.g., show on Start page but not MAME page) is not supported.

I cant proof this currently, but i am pretty sure you can just use coordinates for the weather element, that are outside of the theme resolution, for the pages where you dont want to show the weather.

## 17. Popup Descriptions

I would add a note here: The description element is the foremost layer in the entire theme editor. It is on top of the foreground layer, which in my eyes is clearly a bug. Moreover it has a very thin outline, that can cause jittering on interlaced resolutions and the rating system (set in the setup wizard) for games is tied to this element too and appears on top of that element. AFAIK the description element is only used for MAME in combination with a history.dat file and is empty for other emulators (needs proof).

## 18. "Change View" Feature

I cant proof this currently, but i am pretty sure you can turn off this feature to not appear in the menu. While this feature provides MANY different views for a theme, it can easily destroy the "look and feel" of the whole theme and then you need to find the "one" view you started with, before using/clicking this option. My advice is to carefully observe the different views and how they work, choose one, stick with it and turn the option off in the setup wizard and never come back here. The only thing i can imagine, that would justify this option, is to create a good looking theme for every view, which would be a tremendous work with a small to little benefit in the end result. Not worth IMHO. Usecase is also very questionable.

Thats all from my side now.

[Draco1962]

Good job, @u-man! You pretty much hit the points I had noticed. 

@Gandalf467I would recommend making note of where within the Setup Wizard some of the Theme features can be enabled/disabled. 

As was suggested, some screen caps with pointy-thingies (arrows), boxes, and the like where appropriate will add to the content.

[Gandalf467]

Thanks for the feedback guys!  I'll make the corrections and additions.  Also, I've scraped a number of other threads in the forum,
 

So will have a much more comprehensive user guide for you guys to review on this next pass.  I used the information that stryker had created as a starting base for the new document and have been adding new sections and information based on the other threads (I've finally got the scraper/crawler to a point where it is pretty reliable and can do an entire thread in 5-10 minutes).  Unfortunately I can't crawl the entire forum space in one shot...have to be more selective than that.

If you guys have other suggestions for threads that would be appropriate to grind that might contain troves of valuable information let me know.  I'm trying to be somewhat selective and pick threads that are likely to result in a good amount of useful context.

Regarding the screen grabs...noted...and agree that they would help...unfortunately that isn't something I can get the AI tools to do easily, so I'll have to come up with a different solution for that, but I will work on getting them in there.

[Draco1962]

If you continue to look through the GameEx Media subforum, you may find some more nuggets tucked inside some of the various user submitted themes threads. Your mileage may vary, of course!

[Draco1962]

One item to note is that the Theme Editor for GameEx is not the same for GameEx Evolution, as is noted in the footnote of your doc:

*This document synthesizes practical how-to information from 345 forum posts spanning 2006–2024. Feature limitations noted were accurate as of the thread's last posts and may have changed in later GameEx or GameEx Evolution releases.*

Additionally, there have not been any changes to the functionality of Theme Editor since its last update May ‎16, ‎2021 and that was likely due to a bug fix.