Difference between revisions of "SMDH"

From 3dbrew
Jump to navigation Jump to search
m (→‎Application Titles: Grammar fix: space before opening parenthesis)
 
(42 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 
This page describes the format of the icon stored at [[NCCH#CXI|CXI]] ExeFS:/icon and [[CIA]] icons.
 
This page describes the format of the icon stored at [[NCCH#CXI|CXI]] ExeFS:/icon and [[CIA]] icons.
−
The size of icons is 0x36c0 bytes. The CXI icon is displayed by [[Home Menu]] and [[System Settings]](3DS Software Management), while CIA icons are dummies and not yet utilised by Dev 3DS' (at rev 40909).
+
The size of icons are 0x36c0 bytes. The CXI icon is displayed by [[Home Menu]] and [[System Settings]](3DS Software Management), while [[CIA#Meta|CIA icons]] are dummies and not yet utilised by Dev 3DS' (as of rev 47586).
  
 
== Format ==
 
== Format ==
Line 15: Line 15:
 
|-  
 
|-  
 
|  0x04
 
|  0x04
−
|  0x04
+
|  0x02
 +
|  Version
 +
|-
 +
|  0x06
 +
|  0x02
 
|  Reserved
 
|  Reserved
 
|-
 
|-
 
|  0x8
 
|  0x8
−
|  0x1600
+
|  0x2000
−
|  11 application titles structs, each 0x200 bytes
+
|  16 application titles structs, each 0x200 bytes
−
|-
 
−
| 0x1608
 
−
| 0xA00
 
−
| Reserved
 
 
|-
 
|-
 
| 0x2008
 
| 0x2008
 
| 0x30
 
| 0x30
−
| Flags
+
| Application Settings
 
|-
 
|-
 
| 0x2038
 
| 0x2038
Line 61: Line 61:
  
 
All encoded in UTF-16.
 
All encoded in UTF-16.
−
There are 11 app title structs, each one for separate languages.
+
There are 16 app title structs (currently only 12 are used), each one for separate languages.
  
 
The languages by order of appearance:
 
The languages by order of appearance:
Line 71: Line 71:
 
* 5th: Italian title name
 
* 5th: Italian title name
 
* 6th: Spanish title name
 
* 6th: Spanish title name
−
* 7th: Chinese title name
+
* 7th: Simplified Chinese title name
 
* 8th: Korean title name
 
* 8th: Korean title name
 
* 9th: Dutch title name
 
* 9th: Dutch title name
 
* 10th: Portuguese title name
 
* 10th: Portuguese title name
 
* 11th: Russian title name
 
* 11th: Russian title name
 +
* 12th: Traditional Chinese title name
  
−
== Flags ==
+
== Application Settings ==
  
−
This is where the application [[Home Menu]] flags exist. It is important to note, only the Home Menu uses these flags
+
Most of these flags are only used by the [[Home Menu]]. All of these are represented in SMDH files in little endian. But when documented below, the tables represent values in big endian.
  
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
Line 88: Line 89:
 
|-
 
|-
 
|  0x2008
 
|  0x2008
−
|  0xA
+
|  0x10
 
|  Region Specific Game Ratings (For use with Parental Controls)
 
|  Region Specific Game Ratings (For use with Parental Controls)
 
|-
 
|-
 
|  0x2018
 
|  0x2018
 
|  0x4
 
|  0x4
−
|  BNR Region (Used For Region Locking)
+
|  Region Lockout
 
|-   
 
|-   
 
|  0x201C
 
|  0x201C
Line 100: Line 101:
 
|-     
 
|-     
 
|  0x2028
 
|  0x2028
−
|  0x1
+
|  0x4
−
|  Combined Flag (Various Flags)
+
|  Flags
 +
|-   
 +
|  0x202C
 +
|  0x2
 +
|  EULA Version
 +
|-   
 +
|  0x202E
 +
|  0x2
 +
|  Reserved
 
|-   
 
|-   
−
|  0x2032
+
|  0x2030
−
|  0x2
+
|  0x4
 
|  'Optimal Animation Default Frame' (for BNR)
 
|  'Optimal Animation Default Frame' (for BNR)
 
|-     
 
|-     
Line 129: Line 138:
 
|  0x1
 
|  0x1
 
|  ESRB (USA)
 
|  ESRB (USA)
 +
|-
 +
|  0x200A
 +
|  0x1
 +
|  Reserved
 
|-
 
|-
 
|  0x200B
 
|  0x200B
Line 137: Line 150:
 
|  0x1
 
|  0x1
 
|  PEGI GEN (Europe)
 
|  PEGI GEN (Europe)
 +
|-
 +
|  0x200D
 +
|  0x1
 +
|  Reserved
 
|-
 
|-
 
|  0x200E
 
|  0x200E
Line 152: Line 169:
 
|  0x2011
 
|  0x2011
 
|  0x1
 
|  0x1
−
|  Unknown/Unused
+
|  GRB (South Korea)
 +
|-
 +
|  0x2012
 +
|  0x1
 +
|  CGSRR (Taiwan)
 +
|-
 +
|  0x2013
 +
|  0x1
 +
|  Reserved
 +
|-
 +
|  0x2014
 +
|  0x1
 +
|  Reserved
 +
|-
 +
|  0x2015
 +
|  0x1
 +
|  Reserved
 +
|-
 +
|  0x2016
 +
|  0x1
 +
|  Reserved
 +
|-
 +
|  0x2017
 +
|  0x1
 +
|  Reserved
 
|}
 
|}
  
−
These flags are generated by converting the age rating to a hex value and then adding it to '80'. For example if '7 years' was the rating, then the flag would be '87'(this is a hex value). The unknown/unused rating is only has a value when the BNR is for 'All Regions'. Also if Game Ratings are not used, when selecting a region for the BNR, it generates random Game Age Ratings for all regions.
+
Active ratings have a bitmask of 0x80, and inactive ratings have no bitmask at all. Ratings without the 0x80 bitmask are ignored. 0x40 bitmask indicates Rating Pending. 0x20 bitmask indicates No Age Restriction.
 +
Age limits are set by adding the minimal age to 0x80 (for example, limiting to 12 years and up would give a bitmask of 0x8C)
  
−
=== BNR Region ===
+
=== Region Lockout ===
  
−
This flag is what the Home Menu uses in order to determine the [[Home Menu#Region Lockout|Region Lockout]] of a title.
+
This u32 flag is what the Home Menu uses to determine the [[Home Menu#Region Lockout|Region Lockout]] of a title.
  
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
 
!  REGION
 
!  REGION
−
!  VALUE
+
!  BITMASK
−
|-
 
−
|  All Regions (No region restrictions)
 
−
|  7F FF FF FF
 
 
|-
 
|-
 
|  Japan
 
|  Japan
−
|  00 00 00 01
+
|  0x01
 
|-
 
|-
 
|  North America
 
|  North America
−
|  00 00 00 02
+
|  0x02
 
|-
 
|-
 
|  Europe
 
|  Europe
−
|  00 00 00 0C
+
|  0x04
 +
|-
 +
|  Australia
 +
|  0x08
 +
|-
 +
|  China
 +
|  0x10
 
|-
 
|-
 
|  Korea
 
|  Korea
−
|  00 00 00 20
+
|  0x20
 
|-
 
|-
 
|  Taiwan  
 
|  Taiwan  
−
|  00 00 00 40
+
|  0x40
−
|-
 
−
|  China
 
−
|  00 00 00 50
 
 
|}
 
|}
 +
 +
Regions are 'included' in region lock by setting their bitmask value. Nintendo defines region free as 0x7fffffff. Early in the 3DS' development, Nintendo grouped the Australian and Europe markets together. Nintendo defines market Europe as having the combined bitmasks of Europe and Australia. No 3DS' which check the Australia bitmask have been seen (Australia uses the European 3DS model).
  
 
=== Match Maker IDs ===
 
=== Match Maker IDs ===
Line 207: Line 251:
 
|}
 
|}
  
−
For example, if the Match Maker ID was '12345678' and the Match Maker BIT ID was '1234567891234567', the flags would be '78 56 34 12' and '67 45 23 91 78 56 34 12' respectively
+
=== Flags ===
−
 
+
The u32 is used for storing flags as bit-masks.
−
=== Bit Flags ===
 
−
 
 
−
This flag has multiple flags, packed into one byte. By use of addition the flags are combined:
 
  
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
 
!  FLAG
 
!  FLAG
−
!  VALUE
+
!  BITMASK VALUE
 +
|-
 +
|  Visibility Flag (Required for visibility on the Home Menu)
 +
|  0x0001
 +
|-
 +
|  [[Home Menu#Auto-Boot_Function|Auto-boot]] this gamecard title
 +
|  0x0002
 +
|-
 +
|  Allow use of 3D? (For use with parental Controls. An application can use the 3D affect, even when this flag isn't set)
 +
|  0x0004
 
|-
 
|-
−
|  Visibility Flag (always present)
+
|  Require accepting CTR EULA before being launched by Home (see below)
−
|  01
+
|  0x0008
 
|-
 
|-
−
|  Allow use of 3D? (For use with parental Controls, it does not the affect whether the application uses 3D or not. An application can use the 3D affect, even when this flag isn't set)
+
|  Autosave on exit? (see below)
−
|  04
+
|  0x0010
 
|-
 
|-
−
|  Require accepting CTR EULA?
+
|  Uses an [[Extended Banner]]?
−
|  08
+
|  0x0020
 
|-
 
|-
−
|  Autoboot?
+
|  [[SMDH#Region Specific Game Age Ratings|Region game rating]] required
−
|  02
+
|  0x0040
 
|-
 
|-
−
|  Autosave on exit?
+
|  Uses save data? (see below)
−
|  10
+
|  0x0080
 
|-
 
|-
−
|  Uses an extended Banner?
+
|  Application usage is to be recorded. If this is not set, it causes the application's usage to be omitted from the Home Menu's [[Home_Menu#Cache.dat & CacheD.dat|icon cache]], as well as in [[????????|other places]].
−
|  20
+
|  0x0100
 
|-
 
|-
−
|  Region game rating required?
+
|  Disables [[SD Savedata Backups]] for this title. This is in addition to [[NS CFA|the blacklist]].
−
|  40
+
|  0x0400
 
|-
 
|-
−
|  Uses save data?
+
|  New 3DS exclusive title. Shows an error if used on Old 3DS.
−
|  80
+
|  0x1000
 
|}
 
|}
−
 
−
For example, if we wanted an application to use the 3D effect, autosave on exit and use save data. The combined flag would be '95' (01+04+10+80) (This is a hex value)
 
  
−
=== 'Optimal Animation Default Frame' (for BNR) ===
+
====Effect of SaveData and AutoSave====
 +
 
 +
These options have no effect on the performance of the application itself: they're used to select an appropriate warning when closing an application from [[Home Menu|Home]].
 +
 
 +
* Both off: "Closing software" (no warning if quitting directly with X)
 +
* SaveData: "Do you want to close [...]? (Unsaved data will be lost.)"
 +
* AutoSave: ?
 +
* Both on:  "Saving data and closing software..." (no warning if quitting directly with X)
  
−
Purpose of this flag: If using an animated BNR, it's the most representative frame for the animation.
+
=== EULA Version ===
 +
This is the EULA version which is checked when the Accept EULA flag is set, the version is compared to one stored in the 3DS. If the SMDH version is greater, then the user will be prompted to accept the EULA.
  
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
−
!  OPTIMAL ANIMATION DEFAULT FRAME
+
!  START
−
!  VALUE
+
!  SIZE
−
|-
+
! DESCRIPTION
−
|  0
 
−
|  00 00
 
−
|-
 
−
|  1
 
−
|  3F 80
 
−
|-
 
−
|  2
 
−
|  40 00
 
−
|-
 
−
|  3
 
−
|  40 40
 
−
|-
 
−
|  4
 
−
| 40 80
 
 
|-
 
|-
−
|  5
+
|  0x202C
−
|  40 A0
+
|  0x01
 +
|  EULA Version Minor
 
|-
 
|-
−
|  6
+
|  0x202D
−
|  40 C0
+
|  0x01
 +
|  EULA Version Major
 
|}
 
|}
  
−
Flag Pattern: ???
+
=== 'Optimal Animation Default Frame' (for BNR) ===
 +
 
 +
This is a float, indicating the preferred (or 'most representative') frame for the banner animation.
  
 
=== CEC (StreetPass) ID ===
 
=== CEC (StreetPass) ID ===
  
−
With a size of 4 bytes this represents the applications CEC ID. For example if the ID was '12345678' the flag would be '78 56 34 12'
+
This u32 represents the application CEC ID. This is likely loaded by applications for use with the CEC services as well.
  
 
== Icon graphics ==
 
== Icon graphics ==
Line 316: Line 362:
 
* ETC1A4
 
* ETC1A4
  
−
This does not necessarily mean the other encodings will be used, it is just that those are the options when compiling. Like we've seen with Super Mario 3D Land Nintendo has changed save file encryption, and likewise they can encode icons and banners differently ''should they choose to''. Currently we've seen just RGB565 so don't be fooled if an icon doesn't show up right! It is probably one of these formats above. Although we will probably not see other formats used for a while it's nice to know they have an opportunity to change.
+
This does not necessarily mean the other encodings will be used, it is just that those are the options when compiling. Like we've seen with Super Mario 3D Land Nintendo has changed save file encryption, and likewise they can encode icons and banners differently ''should they choose to''. Currently we've seen just RGB565 so don't be fooled if an icon doesn't show up right! It is probably one of these formats above. Although we will probably not see other formats used for a while it's nice to know they have an opportunity to change. Also note that it seems Nintendo stores each pixel in [https://en.wikipedia.org/wiki/RGBA_color_space word-order], so the actual order of order of each color channel in memory will depend on the endianness.  
−
 
 
−
There's a header of 0x40 bytes and then comes the raw data.
 
  
 
The data is encoded in tiles (starting from size 8x8, continuing recursively).
 
The data is encoded in tiles (starting from size 8x8, continuing recursively).
Line 379: Line 423:
 
|-
 
|-
 
|}
 
|}
 +
 +
== Tools ==
 +
 +
[[CiTRUS]] - (GUI)(Windows Only) Generating ICN files
 +
 +
[[3DSExplorer]] - (GUI)(Windows Only) Parsing ICN files

Latest revision as of 09:35, 31 December 2019

This page describes the format of the icon stored at CXI ExeFS:/icon and CIA icons. The size of icons are 0x36c0 bytes. The CXI icon is displayed by Home Menu and System Settings(3DS Software Management), while CIA icons are dummies and not yet utilised by Dev 3DS' (as of rev 47586).

Format[edit]

OFFSET SIZE DESCRIPTION
0x00 0x04 Magic 'SMDH'
0x04 0x02 Version
0x06 0x02 Reserved
0x8 0x2000 16 application titles structs, each 0x200 bytes
0x2008 0x30 Application Settings
0x2038 0x8 Reserved
0x2040 0x1680 Icon graphics

Application Titles[edit]

START SIZE DESCRIPTION
0x00 0x80 Short Description
0x80 0x100 Long Description
0x180 0x80 Publisher

All encoded in UTF-16. There are 16 app title structs (currently only 12 are used), each one for separate languages.

The languages by order of appearance:

  • 1st: Japanese title name
  • 2nd: English title name
  • 3rd: French title name
  • 4th: German title name
  • 5th: Italian title name
  • 6th: Spanish title name
  • 7th: Simplified Chinese title name
  • 8th: Korean title name
  • 9th: Dutch title name
  • 10th: Portuguese title name
  • 11th: Russian title name
  • 12th: Traditional Chinese title name

Application Settings[edit]

Most of these flags are only used by the Home Menu. All of these are represented in SMDH files in little endian. But when documented below, the tables represent values in big endian.

START SIZE DESCRIPTION
0x2008 0x10 Region Specific Game Ratings (For use with Parental Controls)
0x2018 0x4 Region Lockout
0x201C 0xC Match Maker IDs (Online Play)
0x2028 0x4 Flags
0x202C 0x2 EULA Version
0x202E 0x2 Reserved
0x2030 0x4 'Optimal Animation Default Frame' (for BNR)
0x2034 0x4 CEC (StreetPass) ID (So the Home Menu knows which application icon to show the 'Green' CEC notification for)

Region Specific Game Age Ratings[edit]

These flags tell the 3DS the 'Age Rating' of the software for the below regions:

START SIZE DESCRIPTION
0x2008 0x1 CERO (Japan)
0x2009 0x1 ESRB (USA)
0x200A 0x1 Reserved
0x200B 0x1 USK (German)
0x200C 0x1 PEGI GEN (Europe)
0x200D 0x1 Reserved
0x200E 0x1 PEGI PRT (Portugal)
0x200F 0x1 PEGI BBFC (England)
0x2010 0x1 COB (Australia)
0x2011 0x1 GRB (South Korea)
0x2012 0x1 CGSRR (Taiwan)
0x2013 0x1 Reserved
0x2014 0x1 Reserved
0x2015 0x1 Reserved
0x2016 0x1 Reserved
0x2017 0x1 Reserved

Active ratings have a bitmask of 0x80, and inactive ratings have no bitmask at all. Ratings without the 0x80 bitmask are ignored. 0x40 bitmask indicates Rating Pending. 0x20 bitmask indicates No Age Restriction. Age limits are set by adding the minimal age to 0x80 (for example, limiting to 12 years and up would give a bitmask of 0x8C)

Region Lockout[edit]

This u32 flag is what the Home Menu uses to determine the Region Lockout of a title.

REGION BITMASK
Japan 0x01
North America 0x02
Europe 0x04
Australia 0x08
China 0x10
Korea 0x20
Taiwan 0x40

Regions are 'included' in region lock by setting their bitmask value. Nintendo defines region free as 0x7fffffff. Early in the 3DS' development, Nintendo grouped the Australian and Europe markets together. Nintendo defines market Europe as having the combined bitmasks of Europe and Australia. No 3DS' which check the Australia bitmask have been seen (Australia uses the European 3DS model).

Match Maker IDs[edit]

These IDs are an application's online gaming IDs.

START SIZE DESCRIPTION
0x201C 0x4 Match Maker ID
0x2020 0x8 Match Maker BIT ID

Flags[edit]

The u32 is used for storing flags as bit-masks.

FLAG BITMASK VALUE
Visibility Flag (Required for visibility on the Home Menu) 0x0001
Auto-boot this gamecard title 0x0002
Allow use of 3D? (For use with parental Controls. An application can use the 3D affect, even when this flag isn't set) 0x0004
Require accepting CTR EULA before being launched by Home (see below) 0x0008
Autosave on exit? (see below) 0x0010
Uses an Extended Banner? 0x0020
Region game rating required 0x0040
Uses save data? (see below) 0x0080
Application usage is to be recorded. If this is not set, it causes the application's usage to be omitted from the Home Menu's icon cache, as well as in other places. 0x0100
Disables SD Savedata Backups for this title. This is in addition to the blacklist. 0x0400
New 3DS exclusive title. Shows an error if used on Old 3DS. 0x1000

Effect of SaveData and AutoSave[edit]

These options have no effect on the performance of the application itself: they're used to select an appropriate warning when closing an application from Home.

  • Both off: "Closing software" (no warning if quitting directly with X)
  • SaveData: "Do you want to close [...]? (Unsaved data will be lost.)"
  • AutoSave: ?
  • Both on: "Saving data and closing software..." (no warning if quitting directly with X)

EULA Version[edit]

This is the EULA version which is checked when the Accept EULA flag is set, the version is compared to one stored in the 3DS. If the SMDH version is greater, then the user will be prompted to accept the EULA.

START SIZE DESCRIPTION
0x202C 0x01 EULA Version Minor
0x202D 0x01 EULA Version Major

'Optimal Animation Default Frame' (for BNR)[edit]

This is a float, indicating the preferred (or 'most representative') frame for the banner animation.

CEC (StreetPass) ID[edit]

This u32 represents the application CEC ID. This is likely loaded by applications for use with the CEC services as well.

Icon graphics[edit]

At offset 0x2040, there are two icons:

START SIZE DESCRIPTION
0x2040 0x480 Small - 24x24 (shown on top screen when pausing the app)
0x24C0 0x1200 Large - 48x48 icon (the general icon)

Both of the icons are encoded in RGB565 meaning 16bpp. Although both icons are known to be RGB565, developers have the option of encoding icons (and banners) with the following encodings :

  • RGBA8
  • RGB8
  • RGBA5551
  • RGB565
  • RGBA4
  • LA8
  • HILO8
  • L8
  • A8
  • LA4
  • L4
  • ETC1
  • ETC1A4

This does not necessarily mean the other encodings will be used, it is just that those are the options when compiling. Like we've seen with Super Mario 3D Land Nintendo has changed save file encryption, and likewise they can encode icons and banners differently should they choose to. Currently we've seen just RGB565 so don't be fooled if an icon doesn't show up right! It is probably one of these formats above. Although we will probably not see other formats used for a while it's nice to know they have an opportunity to change. Also note that it seems Nintendo stores each pixel in word-order, so the actual order of order of each color channel in memory will depend on the endianness.

The data is encoded in tiles (starting from size 8x8, continuing recursively).

If the buffer is like this:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

Then the image would look like this:

x=0 x=1 x=2 x=3 x=4
0 1 4 5 16
2 3 6 7 ...
8 9 12 13
10 11 14 15

Tools[edit]

CiTRUS - (GUI)(Windows Only) Generating ICN files

3DSExplorer - (GUI)(Windows Only) Parsing ICN files

Retrieved from "https://www.3dbrew.org/w/index.php?title=SMDH&oldid=21139"