AGB Edit 3DS

AGB Edit
General
Author	joemck
Type	Forwarders and Virtual Console Injectors
Version	0.2.0a
License	MIT License
Last Updated	2022/05/08
Links
Download
Website
Source

This is an interactive Windows command line tool that can display info, dump or edit GBA VCs that use AGB_FIRM.

The main thing that makes it unique is that it can set a button combo that AGB_FIRM will automatically press when you close the lid. Combined with a GBATA or NSUI sleep patch using the same key combo, this can give you proper GBA sleep mode when you close the lid.

In version 0.2, there's a screen filter editor beyond just changing the darken filter amount. AGB_FIRM provides a video lookup table (LUT), which can do the sorts of things the "curves" tool in Photoshop or Gimp can do. The top use of this is to make gamma correction filters -- many games look like the screen brightness is lowered with the darken filter, and washed out without it, but gamma correction makes it a lot more like AGS-101 or DS Lite colors. It can also make things like blue light filters and weird trippy effects.

It supports both official Ambassador Program ones as well as NSUI-generated ones, and preserves the manual in official ones. This was noted as a feature since some other tools only work with one or the other -- Nintendo uses index 2 in the cia for the GBA ROM and adds a manual at index 3, while NSUI puts the ROM at index 0 and no manual.

Features

• Add a button combo to be pressed automatically when the lid is closed.
• Change the LCD ghosting value/remove ghosting.
• Make screen filters beyond just darken.
• Interpret and print all info in the ROM footer.
• Dump GBA ROM file to a file next to the cia but with the gba extension.
• Dump cia and exefs contents to a folder with the name of the cia but .dump.
• Batch processing of all of the above.

User guide

The UI is all terminal based. Simply pass one or more GBA VC cia files on the command line, or drag them onto the tools' icon. It will guide you through its various options in a keyboard-driven menu system.

The following sections describe each function in the main menu. Note that the "progfiles" folder must be in the same directory as agb_edit.exe in order to use the tool's dumping and building features, which are already implemented in 3dstool, ctrtool and makerom.

Note: If you're going to drag and drop CIA files onto agb_edit.exe, put them in the same directory as the exe, or it won't be able to find its progfiles exe's and you'll get "The system cannot find the path specified".

Preset quick fix cia(s)

If you only need to quickly fix your GBA VCs and don't want to edit them, use the Quick Fix Preset option. Drag your cias onto agb_edit.exe and select "P" when prompted for an option. This option will make the following changes:

• Remove any ghosting and dark filters
• Apply gamma correction that approximates the colors of a "New! Brighter screen!" GBA SP AGS-101 (gamma 2.2 => 1.54)
• Set the sleep button combo to L+R+Select, which is the default for the sleep patch from NSUI and is used by the built-in "basic sleep" option in Yoshi's Island and some other games.

Analyze cia(s)

The "Analyze cia(s)" function is straightforward. It provides information about the input file(s). This function displays the same information as the other functions, but without making any changes. For clarity, it's recommended to analyze one cia at a time.

The first block of information displayed after "==> progfiles\ctrtool.exe..." is provided by ctrtool and pertains to the cia header. The only useful piece of information here is the Title ID.

The second information block, following "==== DUMPING INFO FROM FOOTER ====", contains a dump of everything in the GBA-VC-specific ROM footer. The format of the data structures reflects how they are linked together in the footer. The following are the most interesting parts:

Save type:

• If this doesn't match the type of save your ROM actually uses, saving won't work correctly.
• This program cannot currently edit this if it's wrong, but I'm planning to add that in a future version.

Sleep buttons:

• AGB_FIRM has an optional feature that will press a button combination when you close the 3DS's lid, in order to activate a game's sleep function or sleep patch so you can have a normal sleep function on GBA games. The buttons it will press are set here.
• Note: This does NOT set what buttons will activate sleep. The system will blindly press the buttons configured here, at the same time. They might or might not activate a sleep function, but that's the obvious use case.

Video LUT (Look-Up Table):

• This is a color filter. Nintendo's VCs as well as NSUI only use it to implement the darken filter, but it can be made to do so much more -- really, it can do anything that GIMP or Photoshop's "curves" filter can do.
• This program dumps the values in hexadecimal and then draws a small graph on the terminal that's arranged the same as the one in the curves tool: the X axis is input subpixel value, and the Y axis is the output value. A straight line from the bottom left to the top right corresponds to "no darken filter", while a darken filter will move the top end of the line downward.
• Technically speaking, it's a list of 256 triplets of bytes. Inside each triplet, the first byte is for the red channel, the second blue, and the third green. The first triplet says the values to give to each channel when the game outputs a pixel for that channel with a value of 0/black, and so forth up to 255/fully lit.

LCD ghosting:

• This controls how much simulated screen ghosting / anti-flicker / motion blur the system applies to this game. Many GBA games used flickering to create transparency effects. Since the 3DS has a faster screen, you can see the flicker.
• This simulates having a slower screen, converting the flicker into properly rendered transparency. But it can also make fast-moving game elements harder to see.
• The number is shown in decimal and hex, and smaller numbers down to 1 mean a heavier ghosting effect, while 255 (0xff) results in no ghosting. Most people want 255, while Nintendo's VCs use 128 (0x80), 144 (0x90) or 192 (0xc0) depending on the game.

Extract files from cia(s)

This function is primarily useful for those interested in exploring 3DS internals. It enables you to extract the contents of the cia and its exefs into a directory located in the same place as the cia, with the name of the cia but with the .dump extension. The extracted files are organized into three layers. The cia contents are named file.xxxx.yyyyyyyy, where x's and y's are numbers that indicate their index in the cia. Typically, an NSUI inject will have one of these, and a Nintendo VC will have two, with the first being the game and the other being the manual. The main one is then extracted to a number of .bin files, and exefs.bin is extracted into an exefs directory within the .dump directory. Note that code.bin in the exefs directory comprises the GBA ROM and the AGB_FIRM footer.

Dump GBA ROM(s)

To extract the ROM from your GBA VC game, you can use this option.

It extracts a file with the same name as the cia, but with the .gba extension, located next to the cia.

You can drag multiple cias into the program at once to batch extract.

Edit cia(s)

This feature allows you to extract one or multiple CIAs, modify them and then rebuild them. Before proceeding, you will be prompted with a series of questions. For simple yes or no questions, you can press "Y" or "N", respectively. You can also quit the program by typing "Q".

The first prompt will ask if you want to set a lid-close button combination. If you select "Y", you will be asked to enter the buttons you want to press. The button names are not case-sensitive, and you can separate them with either spaces or the "+" symbol.

For example, to set the default NSUI sleep patch configuration, enter "L R SELECT". The order of the button names does not matter since they are all pressed simultaneously. If you want to remove the sleep buttons from an existing CIA, select "Y" and leave the button list blank.

If you select "N", the program will keep the existing sleep button configuration in the CIA(s).

The next prompt asks if you want to edit video parameters. If you select "Y", you will enter a different menu where you can modify various parameters and accept the changes when you are satisfied with the results.

Options in the video parameter (screen filter) editor menu:

A - Change the color channel being edited: You can choose to edit each color channel separately. The default setting is all channels.

B - Adjust brightness (intercept): This option raises or lowers the entire graph. If any part of the graph goes above or below the boundaries, it will be clipped to the top or bottom. The default setting is 0. This option represents the "b" in "y=mx+b".

C - Adjust contrast (slope): This option makes the line steeper or shallower. This is the setting that Nintendo and NSUI use to modify the dark filter. The default value is 1. Adjusting this setting to lower or higher numbers raises or lowers the right end of the line without moving the left end. This option represents the "m" in "y=mx+b".

D - Apply dark filter: This option provides a shortcut to set the contrast value, where 0 represents no modification and 255 darkens everything down until it becomes black.

I - Change input gamma: This option is for gamma correction. The input gamma should approximate the gamma of a GBA screen or the game's art design. Open_agb_firm suggests 2.2 for this option.

O - Change output gamma: This option is also for gamma correction. The output gamma should approximate the gamma of the 3DS screen. Open_agb_firm suggests 1.54, which seems accurate based on testing. A higher output gamma than the input gamma causes the graph line to curve gently upward, while a lower output gamma makes it curve downward. If the input and output gamma are the same, regardless of the absolute value, the gamma remains unchanged.

V - Invert colors amount: This option provides a simple invert/negative filter. A value of 1 represents normal colors, while -1 is inverted colors. You can use numbers between -1 and 1, but they tend toward gray and then into inverted colors. This option may be useful for creating a dark mode in a mostly white game.

S - Solarize amount: This option provides a solarize filter. A value of 0 represents normal, while 1 is fully solarized. Values in between are a blend of the two.

W - Set white point color: This option sets the white point color. It prompts for each red, green, and blue channel, which can range between 0 (black) and 1 (fully lit). Note that this setting affects all channels regardless of the active channel.

T - Set color temperature: This option sets the white point to a value calculated from a color temperature. Like Luma3DS, the default setting is 6500 k. Setting a lower value results in a blue light filter. Note that this setting affects all channels regardless of the active channel.

X - Set maximum/ceiling: This option clips the line to a specified value if it goes above that value. The default value is 255, meaning that it will not clip unless it goes outside the graph.

N - Set minimum/floor: This option clips the line to a specified value if it goes below that value. The default value is 0, meaning that it will not clip unless it goes outside the graph.

G - Set LCD ghosting/anti-flicker/motion blur: Allows you to set the ghosting value between 1 (maximal ghosting) and 255 (minimal ghosting). You can enter the value in decimal or hex by adding "0x" before the number. Note that this option will not modify the value in the cia unless you select it and enter a value.

R - Reset params: Resets all parameters except ghosting to their default values. You can choose between a default gamma-corrected preset (input 2.2 output 1.54) or a plain linear one with no gamma correction.

K - OK! Done!: Exits this menu and sets the video LUT to the changes you made.

Q - Back to previous menu, abandon all parameter changes other than ghosting: Exits this menu and cancels any changes made to the video LUT, except for the ghosting value. To change ghosting without overwriting the LUT, use this option after setting the ghosting value.

Before making any changes, the program will list everything that will be modified and ask for confirmation. If you accept, the program will extract, analyze, modify, and repack each cia you've given it. If you decline, it will quit without doing anything.

Examples

Here are some examples of what screen filters you can make using the above parameters. All of these are on the title screen of Mario Kart Super Circuit, running on an old 3DS XL (the Zelda: Link Between Worlds one). Screen pictures are taken with a Galaxy S7 Edge, in "pro" camera mode, with all fixed settings so the pictures are comparable.

And here is a single-shot comparison showing the game on a GBA SP (AGS-101 / the "New! Brighter Screen!" model), a New 3DS non-XL, and an old 3DS XL, with the brightness matched as best I can.

Changelog

v0.2.0a

• Swapped the 3 exes in progfiles for old versions that work more reliably.

v0.2.0

• Added screen filter editing with gamma correction, color temperature/whitepoint, brightness, contrast, ceiling, floor, invert and solarize effects.
• Moved code to Github.
• Separated code into multiple files.

v.1.0

• Initial release.

External links

• GitHub - https://github.com/joemck/agb_edit
• GBAtemp - https://gbatemp.net/threads/release-agb_edit-edit-dump-gba-vc-injects-auto-sleep-on-lid-close.609451/