-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into wiki/docs/faq-explain-northstar
- Loading branch information
Showing
86 changed files
with
9,008 additions
and
145 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,16 +1,20 @@ | ||
| Titanfall 2 + Northstar Modding Docs | ||
| ==================================== | ||
| # NorthstarDocs | ||
|
|
||
| This repo contains documentation and guides on most things you need to know about creating mods for Northstar. | ||
| This repo contains documentation and guides on most things you need to know about using and creating mods for Northstar. | ||
|
|
||
| It is partitioned into: | ||
| - the **Wiki** section which contains a variety of information on how to install and use Northstar as well as troubleshooting tips. | ||
| - the **Modding** section which contains all the information necessary to create mods for Northstar as well as further technical details for developing for Northstar. | ||
|
|
||
| Especially the technical documentation is not done yet and might be incorrect or outdated in some places. | ||
|
|
||
| If you have some knowledge to share, but don't want to write a PR, you can make an issue explaining what you know and we can try to integrate that into the docs. | ||
|
|
||
| Contributing | ||
| ------------ | ||
| ## Contributing | ||
|
|
||
| The only prerequisites are python and pip. On Linux simply run `run.sh` in the root dir and in windows execute `run.ps1` with powershell in the root dir. You may need to change the Powershell execution policies in order to run the script. | ||
|
|
||
| Running the script will install all dependencies required and build the docs locally. The local version is available at [port 8000](http://127.0.0.1:8000/). The server will get opened in your browser when the script finishes. | ||
| When you change a file the server will automatically rebuild it and refresh your browser window. | ||
|
|
||
| If you get an error message while running the script on Windows, check the following GitHub issue: https://github.com/R2Northstar/NorthstarDocs/issues/106 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Available interfaces | ||
|
|
||
| !!! note | ||
|
|
||
| Not every interface is documented here. | ||
|
|
||
| Feel free to add more or tell us which ones are missing. | ||
|
|
||
| Multiple binaries of the game expose interfaces you can use. | ||
|
|
||
| This section aims to document all of them incrementally. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Northstar | ||
|
|
||
| All interfaces exposed by Northstar. | ||
|
|
||
| ## ISys | ||
|
|
||
| !!! cpp-class "ISys" | ||
|
|
||
| Provides basic functions to interact with northstar. | ||
|
|
||
| !!! cpp-function "void Log(HMODULE pluginHandle, LogLevel level, char* msg)" | ||
|
|
||
| Log a message using the console managed by northstar. | ||
|
|
||
| Messages logged using this method are prefixed with the `LOG_NAME` retrieved via your `PluginId` implementation and printed to the game's console. | ||
|
|
||
| !!! cpp-function "void Unload(HMODULE pluginHandle)" | ||
|
|
||
| Gracefully unload a plugin (usually your own plugin) | ||
|
|
||
| !!! cpp-function "void Reload(HMODULE pluginHandle)" | ||
|
|
||
| Reload a plugin. The plugin can know if it has been reloaded via the `reloaded` parameter passed in the `Init` callback exposed in the `IPluginCallbacks` Interface. | ||
|
|
||
| !!! cpp-enum "LogLevel : i32" | ||
|
|
||
| !!! cpp-member "INFO = 0" | ||
|
|
||
| !!! cpp-member "WARN = 0" | ||
|
|
||
| !!! cpp-member "ERR = 0" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| # Plugins | ||
|
|
||
| !!! note | ||
|
|
||
| Writing plugins require some very basic familiarity with C++ | ||
|
|
||
|
|
||
| Plugins are native modules loaded by Northstar. Because they're not limited to any API provided by the game, plugins are a powerful tool to enable you to do almost anything you could with a custom Northstar Client. | ||
|
|
||
| For example, you could write a plugin that [compiles maps](https://github.com/catornot/furnace) at runtime, allows squirrel scripts to save and load recorded animations [from disk](https://github.com/uniboi/recanim) or provide [discord rpc](https://github.com/R2Northstar/NorthstarDiscordRPC) integration. | ||
|
|
||
| However because plugins have full access to your system plugins should be treated with caution and regular scripts are preferred if possible. | ||
|
|
||
| ## Installation | ||
|
|
||
| Any `.dll` file located in the directories `<Northstar Profile>/plugins/` and `<Northstar Profile>/packages/<Thunderstore package>/plugins/` will be attempted to load as a plugin. | ||
|
|
||
| To manually install a plugin, copy the plugin `.dll` into the `<Northstar Profile>/plugins/` directory. | ||
|
|
||
| !!! note | ||
|
|
||
| The default northstar profile name is `R2Northstar`. Profiles are located in the same location as `NorthstarLauncher.exe`. | ||
|
|
||
|
|
||
| Any Plugin is only valid if it exposes every required [interface](interfaces.md). | ||
|
|
||
| If a plugin does not expose every Interface the Launcher requires, it is unloaded immediately. | ||
|
|
||
| ## Development | ||
|
|
||
| To debug a plugin it's recommended to compile Northstar itself or download the debug data from the [Release Page](https://github.com/R2Northstar/NorthstarLauncher/releases). | ||
|
|
||
| When developing a plugin it's usually easier to output the binary directly in the `<profile>/plugins/` directory, the `packages/` directory is usually only used for complete packaged mods downloaded from Thunderstore. | ||
|
|
||
| ### Valid plugins | ||
|
|
||
| Every plugin must fulfill these criteria to be considered valid by Northstar. | ||
|
|
||
| Invalid plugins get unloaded as soon as possible. | ||
|
|
||
| - The plugin module must export a function named [`CreateInterface`](interfaces.md/#createinterface) that returns an interface instance when called. | ||
|
|
||
| - Every [required interface](required-interfaces.md) must be exposed via `CreateInterface` | ||
|
|
||
| ### Debugging | ||
|
|
||
| If you know how to use a debugger you can safely skip this. | ||
|
|
||
| For simplicity it's assumed your development environment is Visual Studio and you're compiling Northstar from source. | ||
|
|
||
| Otherwise are the steps basically the same everywhere else. | ||
|
|
||
| 1. Clone the [Launcher](https://github.com/R2Northstar/NorthstarLauncher) | ||
|
|
||
| 2. Set the binary output directory to the location wherever you have installed your game. The compiled `NorthstarLauncher.exe` should be outputted next to `Titanfall.exe`. | ||
|
|
||
| 3. Launch `NorthstarLauncher.exe` with a debugger or attach a debugger to a running process | ||
|
|
||
| 4. Load debug symbols of your plugin(s) (for example `myplugin.pdb`) in the debugger | ||
|
|
||
| That's it. | ||
|
|
||
| ### Hooks | ||
|
|
||
| Any Plugin can install hooks anywhere in memory it desires. However, plugins should avoid hooks if possible because of conflicts with Northstar itself or hooks installed by other plugins. | ||
|
|
||
| It is not generically possible to determine if a given address has already been hooked by a different plugin and there is currently **no mechanism for plugins to share information which addresses have hooks installed**. | ||
|
|
||
| Northstar does not expose an interface to (un)install hooks. Every plugin is expected to use their own provider. | ||
|
|
||
| ## Examples and Libraries | ||
|
|
||
| - A small plugin [""framework""](https://github.com/uniboi/NSPluginTemplate/) to show the basics of writing plugins and Squirrel bindings in C | ||
|
|
||
| - A complete [Rust plugin library](https://crates.io/crates/rrplug) that allows you to easily integrate safely with large parts of the engine itself |
Oops, something went wrong.