startmenu.xml

libraries/startmenu.xml lists the scenes the start menu can show behind it. Each scene entry names the cutscene that builds the scene, the music played with it, the galaxy it is built in, the cluster whose sky it shows, and the regions placed around it. One scene is the default, the expansions add their own, and the player picks one in the settings.

This article covers the file: its format, how the expansions change it, how a scene is chosen, and how an extension adds one. It describes version 9.00. How a scene itself is made, the cutscene, the scene object with its camera, ships and stations, and the regions, is covered below this article in Start menu background.

Contents

• Terms
• How a scene entry is used
• The file
  • Layout
  • A scene entry
  • Unlocks
  • The random entry
• How the expansions change it
• Choosing a scene
• Adding a scene from an extension

Terms

• Scene entry: one <scene> in startmenu.xml. It names the cutscene the scene plays, the background cluster whose sky it shows, the music played with it, and the regions placed around it.
• Default scene: the scene shown when the player has not chosen one.
• Background cluster: the cluster content that gives a scene its sky: the skybox, planets, nebulae and the sun's light.
• Scene object: the object the cutscene places in the scene, holding the camera, the lights, and the ships and stations that move in it.

↑ Contents

How a scene entry is used

libraries/startmenu.xml
  <scene cutscene="startmenu_background" music="..." map="blackgalaxy_macro">
    <cluster name="cluster_black_macro" background="cluster_sm3_background_macro"/>   -> the sky
    <regions> <region name="sm_bs_region_macro"> ... </regions>                       -> asteroids, fog
        |
        v
cutscenes/startmenu_background.xml
  <director key="startmenu_background"/>
  <anchor name="startmenu_final_macro"/>                                              -> the scene object
  <teleport zone="tzonecluster_black_sector01_zone_macro"/>
        |
        v
assets/cutscenecore/macros/startmenu_final_macro.xml     the scene object's macro: what fills each connection
assets/cutscenecore/startmenu_final.xml                  its component: camera, lights, dummies, animations

The game builds the galaxy the entry names, with the background cluster's sky and the regions at their positions, plays the cutscene, which places the scene object in the galaxy's zone, and plays the music. Start menu background covers the cutscene, the scene object, the background cluster and the regions.

↑ Contents

The file

Layout

The base file:

<startmenu>
  <background default="startmenu_background">
    <scene cutscene="startmenu_background" music="music_menu_main_music" map="blackgalaxy_macro">
      <cluster name="cluster_black_macro" background="cluster_sm3_background_macro" />
    </scene>
    <scene cutscene="startmenu_basegame_background" music="music_menu_main_bg_music" map="blackgalaxy_macro">
      <cluster name="cluster_black_macro" background="cluster_sm_basegame_background_macro" />
    </scene>
  </background>
</startmenu>

<background> holds the scene entries; its default names the default scene by its cutscene. There is no schema for this file.

A scene entry

A Kingdom End scene, with every element vanilla uses:

<scene cutscene="startmenu_b2_background" music="music_menu_main_bor_music" map="blackgalaxy_macro">
  <unlock>
    <userdata ref="x4ke_sod_discovered" value="1" />
  </unlock>
  <cluster name="cluster_black_macro" background="cluster_sm605_background_macro" />
  <regions>
    <region name="sm_sod_region_macro">
      <position x="0" y="-50000" z="0"/>
    </region>
    <region name="sm_sod_region2_macro">
      <position x="0" y="-20000" z="0"/>
    </region>
  </regions>
  <paintmod default="paintmod_0191" />
</scene>

The vanilla background macros, the vanilla regions and how a region macro is made are listed in Start menu background.

Unlocks

The two locked Kingdom End scenes wait for values a script sets when the player first enters the sector each scene shows:

<set_value name="userdata.x4ke_sod_discovered" exact="1" />

A userdata value is kept in the player's profile, not in a save, so it stays set for every later game. Game starts use the same kind of value for their own unlocks, described in gamestarts.xml.

The random entry

Kingdom End also adds an entry that is not a scene:

<random cutscene="random">
  <unlock>
    <userdata ref="unlock_x4ke_ch6_complete" value="1" />
    <userdata ref="unlock_x4ke_ch8_complete" value="1" />
  </unlock>
</random>

Its two values are set by the Kingdom End story.

↑ Contents

How the expansions change it

Each expansion's libraries/startmenu.xml is a diff that does two things: it adds a scene entry of its own, and it replaces the default entry startmenu_background with a copy using its own background cluster and regions:

<diff>
  <replace sel="/startmenu/background/scene[@cutscene='startmenu_background']">
    <scene cutscene="startmenu_background" music="music_menu_main_music" map="blackgalaxy_macro">
      <cluster name="cluster_black_macro" background="cluster_sm_split_macro" />
    </scene>
  </replace>
  <add sel="/startmenu/background">
    <scene cutscene="startmenu_split_background" music="music_menu_main_split_music" map="blackgalaxy_macro">
      <cluster name="cluster_black_macro" background="cluster_sm_split_macro" />
    </scene>
  </add>
</diff>

Each also diffs the default cutscene, cutscenes/startmenu_background.xml, to point it at its own scene object. Each of those diffs selects the anchor by every name the earlier expansions set, so the default scene shows the most recent expansion's scene:

<diff>
  <replace sel="/cutscene/environments/environment_plot/anchor[@name='startmenu_final_macro' or @name='startmenu_split_final_macro']/@name">startmenu_terran_final_macro</replace>
</diff>

The base game's own scene stays available as the startmenu_basegame_background entry, which no expansion changes.

↑ Contents

Choosing a scene

Settings, Game, "Start Menu Background Scene" is shown only in the start menu. It lists:

• "Default", the scene default names;
• "Random";
• every other scene, labelled with the name of the extension whose startmenu.xml added it, and numbered when one extension adds several.

Changing the choice reloads the start menu, so the new scene is built at once.

↑ Contents

Adding a scene from an extension

A new scene entry is an add on /startmenu/background:

<?xml version="1.0" encoding="utf-8"?>
<diff>
  <add sel="/startmenu/background">
    <scene cutscene="example_startmenu_background" music="music_menu_main_music" map="blackgalaxy_macro">
      <cluster name="cluster_black_macro" background="cluster_sm2_background_macro" />
      <regions>
        <region name="example_sm_asteroids_macro">
          <position x="0" y="-2500" z="0" />
        </region>
      </regions>
    </scene>
  </add>
</diff>

The entry needs a cutscene with the key it names, and every region macro it names needs to exist. Start menu background has this entry with all its files as one complete example.

• The scene is listed under the extension's name in the settings. It does not replace the default scene.
• Replacing the default scene is a replace of the startmenu_background entry, as the expansions do. The expansions replace the same entry, so the result depends on which diff applies last.
• The cutscene key has to be new. It is the scene's id in the settings list.

The extension itself, its folder, content.xml and diff files, is covered in Anatomy of an extension and XML diff patching.

↑ Contents