Table of Contents
This is the Alpha version of the Archipelago mod for the 2025 roguelite puzzle game Blue Prince. This mod is still in active development as we continue to add features and QoL changes.
Special Thanks to:
- ChaseoQueso for the inital item code and the custom archipelago swirly asset.
- Mac for helping out on the mod and APworld
- deefdragon and BatemenzDW for their work on the APworld.
- Ezra3 for some logic fixes on the APworld.
- ZigZuagg and Shavnir for helping out with the mod.
- Zygan for some custom art assets.
- The Blue Prince community on the Archipelago Discord for all of their fantastic ideas.
- The Silksong/HK community for a lot of great tools which made modding so much easier.
If you are a player, Installation instructions are just below. If you are developer please check out the Developer Setup section.
This version of Blue Prince Archipelago is in Alpha and as such has quite a few known issues and limitations. All known Bugs will be listed here. Any QoL changes or future planned changes will live here.
Below are a List of Limitations and Known issues of the Mod that are not expected to be fixed in the short term. While fixes are being looked into and worked on they were not prioritized for Alpha.
- Only save files created on Bequest Mode (the game's default mode) are currently compatible.
- Some special items and rooms can bypass the limited draft pool (such as the Prism Key and Secret Passage).
- Room Upgrades aren't accounted for in logic and may result in out of logic checks.
- Item logic only accounts for the possibility of an item spawning, regardless of the rarity of that item actually showing up.
- Trunk logic currently doesn't account for how likely the rooms are to appear and the luck requirements for a trunk to spawn. I have made a list in discord to use as a guide for selecting trunk options for now.
- This implementation requires some late game knowledge for items and locations even on early goals.
- Certain items don't look quite right in pickup menus or in game please add any to this bug if they aren't already listed so this can be fixed in a future patch.
- Sometimes rooms outside of your draft pool appear in drafts. I am currently unsure on how to fix this fully and need more data on which rooms drafted from where Please add any new instances of this to this issue.
- Certain items like Repellant may not function as intended. Please check if a bug exists here or create a new one if you find an item that doesn't work here
If you haven't set up Archipelago before, please take a look at this general guide for Windows/Linux or this guide for Mac.
Since Blue Prince is a custom world you will need to follow those additional instructions. Here is where you can obtain the lates Blue Prince Apworld.
Extras:
- Blue Prince supports Universal Tracker. You can find it in #Universal-Tracker on the discord or download the client here.
- To disable your mods open up the doorstop_config.ini in your Blue Prince Installation folder and set enabled to false. This will prevent Bepinex from loading.
Before you install this mod, I highly reccomend backing up your save file MtHollyBlueprint.es3 from your ~\AppData\LocalLow\Dogubomb\BLUE PRINCE\storage folder. Copy it somewhere safe. Blue Prince Archipelago does not touch the save file process in any way, but I can't guarantee that it won't. Use this mod at your own discresion.
Here are the currently supported Mod Installation Options:
- Windows BepInEx Steam Setup
- Windows MelonLoader Steam Setup
- Windows BepInEx Xbox GamePass Setup (Microsoft Store)
If your preferred platform/modloader/storefront combination is not listed, it has not been tested or no one has provided fixes. If you do find a way to make that work please let me know so I can get it added.
If you prefer a simpler install we do have a Thunderstore version.
- Install Bepinex 6
- Specifically you will want to get build #755's BepInEx-Unity.IL2CPP-win-x64-6.0.0-be.755+3fab71a.zip from the page here
- Extract the files inside the Blue Prince folder (Steam default of
C:\Program Files (x86)\Steam\steamapps\common\Blue Prince)
-
After installing Bepinex, start the game once from Steam. Wait for the game to start as normal then quit out. This will take some extra time only on the first time you do this on a fresh patch.
-
Download the Latest mod release from here and if you haven't already the APworld Release from here.
-
Extract the contents of the mod to /BepInEx/plugins/BluePrinceArchipelago. Your final folder should look something like this:
-
Start the game. You will notice a new UI at the top. It is best to connect here before starting a new profile. This UI can be shown by pressing "/" and dismissed by pressing "ESC". This also doubles as your game client. Tying /help in the command box will show all the local commands. You can also run archipelago server commands from this console once connected. A lot of the commands are intended for dev usage to allow for progress when there is an issue with the mod.
-
IMPORTANT If you have played a Blue Prince AP before in a different multiworld please press the New Run Data Reset Button or run the /ResetData command before connecting. Due to limitations in the mod, the mod currently can't cleanly detect when it is safe to delete the local data on the last seed you played, so this must be done manually when starting a new seed.
-
To connect to your slot enter the connection details into the box on the left side of the UI. You will receive a message in the console if something goes wrong. If you are continueing a run (like in an async) load the same profile you loaded previously on the async run before connecting. The mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
IMPORTANT After connecting to the Archipelago server, if you are starting a new multiworld, create a new file in Bequest Mode. While the game will function on other modes, it may create impossible to complete scenarios, so it is Bequest Mode only for now. If you are reconnecting or continueing a run, be sure to load the correct profile; the mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
Enjoy!
Please note MelonLoader Support is expirimental and not as well tested. Use with caution. The MelonLoader version of the Thunderstore install is currently not working properly due to an error with the MelonLoader installation. If you prefer a simpler install we do have a Thunderstore version
-
Download MelonLoader 0.7.3 for your platform. Run the installer then install Melonloader onto your Blue Prince installation. If you previously had a different modloader installed you may need to uninstall it before Melonloader will work.
-
Start the game once from Steam. Wait for the game to start as normal then quit out. This will take some extra time only on the first time you do this on a fresh patch.
-
Download the Latest mod release from here and if you haven't already the APworld Release from here.
-
Extract the contents of the mod to /Mods. The DLLs shoot sit in the root folder of mods Your final folder should look something like this:
-
Start the game. You will notice a new UI at the top. It is best to connect here before starting a new profile. This UI can be shown by pressing "/" and dismissed by pressing "ESC". This also doubles as your game client. Tying /help in the command box will show all the local commands. You can also run archipelago server commands from this console once connected. A lot of the commands are intended for dev usage to allow for progress when there is an issue with the mod.
-
IMPORTANT If you have played a Blue Prince AP before in a different multiworld please press the New Run Data Reset Button or run the /ResetData command before connecting. Due to limitations in the mod, the mod currently can't cleanly detect when it is safe to delete the local data on the last seed you played, so this must be done manually when starting a new seed.
-
To connect to your slot enter the connection details into the box on the left side of the UI. You will receive a message in the console if something goes wrong. If you are continueing a run (like in an async) load the same profile you loaded previously on the async run before connecting. The mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
IMPORTANT After connecting to the Archipelago server, if you are starting a new multiworld, create a new file in Bequest Mode. While the game will function on other modes, it may create impossible to complete scenarios, so it is Bequest Mode only for now. If you are reconnecting or continueing a run, be sure to load the correct profile; the mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
Enjoy!
- Install Bepinex 6
- Specifically you will want to get build #788's BepInEx-Unity.IL2CPP-win-x64-6.0.0-be.788+5b766a3.zip from the page here
- Extract the files inside the Blue Prince Installation folder. Xbox Gamepass defaults to
C:\XboxGamesorC:\Program Files\WindowsApps. The folder might not be Named Blue Prince, but instead a meaningless string of numbers and letters.
-
After installing Bepinex, start the game once from Steam. Wait for the game to start as normal then quit out. This will take some extra time only on the first time you do this on a fresh patch.
- If you are on linux you will need to add the following to your steam launch options
WINEDLLOVERRIDES="winhttp=n,b" %command%. You can find them by clicking the gear icon on the right side of the game and click properties.
- If you are on linux you will need to add the following to your steam launch options
-
Download the Latest mod release from here and if you haven't already the APworld Release from here.
-
Extract the contents of the mod to /BepInEx/plugins/BluePrinceArchipelago. Your final folder should look something like this:
-
Start the game. You will notice a new UI at the top. It is best to connect here before starting a new profile. This UI can be shown by pressing "/" and dismissed by pressing "ESC". This also doubles as your game client. Tying /help in the command box will show all the local commands. You can also run archipelago server commands from this console once connected. A lot of the commands are intended for dev usage to allow for progress when there is an issue with the mod.
-
IMPORTANT If you have played a Blue Prince AP before in a different multiworld please press the New Run Data Reset Button or run the /ResetData command before connecting. Due to limitations in the mod, the mod currently can't cleanly detect when it is safe to delete the local data on the last seed you played, so this must be done manually when starting a new seed.
-
To connect to your slot enter the connection details into the box on the left side of the UI. You will receive a message in the console if something goes wrong. If you are continueing a run (like in an async) load the same profile you loaded previously on the async run before connecting. The mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
IMPORTANT After connecting to the Archipelago server, if you are starting a new multiworld, create a new file in Bequest Mode. While the game will function on other modes, it may create impossible to complete scenarios, so it is Bequest Mode only for now. If you are reconnecting or continueing a run, be sure to load the correct profile; the mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
Enjoy!
- Install Bepinex 6
- Specifically you will want to get build #755's BepInEx-Unity.IL2CPP-win-x64-6.0.0-be.755+3fab71a.zip from the page here
- Extract the files inside the Blue Prince folder (Steam default of
C:\Program Files (x86)\Steam\steamapps\common\Blue Prince)
-
On steam you will need to add the following to your steam launch options
WINEDLLOVERRIDES="winhttp=n,b" %command%. You can find them by clicking the gear icon on the right side of the game and click properties. -
After installing Bepinex, start the game once from Steam. Wait for the game to start as normal then quit out. This will take some extra time only on the first time you do this on a fresh patch.
-
Download the Latest mod release from here and if you haven't already the APworld Release from here.
-
Extract the contents of the mod to /BepInEx/plugins/BluePrinceArchipelago. Your final folder should look something like this:
-
Start the game. You will notice a new UI at the top. It is best to connect here before starting a new profile. This UI can be shown by pressing "/" and dismissed by pressing "ESC". This also doubles as your game client. Tying /help in the command box will show all the local commands. You can also run archipelago server commands from this console once connected. A lot of the commands are intended for dev usage to allow for progress when there is an issue with the mod.
-
IMPORTANT If you have played a Blue Prince AP before in a different multiworld please press the New Run Data Reset Button or run the /ResetData command before connecting. Due to limitations in the mod, the mod currently can't cleanly detect when it is safe to delete the local data on the last seed you played, so this must be done manually when starting a new seed.
-
To connect to your slot enter the connection details into the box on the left side of the UI. You will receive a message in the console if something goes wrong. If you are continueing a run (like in an async) load the same profile you loaded previously on the async run before connecting. The mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
IMPORTANT After connecting to the Archipelago server, if you are starting a new multiworld, create a new file in Bequest Mode. While the game will function on other modes, it may create impossible to complete scenarios, so it is Bequest Mode only for now. If you are reconnecting or continueing a run, be sure to load the correct profile; the mod currently cannot detect it has loaded the correct seed so loading the wrong file may bork the mod's local saved data on your seed which may result in unexpected glitches.
-
Enjoy!
Original credit for these instructions goes to RacgiMan on the Archipelago discord. Your milage may vary.
-
Install sikarugir. The readme has an explanation on how to install and the video in that readme shows you how to create a wrapper.
-
Create a sikarugir wrapper and install steam on it.
-
configure winhttp override in winecfg of that wrapper.
- Locate your wrapped steam app
- Right click the app -> "Show Package Contents"
- Open "Configure" (Configure.app)
- In the configuration window, click the "Tools" tab
- Click "Config Utility (winecfg)" in the "Wine Tools" section
- In the Wine configuration window, click the "Libraries" tab
- Click the dropdown, enter "winhttp", then hit "add"
- Verify that the winhttp override was added, then hit "Apply"
- Click ok to exit the wine configuration window, then close the configure app.
-
Follow the regular Windows BepInEx Installation Instructions
- Install Bepinex 6
- Specifically you will want to get build #755's BepInEx-Unity.IL2CPP-win-x64-6.0.0-be.755+3fab71a.zip from the page here
- Extract the files inside the Blue Prince folder (Steam default of
C:\Program Files (x86)\Steam\steamapps\common\Blue Prince)
- Clone the repo
git clone https://github.com/Yascob99/BluePrinceArchipelago.git
- Change git remote url to avoid accidental pushes to base project or check out Contributing if you want to help contribute instead.
git remote set-url origin github_username/repo_name git remote -v # confirm the changes - Add extra nuget package locations:
dotnet nuget add source https://nuget.bepinex.dev/v3/index.json --name Bepinex
dotnet nuget add source https://nuget.samboy.dev/v3/index.json --name Samboy
-
If nuget didn't install the required dependencies and the previous step didn't fully fix the issue, you will need to run the following to install these packages by running these commands in the project folder.
dotnet add package BepInEx.Unity.IL2CPP --version 6.0.0-be.755 dotnet add package Archipelago.MultiClient.Net --version 6.7.1 -
Go to SteamDB, find the depot for your platform. Then go to manifests. Switch it to Steam Console then click the copy icon next to the newest manifest. Open Steam Console when prompted. Once in Steam Console, paste and run the copied download command.
-
Download MelonLoader 0.7.3 for your platform. Install it on the version of Blue Prince that you downloaded with the Steam Console.
-
In Steam choose "Add a Game" from the bottom left and choose "Add Non-Steam Game" navigate the the melonmodded version. This will be your Melonmodded version of Blue Prince. Like Bepinex run the game once without any mods installed. 8.1 If on Linux, you might need to rename Blue Prince.exe to Blue_Prince.exe and Blue Prince_Data to Blue_Prince_Data. Then make sure it is using Proton compatibility.
-
Create a new file in the root of the repository and call it Directory.Build.props. Add this to the file replacing the directory "Path/To/BepInEx/BluePrinceFolderHere" with the path to your BepInEx Blue Prince Installation and "Path/To/MelonLoader/BluePrinceFolderHere" with your MelonLoader Installation. It will be on the lines marked with:
<BluePrinceBepInExDir>and<BluePrinceMelonLoaderDir>
<Project>
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
<AssemblyName>BluePrinceArchipelago</AssemblyName>
<Description>Blue Prince Archipelago</Description>
<Version>0.1.5</Version>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
<LangVersion>latest</LangVersion>
<!-- you may need this for getting the multiclient dll and Newtonsoft.Json.dll to output for .net 6 and netstandard 2.0 -->
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
<GenerateDependencyFile>false</GenerateDependencyFile>
<RootNamespace>BluePrinceArchipelago</RootNamespace>
<Configurations>Debug;Release</Configurations>
<PlatformTarget>AnyCPU</PlatformTarget>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
<BluePrinceBepInExDir>Path/To/BepInEx/BluePrinceFolderHere</BluePrinceBepInExDir>
<BluePrinceMelonLoaderDir>Path/To/MelonLoader/BluePrinceFolderHere</BluePrinceMelonLoaderDir>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>none</DebugType>
<Optimize>true</Optimize>
<OutputPath>$(SolutionDir)\bin\Release\$(Configuration)\$(MSBuildProjectName)\</OutputPath>
<DefineConstants>TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<IsPublishable>False</IsPublishable>
</PropertyGroup>
<ItemGroup>
<Compile Include="../src/**" LinkBase="."/>
</ItemGroup>
<ItemGroup>
<PackageReference Include="Archipelago.MultiClient.Net" Version="6.7.1" IncludeAssets="all" />
<PackageReference Include="Archipelago.MultiClient.Net.Analyzers" Version="2.0.3">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
<EmbeddedResource Include="assets/apprefabs" />
</ItemGroup>
</Project>-
Cinematic Unity Explorer - download BIE 6.X be.647+ IL2CPP then get the plugin into the
Blue Prince\BepInEx\pluginsfolder -
FSMHelper - An extension mod for CinematicUnityExplorer and Unity Explorer which makes FSMs easier to examine in the Object Inspector.
Below are instructions to get access to opening the files in Unity editor.
- Install Unity Hub. You can continue to the step 3 while this installs.
- Install Unity 6000.0.58f2. You can continue to the step 3 while this installs.
- Download AssetRipper
- Open AssetRipper and Click File > Open Folder and navigate to the root install folder of Blue Prince.
- Once AssetRipper has imported all the files click Export > All Files.
- Click select folder and choose an output folder.
- Click Export UnityProject to export it as a Unity project.
- In Unity Hub go to the Projects tab. Click Add > "Add Project From Disk" and navigate to the project you exported via assetRipper.
- Open the project. It will launch in safe mode and give you errors.
- Navigate to the Project folder and go to ExportedProject\Assets\Plugins\Assembly-Csharp-firstpass\Rewired\Demos and delete the ControlRemappingDemo1.cs.
- Navigate to the "ExportedProject\Assets\Plugins\Assembly-CSharp-firstpass\Rewired\UI\ControlMapper\ControlMapper.cs" file and Go to line 152. Change it to:
public GUIInputField(GameObject gameObject) : base(gameObject)
- Change line 156 to:
public GUIInputField(Button button, TMP_Text label) : base(button, label)
- Change line 194 to:
public GUIToggle(GameObject gameObject) : base(gameObject)
- Change line 198 to:
public GUIToggle(Toggle toggle, TMP_Text label) : base(toggle, label)
- Save the file then navigate to ExportedProject\Assets\Plugins\Assembly-CSharp-firstpass\Rewired\Glyphs\UnityUI\UnityUITextMeshProGlyphHelper.cs and go to line 64 and add this line below it:
protected Tag() { }
-
Save the file and check for more errors, attempt to solve them in a similar fashion. You can ignore all of the warnings.
-
The project will now attempt to open and will fail to open. Navigate to ExportedProject\Assets\ and open up the MainMenu.Unity file with Unity 6000.0.58f2. You now will be able to open most of the games prefabs by browsing for them in the asset browser in the bottom left.
- First naviagate to ExportedProject\Assets\Editor then create a file. Call it something on theme that ends with ".cs". It will be a script for creating AssetBundles. Paste the following into it:
using UnityEditor;
using System.IO;
using UnityEngine;
using System.Collections.Generic;
public class BuildSubsetAssetBundles
{
[MenuItem("Assets/Build Selected AssetBundles")]
static void BuildSpecificAssetBundles()
{
string assetBundleDirectory = "Assets/AssetBundles";
if (!Directory.Exists(assetBundleDirectory))
{
Directory.CreateDirectory(assetBundleDirectory);
}
List<AssetBundleBuild> builds = new List<AssetBundleBuild>();
string[] allAssetBundleNames = AssetDatabase.GetAllAssetBundleNames();
// Example: Only build AssetBundles that start with "ap"
foreach (string bundleName in allAssetBundleNames)
{
if (bundleName.StartsWith("ap"))
{
AssetBundleBuild build = new AssetBundleBuild
{
assetBundleName = bundleName,
assetNames = AssetDatabase.GetAssetPathsFromAssetBundle(bundleName)
};
builds.Add(build);
}
}
if (builds.Count > 0)
{
BuildPipeline.BuildAssetBundles(assetBundleDirectory,
builds.ToArray(),
BuildAssetBundleOptions.None,
BuildTarget.StandaloneWindows);
Debug.Log($"Built {builds.Count} specific AssetBundles.");
}
else
{
Debug.Log("No AssetBundles matching criteria found to build.");
}
}
[MenuItem("Assets/Log All AssetBundle Assignments")]
static void LogAllAssetBundleAssignments()
{
string[] allAssetBundleNames = AssetDatabase.GetAllAssetBundleNames();
Debug.Log($"Total AssetBundles Defined: {allAssetBundleNames.Length}");
foreach (string bundleName in allAssetBundleNames)
{
string[] assetPaths = AssetDatabase.GetAssetPathsFromAssetBundle(bundleName);
Debug.Log($"AssetBundle: {bundleName} (Assets: {assetPaths.Length})");
foreach (string path in assetPaths)
{
Debug.Log($" - {path}");
}
}
}
}
- Save the file. Unity Editor will reload and recompile the script automatically.
- You will need to find a prefab file you want to add to the asset bundle. You can create a new prefab by dragging a game object from the hierarchy into the asset browser. You can then open it and edit as desired.
- Once you have chosen a asset bundle right click it in the asset browser and select "properties".
- At the bottom of properties select an assetbundle click new. Name it something starting with ap (unless you change the above script to only build assetbundles that start with whatever is relevant to your name).
- Select the menu option Assets > "Build Selected AssetBundles" and the Asset bundle(s) will be build and exported to the ExportedProject\Assets\AssetBundles folder.
- The asset bundle is now ready to import into the mod!
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT. See LICENSE.MD for more information.