This article contains API reference information for implementing dock screens.

Selecting a Dock Screen

When the player docks with an object, the engine needs to figure out what dock screen to show. This section describes the rules for determining the dock screen to show.

Events

We start by asking various entities to give us a dock screen to show and then take the dock screen with the highest priority.

We collect possible dock screens from the following places:

  • We call <GetGlobalDockScreen> on all types.
  • We call <GetDockScreen> on all overlays on the object.
  • We call <GetDockScreen> on the object itself.

We take the dock screen with the highest priority. If multiple dock screens come back with the same priority, we use the list order above to decide. That is, if both <GetGlobalDockScreen> and an overlay return a dock screen at the same priority, we take the one from <GetGlobalDockScreen>

The events above should return one of the following values:

  • Returning Nil means that they don't have a screen to show.
  • Returning a string or integer is interpreted as either a <DockScreen> type or as a local screen ID. These screens have a priority of 0.
  • In a two-element list, the first element is the dock screen type or local screen ID and the second element is the priority.
  • In a three-element list, the first element is the dock screen type or local screen ID, the second element is the data to pass to the screen (gData), and the third element is the priority.

Default Dock Screen

If none of the above events returns a dock screen, then we use the default dock screen for the object. A station type may define a dock screen to show when abandoned separately from one to show when not.

<OnScreenInit>

Once we've chosen a screen to show, we call <OnScreenInit> on that screen. A screen may decide to show another screen inside this call. For example, a screen might decide to call (scrShowScreen) from inside <OnScreenInit>.

If the new screen being shown is not a nested screen, then the new screen replaces the original screen. Otherwise, we return back the original screen when we're done.