Settings, logs and in-game tools
Sunrise reads one settings file at startup, writes one log, and has one in-game menu. The settings
code is in src/core/settings/, the log in src/core/logging/, and the menu in src/core/ui/.
The settings file
The file is bin/x64/Sunrise/settings.json. It sits in the Sunrise folder beside the DLL.
- If the file does not exist, Sunrise writes the default file there and uses it. The default is
resources/default_settings.json, built into the DLL. - Sunrise reads it once, at startup. Restart the game after a change.
- The file must be valid JSON and at most 1 MiB. A leading UTF-8 byte order mark is fine.
- Unknown keys are skipped. Most known keys may appear only once. A repeat is an error.
- A key you leave out keeps its built-in default.
If the file does not parse, Sunrise does not start. The reason goes to the debugger output as
ev=settings result=fail reason=<step>, because the log is not open yet.
The version key
The root version key is the layout version of the file. This build expects 19.
- A file at version
18is upgraded in place. Sunrise rewrites it to19and keeps every value you set. The debugger output getsev=settings stage=upgrade result=ok. - A file below
18, or with noversionkey, is deleted and replaced by the default file. Your changes in it are lost. Copy the values you want before you update. - A short co-op file with no
versionkey is kept as it is. - A file with a higher version is still read. A mismatch line goes to the debugger output.
Layout
{
"version": 19,
"multiplayer_enabled": false,
"join_code": "",
"core": { "logging": { ... }, "activity_sdk_generation": { ... }, "studio_attach": false },
"steam": { "language": "...", "user": { ... } },
"client": { "ui": { ... }, "external_server": { ... }, ... },
"server": { "max_players": 32, "bap_port": 30974, "bap_bind": "127.0.0.1", "gameplay": { ... }, "activation": { ... } },
"state": { "activity": { ... } },
"complete_exotic_catalysts": true
}
Main keys
The default is the value in the default file. Where a missing key takes a different built-in value, the table says so.
Core
| key | type | default | what it does |
|---|---|---|---|
core.logging.file_sink | bool | false | writes the log to Sunrise/logs/sunrise.log |
core.logging.debugger_sink | bool | true | sends each log line to the Windows debugger output |
core.logging.levels.<channel> | string | "warn" | the lowest level kept for that channel; see Log levels |
core.activity_sdk_generation.lua_declarations | bool | true | writes the sdk/lua tree that mission scripts use |
core.studio_attach | bool | false | lets Sunrise Studio attach to the running game |
Studio attaches through shared memory in the Windows session namespace. Only a program in your own
Windows session on this machine can reach it. There is no network path, so nothing remote can
attach. With studio_attach off, Sunrise opens no Studio link and installs none of its hooks. With
it on, Studio can read the camera, the world, placed objects, animation and the open CUI screens.
It can also ask the game to reload a mod’s mission scripts and packages, to reload the player’s
bubble, and to read and edit the account. See
The Sunrise Studio link.
Steam
| key | type | default | what it does |
|---|---|---|---|
steam.language | string | "english" | the game language; an unknown value falls back to english |
steam.user.persona_name | string | "Player" | your player name; 1 to 63 printable ASCII characters |
The accepted languages are english, french, german, italian, japanese, brazilian,
spanish, russian, polish, schinese, tchinese, latam and koreana. Any other value
writes ev=settings stage=language result=fallback to the debugger output. The game files for a
language come from its own Steam depot; see
Other languages.
Client
| key | type | default | what it does |
|---|---|---|---|
client.ui.enabled | bool | true | off: the menu key does nothing and no HUD overlay draws |
client.ui.toggle_key | string | "insert" | the key that opens and closes the menu |
client.ui.mission_variable_rows | int | 15 | rows the Mission Variables overlay shows, 1 to 48; see Debugging a script |
client.custom_bootflow_textures | bool | true | replaces some startup screen textures with ones built into Sunrise |
client.socket_menu_routing | bool | false | moves four leg mods into the leg mod menu |
client.reveal_lore_books | bool | true | clears the visibility gates on lore book entries |
client.cheats | bool | false | unlocks the cheat tools; the session then saves no progress |
client.exports.package_keys | bool | false | exports the installed package keys for Sunrise Studio during startup |
client.exports.tag_definitions | bool | false | exports the game’s tag definitions for Sunrise Studio during startup |
client.external_server.enabled | bool | false | sends the game’s traffic to another server instead of answering it in process |
client.external_server.host | string | "127.0.0.1" | that server’s IPv4 address; a host name is refused |
client.external_server.config_url | string | "https://127.0.0.1/config/" | the config URL handed to the game; must be a route that server serves |
client.external_server.config_guid | string | "d2legacy-0000-0000-0000-000000000001" | the 36-character config id the game checks the config against |
toggle_key accepts insert, home, end, delete and f1 to f12.
To prepare an install for Sunrise Studio, set client.exports.package_keys to true and start the
game once. Sunrise writes bin/x64/Sunrise/exports/package_keys.bin after its package reader is
ready. Studio reads that file from the selected install. Set the option back to false after the
file appears. Leaving it on replaces the same file on each successful startup.
client.exports.tag_definitions works the same way. Sunrise writes
bin/x64/Sunrise/exports/tagdefs-raw.<id>.json, where <id> is the start of the game executable’s
SHA-256. Studio’s tag registry is generated from this file. The export runs in the background, so it
can finish a few seconds after startup. The log line ev=tagdefs_dump reports the result.
The cheat tools are Teleport, Noclip, Fly and Sword Skate Fix on the Movement page, and Infinite
Ammo on the Player page. With cheats off they are locked and read as off, whatever movement.json
and player.json hold. With cheats on, the session plays on a copy of the save held in memory,
the same as with a cheat mod, so nothing earned that session is kept. A notice at startup says so,
and the Movement page says so above its tools. See
Cheat sessions. Anti AFK is not a cheat and stays
unlocked.
Server
| key | type | default | what it does |
|---|---|---|---|
server.bap_port | int | 30974 | the loopback port the BAP listener binds; SignOn hands it to the game |
server.gameplay.topology | string | "embedded" | who owns the gameplay UDP endpoint; see below |
server.gameplay.bind_address | string | "127.0.0.1" | the local interface the endpoint binds |
server.gameplay.advertised_address | string | "127.0.0.1" | the address the game is told to use |
server.gameplay.transport_address | string | "127.0.0.1" | the address the game’s packets land on after the redirect |
server.gameplay.port | int | 30976 | the first UDP port; must be even |
server.gameplay.relay_port | int | 32000; not in the default file | the relay UDP port; one that collides moves up by 2 |
server.gameplay.server_reserve_count | int | 256 | entity slots held back for server-made entities |
server.gameplay.client_join_grant_count | int | 8192 | entity slots the game gets on join, capped by what the reserve leaves |
server.gameplay.hold_launch_cinematic | bool | false; not in the default file | holds a launch sync open through the load so the spaceflight scenes are skipped |
server.activation.default_client_activation | bool | true | off: a request to start another activity is recorded and gets no answer |
server.activation.activity_public_membership | bool | true | sends membership on a public activity link |
server.activation.prevent_ownerless_channel_close | bool | false | diagnostic only; sets a game feature flag that keeps a channel open when its last owner leaves |
server.activation.mission_scripting | bool | true; false if missing | runs mission scripts |
topology takes one of three values:
| value | meaning |
|---|---|
embedded | Sunrise binds the gameplay UDP endpoint |
external | another process owns the endpoint |
disabled | no endpoint |
The gameplay block is checked as a whole. With a topology other than disabled:
portmust be nonzero and even.- The endpoint binds 512 ports,
port,port + 2, up toport + 1022. That range must stay below 65536 and must not contain 3074. - A relay port must fit outside that range and away from 3074.
server_reserve_countmust be at least 8 and at most 3392. The rest of the 8192 slots must hold 400 for each of 12 players.client_join_grant_countmust be at least 400 and at most 8192.
If any check fails, the settings file fails to parse and Sunrise does not start.
State
| key | type | default | what it does |
|---|---|---|---|
state.activity.default_destination | object | package city_tower_social_d2, activity index 20 | the destination used when nothing else selects one |
state.activity.roster_key_from_identity | bool | false | uses the membership identity as the player key in the activity roster |
default_destination must have all eight fields: reason, source_activity_index,
activity_index, package_name, bubble_count, stateful_bubble_mask, initial_slice_set and
spawn_set_hash. stateful_bubble_mask and spawn_set_hash take a number or quoted hex, like
"0xCF".
Root
| key | type | default | what it does |
|---|---|---|---|
complete_exotic_catalysts | bool | true | completes the catalysts of released exotic weapons |
Co-op
These keys set up co-op play. Leave them out for solo play.
| key | type | default | what it does |
|---|---|---|---|
multiplayer_enabled | bool | false | allows co-op and every network path it opens |
join_code | string | "" | a shared secret, up to 64 bytes; host and guests must use the same one. Empty admits any guest on the local network |
role | string | "embedded"; not in the default file | embedded for solo, host for the host, client for a guest |
machine_id | int | 0; not in the default file | a machine id for a second game on the same PC; also read as client.machine_id |
client.server_endpoint | object | {"host": "127.0.0.1", "bap_port": 30974}; not in the default file | the host a guest connects to, with role client |
server.upstream | object | not in the default file | the same, read from the server block; a host refuses it |
server.bap_bind | string | "127.0.0.1" | the address the BAP listener binds; a host takes only 0.0.0.0 or 127.0.0.1 |
server.max_players | int | 32 | players the host admits, 1 to 32 |
steam.user.steam_id | int | not in the default file | the player’s Steam id; an invalid id is a parse error |
multiplayer_enabled must be true before any of these takes effect. With it false, the file
fails to parse when it sets a role of host or client, an upstream, an external server, the
short form, or a bind address other than 127.0.0.1. The debugger output then gets
ev=settings result=fail reason=multiplayer_opt_in_required.
More checks run after the parse. Each failure stops the start with its own reason:
reason | what is wrong |
|---|---|
host_upstream | a host names an upstream |
host_external | a host has the external server on |
host_local_listener | a host has bap_port 0, or a bap_bind other than 0.0.0.0 or 127.0.0.1 |
host_gameplay | a host has a gameplay topology other than embedded |
lan_only | an address is not on the local network; see Local network only |
The short co-op form
A small file can replace the whole settings file for co-op:
{ "multiplayer_enabled": true, "host": "192.168.1.10:30974", "persona": "Host", "join_code": "pick one" }
{ "multiplayer_enabled": true, "server": "192.168.1.10:30974", "persona": "Guest", "join_code": "pick one" }
| key | meaning |
|---|---|
host | this install hosts. The address is the one guests dial, and the one advertised for gameplay. The BAP listener and the gameplay endpoint bind 0.0.0.0 |
server | this install is a guest of the host at that address |
persona | the player name; the same rules as steam.user.persona_name |
- The port after
:is the host’s BAP port. Without it the port is 30974. - Every other key keeps its default.
- The short form cannot be mixed with
role,client.server_endpointor the external server.personais refused next to asteamblock, and in a file withouthostorserver. - Without
steam.user.steam_id, Sunrise makes a random Steam id once and keeps it incache/platform_identity.bin, so the player keeps the same id on every start.
A full settings file cannot take the guest’s "server": "<address>". The file already has a
server object, and a key may appear only once, so Sunrise refuses the file. In a full file, set
"role": "client" and client.server_endpoint instead. host clashes the same way with a
server object; in a full file a host sets "role": "host" and server.bap_bind.
Values the menu saves
The menu pages do not write settings.json. They save to their own files in the same folder:
| file | written by |
|---|---|
movement.json | the Movement page |
player.json | the Player page |
hud.json | the HUD page |
world_markers.json | the display options of the world markers |
The log
Sunrise has two log outputs. Each is switched in core.logging.
| output | key | default |
|---|---|---|
| the Windows debugger output | debugger_sink | on |
the file bin/x64/Sunrise/logs/sunrise.log | file_sink | off |
The file log is off by default. To get sunrise.log, set file_sink to true. On each start the
previous file is renamed to sunrise.log.old, so one earlier run is kept.
If the file sink is on and the file cannot be opened, Sunrise does not start.
The debugger output can be read with any tool that shows OutputDebugString text.
Line format
Every line has the same shape:
<channel> level=<level> t=<ms> ev=<event> key=value key=value ...
<channel>is one ofcore,client,state,server,middleware.tis milliseconds since the log opened. Gaps in it show stalls.evnames the event. Most lines addstage=andresult=.- A line is at most 1024 bytes. Longer text is cut.
Examples from src/server/transport/bap_listener.cpp and src/server/http/server_http.cpp. The
t values are made up.
server level=info t=4210 ev=transport stage=listen result=ok port=30974
server level=info t=31877 ev=http method=post route=signon result=ok
server level=info t=32015 ev=transport stage=accept result=ok conn=1
To find problems, search for result=fail, level=error and level=warn.
Log levels
There are five levels, from most to least severe: error, warn, info, debug, trace. The
sixth value, off, drops the channel.
Each channel has its own threshold. A line is kept when its level is at or above the threshold.
So warn keeps errors and warnings, and trace keeps everything.
An unknown channel name in levels is skipped. An unknown level name is a parse error, so Sunrise
does not start.
Every channel defaults to warn. This example turns on the file log, raises server to info and
drops middleware:
"core": {
"logging": {
"debugger_sink": true,
"file_sink": true,
"levels": {
"core": "warn",
"client": "warn",
"state": "warn",
"server": "info",
"middleware": "off"
}
}
}
To turn logging down:
- Set a channel to
errorto keep only errors, or tooffto drop it. - Set
file_sinktofalseto stop writing the file. - Set
debugger_sinktofalseto stop the debugger output.
Debug level is for diagnosis. It adds timing lines, such as the server’s two-second service report.
Info level on server adds one ev=activity_incident line per activity incident, in both
directions, with its payload in hex.
For the mission script lines and what they mean, see Debugging a script.
The in-game menu
Press Insert to open or close the menu. The key is client.ui.toggle_key. The menu also has a
close button. The menu starts closed. With client.ui.enabled set to false, the key does nothing.
At startup a hint names the key: “Press INSERT to open the Sunrise overlay”. It shows 2 seconds after the HUD first draws and goes 30 seconds later, or as soon as the menu opens. It does not come back in the same run. The HUD page can turn it off.
The left column lists the pages, in this order: client pages, then server pages, then Core pages.
| page | from | what it has |
|---|---|---|
| Movement | client | Teleport (distance and key), Noclip (toggle key), Fly (toggle key and speed), Sword Skate Fix; all locked unless client.cheats is on |
| Player | client | Infinite Ammo, locked unless client.cheats is on; Anti AFK |
| Activity Launcher | client | browse activities by content (expansions, seasons, events), search, and launch from orbit; Custom Launch picks the arrival by hand |
| Activity Host | server | an instance selector and two windows, World and Packets |
| HUD | Core | one switch per overlay, and one per line of the Current Status overlay |
| Logs | Core | recent log lines, with channel, level and text filters, auto-scroll and Copy Visible |
| Mods | Core | every mod folder: loaded mods in load order, then refused ones with each reason (Mods) |
Changes on the Movement, Player and HUD pages save at once and survive a restart.
The Activity Launcher
The Activity Launcher starts an activity from orbit through the game’s own launch path.
- The library groups activities by first release: All content, Expansions, Seasons and Events. A search box searches every activity by name, package, index or hash.
- Equal launch variants share one card. The detail view has a Variant list when there are several. Include unavailable scenarios also lists activities with no scenario installed.
- Launch activity launches the selected variant with its own arrival.
- Manual Mode in the detail view, and the Custom Launch card, pick the activity, its launch route, and the arrival: Bubble, Slice and Spawn. A spawn of “Client picks” leaves the spawn point to the game.
A manual launch sets a forced destination. Every later launch lands there until you press Clear active override. While one is active, a normal launch is disabled. The forced destination is held in memory only, so a restart clears it. Studio’s Reload bubble can set one too; see Package changes in a running game.
Activity Host windows
The World window has one page per kind of authored content: Squads, Idles, Combatants, Devices, Triggers, Objects, Scenes, Dialogue, Directives, Objectives, Cinematics, Engagement, Public event, Occupancy, Lifetime, States, Mission state, Positions, Behaviors and Script.
The Packets window lists the messages the game sent to the Activity Host.
How to use these windows to find content for a script is in Finding things in game.
HUD overlays
Overlays draw with the menu open or closed. All but one stack in the top-left corner.
| overlay | starts | corner | shows |
|---|---|---|---|
| Sunrise Card | on | top left | the Sunrise name, version and logo |
| Startup Hint | on | top left | the menu key, for 30 seconds after startup |
| Current Status | off | top left | activity, bubble, slice set and closest spawn, each line switchable |
| Session | off | top left | the instances of your current session |
| Client Activity Messages | off | top left | recent client messages at the Activity Host |
| Mission Script | off | top left | what the mission script runtime is doing, per activity |
| Mission Variables | off | top right | the newest mission variable changes, newest last |
The Mission Variables overlay shows client.ui.mission_variable_rows rows. Each row has the age,
the key and the value, with the old value after a change. A new row is tinted for 2 seconds. When
the rows come from more than one activity, each key starts with its activity id. The list is
cleared when a mission script starts.
The Logs page
The Logs page keeps only the newest 128 lines, in memory. It shows lines that passed the channel
thresholds in core.logging.levels, whether or not the file sink is on. A line dropped by the
threshold is not on the page either. For a full record, turn on file_sink.