surface.json
From Sunrise's modding bookead8a1e
On this page
surface.json is the stable surface of one build: everything a mod on the mod API alone can name. It is generated from the declarations the build parses (sunrise-stage surface ROOT OUT), never kept by hand or committed, and is byte-identical for one commit: sorted, with no paths or timestamps.
Records
Every record has an id, unique in the document, and a hash over its contract. Members (a trait's methods, a type's fields and variants, a hook's arguments) are records of their own:
This table is generated when the book is built: see it in the published book.
An item's path is one a mod writes after mod_api::: the path of the module that defines it when that module is public, so a re-export added later never changes its id; otherwise its shortest public path. A record's paths lists every public path a mod can name it by. Types inside signatures are normalised Rust, with paths relative to mod_api and lifetimes kept.
cargo sunrise-mod hooks <text> searches these records offline (Commands).
What a hash covers
A record's hash covers its contract, not its doc, its paths, a hook's engine (where it fires) or counterparts (its names in NeoForge, Fabric and Paper), nor the wasm crossing details of a type. Each member has its own hash, so most additions change no existing hash: a new Host method, a new hook, a new hook argument or a new field on a type change nothing for a mod that doesn't use them. A container's hash covers its members only where a new member breaks users:
- an exhaustive enum's variants;
- the required methods of a trait mods may implement, and its supertrait bounds;
- a hook's side, kind, scope, whether it is cancellable, its context and host, its owner argument, and whether it has an output. Its arguments are member records; its
versionis outside the hash.
A struct's field set is outside its hash. Its fields_hash says whether a literal listing every field still builds, which matters only to a mod that builds it that way. A type's trait impls are a set beside the hash: one gained changes nothing, one lost is named by the fit test. The document's own hash is over every record's id and hash; sdk.json repeats it as surface.hash.
schema is a number: a reader refuses one it doesn't know and ignores fields it doesn't know.
What a change is
sunrise-stage surface-diff OLD NEW compares two documents by id. A record only in the new one is added, only in the old one removed; in both with another hash, changed. A rename shows as a removal and an addition. Each change is in one of three classes:
- Breaking: it can stop any mod that uses the item from compiling or meaning the same. A record removed; a contract changed (a hook's side or kind, a retyped field or argument, a signature, a method no longer on wasm); a variant added to an exhaustive enum; a required item added to a trait mods implement; an impl a type no longer has; a behaviour removed.
- Conditional: it breaks only some mods, which the fit test finds from each mod's source (except a behaviour's
version, which no fit report shows: a mod relies on a behaviour without naming it). A field added to a struct mods can build, or an argument added to a hook (only a mod that writes it out in full); a struct no longer constructible; a public path that goes (only a mod that writes that path); a hook'sversion(only a mod whose manifest names it) or a behaviour'sversion(only a mod that relies on it); a type's wire form or layout (wasm mods only). - Additive: a new record (a behaviour too), and changes that only widen an item: now on wasm, an impl gained, a new public path, an item no longer required, an enum no longer
#[non_exhaustive].
Each change says what changed in words a mod author can act on, for example `argument player: PlayerRef → ServerPlayerRef . cargo sunrise-mod sdk diff <build> <build>` prints the same report for two published builds.
When the verify check runs on a pull request that changes Rust, its summary carries this report, comparing the merge base with the head. It reports, and fails the check only when:
- the head's tree cannot be exported;
- a change note cannot be read, or names an item that did not change;
- a breaking change has no change note: every breaking record the report lists, members included (a removed field is its own line), is named by a note the pull request adds. Conditional and additive changes need none. The gate is
gate = trueintools/ci/surface.toml.
Command completion layouts
CommandSuggestion now carries an optional replace_start byte offset into the prefix. None replaces the whole prefix; Some(offset) preserves the text before that offset, which must be on a UTF-8 character boundary and not past the prefix. This changes the type's Wire layout: wasm mods using it must rebuild against this SDK. The optional tooltip is retained. See Server commands for replacement examples and the id argument's tab_complete completion route.
CommandArgumentType::suggest also requires the optional sender before the prefix. Providers own their sender policy; their returned suggestions remain unfiltered. Implement the required method explicitly, returning an empty list when the argument has no completions.
Change notes
A change can carry a note: one file per change in crates/sunrise-mod-vocab/changes/<name>.toml.
ids = ["hook:player_logged_in", "type:PlayerLoggedIn.player"]
why = "The hook now fires on the server only."
migrate = "Take `ServerPlayerRef` instead of `PlayerRef`." # optionalA note with an unknown key, a missing ids or why, an empty ids, or an id that did not change is refused. The SDK's sdk.json carries the notes of the changes since the SDK before it (surface.notes), and cargo sunrise-mod update prints a changed item's migrate line beside it.
Behaviours
A few promises are neither a type nor a signature, so no other record can pin them: how sunrise:add_to files merge, or what block entity a block with a vanilla template gets. Each is a behaviour:<name> record, generated from one file in crates/sunrise-mod-vocab/behaviours/<name>.toml (the file name is the name; there is no list to keep):
version = 1
doc = "What the engine promises, stated so that a test could check it."
tests = ["crates/sunrise-client/src/some_tests.rs::the_test_that_pins_it"]version starts at 1 and goes up when a mod that relies on the behaviour can see a different meaning. tests lists the tests that pin the promise, each as <file path from the repository root>::<fn name>; the export refuses a behaviour whose test has no fn of that name, and a malformed file, naming it. doc and tests are outside the record's hash.
The diff treats a behaviour like any record: a new one is additive, a removed one is breaking (so it needs a change note that names behaviour:<name>), and a version change is conditional, for the mods that rely on it. Nothing in a mod's code uses a behaviour, so it never appears in a fit report. Only promises kept across builds belong here, not diagnostics or behaviour that vanilla fixes.
Hook versions
A hook's version changes when a listener can see a different meaning under the same signature: its answer now decides the action, or the order or timing it observes changed. It stays when the engine is only corrected to the contract the hook already documents. Every bump comes with a change note in the same change, so sdk diff and cargo sunrise-mod update say what a listener must now do; the version is outside the hook's hash, so the diff counts a bump as a conditional change for the mods that name that version.
Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.



