BeatSaber-IPA-Reloaded/index.json

{
  "index.html": {
    "href": "index.html",
    "title": "BSIPA - Home",
    "keywords": "BSIPA - The Unity mod injector for the new age (pending confirmation). Assuming, that is, that Unity 2017 is \"new age\". How To Install See Installing How To Uninstall See Uninstalling Arguments See The Command Line . How To Develop See Developing for more information. How To Keep The Game Patched BSIPA will automatically repatch the game when it updates, as long as winhttp.dll is present in the install directory."
  },
  "other_api/index.html": {
    "href": "other_api/index.html",
    "title": "",
    "keywords": ""
  },
  "articles/dev-resources/description.html": {
    "href": "articles/dev-resources/description.html",
    "title": "Demo Plugin",
    "keywords": "Demo Plugin A little demo for the BSIPA modding introduction. WE CAN USE MARKDOWN!!!"
  },
  "api/index.html": {
    "href": "api/index.html",
    "title": "BSIPA API Documentation",
    "keywords": "BSIPA API Documentation Welcome to the full class documentation! To see guides, head over to the Articles tab . Select a namespace and a class on the left to get started."
  },
  "articles/contributing.html": {
    "href": "articles/contributing.html",
    "title": "Contributing",
    "keywords": "Contributing Prerequisites Microsoft Visual Studio 2019 or later (2017 may work, no guarantees) Tools for C/C++ (MSVC) v141 .NET 4.6.1 SDK and .NET 4.7.2 SDK Beat Saber (if developing for .NET 4.5+) Muse Dash (if developing for .NET 3.5) Building Clone with git clone https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded.git --recursive Create a file, bsinstalldir.txt in the solution root. Do NOT create this in Visual Studio; VS adds a BOM at the begginning of the file that the tools used cannot read. It should contain the path to your Beat Saber installation, using forward slashes with a trailing slash. e.g. C:/Program Files (x86)/Steam/steamapps/common/Beat Saber/ If you intend to be doing .NET 3.5 centric development, you must put your Muse Dash installation folder in a file named mdinstalldir.txt that is otherwise identical to bsinstalldir.txt . Open BSIPA.sln in Visual Studio. Choose the configuration that you intend to target during development. Rebuild all. When you make a change somewhere in BSIPA itself, right click on BSIPA-Meta and click Build or Rebuild . This sets up the output in path/to/solution/BSIPA-Meta/bin/<Configuration> to be what should be copied to the game directory. When making a change to Mod List, you only need to build Mod List itself. Install by copying everything in path/to/solution/BSIPA-ModList/bin/<Configuration> to your game directory. When building a Debug build, all referenced assemblies from Beat Saber will be copied from the install directory provided in bsinstalldir.txt into Refs/ . Any new references should reference the copy in there. When building for Release, it just uses the files already in Refs/ ."
  },
  "articles/command-line.html": {
    "href": "articles/command-line.html",
    "title": "The Command Line",
    "keywords": "The Command Line BSIPA has 2 command lines: the installer, and the game. Their documentation is below. The Installer ( IPA.exe ) The Game The installer has quite a few options, which are documented inline with the -h or --help flag. This is what it currently looks like: usage: IPA.exe [FLAGS] [ARGUMENTS] flags: -h, --help prints this message -w, --waitfor=PID waits for the specified PID to exit -f, --force forces the operation to go through -r, --revert reverts the IPA installation -n, --nowait doesn't wait for user input after the operation -s, --start=ARGUMENTS uses the specified arguments to start the game after the patch/unpatch -l, --launch uses positional parameters as arguments to start the game after patch/unpatch -R, --no-revert prevents a normal installation from first reverting The game also gets quite a few command line options, though there isn't anything as convenient as a help page for them. Here's a quick list of what they are and what they do. --verbose Makes a console appear with log information at startup. --debug Enables the loading of debug information in Mono. The debugging information must be in the portable PDB format, in the same location as the DLL that it's for. This option also forces BSIPA to show all debug messages in the console, as well as where they were called. This overrides the config settings Debug.ShowDebug and Debug.ShowCallSource . --trace Enables trace level messages. By default, they do not ever enter the message queue, and thus cost almost nothing. When this or the config option is used, they are added and logged with the same rules as Debug messages. This overrides the config setting Debug.ShowTrace . --mono-debug Enables the built-in Mono soft debugger engine. By default, it acts as a client, and requires that there be a soft debugger server running on port 10000 on localhost . Implies --debug . --server Does nothing on its own. When paired with --mono-debug , this option makes the Mono soft debugger act in server mode. It begins listening on port 10000 on any address, and will pause startup (with no window) until a debugger is connected. I recommend using SDB, but that is a command line debugger and a lot of people don't care for those. --no-yeet Disables mod yeeting. By default, whenever BSIPA detects that the game is now running a newer version than previous runs, it will move all mods to another folder and not load them. (They still get checked for updates though.) When this is enabled, that behaviour is disabled. Overrides the config setting YeetMods . --condense-logs Reduces the number of log files BSIPA will output for a given session. By default, BSIPA will create a subfolder in the Logs folder for each mod sublog, as well as each mod. This disables that behaviour, and restricts it to only create a global log and mod logs. Overrides the config setting Debug.CondenseModLogs . --no-updates Disables automatic updating. By default, BSIPA will check BeatMods for all of the loaded mods to see if there is a new version avaliable. If there is, it will be downloaded and installed on the next run. This flag disables that behaviour. Overrides the config settings Updates.AutoCheckUpdates and Updates.AutoUpdate ."
  },
  "other_api/config/schema.html": {
    "href": "other_api/config/schema.html",
    "title": "Configuration File Schema",
    "keywords": "Configuration File Schema { \"definitions\": { \"Debug_\": { \"type\": \"object\", \"properties\": { \"ShowCallSource\": { \"type\": \"boolean\" }, \"ShowDebug\": { \"type\": \"boolean\" }, \"CondenseModLogs\": { \"type\": \"boolean\" }, \"ShowHandledErrorStackTraces\": { \"type\": \"boolean\" }, \"HideMessagesForPerformance\": { \"type\": \"boolean\" }, \"HideLogThreshold\": { \"type\": \"integer\" }, \"ShowTrace\": { \"type\": \"boolean\" } }, \"required\": [ \"ShowCallSource\", \"ShowDebug\", \"CondenseModLogs\", \"ShowHandledErrorStackTraces\", \"HideMessagesForPerformance\", \"HideLogThreshold\", \"ShowTrace\" ] }, \"Updates_\": { \"type\": \"object\", \"properties\": { \"AutoUpdate\": { \"type\": \"boolean\" }, \"AutoCheckUpdates\": { \"type\": \"boolean\" } }, \"required\": [ \"AutoUpdate\", \"AutoCheckUpdates\" ] } }, \"type\": \"object\", \"properties\": { \"Regenerate\": { \"type\": \"boolean\" }, \"Updates\": { \"$ref\": \"#/definitions/Updates_\" }, \"Debug\": { \"$ref\": \"#/definitions/Debug_\" }, \"YeetMods\": { \"type\": \"boolean\" }, \"GameAssemblies\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } }, \"LastGameVersion\": { \"type\": \"string\" } }, \"required\": [ \"Regenerate\", \"Updates\", \"Debug\", \"YeetMods\", \"GameAssemblies\" ] }"
  },
  "articles/start-user.html": {
    "href": "articles/start-user.html",
    "title": "Installing BSIPA",
    "keywords": "Installing BSIPA Note This guide assumes that you are starting completely fresh. Grab a release from the GitHub Releases page . Make sure to download one of the BSIPA-*.zip s, as ModList.zip contains the Beat Saber mod for showing your mods in-game, not the loader itself. Note The specific ZIP you need to download varies on the game you will be patching. For example, if you are patching Beat Saber, you will need the file BSIPA-x64-Net4.zip . This is because Beat Saber is a 64 bit game running .NET 4. If you are patching Muse Dash, however, you nee the file BSIPA-x86-Net3.zip . Tip There are a few tricks for figuring out which file you need. If the game has a folder called MonoBleedingEdge in the install directory, then you need one of the Net4 builds. To determine which build to use, right click on the game executable, go to the Compatability tab, check the Run this program in compatability mode for checkbox, and look and see if the dropdown has any Windows XP emulation options. If it does, the application is 32 bit, and you need to get one of the x86 builds. Otherwise, get one of the x64 builds. Make sure to uncheck that checkbox before leaving the menu. Extract the zip into your game installation directory. There should now be a folder named IPA and a file named IPA.exe in the same folder as the game executable. For example, if you are installing BSIPA in Beat Saber, it might look like this after extraction: Run IPA.exe by double clicking it. A console window should pop up, and eventually, a gold message asking you to press a key will appear. Here is an example of a successful installation: Note In some cases, this may fail, something like this: In these cases, try dragging the game executable over IPA.exe . After installing, your game directory should look something like this: Note At this point it is recommended to run the game once before continuing, to ensure that things are installed correctly. The first run should create a UserData folder with Beat Saber IPA.json and Disabled Mods.json , as well as a Logs folder with several subfolders with their own files. If these are created, then the installation was very likely successful. Tip If you are not installing BSIPA on Beat Saber, you probably want to go to the config at UserData/Beat Saber IPA.json and set both of the following to false : { ... \"Updates\": { \"AutoUpdate\": false, \"AutoCheckUpdates\": false }, ... } Tip Depending on the game, you may have to set the config member GameAssemblies to the names of the assemblies that the game uses for BSIPA to virtualize them properly. For Beat Saber distrobutions, this will be set according to the version that it was built for by default. Otherwise, it will contain just Assembly-CSharp.dll since most games use that default. From here, just place all of your plugins in the Plugins folder, and you're all set! Many plugins will come in a zip such that the root of the zip represents the game install directory, so all you may have to do is extract the plugin into the game installation folder. Note For some reason, by default, Wine does not load DLLs in quite the same way that Windows does, causing issues with the injection. To make the injection work with Wine, winhttp has to have a DLL override set to native,builtin . This can be set either through Protontricks, or with the following .reg file. REGEDIT4 [HKEY_CURRENT_USER\\Software\\Wine\\DllOverrides] \"winhttp\"=\"native,builtin\" For Steam there's a per-game Wine prefix under compatdata . In this case SteamLibrary/steamapps/compatdata/620980/pfx/user.reg . Changes to this file will likely be ovewritten when the game updates or if local files are validated through Steam. Thats really all you have to do! The installation should persist across game updates for as long as winhttp.dll is present in the game directory, though your plugins will be moved to a different folder when it does update so things don't break horribly. Uninstalling Uninstalling is fairly simple, and can be done one of two ways: Drag the game executable over IPA.exe while holding Alt
  },
  "articles/start-dev.html": {
    "href": "articles/start-dev.html",
    "title": "Making your own mod",
    "keywords": "Making a mod Overview What follows is a very barebones, and frankly not very useful plugin class, even as a starting point, but it should be enough to give a decent idea of how to do quick upgrades of existing mods for those who want to. using System; using IPA; using IPA.Logging; namespace Demo { [Plugin(RuntimeOptions.SingleStartInit)] internal class Plugin { public static Logger log { get; private set; } [Init] public Plugin(Logger logger) { log = logger; log.Debug(\"Basic plugin running!\"); // setup that does not require game code // this is only called once ever, so do once-ever initialization } [OnStart] public void OnStart() { // setup that requires game code } [OnExit] public void OnExit() { // teardown } } } There are basically 4 major concepts here: <xref:IPA.Logging.Logger>, the logging system. <xref:IPA.PluginAttribute>, which declares that this class is a plugin and how it should behave. <xref:IPA.InitAttribute>, which declares the constructor (and optionally other methods) as being used for initialization. The lifecycle event attributes <xref:IPA.OnStartAttribute> and <xref:IPA.OnExitAttribute>. I reccommend you read the docs for each of those to get an idea for what they do. It is worth noting that this example is of a mod that cannot be enabled and disabled at runtime, as marked by RuntimeOptions.SingleStartInit . What can be changed Before we go adding more functionality, its worth mentioning that that is not the only way to have a plugin set up. For starters, we can add another method marked [Init] , and it will be called after the constructor, with the same injected parameters, if those are applicable. [Init] public void Init(Logger logger) { // logger will be the same instance as log currently is } If you only had a method marked [Init] , and no constructors marked [Init] , then the plugin type must expose a public default constructor. If multiple constructors are marked [Init] , only the one with the most parameters will be called. You may also mark as many methods as you wish with [Init] and all of them will be called, in no well-defined order on initialization. The same is true for [OnStart] and [OnExit] , respectively. From Scratch If you are starting from scratch, you will need one other thing to get your plugin up and running: a manifest. A basic manifest for that might look a little like this: { \"author\": \"ExampleMan\", \"description\": [ \"A demo plugin written for the BSIPA basic tutorial.\" ], \"gameVersion\": \"1.6.0\", \"id\": null, \"name\": \"Demo Plugin\", \"version\": \"0.0.1\", \"features\": [ ], \"links\": { \"project-home\": \"https://example.com/demo-plugin\", \"project-source\": \"https://github.com/exampleman/demo-plugin/\", \"donate\": \"https://ko-fi.com/exampleman\" }, } There is a lot going on there, but most of it should be decently obvious. Among the things that aren't immediately obvious, are id : This represents a unique identifier for the mod, for use by package managers such as BeatMods. It may be null if the mod chooses not to support those. features : Don't worry about this for now, this is a not-very-simple thing that will be touched on later. In addition, there are a few gatchas with it: description : This can be either a string or an array representing different lines. Markdown formatting is permitted. gameVersion : This should match exactly with the application version of the game being targeted. While this is not enforced by BSIPA, mod repositories like BeatMods may require it match, and it is good practice regardless. version : This must be a valid SemVer version number for your mod. In order for your plugin to load, the manifest must be embedded into the plugin DLL as an embedded resource. This can be set in the Visual Studio file properties panel under Build Action , or in the .csproj like so: <ItemGroup> <EmbeddedResource Include=\"manifest.json\" /> </ItemGroup> At this point, if the main plugin source file and the manifest are in the same source location, and the plugin class is using the project's default namespace, the plugin will lo
  },
  "articles/index.html": {
    "href": "articles/index.html",
    "title": "Getting Started",
    "keywords": "Getting Started Starting out is quite simple. Just follow one of the following guides: Installing BSIPA Making your own mod Or, if you want to contribute, see Contributing ."
  }
}