Home Gallery Resources The Team Rules chat Login Register
  Show Topics
Pages: [1]
1  Super Smash Bros. Brawl Hacking / Programming / The Brawl Expansion Project on: December 31, 2013, 10:18:47 PM
Warning: may contain ham

Ladies, Gentlemen, Hackers, Modders,

Allow me to present to you the product of years of research.

A product wrought from necessity! and desire!.

A product born not just from my own work but of other hackers who have stood! and fought! alongside myself.


The Legendary Code!

The Ars Magnum!!

The Devine! Ins-piration!!!!!

The One! Mod! To Rule! Them All!!!!!!!




. . .

To much?

Yeah, I thought so.

Hyperbole and theatrics aside, how about one more mod to close off the year?

The BrawlEx Expansion project is a mod that allows up to a maximum of 100 characters in the roster. Moreover, it allows you to customize everything about a particular character slot simply using a set of configuration files in the SD card.

By default, BrawlEx doesn't actually change anything functional about the game. The original roster remains unchanged with their data in the exact order it is without the mod. However, BrawlEx both relocates and extends that data to make a total of 100 fighter slots, cosmetic slots, and CSS slots.

For players who are only interested in using custom characters and don't want to deal with configuring individual characters, skip to the downloads section to download Nebulon's pre-made BrawlEx package. Additional packs can be downloaded from the Packs section in the Brawl Vault

ExCharacter Slots

ExCharacter Slots are a feature of BrawlEx that provides are a convenient way of adding new characters into the game. They range from character id 0x3F up to 0x63. These slots can be added to the Character Select Screen roster using either the BrawlEx CSS Expansion or the Custom CSS v3 code created by Spunit. By default, the ExSlots are empty meaning that if you try to load them from the CSS the game will crash. However, These slots may be easily configured by using BrawlEx' config loader.

Config File Specification
BrawlEx supports 4 types of config files for customizing character slots. Each config file is numbered according to which slot is modified. If a config file is not found, the slot will not be modified. Paths shown in the following sections are example files for ExSlot 3F.

Fighter Config Files

Fighter Config files are the core of the character and determine which resources get loaded for the character as well as control various parameters for how the character behaves. FCFG files can be created and edited using the BrawlEx Config Utility.

Example Path:

File Format:
Fighter Config
0x00 Tag ("FITC" or "FCFG")
0x04 File Size (0x100)
0x08 Version (2)
0x0C Edit Flags

0x10 Entry .Pac Color Flag
0x11 Result .Pac Color Flag
0x12 KirbyCopy .Pac Color Flag
0x13 Character Load Flags
0x14 **Final .Pac Color Flag
0x16 Color .Pac Flags
0x18 Entry Article Flag
0x1C Sound Bank
0x20 Kirby Sound Bank
0x30 .Pac Resource String (0x30 chars)
0x60 KirbyCopy .Pac Resource String (0x30 chars)
0x90 Module Resource String (0x20 chars)
0xB0 Internal Name (0x10 chars)
0xC0 IC-Constants
0xF8 Texture Load Function (0, 1, 2, 3, 4, or 5)
0xFC AI Controller (fighter Id)

Edit Flags: None

** Version 2 Only.

OpenSA documentation on Fighter Data

Slot Config Files

Slot Config files are a small auxiliary configuration file that may be used to place more than one fighter in a single character slot (e.g. Zelda/Sheik or PokemonTrainer). They also are connected to which victory fanfare plays for the character as well as which game record the character's play data is stored into.

Example Path:

File Format:

Slot Config0x00 Tag ("SLTC")
0x04 File Size (0x40)
0x08 Version (2)
0x0C Edit Flags

0x10 *Slot Characters (0x10 bytes)
0x20 Victory Fanfare
0x24 Record ID (0x1 byte)

0x28 **Victory AnnouncerCall
0x30 **Victory Camera Distances (0x10 bytes)

Edit Flags:
0x01: Set Slot Characters

* Not set unless specified in Edit Flags.
** Version 2 Only.

OpenSA documentation on Character Slots

CSSSlot Config Files

These files control some of the data for the icons that are shown in the Character Select Screen. In particular they control the Wii Remote sound effect played when selecting the character as well as which colors can be chosen for that character on the character select screen.

Example Path:

File Format:
CSS Slot Config
0x00 Tag ("CSSC")
0x04 File Size (0x40)
0x08 Version (2)
0x0C Edit Flags

0x10 *Primary Character (Slot)
0x11 *Secondary Character (Slot)
0x12 Record Slot
0x13 *Cosmetic Slot
0x14 Wiimote SFX
0x18 Blank
0x1C Status
0x20 Slot Colors (0x20 bytes)

Edit Flags:
0x01: Set Primary Character, Secondary Character
0x02: Set Cosmetic Slot

* Not set unless specified in Edit Flags.

OpenSA documentation on CSSSlot data

Cosmetic Config Files

CosmeticConfig files control the data associated with displaying portrait data for the character as well as their franchise icon and announcer call. They also control the text-based name shown for the character on the victory screen.

Example Path:

File Format:
Cosmetic Config0x00 Tag ("COSC")
0x04 File Size (0x40)
0x08 Version (2)
0x0C Edit Flags

0x10 Cosmetic ID
0x11 Unknown
0x12 *Primary Character (Slot)
0x13 *Secondary Character (Slot)
0x14 Franchise
0x15 Unknown3
0x16 Unknown4
0x17 Unknown5
0x18 Announcer SFX
0x1C Unknown6
0x1D Unknown7
0x1E Unknown8
0x1F Unknown9
0x20 Victory Name (0x20 chars)

Edit Flags:
0x01 Set Primary Character, Secondary Character

* Not set unless specified in Edit Flags.

OpenSA documentation on Cosmetic Slots

Adding Characters Into Brawl

To add characters into the game, you will need at the very least one FighterConfig file. FighterConfig files can be created and edited using the BrawlEx Config Utility. This example will guide you through how to make a clone character of Marth. Because Marth (id 11) will be our base character, go into the Config Templates directory of the BrawlEx package and open Fighter11.dat in the FighterConfig folder. The only thing we want to change in the file is the name which we will be changing to MarthEx.

Once you have changed the name to MarthEx, save the file as Fighter3F.dat and add it into your SD card as directed in the FighterConfig section of this post. The file output shown at the bottom of the Config Utility will show you what files you need for your character as well as where to put them inside your patching directory. Once you have acquired either the original or modified Marth files and named them as directed, your copy of Marth is ready to be used.

Additionally, we will also need Slot, CSSSlot, and Cosmetic config files for our copy of Marth. As we are just copying marth, we do not need to edit these files (right now, we can only modify them with a hex editor anyways). We will be using Slot13.dat, CSSSlot11.dat, and Cosmetic10.dat from the template directory renamed to Slot3F.dat, CSSSlot3F.dat, and Cosmetic3F.dat for our Marth clone.


ExModules are one of the resources required for adding characters into Brawl. Before being used, a character's ExModule must be configured for the slot it is going to be used in. To do this, open the module using the Module Editor 3.3 and open up Section[8] in the memory viewer. Edit the first value in the section with the id of the ExSlot that the character will be using.

It is also necessary to change the id of the module itself to avoid module reference conflicts. Each module used in the game at any time must be unique or the game will crash. Brawl already contains many modules, but module ids 0x8F and up are free for use. The module id can be changed by clicking on the root of the module tree and changing the id in the property window of the Module Editor.

Customizing the Character Select Screen

Once you have configured your character slots you will need to add them to the Character Select Screen. The BrawlEx CSS Expansion mod not only extends the maximum number of characters allowed in the roster up to 100, but it also provides a means for customizing the CSS roster. Adding a character to the roster is as simple as opening up CSSRoster.dat (provided in the BrawlEx CSS Expansion package) using the BrawlEx Config Utility and adding the CSS id of your new character to end of both lists.

Spunit262's Custom CSS Code

Before the BrawlEx CSS Expansion mod was developed, the most common way to add characters to the roster was to use the Custom CSS code. The Custom CSS code allows full customization of the Character Select Screen, but for the sake of simplicity, this example will use a prebuilt version of the code that contains the default Character Select Screen roster.


Custom CSS V3 [spunit262] (Default CSS)
0668310C 00000030
387E006C 3B600000
3C808068 38840DE0
7CBB20AE 7CA50775
41800014 94A30004
3B7B0001 2C1B0032
4180FFE8 48000038
04690338 48000068
066900D8 00000008
2C170028 41820168
02680DE0 0022FFFF
06680DE0 00000024 <----CSS Icon Count
00010203 06070811
12091A0E 1716131B
21260D05 14101F25
200B270C 15242218
0A231929 00000000

In order to add an id to the Character Select Screen - for this example 3F- replace the value of 29 at the end of the code with 3F and replace the next 00 byte to the right with 29 again. If you run out of zeroes on a line, simply add a new line and pad it with zeroes. Additionally, for every id you add, you will need to increase the CSS Icon Count value by 1.

Below is the empty form of the Custom CSS code for people interested in creating their own Character Select Screen.


Custom CSS V3 [spunit262]
0668310C 00000030
387E006C 3B600000
3C808068 38840DE0
7CBB20AE 7CA50775
41800014 94A30004
3B7B0001 2C1B0032
4180FFE8 48000038
04690338 48000068
066900d8 00000008
2c170028 41820168
02680DE0 0022FFFF
06680DE0 000000YY <---- CSS Icon Count

Character Ids:
00 Mario
01 Donkey Kong
02 Link
03 Samus
04 Zero Suit Samus
05 Yoshi
06 Kirby
07 Fox
08 Pikachu
09 Luigi
0A Captain Falcon
0B Ness
0C Bowser
0D Peach
0E Zelda
0F Sheik
10 Ice Climbers
11 Marth
12 Mr. Game & Watch
13 Falco
14 Ganondorf
15 Wario
16 Metaknight
17 Pit
18 Pikmin & Olimar
19 Lucas
1A Diddy Kong
1B Pokemon Trainer
1C Charizard
1D Squirtle
1E Venasaur
1F Dedede
20 Lucario
21 Ike
22 Robot
23 Jigglypuff
24 Toon Link
25 Wolf
26 Snake
27 Sonic
28 None
29 Random

3F+ ExCharacters

Video Tutorials

Video tutorials by Sammi Husky

Regular Brawl:
BrawlEx Clone Engine [tutorial] (vBrawl) step-by-step

Brawl Minus:

Cosmetic Data:

A Note On Config Slot Alignment

There are 4 types of config files used by BrawlEx and likewise there are 4 types of configuration data used in the game. Any one character is capable of using any combination the ids associated with this data. In the example of Marth, his default configuration is Fighter11, Slot13, CSSlot11, and Cosmetic10. For the ExSlots – that is, slot ids 0x3F up to 0x63 – this data is aligned, so a character in slot 0x3F will use 0x3F for all of their configuration ids.

This chart details the associations between config ids and characters.

Fighter Data Chart


Note: Ensure you have your mod launcher's hook method set to AxNextFrame. This fixes many of the issues new users are known to have.

New CSS Icons show up as Random and crash when highlighting them:
If an icon is shown as Random and is not intended as the regular random icon, then the icon has not been mapped by BrawlEx. This could mean that BrawlEx is not running. Ensure that both the Module/bx_fighter.rel and System/Common2.pac files included in the BrawlEx package are in your patching directory.

Icons periodically switch between proper icons and crashing Random icons between startups.
If you are using GeckoOS or USBLoader GX and BrawlEx periodically fails to start, go into ensure that you have your launcher's hook method to AXNextFrame.

New CSS Icons show up as Mario and crash when starting a match with them selected:
If an icon shows up as Mario when it is not intended to, then the character slot has not been configured. This could mean that the wrong id has been assigned to the CSS Icon or the BrawlEx config files have been improperly named. Non-configured ExSlots will try to load resources of the pattern Fighter<id>Ex.pac by default. As those files do not exist in the game, they are intended to crash if used.

New CSS Icons show up properly, but immediately crash when selected:
If an icon crashes immediately when selecting it, then the module used for that character is corrupt. Redownload the module and try again.

New CSS Icons show as Mario, but properly load the desired character when used in a match:
In general, cosmetic data for ExSlots default to Mario for compatibility purposes. An icon showing up as Mario means that the cosmetic data for that css slot is not configured.

New CSS Icons show up properly, but cause a soft crash both when attempting to enter a match or leave the CSS screen after selecting them:
If the game experiences a soft crash (the game endlessly loads, and can still access the Home Menu) both when you try to enter a match or leave the CSS, then either the Fighter Configuration for the slot is missing or one of the resources for the character is missing from you patch directory. Open the Fighter config file in the BrawlEx Config utility and make sure you have all the files shown in the bottom list inside your patching directory.

New CSS Icons show up properly, but crash only when attempting to enter a match.
If the game crashes only when you try to enter a match, then it is likely you are trying to use a v1.0 ExModule with BrawlEx v1.1.0.0 or a v1.1 ExModule with BrawlEx v1.0.0.0. Try redownloading the BrawlEx package and using the latest modules.

CSS Icons show up properly, but crash when highlighting them.
If simply highlighting a CSS icon causes the game to crash, then either you have an outdated version of BX CSS Expansion's Common3.pac, or that character is missing their character portraits that they are required to show when you highlight them.

If you have an issue that you think may be caused by BrawlEx, please post a copy of your .wgc code file as well as the configuration files that you are using so that I may identify the source of the issue and/or determine if the issue is with BrawlEx or the setup being used.


BX Clone Engine v2.0.0.0 Stable
Extends the limit on the brawl character roster up to 128 characters and allows character slots to be customized using slot configuration files. This mod allows the creation of clone characters.

BX CSS Expansion v1.0.2.0 Stable
Extends the limit on the Character Select Screen to 100 character icons. It also allows the character select screen roster to be modified using an external config file.

Nebulon's BrawlEx Pack
Project Thread
The most complete BrawlEx package available by Nebulon featuring 44 extra characters properly configured for sound effects and graphics for a total of 85 playable characters.

BrawlEx Config Utility v1.3a
A tool for editing BrawlEx Config files. Currently, it only supports Fighter Config and Roster Config files.

Module Editor 3.3
A tool for modifying module data. Necessary for configuring ExModules.

BrawlEx Clone Tool
Not compatible with the latest version of BrawlEx
A tool developed by Sammi Husky to manage the creation of clone characters. The latest version of the program can be found in his signature.

Fighter Data Chart
A chart detailing the ordering of each character's configuration data type and the ids they are associated with.

Alloy Cosmetics
Even though the Alloys have Character Select Screen Ids, they cannot be added to the CSS without first adding their missing portraits and icons into the game. This package contains all the Alloy cosmetics required to make them usable.

Bowser/GigaBowser Resources
Merged resource files necessary for cloning Bowser and Gigabowser together or Gigabowser alone.

Additional BrawlEx Versions

BX Clone Engine v1.1.3.1
The BrawlEx clone engine configured for loading config files from the DVD instead of the SD card. Mainly developed to be used with Riivolution. Currently discontinued and out of date.

BX CSS Expansion v1.0.2.2
The current stable version of the BX CSS Expansion configured to use the regular merged behavior for Zelda and Sheik's icons instead of the adjusted behavior where they are separate.

BX CSS Expansion v2.0.0.x
Unstable Build
A new release of the BrawlEx Roster Expansion. It adds the ability to load character selection portraits from the SD card. Suffers from poor load times when loading character portraits.

Known Bugs

BX Clone Engine

-Game startup time is increased by approximately 10 seconds.

-Switching the game language to Japanese no longer replaces names for certain characters at the victory screen. (e.g. Bowser -> Koopa)

-A bug in the original File Patch Code v3.5.1 may cause issues when replacing Common2.pac. It is recommended that you use the File Patch Code v3.5.1b listed in Readme.txt if you are using v3.5.1.

BX CSS Roster Expansion

-Using the BX CSS Roster Expansion will prevent Final Smash music for Luigi, Peach, and Dedede from playing.

-The ordering of the characters in the Subspace Emissary character select page is slightly broken.

-Attempting to enter co-op mode at the character select screen for Classic, All-Star or any Stadium modes will cause the game to crash.

Version History

BX Clone Engine


- Fixed compatibility error making v1 Fighter config unable to set the Final Smash Resource flag.

- Fixed issue causing transforming clone characters to keep their old battle portrait after transforming.

- Added ExModules for Rob, Toon Link, Dedede, Diddy Kong, Ness, Bowser, Giga Bowser, Samus, and Zerosuit Samus.

- Increased number of available Fighter, Slot, CSSSlot, and Cosmetic entries up to 128.

- Added support for setting Victory Camera Distances and Victory Announcer Calls from the Slot config file.

- Added support for enabling per-color final smash resource files from the Fighter config file.

- Completing Classic or AllStar for characters with Slot Id 2C and up will simply return the player to the CSS instead of crashing.

- Fixed bug that caused Slot 58 to crash unless its slot entries had been overwritten using an elevated Slot config file.

- ExCharacters created in training mode will now be properly shown with differing colors.

- Added safety check to ensure that a fighter's record data cannot be set to an invalid record bank using a corrupt Slot config file.

- Reorganized the internal code layout of bx_fighter.rel.

- Updated common2.pac's sora_melee hook.

- Removed ft_kirby copy fix.rel from the ExModules directory to avoid confusion.


- Fixed crash caused by entering Homerun Contest.

- Added ExModules for Metaknight, Jigglypuff, and Ganondorf.


- Fixed crash caused by entering an Event Match requiring you to choose a character.

- Added CSS config files for using independent forms of Charizard, Squirtle, and Ivysaur on the CSS to the CSS config templates.


- DVD loader configuration (x.x.x.1) discontinued until a better hook method is found.

- Fixed a gamebreaking bug involving team battle character portraits.


- Fixed a gamebreaking bug in kirby resource file references for Luigi and Yoshi both in bx_fighter.rel and in their template config files.


- Initial release for DVD config loader configuration.

- BrawlEx Config files load from DVD:/BrawlEx/...


- Fixed a small non-fatal assembly bug in the Marth v1.1 ExModule.


- Removed Test Files directory from BrawlEx package to reduce download size.

- Fixed name reference bug that was causing ExCharacters to crash Pictochat.

- Fixed bug in the Pikachu v1.1 ExModule making it unusable.

- Changed the default cosmetic reference in CSSSlot29 (Random) to Cosmetic2A.


- Fixed game breaking bug that caused various articles to crash the game once a character's ExModule was loaded.

- Updated ExModules to v1.1

- Updated the names of Config Templates with the name of the originating character.


- Initial Release

BX CSS Expansion

Unstable Build

- char_bust_tex_lz77 portrait files in sc_selcharacter.pac will attempt to load them from the SD card before trying to load regularly from the .pac file. (See note in Readme on file paths)


- Fixed bug that caused the Classic Mode Character Select Screen stock option bar to vanish.


- Fixed crash that resulted from hovering over icons that would normally be marked with a "new" tag.


- Initial Release

Special Thanks

Special thanks to Dantarion and his help with the project as well as the documentation resources he posted on the OpenSA website. Brawl hacking wouldn't be anywhere near where it is now without your work on OpenSA, the Brawl Documentation project, and Project M.

I would also like to thank the rest of the Brawl modding community for keeping Brawl going for these past 6 years. I look forward to seeing what everyone is capable of in the following year
2  Super Smash Bros. Brawl Hacking / Programming / The Beginner's Guide to Stage Modules on: August 05, 2011, 06:09:56 PM
I was going through my notes the other day when something caught my attention that I'd meant to expand on a little more. It's not really anything useable at the moment, but hey, I figure someone should be able to get something out of it.

First off, some class declarations

Declaration: 80B292A8
Constructor Method: 809301d0
Inherits: None
Methods: 3
Size: 0x04

Declaration: 80422F08
Constructor Method: 8002d8b8
Inherits: None
Methods: 23
Method Range: 0 - 22
Size: 0x44

Declaration: 80B29088
Constructor Method: 8092c478
Inherits: gfTask
Methods: 127
Method Range: 23 - 126
Size: 0x1A0

Declaration: 80B2B608
Constructor Method: 80942614
Inherits: Stage, gfTask
Methods: 127
Size: 0x1D0

Declaration: 80B2B8E8
Constructor Method: 809435F0
Inherits: stCommonGimmick, Stage, gfTask
Methods: 132
Method Range: 127 - 132
Size: 0x1D8

You may have seen these classes before if you've ever taken the time to look inside any stage module. For the sake of the analysis, I used the Wifi Waiting Room stage(st_otrain.rel) - I will refer to it whenever necessary.

For now we'll look at stClassInfoImpl<55, stOnlineTrainning>, a derived class of the stClassInfo class. (you could argue that it's actually an implementation of the abstract interface stClassInfo, but let's not complicate the terminology) This is a lightweight class that Brawl uses whenever it needs to generate the Wifi Waiting Room stage for you to fight on. (Incidentally, the Results Screen stage's stClassInfo is always loaded into memory, so it can be loaded at any time)

The method in question that loads the stage is stClassInfoImpl<55, stOnlinetrainning>.Method[1]. I won't go into details, but it does 3 main things:

1. Allocate a block of memory on the StageInstance heap the size of the stOnlineTrainning class.
2. Call the stMelee constructor. (the base class of the stOnlineTrainning class)
3. Construct the remaining parts unique to the stOnlineTrainning class.

After the constructor returns, the address of the stOnlineTrainning class gets stored at 80B8A428. (Somewhere inside module 1B) When the match actually starts, stOnlineTrainning gets accessed from 80B8A428 and it's initializer gets called.

For all instances of the Stage class, method[23] is the initalizer. This is the function that is responsible for loading up all the assets from STGONLINETRAINING.pac. It is also responsible for creating any other instances that exist on the stage as separate objects. (The blocks from Mushroomy Kingdom, say)

And unfortunately, that's really as far as I got with this. I might venture a guess as to say that the method at 80015DDC is responsible for loading specific archives out of the .pac with r4 being the type and r5 being the FileIndex, but the rest of it is uncharted territory.

In case that all went by a little bit too fast for you, I whipped up a quick diagram for you to reference at your leisure.
(The diagram says that Method[22] is the Stage initializer - ignore that, it's really Method[23])

Just a few more miscellaneous notes:

As mentioned above, the current existing stage instance can be accessed at any time from the pointer at 80B8A428.

All methods in a class that don't reference assembly inside it's own module are methods that have not been overridden from it's base class.

Method[127] is the main loop of the stage. It is constantly called and is used for things like the Sandbag in WWR or rebuilding the mansion in Luigi's Mansion.

Just as there are constructors and initializers, there are also destructors and finalizers. stClassInfo.Method[0] is used for removing the stClassInfo from memory and Stage.Method[22] is the destructor for the actual stage

The memory allocation function can be found at 8000C8B8, it may be a good idea to see what else calls it if you wish to find out where other classes get constructed. (8000C8C8 is the memory free function if anyone was wondering) Also, here's a list of the types of memory heaps.
00 *Null
01 System FW
02 System
03 Effect
04 RenderFifo
05 Sound
06 Network
07 WiiPad
08 IteamResource
09 InfoResource
0A CommonResource
0B Replay
0C Tmp
0D Physics
0E ItemInstance
0F StageInstance
10 *Null
11 StageResoruce
12 Fighter1Resoruce
13 Fighter2Resoruce
14 Fighter3Resoruce
15 Fighter4Resoruce
16 Fighter1Resoruce2
17 Fighter2Resoruce2
18 Fighter3Resoruce2
19 Fighter4Resoruce2
1A FighterEffect
1B Fighter1Instance
1C Fighter2Instance
1D Fighter3Instance
1E Fighter4Instance
1F FighterTechqniq
20 FighterKirbyResource1
21 FighterKirbyResource2
22 FighterKirbyResource3
23 AssistFigureResource
24 ItemExtraResource
25 *Null
26 PokemonResource
27 *Null
28 InfoInstance
29 *Null
2A MenuInstance
2B *Null
2C CopyFB
2D GameGlobal
2E GlobalMode
2F *Null
30 MeleeFont
31 *Null
32 OverlayCommon
33 OverlayStage
34 OverlayMenu
35 OverlayFighter1
36 OverlayFighter2
37 OverlayFighter3
38 OverlayFighter4
39 *Null
3A Thread

That's all for now folks. I'll hang around for a little while to see if this can be taken anywhere, but I'll be riding backseat for the most part.
Pages: [1]