introduction
a runtime mod framework for native apps, and the tools for adapting it to each build.
what fpui is
fpui is a runtime mod framework for native apps. it works on the app’s machine code: a loader injects an in-process agent, the agent finds and checks the sites a mod changes, native backends apply byte patches and detours, and a sandboxed webassembly host runs plugins on hooks the app defines. the engine reads no ui framework’s types and depends on none, so its core does not change when a target uses a different or custom native framework.
the engine gives hooks and capabilities no meaning of its own: each app names them and defines what every payload holds. themes work the same way, with generic color roles and value encodings. the HSLA mapping used by current gpui targets and the native scene and settings experiments are target-specific integrations, not requirements of the engine.
an adapter connects those reusable parts to one specific executable build. it maps named colors, event hooks, and supported operations to concrete machine-code sites, located by pinned offsets, byte signatures, or string anchors and checked against expected bytes, so themes and plugins can express intent without hard-coding every address. each new target needs its own mappings and knowledge of its calling conventions.
live themes, event hooks that feed wasm plugins, argument and return overrides, and fixed-length byte patches have been demonstrated on controlled native targets on macos arm64. replacing a whole function with a fixed result is implemented and unit tested, but not yet proven end to end. site discovery has also been exercised on stripped release binaries. a javascript plugin backend exists behind the experimental js feature but is not yet wired into the agent’s plugin loading. complete application support still depends on validating the whole workflow for that build.
the modding tools
the framework includes tools for the work around a patch, from finding its location to checking whether an application update has moved it.
| tool | what it helps you do |
|---|---|
| discovery | locate sites by symbol, offset, or referenced string, and generate signature-equipped entries |
| adapters | describe a supported build, its identity, the exact sites your mod can change, and the hook each event feeds |
| monitor | check color, event, and byte-patch sites against a binary without running or modifying it |
| loader and agent | load into a compatible target, check each site, and apply the supported changes |
| theme system | map a palette onto the application’s supported named roles |
| plugin sdk and host | build wasm extensions that transform or observe app-defined hooks, behind granted capabilities and resource limits |
| bundle wrapper | configure a development app to load the agent on normal launches |
start from the source repository and development setup. the update guide covers discovery and monitoring, and the reference explains the adapter contract.
how it works
- describe the build. an adapter records the executable identity and the color sites, function entries, and patches it supports.
- load the agent. launching through the loader checks the whole-file identity first. inside the app, the agent resolves and checks each site’s expected bytes before changing it, and skips any site it cannot match.
- apply the customization. themes supply colors, plugins transform or observe app-defined hooks within granted capabilities, and native backends change the operations mapped by the adapter.
create a theme, write a plugin, or use the native primitives to adapt an application. each route needs a compatible target build; see status and roadmap for the current boundaries.