XMBML Coding

From PS3 Developer wiki
Revision as of 02:11, 7 August 2012 by Ps3hen (talk | contribs)
Jump to navigation Jump to search

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


Basic Structure

Every XMB .xml configuration file starts with this header: 

<?xml version="1.0" encoding="UTF-8"?>
<XMBML version="1.0">

And has at least one 'entry' which follows this format: 

	<View id="Entry_1">
		<Attributes>
			<Table key="item_1">
				<Pair key="pair_key1"><String>a valid entry for this pair key</String></Pair>
				<Pair key="pair_key2"><String>a valid entry for this pair key</String></Pair>
				<Pair key="pair_key3"><String>a valid entry for this pair key</String></Pair>
				<Pair key="pair_key4"><String>a valid entry for this pair key</String></Pair>
			</Table>
		</Attributes>
		<Items>
			<Query class="item_1_class" key="item_1" attr="item_1" src="#Entry_1_contents" />
		</Items>
	</View>

<View id=""> - this is so the entry can be identified from within the .xml by the PS3. The id must consist of UTF-8 characters and have no spaces. There must be no other entries with the same View id.

Within a entry there are two sub groups "<Attributes>" and "<Items>".

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

<Attributes> - this provides additional information about the <Items> sub-entries. For each <Items> sub-entry there can(not all <Items> sub-entries requires attributes) be attributes assigned, each in its own table with an 'key' matching the <Items> sub-entry. The number of attribute sub-entries within a table varies depending on the <Items> sub-entry.


Creating XMB .xml Entries

<Items> sub-entries

When creating an XMB entries, you must tell the PS3 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 what kind of entry this XMB entry is in the form of either "<Query class=""" or "<Item class=""". There are many acceptable values possible here but only 3 have more than one theoretical use:

  • <Query class="type:x-xmb/folder-pixmap"
  • <Item class="type:x-xmb/module-action"
  • <Query class="type:x-xmb/xmlpackagefolder"

A table of the above types of <Items> sub-entries and what sections of a <Items> sub-entry they can/must use:

Entry Identification "key=""" required ? "attr=""" required ? "src=""" required ? Attributes Required ? Remarks
<Query class="type:x-xmb/folder-pixmap" Yes Opt Yes Opt Has many uses see here
<Item class="type:x-xmb/module-action" Yes Yes No Yes Uses a particular module to support the XMB item, see Module-Action below
<Query class="type:x-xmb/xmlpackagefolder" Yes Opt Yes Yes Used for installing package files

A table explaining the possible 'sections' to <Items> sub-entries and some acceptable uses of such:

<Items> sub-entry 'section' Use Example(s) Remarks
key Used to identify the sub-entry which can also be used link attributes(see below) "gamedata" -
attr ? "gamedata" generally the same value as 'key'
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 :"#seg_package_files".
* Refer to another XMB entry inside another xml file :"xmb://localhost/dev_flash/vsh/resource/explore/xmb/category_game_tool2.xml#seg_package_files".
* Utilise a XMB database function:"xcb://localhost/query?sort=+Game:Common.titleForSort&cond=AGL+Game:Game.titleId BC0000000 BCZZZZZZZ+OGL+Game:Game.titleId BL0000000 BLZZZZZZZ+OGL+Game:Game.titleId NP0000000 NPZZZZZZZ+OGL+Game:Game.titleId SC0000000 SCZZZZZZZ+An+Game:Game.titleId BLES01337+An+Game:Game.titleId BLES80608+An+Game:Game.titleId BLES80610+An+Game:Game.titleId BLES80611+An+Game:Game.titleId BLES80607+An+Game:Game.titleId NPXS00006+An+Game:Game.titleId BLES01059+An+Game:Game.category 2D+An+Game:Game.category BV+An+Game:Game.category GD+An+Game:Game.category HM+An+Game:Game.category SD+An+Game:Game.category VF+An+Game:Game.category WT"		 XMB database function was taken from the XMBM+.



<Attributes>

A table of usable attributes and what <Items> sub-entries they can be used with:

Attribute Use Used by type:x-xmb/folder-pixmap Used by type:x-xmb/module-action Used by type:x-xmb/xmlpackagefolder Example(s)
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. 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


Module-Action

This is acts like a module (SPRX) intercom, allowing XML files to use/send commands to select modules. The list of 'useable' modules is indexed in the xmb_plugin.sprx and contains a Module Reference and the path to the module .sprx file and associated .rco file for each module. The the list of 'useable' modules for 3.55 CEX:

Module Reference Associated .rco Filepath Module Filepath Known Use
playlist_plugin /dev_flash/vsh/resource/playlist_plugin.rco /dev_flash/vsh/module/playlist_plugin.sprx
scenefolder_plugin /dev_flash/vsh/resource/scenefolder_plugin.rco /dev_flash/vsh/module/scenefolder_plugin.sprx
system_plugin N/A N/A
xmb_plugin N/A N/A
explore_plugin /dev_flash/vsh/resource/explore_plugin_full.rco /dev_flash/vsh/module/explore_plugin.sprx Used to stub XMB items in Kiosk(SEX/Shop) Firmware
game_plugin /dev_flash/vsh/resource/game_plugin.rco /dev_flash/vsh/module/basic_plugins.sprx
np_trophy_ingame /dev_flash/vsh/resource/np_trophy_ingame.rco /dev_flash/vsh/module/np_trophy_ingame.sprx
gamedata_plugin /dev_flash/vsh/resource/gamedata_plugin.rco /dev_flash/vsh/module/gamedata_plugin.sprx
game_ext_plugin /dev_flash/vsh/resource/gamedata_plugin.rco /dev_flash/vsh/module/game_ext_plugin.sprx
premo_plugin /dev_flash/vsh/resource/premo_plugin.rco /dev_flash/vsh/module/premo_plugin.sprx
micon_lock_plugin N/A /dev_flash/vsh/module/micon_lock_plugin.sprx
category_setting_plugin /dev_flash/vsh/resource/category_setting_plugin.rco /dev_flash/vsh/module/category_setting_plugin.sprx
sysconf_plugin /dev_flash/vsh/resource/sysconf_plugin.rco /dev_flash/vsh/module/sysconf_plugin.sprx
netconf_plugin /dev_flash/vsh/resource/netconf_plugin.rco /dev_flash/vsh/module/netconf_plugin.sprx
software_update_plugin /dev_flash/vsh/resource/software_update_plugin.rco /dev_flash/vsh/module/software_update_plugin.sprx
bdp_plugin /dev_flash/vsh/resource/bdp_plugin.rco /dev_flash/vsh/module/bdp_plugin.sprx
bdp_disccheck_plugin /dev_flash/vsh/resource/bdp_disccheck_plugin.rco /dev_flash/vsh/module/bdp_disccheck_plugin.sprx
bdp_storage_plugin /dev_flash/vsh/resource/bdp_storage_plugin.rco /dev_flash/vsh/module/bdp_storage_plugin.sprx
user_plugin /dev_flash/vsh/resource/user_plugin.rco /dev_flash/vsh/module/user_plugin.sprx
friendim_plugin N/A /dev_flash/vsh/module/friendim_plugin.sprx
friendml_plugin /dev_flash/vsh/resource/friendml_plugin.rco /dev_flash/vsh/module/friendml_plugin.sprx
friendtrophy_plugin /dev_flash/vsh/resource/friendtrophy_plugin.rco /dev_flash/vsh/module/friendtrophy_plugin.sprx
profile_plugin /dev_flash/vsh/resource/profile_plugin.rco /dev_flash/vsh/module/profile_plugin.sprx
photoviewer_plugin /dev_flash/vsh/resource/photoviewer_plugin.rco /dev_flash/vsh/module/photoviewer_plugin.sprx
videoplayer_plugin /dev_flash/vsh/resource/videoplayer_plugin.rco /dev_flash/vsh/module/videoplayer_plugin.sprx
webbrowser_plugin /dev_flash/vsh/resource/webbrowser_plugin.rco /dev_flash/vsh/module/webbrowser_plugin.sprx Can be used to link to webpages
webrender_plugin /dev_flash/vsh/resource/webrender_plugin.rco /dev_flash/vsh/module/webrender_plugin.sprx
xai_plugin /dev_flash/vsh/resource/xai_plugin.rco /dev_flash/vsh/module/xai_plugin.sprx
audioplayer_plugin /dev_flash/vsh/resource/audioplayer_plugin.rco /dev_flash/vsh/module/audioplayer_plugin.sprx
videodownloader_plugin /dev_flash/vsh/resource/videodownloader_plugin.rco /dev_flash/vsh/module/videodownloader_plugin.sprx
nas_plugin /dev_flash/vsh/resource/nas_plugin.rco /dev_flash/vsh/module/nas_plugin.sprx
download_plugin /dev_flash/vsh/resource/download_plugin.rco /dev_flash/vsh/module/download_plugin.sprx
ps3_savedata_plugin /dev_flash/vsh/resource/ps3_savedata_plugin.rco /dev_flash/vsh/module/ps3_savedata_plugin.sprx
vmc_savedata_plugin /dev_flash/vsh/resource/vmc_savedata_plugin.rco. /dev_flash/vsh/module/vmc_savedata_plugin.sprx
thumthum_plugin /dev_flash/vsh/resource/thumthum_plugin.rco /dev_flash/vsh/module/thumthum_plugin.sprx
npsignin_plugin /dev_flash/vsh/resource/npsignin_plugin.rco /dev_flash/vsh/module/npsignin_plugin.sprx
avc_plugin /dev_flash/vsh/resource/avc_plugin.rco /dev_flash/vsh/module/avc_plugin.sprx
avc2_text_plugin /dev_flash/vsh/resource/avc2_text_plugin.rco /dev_flash/vsh/module/avc2_text_plugin.sprx
sacd_plugin /dev_flash/vsh/resource/sacd_plugin.rco /dev_flash/vsh/module/sacd_plugin.sprx
eula_cddb_plugin /dev_flash/vsh/resource/eula_cddb_plugin.rco /dev_flash/vsh/module/eula_cddb_plugin.sprx
strviewer_plugin /dev_flash/vsh/resource/strviewer_plugin.rco. /dev_flash/vsh/module/strviewer_plugin.sprx
edy_plugin /dev_flash/vsh/resource/edy_plugin.rco /dev_flash/vsh/module/edy_plugin.sprx
print_plugin /dev_flash/vsh/resource/print_plugin.rco /dev_flash/vsh/module/print_plugin.sprx
newstore_plugin /dev_flash/vsh/resource/newstore_plugin.rco /dev_flash/vsh/module/newstore_plugin.sprx
deviceconf_plugin /dev_flash/vsh/resource/deviceconf_plugin.rco /dev_flash/vsh/module/deviceconf_plugin.sprx
dlna_plugin /dev_flash/vsh/resource/dlna_plugin.rco /dev_flash/vsh/module/dlna_plugin.sprx
np_trophy_plugin /dev_flash/vsh/resource/np_trophy_plugin.rco /dev_flash/vsh/module/np_trophy_plugin.sprx
kensaku_plugin /dev_flash/vsh/resource/kensaku_plugin.rco /dev_flash/vsh/module/kensaku_plugin.sprx
regcam_plugin /dev_flash/vsh/resource/regcam_plugin.rco /dev_flash/vsh/module/regcam_plugin.sprx
idle_plugin /dev_flash/vsh/resource/idle_plugin.rco /dev_flash/vsh/module/idle_plugin.sprx
filecopy_plugin /dev_flash/vsh/resource/filecopy_plugin.rco /dev_flash/vsh/module/filecopy_plugin.sprx
wboard_plugin /dev_flash/vsh/resource/wboard_plugin.rco /dev_flash/vsh/module/wboard_plugin.sprx
checker_plugin /dev_flash/vsh/resource/checker_plugin.rco /dev_flash/vsh/module/checker_plugin.sprx
hknw_plugin /dev_flash/vsh/resource/hknw_plugin.rco /dev_flash/vsh/module/hknw_plugin.sprx
poweroff_plugin /dev_flash/vsh/resource/poweroff_plugin.rco /dev_flash/vsh/module/poweroff_plugin.sprx
eula_hcopy_plugin /dev_flash/vsh/resource/eula_hcopy_plugin.rco /dev_flash/vsh/module/eula_hcopy_plugin.sprx
videoeditor_plugin /dev_flash/vsh/resource/videoeditor_plugin.rco /dev_flash/vsh/module/videoeditor_plugin.sprx


Worked 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 

<View id="XMB_Folder_1">
		<Attributes>
			<Table key="xmb_folder">
				<Pair key="icon_rsc"><String>tex_album_icon</String></Pair>
				<Pair key="title"><String>XMB Menu Item</String></Pair>
				<Pair key="info"><String>This will subdivide into 3 items :)</String></Pair>
				<Pair key="child"><String>segment</String></Pair>
			</Table>
		</Attributes>
		<Items>
			<Query class="type:x-xmb/folder-pixmap"  key="xmb_folder" attr="xmb_folder" src="#XMB_Folder_1_items" />
		</Items>
	</View>

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 'key' 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_items' - 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 contents linker(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): 

<View id="XMB_Folder_1_items">
		<Items>
			<Query class="type:x-xmb/folder-pixmap"  key="xmb_folder" attr="xmb_folder" src="#XMB_Folder_1_contents" />
		</Items>
	</View>

Important Notes:

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

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

<View id="XMB_Folder_1_contents">
		<Attributes>
			<Table key="xmb_subitem_1">
				<Pair key="icon_rsc"><String>tex_album_icon</String></Pair>
				<Pair key="title"><String>XMB Sub Menu Item</String></Pair>
				<Pair key="info"><String>Dummy Sub item 1</String></Pair>
				<Pair key="str_noitem"><String>msg_error_no_gamedata</String></Pair>
			</Table>
			<Table key="xmb_subitem_2">
				<Pair key="icon_rsc"><String>tex_album_icon</String></Pair>
				<Pair key="title"><String>XMB Sub Menu Item</String></Pair>
				<Pair key="info"><String>Dummy Sub item 2</String></Pair>
				<Pair key="str_noitem"><String>msg_error_no_gamedata</String></Pair>
			</Table>
			<Table key="xmb_subitem_3">
				<Pair key="icon_rsc"><String>tex_album_icon</String></Pair>
				<Pair key="title"><String>XMB Sub Menu Item</String></Pair>
				<Pair key="info"><String>Dummy Sub item 3</String></Pair>
				<Pair key="str_noitem"><String>msg_error_no_gamedata</String></Pair>
			</Table>
		</Attributes>
		<Items>
			<Query class="type:x-xmb/folder-pixmap"  key="xmb_subitem_1" attr="xmb_subitem_1" />
			<Query class="type:x-xmb/folder-pixmap"  key="xmb_subitem_2" attr="xmb_subitem_2" />
			<Query class="type:x-xmb/folder-pixmap"  key="xmb_subitem_3" attr="xmb_subitem_3" />
		</Items>
	</View>

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 keys from the <Items> sub entries match 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, they just have to have their 'key' in common

A web 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'. It's quite self-explanatory. Example: 

		<View id="seg_links_ps3scene">
			<Attributes>
				<Table key="google">
					<Pair key="icon_rsc"><String>google_icon</String></Pair>
					<Pair key="title"><String>Google</String></Pair>
					<Pair key="info"><String>A really cool webpage</String></Pair>
					<Pair key="module_name"><String>webbrowser_plugin</String></Pair>
					<Pair key="module_action"><String>http://www.google.com/</String></Pair>
  				</Table>
			</Attributes>
			<Items>
				<Item class="type:x-xmb/module-action" key="google" attr="google"/>
			</Items>
		</View>
Retrieved from "http://www.psdevwiki.com/ps3/index.php?title=XMBML_Coding&oldid=12947"