mirror of
https://github.com/valentderah/totk-pc-recomp.git
synced 2026-11-21 04:55:56 +00:00
The rebuild builds mod plugins in: service run, checks, patch sets and status lines (#845)
After the design in #845 by itaskaev2. tools/exefs_plugins.py writes an accepted plugin's patch set (recomp/patches.py plugin lines and hook sites, one ordered set mod_<hash> per plugin, several plugins in one record told apart by their hooks) and a line per plugin of build-cache/plugins.status: built, or refused with the first reason. It also checks the code the hooks reach (direct branches and calls from the stubs, impls, callbacks and targets): no svc but OutputDebugString, imports only from a reviewed list. The init's imports may now include malloc, free, memcpy, memmove and memset, because the init runs again at every start and its heap blocks exist while the game runs. The setup's lift step runs the plugin stage when a mod has exefs/subsdk*: a lift with the plugins, a totk.exe of it in the compile step's folder, the service run, then the lift with the hook sites; a failed stage warns (warn.plugins_skipped) and installs without the plugins. docs/mods.md describes what works, what is refused and why, and the rebuild. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
d865000929
commit
8cee1afe5d
11 files changed
+671
-34
No files matched your search
+34
-3
@@ -49,8 +49,8 @@ named ones.
|
||||
|
||||
### Mods with code the port cannot run
|
||||
|
||||
Some mods bring code the port cannot run: their own Switch code (a subsdk plugin or a replaced main, as UltraCam ships)
|
||||
or a code patch in a form the port cannot apply. Such a mod stays off as a whole, because its other files may expect
|
||||
Some mods bring code the port cannot run: their own Switch code (a replaced main, or a subsdk plugin the rebuild
|
||||
refused, as it refuses UltraCam's) or a code patch in a form the port cannot apply. Such a mod stays off as a whole, because its other files may expect
|
||||
that code. Under its row the Mods tab then shows **Use <mod> without its code** (off by default). Switched on, the code
|
||||
the port cannot run is left out and the rest of the mod loads after a restart: its game files, cheats and the code
|
||||
patches that work. The mod's row says which part is left out and why. If the game misbehaves with it, switch it off
|
||||
@@ -96,6 +96,35 @@ A patch file may also change the game's data (constants and tables in its `.roda
|
||||
stored into the loaded game at start, before it runs. When two mods write the same bytes, the higher one wins,
|
||||
as with files.
|
||||
|
||||
## Code plugins (exefs subsdk)
|
||||
|
||||
Some mods ship their own Switch code as an exlaunch plugin: a file `exefs\subsdk<N>` (The Second Quest's MSFix, Full
|
||||
Inventory Expansion's sort fixer, Quick Weapon Durability). On the Switch the plugin starts with the game and
|
||||
redirects some of the game's instructions into its own code. The port does the same with the plugin's code compiled
|
||||
ahead of time, after the design in [#845](https://github.com/valentderah/totk-pc-recomp/issues/845) by itaskaev2:
|
||||
|
||||
1. The rebuild (the same one as for code patches above) compiles the plugin with the game, starts the game's code
|
||||
once in a service mode that runs only the plugin's start-up (`totk.exe --plugin-init`), twice, and records which
|
||||
instructions it redirects. Each redirect becomes a code site of the mod, built into `totk.exe`.
|
||||
2. At every start the plugin's start-up runs again, before the game's own start-up code, in the same setting. Its
|
||||
redirects are compared with the record of the rebuild. When they match, the mod's code sites go on. When they do
|
||||
not, the plugin stays off for this run, the mod's row says why, and the next start runs the rebuild.
|
||||
3. The plugin keeps what its start-up made (its memory, its tables), so its code works as on the Switch. The start
|
||||
costs about 50 ms per plugin; the game runs no differently without a plugin.
|
||||
|
||||
The Mods tab order decides between a plugin and another mod's patch on the same instruction, as for code patches. A
|
||||
plugin site over one of the port's own patches turns that built-in patch off while the mod is on.
|
||||
|
||||
The rebuild refuses a plugin when its start-up or the code its redirects reach needs what the port does not give it:
|
||||
system calls other than the few its start-up needs (memory queries and maps, the clock, debug output), library calls
|
||||
outside a reviewed list (memory and string functions, the heap, text formatting), threads, services or input; a
|
||||
redirect that is not one of exlaunch's hook shapes (inline hook, replace hook, call-site rewrite); or two runs of its
|
||||
start-up that differ in code. The row then says **Its plugin ... cannot run in the port** with the reason, and the
|
||||
mod stays off; **Use <mod> without its code** uses the rest of it. UltraCam stays refused: it hooks the graphics API,
|
||||
reads input and opens sockets.
|
||||
|
||||
`plugin_trace = 1` in `totk.ini` logs the first call into each of a plugin's hooks (`plugins: hook entry ... reached`).
|
||||
|
||||
## Cheats
|
||||
|
||||
A cheat file is part of a mod: `mods\<mod>\cheats\<build id>.txt`, switched cheat by cheat on the Cheats tab. Cheats
|
||||
@@ -134,7 +163,9 @@ keeps its textures at a quarter of the size.
|
||||
| This folder has no romfs, exefs or cheats files. | The archive was unpacked one level too deep (`mods\Mod\Mod\romfs`), or it holds no game files. | Move the folders up so `romfs` sits directly in the mod's folder. |
|
||||
| ... files carry another game version in their names. | The files are named for another update (`.Product.<number>.`) and the game's own files have no such name. They are still served under those names, as on a console, because the game sometimes asks for one; another update's resource size table is the exception and only lends its entries. | Nothing if the mod works. If it does nothing, download its release for your game update. |
|
||||
| Its code patches (exefs) are made for another game version. | The patch files name another update's build id. | Same: get the release for your update. |
|
||||
| This mod brings its own game code (a subsdk plugin or a replaced main). | Mods such as UltraCam ship compiled Switch code. The port cannot load it. | The whole mod stays off. **Use <mod> without its code** under its row uses the rest of it, which may expect the missing code (see Mods with code the port cannot run). |
|
||||
| This mod brings its own game code (a subsdk plugin or a replaced main). | The mod replaces the game's main code, which the port cannot load. | The whole mod stays off. **Use <mod> without its code** under its row uses the rest of it, which may expect the missing code (see Mods with code the port cannot run). |
|
||||
| Its plugin ... cannot run in the port: ... | The rebuild refused the mod's code plugin; the reason follows (see Code plugins). | The whole mod stays off. **Use <mod> without its code** under its row uses the rest of it. |
|
||||
| Its plugin stays off this time: it started differently from the build. | The plugin redirected other instructions at this start than in the rebuild, for example after the mod was updated in place. | Nothing: the next start runs the rebuild. |
|
||||
| This mod patches the game code (exefs) in a way the port cannot apply. | The patch changes code in a form the port cannot build, or bytes the port cannot change at start. The reason follows on the row. | The whole mod stays off. **Use <mod> without its code** under its row leaves that patch file out and uses the rest of the mod. |
|
||||
| The folder name contains \|. | The mod list uses `\|` between names. | Rename the folder. |
|
||||
|
||||
|
||||
+2
-1
@@ -24,7 +24,8 @@ Many rows below are developer tools that only act together with another setting
|
||||
| `core_diag` | `1` records why ready guest threads wait for a virtual core and for how long, with a histogram every 60 presents. | Turns on host-call and SVC depth tracking and writes many log lines (one per present over 25 ms); frames get slower. | Caution |
|
||||
| `barrier_merge` (default `0`) | Experimental. `1` keeps a render pass open through the game's Barrier calls that ask only for fragment ordering and texture invalidation, when no draw of the pass can write a storage buffer or image; the next draw that samples a written target gets a by-region barrier in the pass (the feedback layout). In scenes with about a thousand such barriers a frame this cuts the passes from about 1200 to 130 and the GPU time from 24.5 to 7.8 ms. | The game's barrier orders every pixel, the in-pass by-region barrier only the pixel a draw writes: a driver that runs it per screen tile can show flicker or squares at the edges of water, decals or particles. | Caution |
|
||||
| `menu_cursor_log` | `1` logs what the menu cursor code reads at every screen change. | Only adds log lines. | Safe |
|
||||
| `plugin_tick_offset` (default `0`) | Added to every GetSystemTick in the plugin service run (`totk.exe --plugin-init DIR`), so `tools/exefs_plugins.py` can run a plugin's init twice with other ticks and compare the records. | Has no effect outside `--plugin-init`; the game never asks for GetSystemTick. | Safe |
|
||||
| `plugin_tick_offset` (default `0`) | Added to every GetSystemTick in the plugin service run (`totk.exe --plugin-init DIR`), so `tools/exefs_plugins.py` can run a plugin's init twice with other ticks and compare the records. | Has no effect outside `--plugin-init`; a plugin's init at the start of the game gets the plain ticks. | Safe |
|
||||
| `plugin_trace` | `1` logs the first call of each entry of a mod plugin's hooks (its callbacks, replace and call targets) as `plugins: hook entry ... reached`. | Each such call goes through a counting step; nothing changes without a mod plugin. | Safe |
|
||||
| `perf_slow_ms` (default `50`) | Frames at least this many milliseconds long get a `perf: slow frame` log line with the time blocked per cause. | Changes how many frames are logged; a small value fills the log. | Safe |
|
||||
| `replay_check` | `1` reads every texture read-back a second time after a full drain of the replay queue and compares the two. | Stalls the replay queue at every read-back, so frames get much slower; mismatches are only counted and logged. | Caution |
|
||||
| `resolve_check` | `1` compares every cached pool lookup with the locked lookup and stops on a difference. | Slows every pool lookup; the game stops if the two ever differ. | Caution |
|
||||
|
||||
Reference in new issue
Block a user