XMBML Coding

From PS3 Developer wiki
Revision as of 10:02, 5 May 2013 by Euss (talk | contribs)
Jump to navigation Jump to search

This page will outline the logic behind XMB .xml configuration files.

Basic Structure

This is a reduced version of category_network.xml with only one icon (tex_browser) that launches the webbrowser (type:x-xmb/xmlwebbrowser). The .xml is loaded starting from <View id="root">, then inside the <Items> table there is a <Query> linking to #seg_browser (the character "#" links to a <View id> in the same file, so is linked to <View id="seg_browser">). When <View id="seg_browser"> is loaded first starts reading the table of <Items> that contains an <Item> that is linked using attr="browser" to a table of attributes <Table key="browser" 

Code Sample
  • The whole contents of the .xml file can be identifyed by the <View id> and <key> this way:
    • <View id="root"> contains 1 <Items> with the key="seg_browser"
    • <View id="seg_browser"> contains 1 <Items> with the key="browser"

View id

Must consist of UTF-8 characters and have no spaces. There must be no other entries with the same <View id>.

  • There are some specific <View id> names that are placed at the top of the .xml and can be considered the "XMB enviroments" that can be loaded by VSH
    • "root", "root_for_dex", " tool_root", "shop_root", "shop_guest_root", "shop_staff_root", and "root_arcade"
    • Are used to be able to load specific items for every Target ID or for loading items in specific conditions (e.g: is shop firmware "locked" or "unlocked" modes)
  • A <View id> can load another <View id> from the same or other .xml file by making one of his <items> to point to the other <View id>
    • Links to a <View id> in the same .xml file can be considered "direct links" and uses the character "#" followed by the <View id> of the linked item (e.g: src="#seg_poweroff")
    • Links to a <View id> in another .xml file uses the localhost functions with the full path of the file followed by the character "#" and the <View id> of the linked item (e.g: src="xmb://localhost/dev_flash/vsh/resource/explore/xmb/category_user.xml#seg_poweroff")

Items

The contents of this sub group dictates what exists on the XMB when this entry is used. There can be more than one.

When creating a XMB entry, you must tell vsh.self and its modules what you want to do. And the first part of a <Items> sub-entry does just this by telling the PS3 the "class" of the entry in the form of either "<Item class=""" or "<Query class=""" (in the case of "<Query class=""" can be used several times under the same <items> to perform group of actions). There are many acceptable values possible, here are some examples:

A table with the <class> types and the tags they can/must use
class Type <class> Identification <key> <attr> <src> Remarks
Query class <Query class="type:x-xmb/folder-pixmap" Yes Opt Yes Has many uses see here
<Query class="type:x-xmb/xmlpackagefolder" Yes Opt Yes Used for installing package files
<Query class="type:x-xmb/xmlmcutility" ? ? ?
<Query class="type:x-xmb/xmlsavedata-ps3" ? ? ?
<Query class="type:x-xmb/xmlsavedata-psp" ? ? ?
Item class <Item class="type:x-xmb/module-action" Yes Yes No Uses a particular module to support the XMB item, see the Module-Action list
<Item class="type:x-xmb/xmlpoweroff" ? ? ?
<Item class="type:x-xmb/xmlsysconf" ? ? ?
<Item class="type:x-xmb/xmlplaylist" ? ? ?
<Item class="type:x-xmb/xmlhakoniwa" ? ? ?
<Item class="type:x-xmb/xmlscreenshot" ? ? ?
<Item class="type:x-xmb/xmlgameexit" ? ? ?
<Item class="type:x-xmb/xmlnowplaying" ? ? ?
<Item class="type:x-xmb/xmlbddatamgmt" ? ? ?
<Item class="type:x-xmb/xmleditingvideo" ? ? ?
<Item class="type:x-xmb/xmlwelcome" ? ? ?
<Item class="type:x-xmb/xmltrophy" ? ? ?
<Item class="type:x-xmb/vmc-new" ? ? ?
<Item class="type:x-xmb/xmlpremo" ? ? ?
<Item class="type:x-xmb/xmlwebbrowser" ? ? ?
<Item class="type:x-xmb/xmlnpsignup" ? ? ?
<Item class="type:x-chat/xmlchatroom-manager" ? ? ?
<Item class="type:x-xmb/xmlmessagelist" ? ? ?
  • <key>
    • Used to identify the sub-entry inside <Items> tables (usually the same value as <attr> and the < Table key> associated if present)
    • Example: key="my_icon"
  • <attr>
    • Used to link <Items> to a table of attributes with the same name < Table key> inside <Attributes>
    • Example: attr="my_icon_metadata"
  • <src>
    • Used to link to other xml files or utilise a XMB database functions (see XMB database)
    • Refer to another XMB entry inside the current xml file. Example: src="#seg_package_files"
    • Refer to another XMB entry inside another xml file. Example: src="xmb://localhost/dev_flash/vsh/resource/explore/xmb/category_game_tool2.xml#seg_package_files"
    • Use a XMB database function. Example: src="xcb://localhost/query?table=MMS_MEDIA_TYPE_SYSTEM&genre=Music&sort=+StorageMedia:Common.titleForSort&cond=Ae+StorageMedia:StorageMedia.type %xCB_MEDIA_TYPE_DLNA"

Attributes

This provides additional information about <Items> sub-entries by linking them to a table with attributes associated (is optionall, not all <Items> requires attributes), this tables uses a < Table key> matching the <attr> sub-entry asociated and contains one or more attributes separated in lines starting with <Pair key>.

A table of usable attributes and what <Items> sub-entries they can be used with
<Pair key> Use Used by class type: Example(s)
x-xmb/folder-pixmap x-xmb/module-action x-xmb/xmlpackagefolder
icon_rsc displays a .rco referable image as XMB icon. Cannot be used at the same time as 'icon'. Yes Yes Yes "tex_album_icon"
icon displays a .png image from an absolute path as XMB icon. Cannot be used at the same time as 'icon_rsc'. Yes Yes Yes "/dev_hdd0/game/XMBMANPLS/USRDIR/IMAGES/filemanager.png"
icon_notation tells the XMB how to treat the icon (transparency etc.) by refering to the relevant .rco. Can in some cases override 'icon' or 'icon_rsc' Yes Yes Yes "WNT_XmbItemSavePS3"
title_rsc displays XMB main title text referred from relevant .rco. Cannot be used at the same time as 'title'. Yes Yes Yes "msg_tool_app_home_ps3_game"
title displays XMB main title from plain text input. Cannot be used at the same time as 'title_rsc'. Yes Yes Yes "Debug Settings"
info_rsc displays XMB title information from relevant .rco. This is shown below the 'title' or 'title_rsc' entry ins a smaller font. Cannot be used at the same time as 'info'. Yes Yes Yes "item_tex_cam_icon"
info displays XMB title information from plain text input. This is shown below the 'title' or 'title_rsc' entry ins a smaller font. Cannot be used at the same time as 'info_rsc'. Yes Yes Yes "This is a cool plain text info string"
child tells the PS3 what action should be taken when the XMB item is selected. Yes No Yes "segment"
ingame tells the PS3 if the item can be accessed ingame. Yes No Yes "enable"/"disable"
str_noitem displays information from relevant .rco when no data/XMB items are found from then search function of the current XMB item. Yes No No "msg_error_no_gamedata"
module_name the name of the module to be used from this list No Yes No "webbrowser_plugin"/"explore_plugin"
module_action what the module is commanded to use. The example commands are in respect the above modules No Yes No "http://m.facebook.com"/"NotifyErrorNoExecute"
bar_action ? No Yes No "none"
lbl_half ? No Yes No "1"
focus_detect tells the PS3 to focus on the item if it is activated/utilised (like inserting a PS3 game disc). Of course the vsh.self has the final say on whether it is used (turning off auto boot) Yes Yes Yes "enable"
focus_priority tells the PS3 the order in which the XMB items are loaded. This is use more by XMB items on the root of the XMB. Yes Yes Yes any integer
fo_lbl2_alpha ? Yes ? ? "0"
item_type ? Yes ? ? "systop"
ch_pos ? Yes ? ? "1"
  • Others not in the table:
    • In category_photo.xml
      • class="type:x-xmb/xmlplaylist" - <Pair key="mode"><String>playlistmgmt</String></Pair>
      • class="type:x-xmb/xmlplaylist" - <Pair key="type"><String>photo</String></Pair>
      • class="type:x-xmb/xmlplaylist" - <Pair key="id"><String></String></Pair>
      • class="type:x-xmb/xmlplaylist" - <Pair key="path"><String></String></Pair>
    • In category_music.xml
      • class="type:x-xmb/xmlplaylist" - <Pair key="type"><String>music</String></Pair>
    • In category_video.xml
      • class="type:x-xmb/folder-pixmap" - <Pair key="custom_priority"><String>video=-80</String></Pair>
    • In category_game.xml
      • class="type:x-xmb/folder-pixmap" - <Pair key="custom_priority"><String>game=-80</String></Pair>
      • class="type:x-xmb/folder-pixmap" - <Pair key="action"><String>exec_game</String></Pair>
      • class="type:x-xmb/xmlmcutility" - <Pair key="action"><String>exec_vmcsavedata</String></Pair>
      • class="type:x-xmb/xmlmcutility" - <Pair key="vmc"><String>promote</String></Pair>
      • class="type:x-xmb/xmlsavedata-ps3" - <Pair key="action"><String>exec_ps3savedata</String></Pair>
      • class="type:x-xmb/xmlsavedata-ps3" - <Pair key="ms_connection"><String>xcb://localhost/query?... (too long for wiki)
      • class="type:x-xmb/xmlsavedata-ps3" - <Pair key="sd_connection"><String>xcb://localhost/query?... (too long for wiki)
      • class="type:x-xmb/xmlsavedata-ps3" - <Pair key="cf_connection"><String>xcb://localhost/query?... (too long for wiki)
      • class="type:x-xmb/xmlsavedata-ps3" - <Pair key="mass_connection"><String>xcb://localhost/query?... (too long for wiki)
      • class="type:x-xmb/xmlsavedata-ps3" - <Pair key="data_connection"><String>xcb://localhost/query?... (too long for wiki)
      • class="type:x-xmb/xmlsavedata-psp" - <Pair key="action"><String>exec_pspsavedata</String></Pair>
      • class="type:x-xmb/xmlsavedata-psp" - (same xcb querys than above for: ms, sd, cf, mass, data)
      • class="type:x-xmb/xmltrophy" - <Pair key="data_connection"><String>xcb://localhost/query?limit=2048</String></Pair>
      • class="type:x-xmb/xmlwelcome" - <Pair key="content_type"><String>game</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - Pair key="info"><String>net_package_install_with_eula</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="pkg_src"><String>http://dL-REGION01.ps3.download.playstation.net/download/ps3/L-REGION/lwp/lwp.pkg</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="content_name"><String>msg_title_lwp</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="content_id"><String>IP9100-NPIA00002_00-0000111122223333</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="instruction_rsc"><String>msg_lwp_explanation</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="prod_pict_path"><String>/dev_flash/vsh/resource/explore/icon/fah-xmb.png</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="focus"><String>last</String></Pair>
    • In category_psn.xml
      • class="type:x-xmb/xmlnpsignup" - <Pair key="content_info_text"><String>msg_ps3_portal</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="content_info_title"><String>msg_psstore_explanation_hd</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="content_info_title_sd"><String>msg_psstore_explanation_sd</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="content_info_pict"><String>/dev_flash/vsh/resource/explore/icon/pstex01.png</String></Pair>
      • class="type:x-xmb/xmlnpsignup" - <Pair key="content_info_pict_sd"><String>/dev_flash/vsh/resource/explore/icon/pstex-sd.png</String></Pair>
    • In category_friend.xml
      • class="type:x-xmb/folder-pixmap" - <Pair key="title_fo"><String>1</String></Pair>
      • class="type:x-xmb/module-action" - <Pair key="start_factor_play"><String>disable</String></Pair>

Examples

An XMB item tree

For this we will make a XMB item which will act as a folder opening up into 3 other XMB items.

1/ First create the root XMB item which acts as a folder 

Code Sample

Important Notes:

  • I've used "<Query class="type:x-xmb/folder-pixmap"" for <Items> sub-entry type as it is good for displaying menus.
  • The 'attr' in the <Items> sub-entry (xmb_folder) is the same as the table key in Attibutes, so those attributes are assigned to the xmb_folder <Items> sub-entry.
  • the 'src' is pointing to 'XMB_Folder_1_container' - the another XMB .xml entry in the current .xml
  • the icon is from a .rco file and is a basic folder icon, like what the 'Game Data' XMB item uses
  • 'title' and 'info' are in plain text
  • 'child' is set as 'segment' so the XMB knows this item will subdivide into other XMB items

In order to create a working XMB sub menu the root xmb item (in this "XMB_Folder_1") must have its 'src' linking to a "container" (its the best way to think about it) and not directly linking to XMB items in the sub menu.( If you do not do this when you select your root XMB item to display a sub menu, the 'output' or 'action' of the XMB items of the sub menu will be shown rather than the actual XMB items): 

Code Sample

Important Notes:

  • This has no attributes as it simply acts as a contents container/linker

Now to create the XMB .xml entry which holds the sub menu items: 

Code Sample

Important Notes:

  • These are dummy items, they do not 'go anywhere' or perform any function. They will just print the str_noitem message when clicked because they have no function
  • notice how the <attr> from the <Items> sub entries matches the <Table keys> from the <Attributes> sub entries
  • The <Attributes> and the <Items> sub entries do not have to be in the same order to work

A Web-Site link

This type of entry could be placed on the root of the XMB category, or in an XMB Item Tree. This is also an application of the 'module-action' function. Example: 

Code Sample
  • Important Notes:
    • The 'Attributes' for this Web-Link follows the Attribute rules for a 'module-action' entry.
    • The 'webbrowser_plugin' module has been used to handle the request in the 'module_action' pair key, which is a web address
    • The 'attr' in the Items sub-entry is the same as the table key in the 'Attributes' sub-entry.
    • Remember that the icon_rsc string will search the rco file(used by the module running the category which this web link is on) for the icon 'dev_wiki_icon'. Whereas the title and info strings will just print the contents of the string.
Retrieved from "http://www.psdevwiki.com/ps3/index.php?title=XMBML_Coding&oldid=21016"