The native route
The native route lets a native mod change the game's own code: a function's body, a value or call inside it, or a hot loop. You declare it with [[native.*]] tables written after [native] in sunrise-mod.toml, and the launcher applies them to the prebuilt game without rebuilding the game.
From Sunrise's modding bookead8a1e
When to use it
Try these first. They work on native and wasm:
- a hook, a method of
mod_api::Hooksthat the game calls at one moment, or a Part method (Your first native mod); - an
[[inject]]listener: your function, run at the start or end of a game function withmod_apivalues (Injections).
Take the native route when neither can do it: you need the game's real types or private fields, a change in the middle of a function, a whole function replaced, or a change inside a hot loop. It is not for a wasm mod, which cannot declare [native] tables. Data kept on one entity or block is an attachment, not this route.
The tables
[[native.mixin]]- Use it to
- run code at the start or end of a game function, change a value or a call inside it, or replace its body
- Page
- Mixins
[[native.loop]]- Use it to
- run code before and after each entry of a hot loop the game publishes, such as the block entity tick
- Page
- Published loops
[[native.bridge]]- Use it to
- read, write or call a private field or method of a game type from your mixin code
- Page
- Bridges
[[native.module]]- Use it to
- add a module of your own code inside a game source file, for your mixin code to share
- Page
- Support modules
[[native.state]]- Use it to
- add a field to a game type: refused, use an attachment
- Page
- Native state
Every row of these tables has an id. No two rows of one mod share an id, counting [[inject]] rows too.
It is tied to one game build
A mod on this route builds against one exact game build: the commit in [native] sunrise. Your code gets the game's own types, such as Game and its fields, and these change between builds without notice.
- To move to a new build, change
sunriseand rebuild. A target that was renamed or moved fails the build with an error naming your mod. - A change elsewhere in a target's body is not reported. Reread the functions you target on each new build.
- Read the game's source at your
sunrisecommit on GitHub. Every target path, field and type on these pages comes from it. - This code runs with the player's rights. It is not sandboxed.
The [native] table
| Field | Value |
|---|---|
game | The Minecraft version, "26.3". |
sunrise | The game build: the exact Sunrise commit, 40 lowercase hex characters. |
mixins | The exact commit of the horizon-mixins tool, which applies [[native.mixin]] rows; 40 lowercase hex characters. |
cargo sunrise-mod new path/to/mod --template native writes all three; to move an existing mod, edit them. Otherwise the mod is an ordinary native mod (Your first native mod).
Building
Build as for any native mod: the launcher's Build, or sunrise-launcher native-build path/to/mod --trust-native-code. The flag says you trust the mod's code to run with your rights.
A build with a [[native.mixin]] row obtains the horizon-mixins tool for your mixins commit.
The prebuilt tool is checked against its release's SHA256SUMS and against the commit, patch and platform the launcher pins. Where no prebuilt exists for your platform or pin, the launcher builds the tool from source.
Read the launcher's build log (native/build.log, also available through Build log) for the number of patched functions and mixin rows.
What the launcher does under the hood is on How the native route works.
Chapters
- Changing the game's own code
- [Mixins: [[native.mixin]]](native-route/2-mixins.md)
- [Published loops: [[native.loop]]](native-route/3-loops.md)
- [Bridges: [[native.bridge]]](native-route/4-bridges.md)
- [Support modules: [[native.module]]](native-route/5-support-modules.md)
- [Native state: [[native.state]] is refused](native-route/6-native-state.md)
- How the native route works
Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.



