⚠️ This project is NOT affiliated with BepInEx
This project is not maintained by the creators of BepInEx; the logo is merely an illustration to imply the dependency of this project on BepInEx and the functionality behind this BepInSerializer.
During the development of a plugin to be used with a code-injector for Unity, there are many times the developer will need to create some sort of data structure to wrap up many basic types for its customized components.
In BepInEx, it's known that attempting to create a data structure (classes, structs) marked as serializable that is actually serialized is virtually impossible through Unity alone.
The main reason is due to how Unity internally works; keeping things simple, when we have a custom component with a [Serializable] class reference, that was injected into the engine, the field pointing to the data won't actually make it after the cloning process and, instead, point to null, which loses the previous information in the process.
BepInSerializer is a universal plugin made for BepInEx 5 and designed with cross-platform — Windows, Mac OS, Linux — in mind. This project aims to fix the aforementioned issue by acting as an intermediate bridge in the serialization process that handles all the UnityEngine.Object instantiation calls, and properly serialize/deserialize their fields using a custom conversion system.
This plugin does not add any other meaningful elements to the gameplay; there isn't much else this does aside from serialization. If you ever find anything different inside the gameplay with only this plugin alone, then you're welcome to report such bug in the Issues Tracker.
If you've paid enough attention, this project only has the suffix Mono, which means it'll work exclusively for any Unity build made without IL2CPP.
There are two main reasons for this to occur:
- The project was made for BepInEx 5, which does not work with IL2CPP. However, a version for BepInEx 6 is still planned to be developed. Although, the second reason is...
- Due to the fact BepInSerializer has been made from the ground up to attend Mono projects, the architecture barely understands the complexity of IL2CPP Interop. And so, at this point, it would be better to not even touch this type of closed compilation yet.
This project will still be maintained in the Mono environment.
If you're an ambitious developer, and you're willing to contribute to this project with a IL2CPP solution, or even a BepInEx 6 build, you're always welcome to do so! We'd appreciate it! 😁
Here's a quick image showcasing this plugin in action:
Before BepInSerializer:
SerializationBridgeTestsimply doesn't contain a reference toBridgePayloadafter this component is instantiated.After BepInSerializer: the serializer takes action and serializes
BridgePayloadexactly as it was structured.
If you're here because a mod has a dependency on this project, just follow the Installation guide and you're good to go.
BepInSerializer is a plugin made for BepInEx 5.
If you're looking for building the binary from the repository, follow the instructions in the Cloning & Building locally section.
Here's the step-by-step to install this plugin into your game:
- Install BepInEx into the game you're wishing to play with mods.
- Once BepInEx is installed, download this plugin through the Releases page.
- With the binary downloaded, your last task is to merely put that inside the
BepInEx/pluginsfolder.
Note that running the game alone with this plugin won't really change much inside the game itself.
You can verify if the serializer loaded in through BepInEx Console or inside BepInEx/LogOutputs.log.
On the other hand, in order to verify that the serializer is working as intended, use a separate mod that supports this serializer to assure everything's functioning as expected.
This basic bash script should do the job:
git clone https://github.com/PixelGuy123/BepInSerializer.Mono.git
cd BepInSerializer.MonoThe
.csprojcontains aPostBuildevent to copy the files to a few specific game locations; it is recommended to edit this event or completely remove it.
After cloning the project, a simple dotnet build should be enough to test if it builds locally. Finally, just copy-paste the compiled file, located in the bin folder, into any game with BepInEx 5.
You can contribute by testing the Unity builds not tested yet (⭕) in the table below!
If you find issues with these versions, the Issues Tracker is always open for feedback!
Even though BepInSerializer is meant to be universal and Unity barely changes their serialization/instantiation rules, there's always a bit of unpredictability when working with different Unity versions.
Currently, since this project is held by a single developer, it is quite impossible to ensure every Unity version is safe to use, only the newer ones (from games I have installed) have been tested — 2020.1.x, 2021.1.x and 6000.1.x. Nevertheless, as time goes on, more Unity versions can be tested by the community or by the developer.
Here is a table of all the Unity versions this tool has seen once in its lifetime:
| Unity Sub-Version | 2020 | 2021 | 2022 | 2023 | 6000 |
|---|---|---|---|---|---|
| XXXX.0.X | - | - | - | - | 6000.0.x – ⭕ |
| XXXX.1.X | 2020.1.x – ✅ | 2021.1.x – ⭕ | 2022.1.x – ✅ | 2023.1.x – ⭕ | 6000.1.x – ✅ |
| XXXX.2.X | 2020.2.x – ⭕ | 2021.2.x – ⭕ | 2022.2.x – ⭕ | 2023.2.x – ⭕ | 6000.2.x – ⭕ |
| XXXX.3.X | 2020.3.x – ⭕ | 2021.3.x – ⭕ | 2022.3.x – ⭕ | - | 6000.3.x – ⭕ |
| XXXX.4.X | - | - | - | - | 6000.4.x – ⭕ |
| XXXX.5.X | - | - | - | - | 6000.5.x – ⭕ |
Subtitles:
- ✅ – Fully tested/supported.
- 🚧 – Tested and Planned to be supported.
- ❌ – Tested and Not planned to be supported.
- ⭕ – Not tested yet.
Check how to contribute to this project in the Contributing section.
This project is licensed under the MIT license. For more information, see License.