diff --git a/Dependencies/README.md b/Dependencies/README.md index 8a5638e..31e9c50 100644 --- a/Dependencies/README.md +++ b/Dependencies/README.md @@ -10,3 +10,4 @@ Please use your own copies of FEZ's binaries. This directory should contain the - FNA.dll - MonoMod.exe - MonoMod.Utils.dll +- MonoMod.RuntimeDetour.dll diff --git a/Docs/additional.md b/Docs/additional.md new file mode 100644 index 0000000..95f8673 --- /dev/null +++ b/Docs/additional.md @@ -0,0 +1,8 @@ +# Additional HAT behaviour + +Apart from loading mods, HAT does some additional internal behaviour worth mentioning. Here's a full list: + +- `FezLogo` class has been patched in order to draw HAT logo and mod loader tooltip. +- Several methods in `Logger` class have been hooked to override location of debug log files (they're now stored in `%appdata%/FEZ/Debug Logs` directory) and to show an error with stack trace on fatal error. +- `StaticText` class used to fetch localized text has been patched to return a raw string if it's prefixed by `@`. This is useful when you want to create your own menus where you have limited control over how text is displayed. +- `Menu Base` class' `Initialize` method has a hook which adds an additional `MODS` menu, where you can preview a list of currently installed modifications. diff --git a/Docs/createmods.md b/Docs/createmods.md new file mode 100644 index 0000000..5f2cc97 --- /dev/null +++ b/Docs/createmods.md @@ -0,0 +1,59 @@ +# Create your own HAT modifications + +## Basic mod architecture + +Start by creating a mod's directory within `FEZ/Mods` directory. You can name it whatever you'd like, as the mod loader doesn't actually use it for mod identification, but it would be nice if it at least contained the actual mod's name to avoid confusion. + +Mod loader expects `Metadata.xml` file in the mod's directory. Create one in a directory you've just made. Its content should look roughly like this: + +```xml + + YourModName + Short description of your mod. + YourName + 1.0 + + + + + +``` + +`Name` tag is required and is treated as an unique case-sensitive identifier of your mod - mod loader will load only one mod with the same name (it'll choose the one with the most recent version). + +`Version` tag is also required. Mod loader compares two version strings by putting them in an alphanumberical order, however, each number is treated as a separate token, which order is determined by numberical value (this means `1.2beta` will be treated as older version to `1.11`). + +`LibraryName` is used to determine a DLL library with C# assembly the mod loader will load. The library should end with `.dll` extension and should be placed in your mod's directory. This tag is optional, as your mod doesn't have to add any new logic. + +`Dependencies` is a list of `DependencyInfo` tags. If your mod requires a specific version of HAT mod loader or relies on another mod, your can use these tags to prevent mod loader from loading this mod if given dependencies aren't present. It's entirely optional. + +All other fields are purely informational. + +## Creating asset mod + +If you want to add new assets or override existing ones, create `Assets` directory within your mods directory. All valid files within it will be loaded as game assets with path relative to the `Assets` directory. Currently, the only supported format is `.xnb`, but in the future, a conversion from popular file formats will be implemented, allowing much easier modding process (for isntance, PNG files will be automatically converted to Texture2D assets). As of right now, there isn't really a good way of creating `.xnb` assets and you have to rely on [FEZRepacker](https://github.com/Krzyhau/FEZRepacker). + +As an example, here's an instruction on how to change Gomez's house background plane. Keep in mind that right now this process is unnecessarily convoluted and will definitely be simplified with the next FEZRepacker update: + +1. Use FEZRepacker to unpack game's `Other.pak` archive. +2. Find `background planes/gomez_house_a.png` file and copy it. +3. Create directory, name it something like `Export`. In it, create `background planes` directory and put a copy of PNG file there. +4. Edit the image however you'd like. +5. Use FEZRepacker to pack the `Export` directory into a PAK package. +6. Use FEZRepacker to unpack previously packed PAK file into XNB files. You should have a modified `gomez_house_a.xnb` file. +7. In your mod's `Assets` directory, create `background planes` directory and put your XNB file there. +8. From now on Gomez's house should have your modified texture. + +## Creating custom logic mod + +Mod loader loads library file given in metadata as an assembly, then attempts to create instances of every public class inheriting from game's `IGameComponent` interface before initialization (before any services are created). After the game has been initialized (that is, as soon as all necessary services are initiated), it adds created instances into the list of game's components and initializes them, allowing their `Update` and `Draw` (use `DrawableGameComponent`) to be properly executed within the game's loop. + +In order to create a HAT-compatible library, start by creating an empty C# library project. Then, add `FEZ.exe`, `FezEngine.dll` and all other needed game's dependencies as references - make sure to set "Copy Local" to "False" on all of those references, otherwise you will ship your mod with copies of those files. + +Once you have your project done, create a public class inheriting from either `GameComponent` or `DrawableGameComponent` and add your logic there. Once that's done, build it and put it in the mod's directory. + +For help, you can see an example of already functioning custom logic mod: [FEZUG](https://github.com/Krzyhau/FEZUG). + +## Distributing your mod + +Mod loader is capable of loading ZIP archives the same way directories are loaded. Simply pack all contents of your mod's directory into a ZIP file. In order for other people to use it, they simply need to put the archive in the `FEZ/Mods` directory and it should work right off the bat. diff --git a/Docs/thumbnail.png b/Docs/thumbnail.png new file mode 100644 index 0000000..c4d8a87 Binary files /dev/null and b/Docs/thumbnail.png differ diff --git a/README.md b/README.md index 1472aab..8c8aeef 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,17 @@ -# HAT +# HAT - Simple mod loader for FEZ -## Overview +![Thumbnail](Docs/thumbnail.png) -**HAT** is a [MonoMod](https://github.com/MonoMod/MonoMod)-based mod loader for FEZ, currently in development. When patched into the FEZ instance, it can be used to dynamically load game modifications on the game launch. The mods themselves can add/override assets or inject its own logic. +## Overview -## Building +**HAT** is a [MonoMod](https://github.com/MonoMod/MonoMod)-based mod loader for FEZ, currently in development. Its main purpose is to make process of FEZ modding slightly easier for end user. -1. Clone repository. -2. Copy all dependencies listed in `Dependencies` directory and paste them into said directory. -3. Build it. idk. it should work. +When patched into the FEZ instance, it can be used to dynamically load game modifications on the game launch. Correctly prepared mods can add/override game assets or inject its own logic through custom-made plugin. ## Installing mod loader 1. Download [MonoMod](https://github.com/MonoMod/MonoMod/releases) (for .NET 4.5.2) and unpack it in the game's directory. -2. Put FEZ.HAT.mm.dll in the game's directory. +2. Download latest `FEZ.HAT.mm.dll` from Release tab and put it in the game's directory. 3. Run command `MonoMod.exe FEZ.exe` (or drag `FEZ.exe` onto `MonoMod.exe`). This should generate new executable file called `MONOMODDED_FEZ.exe`. 4. Run `MONOMODDED_FEZ.exe` and enjoy modding! @@ -21,38 +19,22 @@ In the future, this process will be automated by a custom-made installer/mod man ## Adding mods -1. On first HAT launch, "Mods" directory should be created in the executable's directory. If not, create it. -2. Put a mod in this directory +1. On first HAT launch, `Mods` directory should be created in the executable's directory. If not, create it. +2. Download the mod's archive and put it in this directory. 3. Start the game. It's that simple! -## Creating your own mod - -1. Create a mod's directory. You can name it whatever, but it would be nice if it at least contained the actual mod's name to avoid confusion. - -2. In your mod's directory, create `Metadata.xml` file. Its content should look roughly like this: - -```xml - - YourModName - Short description of your mod. - YourName - 1.0 - - -``` +## Building HAT -3. If you want to add new assets or override existing ones, create `Assets` directory within your mods directory. All valid files within it will be loaded as game assets with path relative to the `Assets` directory. Currently, the only supported format is `.xnb`. As of right now, there isn't really a good way of creating `.xnb` assets and you have to rely on [FEZRepacker](https://github.com/Krzyhau/FEZRepacker). - -4. If you want to append a library with a custom logic, put it in your mod's directory and put its name with extension into the `LibraryName` property in mod's metadata. The library will be loaded only if its extension ends with `.dll`. - -## Creating custom logic - -Mod loader loads library file given in metadata as an assembly, then attempts to create instances of every public class inheriting from game's `IGameComponent` interface before initialization (before any services are created). After the game has been initialized, it adds created instances into the list of game's components and initializes them, allowing their `Update` and `Draw` (use `DrawableGameComponent`) to be properly executed within the game's loop. - -In order to create a HAT-compatible library, start by creating an empty C# library project. Then, add `FEZ.exe`, `FezEngine.dll` and all other needed game's dependencies as references - make sure to set "Copy Local" to "False" on all of those references, otherwise you will ship your mod with copies of those files. +1. Clone repository. +2. Copy all dependencies listed in `Dependencies` directory and paste them into said directory. +3. Build it. idk. it should work. -Once you have your project done, create a public class inheriting from either `GameComponent` or `DrawableGameComponent` and add your logic there. Once that's done, build it and put it in the mod's directory. +## "Documentation" +- [Create your own HAT modifications](/Docs/createmods.md) +- [Additional HAT behaviour](/Docs/additional.md) -For help, you can see an example of already functioning mod: [FEZUG](https://github.com/Krzyhau/FEZUG). +## Mods created for HAT +- [FEZUG](https://github.com/Krzyhau/FEZUG) - a power tool for speedrun practicing and messing with the game (NOT PORTED YET) +- [FezSonezSkin](https://github.com/Krzyhau/FezSonezSkin) - mod replacing Gomez skin with Sonic-like guy seen in Speedrun Mode thumbnail (NOT PORTED YET)