BDO Toolkit - A .NET modding library for Black Desert Online (1 Viewer)

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
If my tools enhance your experience, please consider supporting me with a sponsorship on GitHub Sponsors, it'll be greatly appreciated.
Sponsors may receive early access to updates and to work-in-progress tools.


Table of contents

BDO Toolkit
A .NET modding library for Black Desert Online

Requirements

Installation/Usage
  1. Download the archive anywhere on your computer.
  2. Unzip all the files in the archive.
  3. Open the executable "BDOToolkit Installer.exe".
  4. Press 1 then enter, and then any key to exit. You're done!
Developers only: Reference your projects to BDOToolkit.dll.
Note that redistribution of the library is prohibited, users will install the library to the GAC (Global Assembly Cache), and your project will load the library from the GAC (handled automatically by the .NET Framework) on their machine, this is so that projects that were not updated to the library's latest changes (such as bug fixes) do not roll back users. DO NOT include BDOToolkit.dll while redistributing your project, link to this thread instead.

FAQ
Q: Who is it for?
A: For mod developers to code with, and for users to install so that projects using the library may access it.

Q: Can I include the library in my project's/mod pack's archive?
A: No, redistribution is prohibited to prevent version conflicts, the GAC installation will provide the relevant projects with the library.

Q: Can I see the source code?
A: Not at the moment, no. The library is in serious need of clean up, refactoring and optimizations, the source code will not be made available at this time.

Q: Documentation?
A: Sadly not available yet. Documentation will be available in the library with future updates.



Meta Injector
A port of Meta Injector which utilizes the library.

Requirements

Installation/Usage
  1. Download the archive anywhere on your computer.
  2. Unzip "Meta Injector.exe" to your game's "Paz" folder.
  3. Copy your modified files to the sub-folder "files_to_patch" in your game's "Paz" folder
  4. Run "Meta Injector.exe" and follow the menu instructions.



Meta Patcher *NEW*
Applies a correcting patch to meta files to allow mods to work once again.

Requirements
  • .NET 6
  • BDO Toolkit 1.3.0 Embedded since .NET no longer supports the GAC (Global Assembly Cache).
  • A functional backup of the meta file (that allows you to play the game normally) that the library can detect (created automatically by Meta Injector).

Installation/Usage
  1. Download the archive anywhere on your computer.
  2. Unzip "Meta Patcher.exe" to your game's "Paz" folder.
  3. Apply your mods with other tools such as Meta Injector.
  4. Run "Meta Patcher.exe", if told the patching was done successfully you should be able to enter the game with mods.

FAQ
Q: Who is it for?/Who needs this?
A: Every player that wishes to use mods on an official PA server that "blocks" mods (currently that's every region except NA/EU).

Q: The program won't open, what am I doing wrong?
A: Make sure .NET 6 is installed, if it is, run a repair with the .NET 6 installer.

Q: The program says "An unmodified backup is required."
A (v1.1.0+): The most recent backup of the current game version is modded, remove it and run a repair with the game launcher. Modded backups only happen when using outdated tools (such older versions of Resorepless), please avoid using those.
A (v1.0.0): If the game just updated, you probably ran the tools in the wrong order and a backup currently does not exist. If a backup does exist, then it may have been tampered with as mods are detected with it.

Q: The program says it's "Unable to generate match!"
A: If you're playing on OFFICIAL servers by Pearl Abyss, please upload a copy of the automatically generated backup and your current meta file and name the region you play on.



Restore N' Patch
A launcher wrapper for Black Desert Online to avoid repairs during updates

Requirements

Installation/Usage
  1. Download the archive anywhere on your computer.
  2. Unzip the archive's contents to your game's "Paz" folder.
  3. Create a shortcut to "Restore N' Patch.exe" on your desktop (or wherever you normally launch the game from).
  4. Use the shortcut from now on to run the game. No longer fearing a sudden update triggering a file recheck.

FAQ
Q: What does it do?
A: The program restores the latest backup of the meta file, and launches the game's launcher, waiting for the launcher's closure, the program then attempts to find the game's process to suspend it, the program will then check if the meta file was updated, if not, the original patched meta will be restored, if it was updated, the program will execute compatible programs to patch the meta file.

Q: Does the program have to run as Administrator?
A: Yes, Black Desert Online runs as Administrator, and for the program to have access to suspend and later resume the process, the program has to have elevated permissions.




blahblahblah I'll finish this post later, you all are going mad while you wait...
 
Last edited:

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
OpenBD *WIP*
An OpenIV inspired project to eventually consolidate all tools and features needed by both developers and users.
This project is currently exclusive to sponsors on GitHub.

Requirements

Installation/Usage
  1. Download the latest "OpenBD" archive anywhere on your computer (only available to sponsors).
  2. Unzip all of the archive's contents to your game's "Paz" folder.
  3. Run "OpenBD.exe", after a bit of processing an interface will appear.

About
Current features include easy browsing of the game's files, the ability to open and preview most files (using software installed on your computer, except for pac model files, which are previewed using a bundled copy of i3dconverter), single/multi file extraction, full directory extraction, mesh conversion to OBJ and Collada DAE (incomplete), filtering by file name with wildcards (*, ?, #) with a toggle to include results from subfolders (off by default), and more.

Planned features include consolidation of Meta Injector and pactool features, mod management (one click on/off) and sorting, mod package formats, mod conflict resolution, automation for mods affecting text-based files (applying changes to the latest unmodified files based on defined rules, i.e. removing certain files from partcutdesc.xml, adding certain lines to characteraotexturelist.txt without including the full file, which may become outdated with future updates and cause issues), mesh conversion to more formats (primary focus on FBX), animation conversion and a lot more.

Previews
1660377829985.png
1660377944109.png
1660378993874.png
1660379453010.png


FAQ
Q: The download link isn't working.
A: As I'm not comfortable releasing the tool to the public at it's current state where features might be broken or missing, access is only available to my sponsors on GitHub, if you are a sponsor, make sure you're signed in and that the tier you've chosen qualifies for access to work-in-progress tools.

Q: Why not just release it for everyone?
A: Because there's still a lot of work to be done on it, I would like to rewrite and redesign it before a public release, it's been in development since late 2017, although development has grown somewhat stale during late 2018 onwards due to my declining interest in the game, I've still added some features and improved performance with certain uses, but there are still many bugs to fix, code to rewrite to make it more extensible, features to add or consolidate, and a redesign with another UI framework would also be ideal to address performance issues due to limitations with the current one.
I know the project would have a use for a lot of people even at it's current state, as a "paz browser successor" if nothing else, but I've always wanted it to be a lot more than that and so I'm not ready to make it public.

Q: Where do I sponsor?
A: You can sponsor me on GitHub here, make sure the tier you select qualifies for access to work-in-progress tools if you would like to access this tool.



PartCutGen
Automatically generate an up-to-date partcutdesc file with exclusion filter support and the option to use a new method to reduce the need to re-generate the file every time a new outfit is added.

Requirements

Installation/Usage
  1. Download the archive anywhere on your computer.
  2. Extract "PartCutGen.exe" to your game's "Paz" folder.
  3. Run "PartCutGen.exe", a "partcutdesc_exclusions.txt" file will be created in the "Paz" folder if you do not have one already, list the files you wish to stop cutting there.
  4. Use Generate partcutdesc to generate a new file with your exclusions.
  5. When done, the file will be saved to files_to_patch/_PartCutGen/character/partcutdesc.xml.

About
The tool was originally meant to use the well-known method of "converting" the "basic" CutType groups that list folders to normal ones that list every file individually, there were some issues and through resolving the issues came the discovery that duplicate file entries are ignored, leading to a new process where instead of re-writing the entire file (which needs to be re-done every time new outfits are added) just to comment out a handful of entries, the default file can be used and a new CutType group can be added to the top, listing the files you wish to disable, since duplicate entries are ignored, this yields the same results.
The new method is lower maintenance as the original file remains untouched, which means when new outfits are added they'll still be cut correctly, the file only needs to be re-generated when it updates to include new classes or when new CutType groups are added, which can be months apart.
The tool now also supports wildcard pattern matching, making it so disabling all parts of an outfit or disabling it on all classes is less tedious, as it can be done with a single line.


Info to modders
The tool will collect exclusions from all files named _partcutdesc_exclusions.txt, .partcutdesc_exclusions.txt or partcutdesc_exclusions.txt anywhere in files_to_patch (or the path specified with the -files <path> launch argument), the names prefixed with a dot or underscore are preferred, as they would be ignored by Meta Injector (meaning they won't display as "failed to patch"), when using sorting folders this allows you to bundle an exclusions file for a specific outfit mod (files_to_patch/_author/_mod/character/...).
 
Last edited:

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
CHANGE LOGS

BDO Toolkit

  • 1.3.0 (Mar 28, 2018):
    - The installer has been touched up a little for the first time since release.
    - Version policy not included in this release, this means programs targetting older versions of the library will not be using this update. This is done to encourage users to update to the latest version of all of the provided tools. The next update which will include automatic updates will also not include the version policy, back to normal after that.
    - Performance improvements when asked to refresh the meta file's contents.
    - Performance improvements when saving modifications (rework still needed).
    - Performance improvements when checking for modifications.
    - Fixed file extraction possibly corrupting the file when attempting to clean up the file's data.
    - Fixed an optimization issue causing files with the same name to not be detected properly.

  • 1.2.0 (Feb 28, 2018, 4,090 downloads):
    - Improved legacy patching support, although far from complete. Unintended behaviors may still occur.
    - Added Paz property to the FileBlock class.
    - Added property LegacyMods to class MetaFileInfo.
    - Performance improvements when attempting to locate file blocks.
    - Bug fixes.

    * Minor breaking changes, recompilation of affected programs is needed.

  • 1.1.0 (Feb 10, 2018, 3,151 downloads):
    - Fixed and optimized adding file blocks.
    - Removed unneeded sort for file blocks.
    - Import() with matchPath set to false will now only compare the file name instead of the full path.

  • 1.0.0 (Feb 7, 2018, 1,690 downloads):
    - First public release

  • 1.4.1 (August 10, 2020):
    - Eyesight check.
    - Added -files launch argument to specify a directory other than "files_to_patch".
    - Added -paz launch argument to specify a different Paz archive index to create (between 7777 and 99999) default is 61337. Note that archive index auto-increments when an archive would surpass 100MB with the next file to be included.
    - Small anti-measure for the hash flagging of XIGNCODE.


  • 1.4.0.1 (June 27, 2019, 29,837 downloads):
    - Rebuilt/1.4.0 re-release to address XIGNCODE "detection".
    - Signed (apparently I forgot to do a year and a half ago).

  • 1.4.0 (Mar 28, 2018, 39,817 downloads):
    - Meta contents refreshed every time the main menu is loaded and before attempting to patch.
    - Fixed underscore-prefixed files not being ignored.
    - Double dot/underscore folders will now have all the files inside them ignored (useful if you want to temporarily stop using certain files, without having to move them out).
    - More fixes regarding file detection order, now matches better with Windows Explorer.
    - Added numerous warnings regarding the automatic patching method.
    - Added duplicate file alerts.
    - Fixed an issue with the Restore N' Patch implementation.

  • 1.3.0 (Feb 28, 2018, 4,086 downloads):
    - Current file number/total count for the current paz archive (the square brackets) will now be gray.
    - Added legacy patching support. To perform a legacy patch, create a "legacy" folder prefixed by a dot/underscore in the path of the files meant to be legacy patched, and place the files/folders inside (i.e. files_to_patch/_legacy/character/model/...).
    - Added warning to option 2 to indicate that it's not fully compatible with all the changes made.

    * Requires BDO Toolkit 1.2.0 or higher.

  • 1.2.2 (Feb 14, 2018, 2,457 downloads):
    - Fixed an issue where the last (and possibly only) file meant to be added to an archive would be skipped and re-attempted on the next archive which ended up skipping it again (fixes the archive creation loop).
    - Zeroes will now be filled when enumerating the files for a more consistent look.
    - If multiple archives are needed to perform the patch, the current file number for the current archive and the total amount of files meant for the archive would be displayed in square brackets after the total count (should make the "breaks" in patching clearer).

  • 1.2.1 (Feb 11, 2018, 713 downloads):
    - Fixed an issue caused by the default sorting behavior of Windows, where files placed in a folder would be enumerated before the folders in that folder.

  • 1.2.0 (Feb 10, 2018, 562 downloads):
    - Requires BDO Toolkit v1.1.0 or higher.
    - Underscore-prefixed folders have also been added as path exceptions similarly to dot-prefixed folders (since you can't actually create dot-prefixed folders via Windows Explorer).
    - Folders with the name "add" prefixed by a dot or underscore will have the files inside them added to the game if they don't exist (under the parent folder of the "add" folder. I.E. "character\texture\_add\" will add files to "character\texture\").
    - The file count when patching will now reflect the total count, not the count set for the currently used archive.

  • 1.1.3 (Feb 10, 2018, 513 downloads):
    - Added the version to the title.
    - Fixed improper patching order caused by sorting.
    - Duplicate files will no longer be patched twice, the last one discovered will be the one applied.
    - Updated the description of the automatic detection.

  • 1.1.2 (1.1.1 re-release, Feb 9, 2018, 69 + 224 downloads):
    - Dot-prefixed files are now ignored when the program is searching for files in "files_to_patch" (can be used to leave notes).
    - Minimum Paz archive size before skipping files that would cause the archive to exceed 100MB is changed from nothing to 10KB (this should address the issue with empty archives being created indefinitely when there are individual files larger than 100MB).

  • 1.1.0 (Feb 8, 2018, 1,051 downloads):
    - Paz archives will now be built up to 100MB per archive, the paz number will start at 61337 and increment by one every time a new archive is needed (should fix the "Out of memory" exceptions).
    - Implemented Restore N' Patch support (currently only uses the "structure" patching method).

  • 1.0.1 (Feb 7, 2018, 458 downloads):
    - First public release.


  • 1.1.0 (August 8, 2022, public August 11, 2022):
    - Improved automatic backup selection.
    - Better feedback when a backup does not exist.
    - Better feedback when the current meta file is unmodded.
    - Updated startup notice to mention GitHub as another official source of the tools.

  • 1.0.0 (July 30, 2022, 127 downloads):
    - Initial release.


  • 1.3.2 (August 10, 2020):
    - Signed (should address the issue with Meta Injector).
    - Small anti-measure for the hash flagging of XIGNCODE.

  • 1.3.1.3 (June 27, 2019, 15,519 downloads):
    - Rebuilt/1.3.1.2 re-release to address XIGNCODE "detection".

  • 1.3.1.2 (Apr 25, 2019, 4,896 downloads):
    - Should address the issue where the program would proceed to the patching process before it was supposed to (when the launcher is relaunched due to an update, affects NA/EU non-Steam).
    - Game process/launcher search timeout increased from 5 to 60 seconds.
    - Fixes launcher reopens not being detected.

  • 1.3.0 (Apr 5, 2019, 1,722 downloads):
    - Fixed automatic switch to "idle mode" when the launcher isn't found.
    - Added the -patch argument which will force a re-patch of the files even if there wasn't an update.
    - Added the -launcher "path" argument - allows the specification of a custom launcher path (for regions besides NA/EU, the launcher path has to be within quotes, ex: -launcher "C:\Path\To\The\Launcher.exe").
    - Added the -dontwait argument which makes the program proceed even if the launcher has yet to close, this is automatically activated for the Steam client.
    - If there wasn't an update but the "patched" meta is clean, files will now be automatically patched instead of forcing the user to manually perform the patches (or use the newly added -patch argument).
    - Fixed the issue where the program would fail to start if the last patched backup that was created was corrupted.

  • 1.2.1 (Mar 28, 2018, 30,733 downloads):
    - The program will pause on errors so that they could be more easily reported.

  • 1.2.0 (Feb 28, 2018, 3,519 downloads):
    - Will now automatically default to "idle mode" if the launcher is not found.
    - Fixes a possible conflict.

    * Compiled against BDO Toolkit 1.2.0, hence version 1.2.0 or higher is required.

  • 1.1.0 (Feb 8, 2018, 2,543 downloads):
    - Added "idle mode", activated by the "-idle" startup argument. The mode disables all the launcher-related part of the code, and makes the program idle for the game process indefinitely until it's found.

  • 1.0.0 (Feb 8, 2018, 88 downloads):
    - First public release.


  • 0.1.0 (August 6, 2022):
    - Initial Sponsors release.


  • 1.1.0 (December 28, 2022, January 2, 2023):
    - Corrected save path to files_to_patch/_PartCutGen/character/partcutdesc.xml.
    - Removed Seek exclusions option, all exclusions files will now be read when Generate partcutdesc is used.
    - Added warning when there are 0 effective exclusions.
  • 1.0.0 (December 24, 2022):
    - Backported to BDO Toolkit 1.3.0.
    - Relation groups will now maintain their default order.
    - The default exclusions file will now be automatically created when the program is started (no longer included separately in the archive).
    - Added Seek exclusions option, which looks for all files named .partcutdesc_exclusions.txt, _partcutdesc_exclusions.txt and partcutdesc_exclusions.txt inside the files_to_patch folder (or the path specified with the -files <path> launch argument) and combines them into partcutdesc_exclusions_merged.txt, which is now also read for exclusions when using Generate partcutdesc (this allows shared mods to bundle their own exclusions file with entries relevant to the mod).
    - Fixed potential crashes.
    - Fixed count of files matched by a pattern.

  • 0.2.0 (December 21, 2022):
    - Reworked to support the "new" method of disabling cuts.
    - Exclusions support with wildcard filtering.
    - Cleaned up logging and the console interface.
    - Is a 1.0.0 release candidate.

  • 0.1.2:
    - Unreleased intermediate build, addressed the issues with the generation process.

  • 0.1.1 (August 7, 2022):
    - A new option to toggle which groups get converted, in an attempt to diagnose some of the issues reported previously.

  • 0.1.0 (August 5, 2022):
    - Initial Sponsors release.
 
Last edited:

Boss

Potential Patron
Joined
Apr 19, 2011
How do I verify that this was even installed when run? My virus protection, idk if its blocking it or not....

Also:

UndercoverPervert UndercoverPervert How does your MetaInjector work file structure wise? I have quite a few outfits that I have edited and used to let the program automatically find the locations...

Where would I put the .pac and .dds?
X:\Black Desert Online\Paz\files_to_patch\.resorepless\??????????????

(sorry if this was all ready answered) Thanks,

Edit: I can not for the life of me figure out how to setup the folder structure for .pac's.....
(the below are what failed...)
9X6q5Bv.png


Edit x2: I believe this will be the file path for pacs.....
(Use Pax_Browser)
69fe6f3d-7ceb-4c93-8334-0225eef43a42
uJ9T0ZY.png
 
Last edited:

BlackFireBR

Content Creator
Joined
Sep 2, 2013
How do I verify that this was even installed when run? My virus protection, idk if its blocking it or not....

Also:

UndercoverPervert UndercoverPervert How does your MetaInjector work file structure wise? I have quite a few outfits that I have edited and used to let the program automatically find the locations...

Where would I put the .pac and .dds?
X:\Black Desert Online\Paz\files_to_patch\.resorepless\??????????????

(sorry if this was all ready answered) Thanks,

Edit: I can not for the life of me figure out how to setup the folder structure for .pac's.....
(the below are what failed...)
9X6q5Bv.png


Edit x2: I believe this will be the file path for pacs.....
(Use Pax_Browser)
69fe6f3d-7ceb-4c93-8334-0225eef43a42
uJ9T0ZY.png
You can always use:
Untitled.jpg


Instead of guessing the folder structure for each file.

MetaInjector does that automatically for you if you choose this option
 

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
Added Restore N' Patch, info in the first post.

When Meta Injector has more downloads than BDO Toolkit, but BDO Toolkit is required in order to use Meta Injector :thonk:
 
Last edited:

h4iterr

Potential Patron
Joined
Oct 18, 2016
Thanks, for some reason i was under the impression that feature didnt work any more... Boy I feel silly....
UndercoverPervert UndercoverPervert himself said it:
"Unlike BlackFireBR's Meta Injector, the default and recommended patching method is by folder structure instead of automatic, if you have files that are not in their right folders, they'll most likely fail to patch."
I understood it as the automatic method not working anymore.
 

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
UndercoverPervert UndercoverPervert himself said it:
"Unlike BlackFireBR's Meta Injector, the default and recommended patching method is by folder structure instead of automatic, if you have files that are not in their right folders, they'll most likely fail to patch."
I understood it as the automatic method not working anymore.
It does work, but I don't recommend it since any "misfires" can result bigger issues than they would've before. Also it is way neater to organize your files since you can then use the new dot-prefixed folders being ignored in the paths, like Resorepless copying the relevant files to "files_to_patch\.resorepless" instead of just "files_to_patch". You can organize custom outfits and mods from others like that. For example you could create a ".suzu" folder if you use suzu's outfit mods.
 

h4iterr

Potential Patron
Joined
Oct 18, 2016
It does work, but I don't recommend it since any "misfires" can result bigger issues than they would've before. Also it is way neater to organize your files since you can then use the new dot-prefixed folders being ignored in the paths, like Resorepless copying the relevant files to "files_to_patch\.resorepless" instead of just "files_to_patch". You can organize custom outfits and mods from others like that. For example you could create a ".suzu" folder if you use suzu's outfit mods.
I thought as much. I've had my problems with the automatic sorting method, but it's just so convenient.
I've tried the new meta injector version and it works, mostly. It does have a problem with huge files though - namely the tattoo files, which contain all available tattoos, and my modded ones have a higher resolution, so they're 90MB big. When I try to patch with them, the injector creates a few "normal" paz files, but then it gets confused and starts creating new paz files that are all 20 bytes big, without actually putting any files into them, and I have to cancel it.
I've experimented with the previous version and it seems like the limit is slightly lower than 1GB, so you could make each single paz file around 500MB safely, I think.
Appreciate your work! Sorry for all the impatience and outright rudeness you have to deal with around here.
 

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
I thought as much. I've had my problems with the automatic sorting method, but it's just so convenient.
I've tried the new meta injector version and it works, mostly. It does have a problem with huge files though - namely the tattoo files, which contain all available tattoos, and my modded ones have a higher resolution, so they're 90MB big. When I try to patch with them, the injector creates a few "normal" paz files, but then it gets confused and starts creating new paz files that are all 20 bytes big, without actually putting any files into them, and I have to cancel it.
I've experimented with the previous version and it seems like the limit is slightly lower than 1GB, so you could make each single paz file around 500MB safely, I think.
Appreciate your work! Sorry for all the impatience and outright rudeness you have to deal with around here.
The latest version should address the issue you were having.
 

h4iterr

Potential Patron
Joined
Oct 18, 2016
Here's one of the files. I've found that just itself doesn't hinder the meta injector. But: Make a copy of it, rename it to phw_00_customizing_body_tattoo_0001.dds, and with the two files together, it messes things up.
 

Attachments


UndercoverPervert

Content Creator
Joined
Aug 9, 2016
Here's one of the files. I've found that just itself doesn't hinder the meta injector. But: Make a copy of it, rename it to phw_00_customizing_body_tattoo_0001.dds, and with the two files together, it messes things up.
Try version 1.2.2, this should now be fixed.
 

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
That worked, thanks!
I've seen that you added the ability to insert own files. I'm going to try this out with textures. Is there anything I have to keep in mind, like naming conventions?
Adding you own files won't net you anything unless you know what you're doing. This was mostly added to allow us to modify some models that use the same textures to use different ones, custom ones, like the few female classes that use the same body textures.
 

h4iterr

Potential Patron
Joined
Oct 18, 2016
Adding you own files won't net you anything unless you know what you're doing. This was mostly added to allow us to modify some models that use the same textures to use different ones, custom ones, like the few female classes that use the same body textures.
Well... I know what I'm doing, I think. You should be able to add a texture and change a model with a hex editor to use it, correct?
 

UndercoverPervert

Content Creator
Joined
Aug 9, 2016
Editing the texture a model uses with a hex editor is not the right way to do it. The library contains parsing code for Pac files (currently supporting two versions of the format, there are some unsupported versions and types of the format, mostly to do with certain customization aspects), it is capable of changing texture names for each of the meshes in a model, to any length that you'd like (unlike hex editing which would have you restricted to the same length).
 

Users who are viewing this thread

Top


Are you 18 or older?

This website requires you to be 18 years of age or older. Please verify your age to view the content, or click Exit to leave.