[TUTO] Making a MIX Template
Making a MIX Template is now "easy".
Like a theme in emulationstation, all information are in a XML Descriptor.
All files in a zip and there is a "repository" to publish them to the community.
This is the description of all information needed to make a good MIX Template.
The zip filename must be the same as the name you give to your template (in config.xml) it's important
All information and file must be at the "root" position in a zip file like this :
The minimum file needed are :
- config.xml
- Empty_exemple.jpg
- Full_exemple.jpg
You can add "Fixe" picture to your template at the same level.
The main file with all the information needed
An exemple of what is "generated" by UXS if no media were found
The file need to be in 400x200
It can be "empty" like this :
An exemple with all the media founded
The file need to be in 400x200
like this :
You can add other "Fixe image" to your template like Flag, arcade cabinet, TV screen, what you want to add...
The config.xml file must be a legit XML file ( XML Syntax ) It's composed of 2 parts :
- The "header" part
- The "Elements" part
It contain all "descriptive" informations and some general configuration.
Optional, but you can add it :
<?xml version="1.0" encoding="UTF-8"?>
The root element contains the Template Name as attribut. It must match the Zip filename.
<Profil Name="Arcade (moon)">
The "header" nodes are the folowing :
It contains :
- Author : Your name or pseudo
- Description : A "light" description of your template. If you want you can add "@CRLF" to structure your Description
<Infos>
<Author>Screech</Author>
<Description>A nice cabinet (moon, credit : omegaman) with Marquee (or wheel in the Marquee) and screenshot</Description>
</Infos>
It contains :
- Empty_Exemple : Your "Empty_exemple.jpg" filename
- Full_Exemple : Your "Full_exemple.jpg" filename
- Target_Width : The "Default" width (you can change it in UXS option directly)
- Target_Height : The "Default" Height (you can change it in UXS option directly)
<General>
<Empty_Exemple>Empty_exemple.jpg</Empty_Exemple>
<Full_Exemple>Full_exemple.jpg</Full_Exemple>
<Target_Width>341</Target_Width>
<Target_Height>400</Target_Height>
</General>
It define if there is a "post" action after the mix generation. I use pngquant, but if you want you can try "other" compressor or post traitment
- use : simply "yes" or "no" to activate or desactivate.
- soft : the "exe" file you want to use. It need to be in the UXS's "ressources" folder.
- parameter : the parameter you want to use. It will be placed just after the "exe" and before the full path to the rendered picture. (in the exemple below it will be : pngquant.exe --force --verbose --ordered --speed=1 --quality=30-90 --ext .png "FullPathToPicture" )
<Compression>
<use>yes</use>
<soft>pngquant.exe</soft>
<parameter>--force --verbose --ordered --speed=1 --quality=30-90 --ext .png</parameter>
</Compression>
Don't touch these nodes ;) I need it to "read" more efficiently the API Request return ;)
(But I need them)
Elements are the structured part for each images or GDI_Function.
1 Element node by image or function.
It works like "stack" so first image will be first, second one on top of the first one, and so on...
So ordering your "lyer" is important.
The same for GDI_Function, They (when needed) act on the "last" elements.
All element can "accept" some node. This is the list :
The Element name. Easy... But, it have an other function. You can do "fallback" with it. If 2 elements have the same name, the second one is used only if the first one don't work. Exemple : First Element is a Screenshot named "MainPic" Second Element is a 2D Box named "MainPic" If there is a screenshot available, no 2D Box were downloaded. If no screenshot is available, it try to download the 2D Box. It works with 2, 3, or more fallback...
<Name>fanartTEMP</Name>
FYI : I always name them with "TEMP" but it's just me... It's not needed ;)
The Source to use.
It can be :
1- Fixe_Value : simply a predefined picture you put in the Template ZIP.
2- XML_Value : a dynamique picture comming from the scrape
3- GDI_Function : a function (see Source_Function part)
4- Text : write Text directly in the picture (see Source_TextType part)
This is some function you can use :
1- Transparency : put an alpha transparancy on the last Element (Source_Value = 0 to 1, where 0 is total transparancy, 1 is total opacity)
<Element>
<Name>TransTEMP</Name>
<Source_Type>GDI_Function</Source_Type>
<Source_Function>Transparency</Source_Function>
<Source_Value>0.25</Source_Value>
</Element>
2- TransparencyZone : put an alpha transparancy zone on the last Element (Source_Value = 0 to 1, where 0 is total transparancy, 1 is total opacity and Zone defined by : Target_Width, Target_Height, Target_TopLeftX, Target_TopLeftY)
<Element>
<Name>TransZoneTEMP</Name>
<Source_Type>GDI_Function</Source_Type>
<Source_Function>TransparencyZone</Source_Function>
<Source_Value>0.50</Source_Value>
<Target_Width>%0.359</Target_Width>
<Target_Height>%0.68</Target_Height>
<Target_TopLeftX>%0.610</Target_TopLeftX>
<Target_TopLeftY>%0.22</Target_TopLeftY>
</Element>
3- Merge : Merge the 2 last Elements. Exemple if you want to put transparancyZone on 2 (or more) Elements at the same time.
<Element>
<Name>MergeTEMP</Name>
<Source_Type>GDI_Function</Source_Type>
<Source_Function>Merge</Source_Function>
</Element>
You can specify here the source of Text
1- XML_Value : to catch some Info from the scrape and put it in the picture (Specified by <source_Origin> and <Source_Value> )
2- Fixe : a simple string of text (not yet implemented)
In both case you can use <Target_TopLeftX> <Target_TopLeftY> <Target_Font> <Target_FontSize> <Target_FontStyle> <Target_FontColor>
Define from wich API request media came from.
1- Game : Media are from the game (Screenshot, 2D Box,....)
2- System : Media are from the system (Console picture, Controler, Bezel, Wheels, ...)
3- Genre : Media from the genre list
Depend on Source_Type :
1- GDI_Function : Depend on Function (Exemple : Transparency Value)
2- Fixe_Value : The filename picture stored in the ZIP file
3- XML_Value : Xpath from the API request XML (See the XML Xpath chapter)
Width and height of the downloaded media.
It can be a standard value like "300" meening 300px or a relative value like "%0.5" meening 50% of the final picture.
Move the "origin" point for the media position.
Default value is 0x0 meening the top left corner.
It can be a standard value like "300" meening 300px or a relative value like "%0.5" meening 50% of the final picture.
Top Left corner ajusted with Target_Origin if needed.
It can be a standard value like "300" meening 300px or a relative value like "%0.5" meening 50% of the final picture.
You can use "predefined" value like LEFT, RIGHT, UP, DOWN, or CENTER.
Just rotate or flip the picture with these number :
0 - No rotation and no flipping (A 180-degree rotation, a horizontal flip and then a vertical flip)
1 - A 90-degree rotation without flipping (A 270-degree rotation, a horizontal flip and then a vertical flip)
2 - A 180-degree rotation without flipping (No rotation, a horizontal flip followed by a vertical flip)
3 - A 270-degree rotation without flipping (A 90-degree rotation, a horizontal flip and then a vertical flip)
4 - No rotation and a horizontal flip (A 180-degree rotation followed by a vertical flip)
5 - A 90-degree rotation followed by a horizontal flip (A 270-degree rotation followed by a vertical flip)
6 - A 180-degree rotation followed by a horizontal flip (No rotation and a vertical flip)
7 - A 270-degree rotation followed by a horizontal flip (A 90-degree rotation followed by a vertical flip)
<Target_Rotation>1</Target_Rotation>
Simply the Font name (it must be installed on your computer) like 'Arial', 'Times New Rom', ...
<Target_Font>Arial</Target_Font>
The font Size like '8', '10', '48',...
<Target_FontSize>20</Target_FontSize>
The number corresponding to the style or an addition of the number to make 2 differents styles :
0 - Normal weight or thickness of the typeface
1 - Bold typeface
2 - Italic typeface
4 - Underline
8 - Strikethrough
<Target_FontStyle>3</Target_FontStyle> (Italic + Bold)
The font Color in the format Alpha, Red, Green, Blue in Hexa (starting by '0x'):
<Target_FontColor>0xFFFF0000</Target_FontColor> (Full Red)
<Target_FontColor>0x8000FF00</Target_FontColor> (Green with some transparency)
If you want to transform the "shape" of the media, you can precise the top right and bottom left corner position.
It can be a standard value like "300" meening 300px or a relative value like "%0.5" meening 50% of the final picture.
You can use "predefined" value like LEFT, RIGHT, UP, DOWN, or CENTER.
Resize the picture to match the Target_Width and Target_Height without changing the ratio.
So it can be smaller in one way but maximized in the other way. (Never bigger)
You can choose from a lot's of possible media comming from Screenscraper Web API
Some of the media :
- Screenshot : Data/jeu/medias/media_screenshot
- 2D Box : Data/jeu/medias/media_boxs/media_boxs2d/media_box2d_%COUNTRY%
- 3D Box : Data/jeu/medias/media_boxs/media_boxs3d/media_box3d_%COUNTRY%
- Texture Box : Data/jeu/medias/media_boxs/media_boxstexture/media_boxtexture_%COUNTRY%
- 2D Support : Data/jeu/medias/media_supports/media_supports2d/media_support2d_%COUNTRY%
- Texture Support : Data/jeu/medias/media_supports/media_supportstexture/media_supporttexture_%COUNTRY%
- Fanart : Data/jeu/medias/media_fanart
- Wheels : Data/jeu/medias/media_wheels/media_wheel_%COUNTRY%
- Wheels Carbon : Data/jeu/medias/media_wheelscarbon/media_wheelcarbon_%COUNTRY%
- Wheels Steel : Data/jeu/medias/media_wheelssteel/media_wheelsteel_%COUNTRY%
- And lot's more...
The %COUNTRY% tag meen : "Rom country" with fallback. Exemple : If you have a japan rom, it try to take the japan media first. If not possible, it fallback on your "language" selection (you can configure it in "General Option" )
But if you want to fixe it, you can.
Exemple :
Data/jeu/medias/media_supports/media_supports2d/media_support2d_jp
Data/jeu/medias/media_boxs/media_boxs3d/media_box3d_us
- Monochrome logo : Data/systeme/medias/media_logosmonochrome/media_logomonochrome_%COUNTRY%
- Wheels : Data/systeme/medias/media_wheels/media_wheel_%COUNTRY%
- Wheels Carbon : Data/systeme/medias/media_wheelscarbon/media_wheelcarbon_%COUNTRY%
- Wheels Steel : Data/systeme/medias/media_wheelssteel/media_wheelsteel_%COUNTRY%
- Empty Wheels Carbon : Data/systeme/medias/media_wheelcarbonvierge
- Empty Wheels Steel : Data/systeme/medias/media_wheelsteelvierge
- System photo : Data/systeme/medias/media_photos/media_photo_%COUNTRY%
- controler photo : Data/systeme/medias/media_controleur/media_controleur_%COUNTRY%
- And lot's more...
- Monochrome picto : Data/genres/genre[id = %IDGENRE%]/medias/media_pictomonochrome
- Color picto : Data/genres/genre[id = %IDGENRE%]/medias/media_pictocouleur (not yet available)
- Background : Data/genres/genre[id = %IDGENRE%]/medias/media_background (not yet available)
Coming from the Game API, The screenshot take 90% width and 85% height of the finale picture.
Position is CENTER / UP and it's maximized to keep the ratio.
<Element>
<Name>screenTEMP</Name>
<Source_Type>XML_Value</Source_Type>
<source_Origin>Game</source_Origin>
<Source_Value>Data/jeu/medias/media_screenshot</Source_Value>
<Target_Width>%0.9</Target_Width>
<Target_Height>%0.85</Target_Height>
<Target_TopLeftX>CENTER</Target_TopLeftX>
<Target_TopLeftY>UP</Target_TopLeftY>
<Target_Maximize>Yes</Target_Maximize>
</Element>
It's this screenshot :
It's one method, I put the "snow" effect first, and add over it the screenshot.
I also can change the order and put the same name to both Element. So when Screenshot not found, it put the "snow" effect.
Both are deformed to match the TV Screen.
<Element>
<Name>screenfixeTEMP</Name>
<Source_Type>Fixe_Value</Source_Type>
<Source_Value>neige.png</Source_Value>
<Target_Width>%0.588</Target_Width>
<Target_Height>%0.500</Target_Height>
<Target_TopLeftX>%0.147</Target_TopLeftX>
<Target_TopLeftY>%0.375</Target_TopLeftY>
<Target_TopRightX>%0.5</Target_TopRightX>
<Target_TopRightY>%0.345</Target_TopRightY>
<Target_BottomLeftX>%0.191</Target_BottomLeftX>
<Target_BottomLeftY>%0.658</Target_BottomLeftY>
</Element>
<Element>
<Name>screenTEMP</Name>
<Source_Type>XML_Value</Source_Type>
<source_Origin>Game</source_Origin>
<Source_Value>Data/jeu/medias/media_screenshot</Source_Value>
<Target_Width>%0.588</Target_Width>
<Target_Height>%0.500</Target_Height>
<Target_TopLeftX>%0.147</Target_TopLeftX>
<Target_TopLeftY>%0.375</Target_TopLeftY>
<Target_TopRightX>%0.5</Target_TopRightX>
<Target_TopRightY>%0.345</Target_TopRightY>
<Target_BottomLeftX>%0.191</Target_BottomLeftX>
<Target_BottomLeftY>%0.658</Target_BottomLeftY>
</Element>
This is with no screenshot :
This is with the screenshot :
Don't hesitate to contact me to add your Mix Template to the repository or to ask some advice. Use github issue or contact me on the IRC Channel