UnityExplorer/README.md

153 lines
8.4 KiB
Markdown
Raw Normal View History

2020-08-20 18:53:56 +10:00
<p align="center">
2020-11-17 17:08:11 +11:00
<img align="center" src="img/icon.png">
2020-08-20 18:53:56 +10:00
</p>
2020-08-22 01:42:29 +10:00
<p align="center">
2020-11-12 15:58:28 +11:00
An in-game explorer and a suite of debugging tools for <a href="https://docs.unity3d.com/Manual/IL2CPP.html">IL2CPP</a> and <b>Mono</b> Unity games, to aid with modding development.
2020-11-12 15:59:34 +11:00
</p>
<p align="center">
2020-08-22 01:42:29 +10:00
<a href="../../releases/latest">
<img src="https://img.shields.io/github/release/sinai-dev/Explorer.svg" />
2020-08-22 01:42:29 +10:00
</a>
<img src="https://img.shields.io/github/downloads/sinai-dev/Explorer/total.svg" />
2020-08-22 01:42:29 +10:00
</p>
2020-08-22 01:02:04 +10:00
2020-10-05 23:13:09 +11:00
- [Releases](#releases)
2020-09-14 16:56:42 +10:00
- [Features](#features)
2020-10-08 06:15:42 +11:00
- [How to install](#how-to-install)
- [Mod Config](#mod-config)
2020-09-14 16:56:42 +10:00
- [Building](#building)
- [Credits](#credits)
2020-10-05 23:13:09 +11:00
## Releases
2020-11-12 15:58:28 +11:00
| Mod Loader | IL2CPP | Mono |
| ----------- | ------ | ---- |
2021-03-10 05:04:43 +11:00
| [BepInEx](https://github.com/BepInEx/BepInEx) 6.X | ✅ [link](https://github.com/sinai-dev/UnityExplorer/releases/latest/download/UnityExplorer.BepInEx.Il2Cpp.zip) | ❔* [link](https://github.com/sinai-dev/UnityExplorer/releases/latest/download/UnityExplorer.BepInEx6.Mono.zip) |
| [BepInEx](https://github.com/BepInEx/BepInEx) 5.X | ❌ n/a | ✅ [link](https://github.com/sinai-dev/UnityExplorer/releases/latest/download/UnityExplorer.BepInEx5.Mono.zip) |
| [MelonLoader](https://github.com/HerpDerpinstine/MelonLoader) 0.3 | ✅ [link](https://github.com/sinai-dev/UnityExplorer/releases/latest/download/UnityExplorer.MelonLoader.Il2Cpp.zip) | ✅ [link](https://github.com/sinai-dev/UnityExplorer/releases/latest/download/UnityExplorer.MelonLoader.Mono.zip) |
| Standalone | ✅ [link](https://github.com/sinai-dev/UnityExplorer/releases/latest/download/UnityExplorer.Standalone.Il2Cpp.zip) | ✅ [link](https://github.com/sinai-dev/UnityExplorer/releases/latest/download/UnityExplorer.Standalone.Mono.zip) |
2020-09-14 16:56:42 +10:00
2021-03-09 22:28:43 +11:00
\* BepInEx 6.X Mono release may not work on all games yet.
2020-10-08 06:15:42 +11:00
## Features
2020-11-17 17:08:11 +11:00
<p align="center">
<a href="https://raw.githubusercontent.com/sinai-dev/UnityExplorer/master/img/preview.png">
<img src="img/preview.png" />
</a>
</p>
2020-10-08 06:15:42 +11:00
* <b>Scene Explorer</b>: Simple menu to traverse the Transform heirarchy of the scene.
* <b>GameObject Inspector</b>: Various helpful tools to see and manipulate the GameObject, similar to what you can do in the Editor.
* <b>Reflection Inspector</b>: Inspect Properties and Fields. Can also set primitive values and evaluate primitive methods.
* <b>Search</b>: Search for UnityEngine.Objects with various filters, or use the helpers for static Instances and Classes.
* <b>C# Console</b>: Interactive console for evaluating C# methods on the fly, with some basic helpers.
2021-03-11 17:57:58 +11:00
* <b>Inspect-under-mouse</b>: Hover over an object with a collider and inspect it by clicking on it. There's also a UI mode to inspect UI objects.
2020-10-08 06:15:42 +11:00
2021-03-25 18:47:52 +11:00
### C# Console Tips
The C# Console can be used to define temporary classes and methods, or it can be used to evaluate an expression, but you cannot do both at the same time.
For example, you could run this code to define a temporary class (it will be visible within the console until you run `Reset();`).
```csharp
public class MyClass
{
public static void Method()
2021-03-25 18:48:40 +11:00
{
UnityExplorer.ExplorerCore.Log("hello");
}
2021-03-25 18:47:52 +11:00
}
```
You could then delete or comment out the class and run the following expression to run that method:
```csharp
MyClass.Method();
```
However, you cannot define a class and run it both at the same time. You must either define class(es) and run that, or define an expression and run that.
You can also make use of the helper methods in the console to simplify some tasks, which you can see listed when the console has nothing entered for input. These methods are **not** accessible within any temporary classes you define, they can only be used in the expression context.
2020-08-07 22:24:42 +10:00
## How to install
2020-11-12 15:58:28 +11:00
### BepInEx
2020-08-07 22:24:42 +10:00
Note: For IL2CPP you should use [BepInEx 6 (Bleeding Edge)](https://builds.bepis.io/projects/bepinex_be), for Mono you should use [BepInEx 5](https://github.com/BepInEx/BepInEx/releases) (until Mono support stabilizes in BepInEx 6).
2020-11-12 15:58:28 +11:00
0. Install [BepInEx](https://github.com/BepInEx/BepInEx) for your game.
1. Download the UnityExplorer release for BepInEx IL2CPP or Mono above.
2020-12-31 18:34:26 +11:00
2. Take the `UnityExplorer.BIE.___.dll` file and put it in `[GameFolder]\BepInEx\plugins\`
2021-01-28 02:09:40 +11:00
3. In IL2CPP, it is highly recommended to get the base Unity libs for the game's Unity version and put them in the `BepInEx\unity-libs\` folder.
2020-11-12 15:58:28 +11:00
### MelonLoader
Note: You must use version 0.3 of MelonLoader or greater. Version 0.3 is currently in pre-release, so you must opt-in from your MelonLoader installer (enable alpha releases).
2020-11-12 15:58:28 +11:00
0. Install [MelonLoader](https://github.com/HerpDerpinstine/MelonLoader) for your game.
1. Download the UnityExplorer release for MelonLoader IL2CPP or Mono above.
2021-01-03 19:27:02 +11:00
2. Take the contents of the release and put it in the `[GameFolder]\Mods\` folder. It should look like `[GameFolder]\Mods\UnityExplorer.ML.___.dll`
2020-08-07 22:24:42 +10:00
2021-01-20 19:10:13 +11:00
### Standalone
2021-03-11 18:32:57 +11:00
The standalone release is based on the BepInEx build, so it requires Harmony 2.0 (or HarmonyX) to function properly.
2021-03-09 22:29:53 +11:00
0. Load the DLL from your mod or inject it. You must also make sure that the required libraries (Harmony, Unhollower for Il2Cpp, etc) are loaded.
2021-03-11 17:57:58 +11:00
1. Create an instance of Unity Explorer with `ExplorerStandalone.CreateInstance();`
2. Optionally subscribe to the `ExplorerStandalone.OnLog` event to handle logging if you wish.
2021-03-11 17:57:58 +11:00
## Logging
Explorer saves all logs to disk (only keeps the most recent 10 logs). They can be found in a "UnityExplorer" folder in the same place as where you put the DLL file.
These logs are also visible in the Debug Console part of the UI.
2021-01-20 19:10:13 +11:00
## Settings
2020-09-10 20:35:41 +10:00
You can change the settings via the "Options" page of the main menu, or directly from the config file (generated after first launch). The config file will be found either inside a "UnityExplorer" folder in the same directory as where you put the DLL file, or for BepInEx it will be at `BepInEx\config\UnityExplorer\`.
2020-09-10 20:36:24 +10:00
2020-11-12 15:58:28 +11:00
`Main Menu Toggle` (KeyCode)
* Default: `F7`
2020-09-10 20:35:41 +10:00
* See [this article](https://docs.unity3d.com/ScriptReference/KeyCode.html) for a full list of all accepted KeyCodes.
`Force Unlock Mouse` (bool)
2020-11-12 15:58:28 +11:00
* Default: `true`
* Forces the cursor to be unlocked and visible while the UnityExplorer menu is open, and prevents anything else taking control.
2020-09-10 20:35:41 +10:00
2020-11-12 15:58:28 +11:00
`Default Page Limit` (int)
* Default: `25`
2020-10-01 20:26:25 +10:00
* Sets the default items per page when viewing lists or search results.
2020-11-12 15:58:28 +11:00
* <b>Requires a restart to take effect</b>, apart from Reflection Inspector tabs.
2020-08-30 16:49:44 +10:00
2020-11-12 15:58:28 +11:00
`Default Output Path` (string)
2020-11-23 21:16:29 +11:00
* Default: `Mods\UnityExplorer`
* Where output is generated to, by default (for Texture PNG saving, etc).
2020-08-30 16:49:44 +10:00
2020-11-12 15:58:28 +11:00
`Log Unity Debug` (bool)
* Default: `false`
* Listens for Unity `Debug.Log` messages and prints them to UnityExplorer's log.
2020-09-14 17:07:52 +10:00
`Hide on Startup` (bool)
* Default: `false`
* If true, UnityExplorer will be hidden when you start the game, you must open it via the keybind.
2020-09-08 20:18:37 +10:00
## Building
2021-03-26 05:40:12 +11:00
If you'd like to build this yourself, all you need to do is download this repository and build from Visual Studio.
2020-09-08 20:18:37 +10:00
1. Open the `src\UnityExplorer.sln` project.
2021-03-26 05:40:12 +11:00
2. Select `Solution 'UnityExplorer' (1 of 1 project)` in the Solution Explorer panel, and set the <b>Active config</b> property to the version you want to build, then build it. Alternatively, use "Batch Build" and select all releases.
3. The DLLs are built to the `Release\` folder in the root of the repository.
2020-08-08 00:02:32 +10:00
2021-03-26 05:40:12 +11:00
The references are all inside the `lib\` folder, if you need to change them for some reason then you can replace them there.
2020-08-08 00:02:32 +10:00
2021-03-26 05:40:12 +11:00
## Acknowledgments
2020-11-17 17:56:48 +11:00
* (GPL) [ManlyMarco](https://github.com/ManlyMarco)'s [Runtime Unity Editor](https://github.com/ManlyMarco/RuntimeUnityEditor), which I used for some aspects of the C# Console and Auto-Complete features. The snippets I used are indicated with a comment.
* (MIT) [denikson](https://github.com/denikson) (aka Horse)'s [mcs-unity](https://github.com/denikson/mcs-unity). I commented out the `SkipVisibilityExt` constructor since it was causing an exception with the Hook it attempted in IL2CPP.
2021-03-26 05:40:12 +11:00
* (Apache) [HerpDerpenstine](https://github.com/HerpDerpinstine) for [MelonCoroutines](https://github.com/LavaGang/MelonLoader/blob/master/MelonLoader.Support.Il2Cpp/MelonCoroutines.cs), which were included for standalone Il2CPP coroutine support.
2021-03-18 18:52:30 +11:00
* (Apache) [InGameCodeEditor](https://assetstore.unity.com/packages/tools/gui/ingame-code-editor-144254) was used as the base for the syntax highlighting for UnityExplorer's C# console, although it has been heavily rewritten and optimized. Used classes are in the `UnityExplorer.UI.Main.CSConsole.Lexer` namespace.