SUNRISE

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 18 is upgraded in place. Sunrise rewrites it to 19 and keeps every value you set. The debugger output gets ev=settings stage=upgrade result=ok.
  • A file below 18, or with no version key, 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 version key 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

keytypedefaultwhat it does
core.logging.file_sinkboolfalsewrites the log to Sunrise/logs/sunrise.log
core.logging.debugger_sinkbooltruesends 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_declarationsbooltruewrites the sdk/lua tree that mission scripts use
core.studio_attachboolfalselets 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

keytypedefaultwhat it does
steam.languagestring"english"the game language; an unknown value falls back to english
steam.user.persona_namestring"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

keytypedefaultwhat it does
client.ui.enabledbooltrueoff: the menu key does nothing and no HUD overlay draws
client.ui.toggle_keystring"insert"the key that opens and closes the menu
client.ui.mission_variable_rowsint15rows the Mission Variables overlay shows, 1 to 48; see Debugging a script
client.custom_bootflow_texturesbooltruereplaces some startup screen textures with ones built into Sunrise
client.socket_menu_routingboolfalsemoves four leg mods into the leg mod menu
client.reveal_lore_booksbooltrueclears the visibility gates on lore book entries
client.cheatsboolfalseunlocks the cheat tools; the session then saves no progress
client.exports.package_keysboolfalseexports the installed package keys for Sunrise Studio during startup
client.exports.tag_definitionsboolfalseexports the game’s tag definitions for Sunrise Studio during startup
client.external_server.enabledboolfalsesends the game’s traffic to another server instead of answering it in process
client.external_server.hoststring"127.0.0.1"that server’s IPv4 address; a host name is refused
client.external_server.config_urlstring"https://127.0.0.1/config/"the config URL handed to the game; must be a route that server serves
client.external_server.config_guidstring"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

keytypedefaultwhat it does
server.bap_portint30974the loopback port the BAP listener binds; SignOn hands it to the game
server.gameplay.topologystring"embedded"who owns the gameplay UDP endpoint; see below
server.gameplay.bind_addressstring"127.0.0.1"the local interface the endpoint binds
server.gameplay.advertised_addressstring"127.0.0.1"the address the game is told to use
server.gameplay.transport_addressstring"127.0.0.1"the address the game’s packets land on after the redirect
server.gameplay.portint30976the first UDP port; must be even
server.gameplay.relay_portint32000; not in the default filethe relay UDP port; one that collides moves up by 2
server.gameplay.server_reserve_countint256entity slots held back for server-made entities
server.gameplay.client_join_grant_countint8192entity slots the game gets on join, capped by what the reserve leaves
server.gameplay.hold_launch_cinematicboolfalse; not in the default fileholds a launch sync open through the load so the spaceflight scenes are skipped
server.activation.default_client_activationbooltrueoff: a request to start another activity is recorded and gets no answer
server.activation.activity_public_membershipbooltruesends membership on a public activity link
server.activation.prevent_ownerless_channel_closeboolfalsediagnostic only; sets a game feature flag that keeps a channel open when its last owner leaves
server.activation.mission_scriptingbooltrue; false if missingruns mission scripts

topology takes one of three values:

valuemeaning
embeddedSunrise binds the gameplay UDP endpoint
externalanother process owns the endpoint
disabledno endpoint

The gameplay block is checked as a whole. With a topology other than disabled:

  • port must be nonzero and even.
  • The endpoint binds 512 ports, port, port + 2, up to port + 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_count must 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_count must be at least 400 and at most 8192.

If any check fails, the settings file fails to parse and Sunrise does not start.

State

keytypedefaultwhat it does
state.activity.default_destinationobjectpackage city_tower_social_d2, activity index 20the destination used when nothing else selects one
state.activity.roster_key_from_identityboolfalseuses 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

keytypedefaultwhat it does
complete_exotic_catalystsbooltruecompletes the catalysts of released exotic weapons

Co-op

These keys set up co-op play. Leave them out for solo play.

keytypedefaultwhat it does
multiplayer_enabledboolfalseallows co-op and every network path it opens
join_codestring""a shared secret, up to 64 bytes; host and guests must use the same one. Empty admits any guest on the local network
rolestring"embedded"; not in the default fileembedded for solo, host for the host, client for a guest
machine_idint0; not in the default filea machine id for a second game on the same PC; also read as client.machine_id
client.server_endpointobject{"host": "127.0.0.1", "bap_port": 30974}; not in the default filethe host a guest connects to, with role client
server.upstreamobjectnot in the default filethe same, read from the server block; a host refuses it
server.bap_bindstring"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_playersint32players the host admits, 1 to 32
steam.user.steam_idintnot in the default filethe 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:

reasonwhat is wrong
host_upstreama host names an upstream
host_externala host has the external server on
host_local_listenera host has bap_port 0, or a bap_bind other than 0.0.0.0 or 127.0.0.1
host_gameplaya host has a gameplay topology other than embedded
lan_onlyan 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" }
keymeaning
hostthis 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
serverthis install is a guest of the host at that address
personathe 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_endpoint or the external server. persona is refused next to a steam block, and in a file without host or server.
  • Without steam.user.steam_id, Sunrise makes a random Steam id once and keeps it in cache/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:

filewritten by
movement.jsonthe Movement page
player.jsonthe Player page
hud.jsonthe HUD page
world_markers.jsonthe display options of the world markers

The log

Sunrise has two log outputs. Each is switched in core.logging.

outputkeydefault
the Windows debugger outputdebugger_sinkon
the file bin/x64/Sunrise/logs/sunrise.logfile_sinkoff

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 of core, client, state, server, middleware.
  • t is milliseconds since the log opened. Gaps in it show stalls.
  • ev names the event. Most lines add stage= and result=.
  • 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 error to keep only errors, or to off to drop it.
  • Set file_sink to false to stop writing the file.
  • Set debugger_sink to false to 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.

pagefromwhat it has
MovementclientTeleport (distance and key), Noclip (toggle key), Fly (toggle key and speed), Sword Skate Fix; all locked unless client.cheats is on
PlayerclientInfinite Ammo, locked unless client.cheats is on; Anti AFK
Activity Launcherclientbrowse activities by content (expansions, seasons, events), search, and launch from orbit; Custom Launch picks the arrival by hand
Activity Hostserveran instance selector and two windows, World and Packets
HUDCoreone switch per overlay, and one per line of the Current Status overlay
LogsCorerecent log lines, with channel, level and text filters, auto-scroll and Copy Visible
ModsCoreevery 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.

overlaystartscornershows
Sunrise Cardontop leftthe Sunrise name, version and logo
Startup Hintontop leftthe menu key, for 30 seconds after startup
Current Statusofftop leftactivity, bubble, slice set and closest spawn, each line switchable
Sessionofftop leftthe instances of your current session
Client Activity Messagesofftop leftrecent client messages at the Activity Host
Mission Scriptofftop leftwhat the mission script runtime is doing, per activity
Mission Variablesofftop rightthe 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.