Skip to content

CtrBootManager setup

Jump to bottom Edit New page
OperationNT414C edited this page Jun 7, 2017 · 34 revisions

CtrBootManager needs a configuration file to be customized. The configuration file must be at following path:

  • SDCardRoot:/boot.cfg for CtrBootManager.3dsx (3DSX version)
  • SDCardRoot:/a9lh.cfg for CtrBootManager9.bin or CtrBootManager9.firm started from SD card (A9LH/B9S version)
  • SysNANDRoot:/CtrBootManager.cfg for CtrBootManager9.firm started from SysNAND (B9S version)

This configuration file is a ".ini" document style. So the syntax of this file must look like this:

[category1]
property1=value1;
property2=value2;

[category2]
property3=value3;

Currently, CtrBootManager reads the following categories:

  • [general] : generic boot parameters
  • [password] : password settings
  • [theme] : background, menu and text default colors
  • [animation] : animations for background, menu and text colors
  • [topMovie] and [bottomMovie] : setup for top/bottom screen movies
  • [top3DMovie] : setup for top screen right eye movie (only for 3DSX version, activates 3D mode)
  • [entry] : list of possible boot entries (first opened menu)

A lot of properties are file pathes. File pathes must start with one of the following prefix:

  • "sdmc:/" for a file on SD card
  • "nand:/" for a file on SysNAND (only for A9LH/B9S version)
  • "/" for a file on the same drive as CtrBootManager was booted from

General category properties

[general]
timeout=-1;
recovery=3;
default=3;
autobootfix=8;
screeninit=0;
brightness=4;
splashTop=/directory/image_RGB_400x240.bin;
splashBot=/directory/image_RGB_320x240.bin;

Those properties are integer values:

  • "default" : the entry index which will be selected on CtrBootManager start
  • "timeout" : the time in seconds before automatic boot on default entry if no key is pressed
    • "-1" means disable the timer
    • "0" means instantaneous boot on default entry (see "recovery" key)
  • "recovery" : key to stop instantaneous automatic boot
    • "0" is the A button
    • "1" is the B button
    • "2" is the Select button
    • "3" is the Start button
    • "4" is the Right direction
    • "5" is the Left direction
    • "6" is the Up direction
    • "7" is the Down direction
    • "8" is the Right trigger
    • "9" is the Left trigger
    • "10" is the X button
    • "11" is the Y button
  • "autobootfix" (only for 3DSX version) : the number of frames wait before automatic boot (it can avoid some instabilities)
  • "screeninit" (only for A9LH/B9S version) : screen initialization for direct chainloading
    • This is only used when "timeout" is set to "0" and the recovery key is not pressed on CtrBootManager start
    • "0" means that the screen will not be initialized on direct chainloading
    • WARNING: If the chainloaded binary doesn't make any screen initalization, enabling this feature will make it crash!
  • "brightness" (only for A9LH/B9S version) : the screen initialization brightness
    • Only 4 brightness levels are supported (values from 0 to 3)
    • Not used if the screen is already initialized on CtrBootManager start

Those properies are strings:

  • "splashTop" : default splash image on top screen when an entry is loaded
    • If this property is not set, the screen will stay on its last rendered image
    • "splashTop=clear;" will clear the screen (full black color)
  • "splashBot" : default splash image on bottom screen when an entry is loaded
    • If this property is not set, the screen will stay on its last rendered image
    • "splashBot=clear;" will clear the screen (full black color)

Password category properties

[password]
keys=0:1:2:3:4:5:6:7:8:9:10:11:0;
attempts=3;
failPath=/CustomProgramPath.bin;
failOffset=0;
failImgTop=/directory/image_RGB_400x240.bin;
failImgBot=/directory/image_RGB_320x240.bin;
  • "keys" : list of the password keys (maximum of 16 keys supported)
    • "0" is the A button
    • "1" is the B button
    • "2" is the Select button
    • "3" is the Start button
    • "4" is the Right direction
    • "5" is the Left direction
    • "6" is the Up direction
    • "7" is the Down direction
    • "8" is the Right trigger
    • "9" is the Left trigger
    • "10" is the X button
    • "11" is the Y button
  • "attempts" : the maximum autorized attempts
    • "0" means infinite attempts (never fallback)
    • If all attempts were wrong, the password check is considered as failed and we enter in the fallback
  • "failPath" : password fallback path
    • It should be a ".dat", ".bin" or ".firm" file for A9LH/B9S
    • ".firm" files are only supported by A9LH/B9S version
    • ".3dsx" files are only supported by 3DSX version
    • If this property is empty or not set, the console will freeze using the splash screen configuration
    • If this property is set to "shutdown", the console will be powered off
    • If this property is set to "reboot", the console will be rebooted
    • If this property is set to "homemenu", the console will return to home menu (3DSX version only)
  • "failOffset" : entry point offset (in hexadecimal value) used if password fallback path points out an existing binary file
    • For ".3dsx", ".firm" and most ".bin" binary files, it should be "0"
    • For most ".dat" binary files, it should be "12000"
  • "failImgTop" : splash image on top screen on password fallback
    • If this property is not set, the screen will stay on its last rendered image
    • "failImgTop=clear;" will clear the screen (full black color)
  • "failImgBot" : splash image on bottom screen on password fallback
    • If this property is not set, the screen will stay on its last rendered image
    • "failImgBot=clear;" will clear the screen (full black color)

If there is a default boot setup in the "[general]" category, the password will only be asked when:

  • The recovery key is pressed if "timeout" property is 0
  • Any key is pressed if "timeout" property is strictly positive

Theme category properties

[theme]
bgTop1=000000;
bgTop2=000000;
bgBottom=000000;
highlight=FF00004F;
borders=C9FFFCBF;
font1=C9FFFCBF;
font2=C9FFFC;
font3=C9FFFC;
bgImgTop=/directory/image_RGB_400x240.bin;
bgImgTopAlpha=no;
bgImgBot=/directory/image_RGBA_320x240.bin;
bgImgBotAlpha=yes;
bgImgTop3D=/directory/image_RGB_400x240_RightSide.bin;
bgImgTop3DAlpha=no;
  • "bgTop1" : RGB color on top screen (gradient bottom)
  • "bgTop2" : RGB color on top screen (gradient top)
  • "bgBottom" : RGB color on bottom screen
  • "highlight" : RGBA color for selection rectangle
  • "borders" : RGBA color for border lines
  • "font1" : RGBA color for all texts execpt the one under selection
  • "font2" : RGBA color for text under selection
  • "font3" : RGBA color for texts on the bottom screen (if not defined, "font1" color is used for botoom screen texts)
  • "bgImgTop" : path to an image for top screen
    • It hides impact of "bgTop1" and "bgTop2" properties if there is no "bgImgTopFadeIn" property
    • The given image must have a resolution of 400x240 (its size must be 288000 bytes for RGB format and 384000 for RGBA)
  • "bgImgTopAlpha" : defines if "bgImgTop" is in RGBA format ("true", "yes" or a not null value for RGBA)
  • "bgImgBot" : path to an image for bottom screen
    • It hides impact of "bgBottom" property if there is no "bgImgBotFadeIn" property
    • The given image must have a resolution of 320x240 (its size must be 230400 bytes for RGB format and 307200 for RGBA)
  • "bgImgBotAlpha" : defines if "bgImgBot" is in RGBA format ("true", "yes" or a not null value for RGBA)
  • "bgImgTop3D" : path to an image for top screen (only for 3DSX version)
    • Having this property active with a valid image will activate 3D display
    • The given image must correspond to the right eye view ("bgImgTop" will be considered as the left eye view)
    • It hides impact of "bgTop1" and "bgTop2" properties for the right eye if there is no "bgImgTopFadeIn" property
    • The given image must have a resolution of 400x240 (its size must be 288000 bytes for RGB format and 384000 for RGBA)
  • "bgImgTop3DAlpha" : defines if "bgImgTop3D" is in RGBA format ("true", "yes" or a not null value for RGBA)

Colors are in hexadecimal form. For each color channel, 00 is the minimum and FF is the maximum (which represents 255 in decimal value).

RGB colors take the following form: "XXYYZZ"

  • XX is the red color
  • YY is the blue color
  • ZZ is the green color You can use the following page to visualize a color: http://www.colorpicker.com/

RGBA colors take the following form: "XXYYZZAA"

  • XX is the red color
  • YY is the blue color
  • ZZ is the green color
  • AA is the transparency
    • 00 means you won't see the object
    • FF means the object is fully opaque (nothing behind it is seen) You can replace an RGBA color with an RGB color, in that case "AA" will be at maximum value (fully opaque).

For images, you can use this web tool to convert most files: https://xem.github.io/3DShomebrew/tools/image-to-bin.html

If your image has an alpha channel, you must check "preserve transparency" box on the given page and set the "bgImgXXXAlpha" property to indicate the RGBA format.

Animation category properties

[animation]
bgTop1=30:0:FF0000;
bgTop2=30:15:0000FF;
bgBottom=20:0:00FF00;
highlight=12:0:FF0000AF;
borders=30:0:C9FFFCBF;
font1=12:0:FFFFFFFF;
font2=12:0:FFFFFF;
font3=12:0:FFFFFF;
menuFadeIn=20:10;
bgImgTopFadeIn=0:20;
bgImgBotFadeIn=0:20;

WARNING: Most animation properties have the same name as theme properties, so category is essential to avoid any confusion!

For properties which have the same name as properties inside the theme category, the syntax takes the following form: "X:Y:COLOR"

  • COLOR is the animation target color (it can be an RGB or RGBA color, depending on which theme property it animates)
  • X is a positive integer which represents the duration in frames for go from the original theme color to the target color
  • Y is an integer which adds an offset (if 2 animated properties have the same duration but you wish them to be desynchronized) A complete animation loop for a property is 2 times "X" (for a round-trip).

The only properties which don't have a common name with a theme category property are "menuFadeIn", "bgImgTopFadeIn" and "bgImgBotFadeIn". The "menuFadeIn" property allow to hide all menu elements (texts, selection rectangle, thumbnails and borders) during a given time, then they fully appear in another given time. The "bgImgTopFadeIn"/"bgImgBotFadeIn" allow to hide the top/bottom screen background images during a given time, then the images fully appear in another given time. Those properties follow this syntax: "X:Y"

  • X is the time in frames where the elements stay hidden
  • Y is the time in frame for elements apparition with full opacity So elements take "X"+"Y" frames to appear with their maximum opacity.

Movies categories properties

[topMovie]
path=/anim/0/anim;
compression=QuickLZ;
loopCount=infinite;
loopStreamType=compressed_memory;
loopReverse=yes;
loopStartFrame=10;
delayOnLoopStart=5;
loopEndFrame=30;
delayOnLoopEnd=5;

[bottomMovie]
path=/anim/0/bottom_anim;
compression=0;
loopCount=5;
loopStreamType=memory;
loopReverse=no;
loopStartFrame=0;
loopEndFrame=-1;

[top3DMovie]
path=/anim/0/anim_RightSide;
compression=QuickLZ;
loopCount=infinite;
loopStreamType=compressed_memory;
loopReverse=yes;
loopStartFrame=10;
delayOnLoopStart=5;
loopEndFrame=30;
delayOnLoopEnd=5;

The "topMovie" category allows to setup a movie for top screen and the "bottom" category is for the bottom screen. The "top3DMovie" category is only for 3DSX version: having a valid movie path for this category will activate 3D display. The "top3DMovie" category represents the right eye view and "topMovie" represents the left eye view: except for the path, you shoud keep the same properties for both! Keep in mind that movie resolution must be 400x240 for top screen and 320x240 for bottom screen.

Property names are the same for top and bottom movies:

  • "path" : path to the movie file
  • "compression" : specify if the given file is a compressed movie
    • "0" means that the movie is not compressed (default value)
    • "QuickLZ" or currently any not null integer value means that the movie is compressed
  • "loopCount" : movie loops to do once the movie is over
    • It can be "infinite", "INFINITE" or a negative value to infinitely loop the movie
    • "0" means the movie won't be played again after it is over (default value)
  • "loopStreamType" : specify how the movie loop is stored for replay
    • "file" or "0" means the movie file will be kept opened and used again for each loop (loops could be very slow, default value)
    • "memory" or any integer value other than "0" and "2" means the loop frames are kept uncompressed in memory (movie file is closed)
    • "compressed_memory" or "2" (only available for compressed movies) means compressed data to restore loop frames is kept in memory
  • "loopReverse" : allows loop play in reverse mode
    • "yes", "YES" or any not null integer means that reverse mode will be active
    • "no", "NO" or "0" means that reverse mode will be deactivated (default value)
    • When this mode is active, movie continuity will be preserved (so if "loopEndFrame" is not at movie end, the movie won't be played entirely even on first time)
  • "loopStartFrame" : movie start frame for loop (positive integer)
    • "0" means the movie first frame will be used (default value)
    • If this value is too big, the loop will be reduced to the movie last frame (it will look like a static image)
  • "delayOnLoopStart" : once a loop play is on the first frame, it will stay on this frame during the time in frames specified on this value
  • "loopStartEnd" : movie start frame for loop (positive integer)
    • A negative integer means that the movie last frame will be used (default value)
    • If this value is less than "loopStartFrame", it will be set at "loopStartFrame" value (so the loop will be reduced to "loopStartFrame")
  • "delayOnLoopEnd" : once a loop play is on the last frame, it will stay on this frame during the time in frames specified on this value

By default, "loopStreamType" is set to "file" to avoid any crash due to insuffisent memory if movie loops are too long. You can change this default value if you wish to optimize loop replays. The fastest mode is "memory" but it can easily crash on too long movies, "compressed_memory" is a good compromise for compressed movies.

Once movie is played and all its loops are over, CtrBootManager will fallback on theme default background behavior (image first then color if no image is specified).

CtrBootManager is compatible with BootAnim9 movies. To generate your own movies, you can follow "cots" tutorial: https://gbatemp.net/threads/tutorial-a9lh-boot-animations.430867/

However, the "framerate" will be ignored and, if the movie is compressed, you must specify it in the "compression" property.

Entries category properties

[entry]
title=Luma3DS;
path=/MyLuma3DSPath.bin;
offset=0;
patchMemSearch=730064006D0063003A002F00;
patchMemOverwriteWStr=sdmc:/MyLuma3DSPath.bin;
patchOccurence=1;
thumbTop=/luma_thumb.bin;
thumbTopParams=316:12:64:64:yes;
thumbBot=/luma_thumb.bin;
thumbBotParams=236:12:64:64:yes;
key=-1;

[entry]
title=CtrBootManager with another configuration;
path=/luma/payloads/CtrBootManager9.firm;
offset=0;
patchMemSearch=2F61396C682E63666700;
patchMemOverwriteStr=/other_a9lh.cfg;
patchOccurence=0;
splashTop=/directory/image_RGB_400x240.bin;
splashBot=/directory/image_RGB_320x240.bin;
key=-1;

All CtrBootManager versions read the following properties:

  • "title" : title to display in menu
  • "path" : the binary file path
    • It should be a ".dat", ".bin" or ".firm" file for A9LH/B9S
    • ".firm" files are only supported by A9LH/B9S version
    • ".3dsx" files are only supported by 3DSX version
    • If this property is set to "shutdown", the console will be powered off
    • If this property is set to "reboot", the console will be rebooted
    • If this property is set to "homemenu", the console will return to home menu (3DSX version only)
  • "offset" : entry point offset (in hexadecimal value) if "path" points out a binary file
    • For ".3dsx", ".firm" and most ".bin" binary files, it should be "0"
    • For most ".dat" binary files, it should be "12000"
  • "thumbTop" : path to thumbnail which is displayed on top screen when the entry is selected
  • "thumbTopParams" : top screen thumbnail parameters (ignored if "thumbTop" is empty)
  • "thumbTop3D" (3DSX version only) : path to thumbnail which is displayed on top screen when the entry is selected
  • "thumbTop3DParams" (3DSX version only) : right eye top screen thumbnail parameters (ignored if "thumbTop3D" is empty)
  • "thumbBot" : path to thumbnail which is displayed on bottom screen when the entry is selected
  • "thumbBotParams" : bottom screen thumbnail parameters (ignored if "thumbBot" is empty)
  • "splashTop" : splash image on top screen when this entry is loaded
    • If this property is not set, the screen will stay on its last rendered image
    • "splashTop=clear;" will clear the screen (full black color)
  • "splashBot" : splash image on bottom screen when this entry is loaded
    • If this property is not set, the screen will stay on its last rendered image
    • "splashBot=clear;" will clear the screen (full black color)
  • "key" : key which could be maintained at CtrBootManager start to direcly boot into this entry
    • The key values are the same as "recovery" property description in "[general]" category
    • "-1" means that the entry cannot be directly boot by maintaining a key
    • This property MUST be used to end an entry!

Thumbnail parameter properties follow this syntax: "X:Y:W:H:A"

  • "X" and "Y" represent the thumbnail position
  • "W" and "H" represent the thumbnail size (width and height)
  • "A" indicates if the thumbnail is in RGBA format ("true", "yes" or a not null value for RGBA)

Like background images, thumbnails are image raw data. Most formats can be converted to this raw data using this web page: https://xem.github.io/3DShomebrew/tools/image-to-bin.html

A9LH/B9S version supports binary patch feature. This feature allow to dynamicaly modify the loaded binary. The feature primary usage was for Luma3DS which must internally have its path for GBA and TWL reboot support.

So the following properties are read by A9LH/B9S version:

  • "patchMemSearch" : binary data (in hexadecimal form) to search in loaded binary file
  • "patchMemOverwrite" : binary data (in hexadecimal form) which will be used to overwrite found "patchMemSearch"
  • "patchMemOverwriteStr" : binary string which will be used to overwrite found "patchMemSearch"
    • This property replaces "patchMemOverwrite" and "patchMemOverwriteWStr"
    • It allows a more easily readable content than "patchMemOverwrite"
    • This string is ended by a null character which will "cut" the rest of found "patchMemSearch"
  • "patchMemOverwriteWStr" : binary string with wide characters which will be used to overwrite found "patchMemSearch"
    • This property replaces "patchMemOverwrite" and "patchMemOverwriteStr"
    • It is basicly the same as "patchMemOverwriteStr" with additional null byte between each character
  • "patchOccurence" : occurence found in binary file which must be replaced
    • "0" means all occurences in binary file will be replaced
    • Other strictly positive integer will indicate to replace only one occurence in the binary file
    • This property MUST be used to end a binary patch description!

Some useful "patchMemOverwrite":

  • 730064006D0063003A002F00 => "sdmc:/" separated with null byte between each character (used for Luma3DS path)
  • 636F6E6669672E62696E00 => "config.bin" (Luma3DS configuration file: can be patched to test an older Luma3DS version without losing configuration for the newer version)
  • 2F61396C682E63666700 => "/a9lh.cfg" (CtrBootManager9 configuration file)

The "[entry]" category text can be repeat for each boot entry to simplify configuration file reading. However, it is the "key" property which really ends an entry and starts a new one! The same goes for binary patches, each patch is ended with "patchOccurence" property.

Up to 4 binary patches are supported per entry.

Add a custom footer
Add a custom sidebar
Clone this wiki locally