Level transition scripts and object elevatoring

[663680dd721d9ZylonBane]

The SS2 main campaign is constructed of numerous linked map files that the player can move between at will. This article describes how to implement these map transitions. This article assumes that you already know how to set up standalone playable levels with the requisite player factory markers, etc.

Using Level Transition Scripts

To perform a player-initiated level transition, you must place a level transition script on either a button or a tripwire.

The majority of level transitions will be perfomed by the following scripts:

• LevelChangeButton: Place on a button to trigger level change when player frobs the button. Performs object elevatoring.
• SimpleLevelChangeButton: Place on a button to trigger level change when player frobs the button. Does not perform object elevatoring.

The available level transition scripts are described in more detail later in this article.

Linking Locations
Telling a script which level to go to is easy—just add Multilevel/Dest Level to the same object as the script and give it a map filename (without the ".mis" extension). But how does the engine know where in the level to go?

To transition to a specific location in a level, the game uses two properties called Start Loc and Dest Loc.

• Multilevel/Dest Loc is added to the object with the level transition script.
• Multilevel/Start Loc is added to an object in the destination level.

Any object with the Start Loc property is referred to as a level start marker. The number in the Loc fields is not an object number. It's just an arbitrary ID number that must be unique for the maps it's used in.

This is how it works when a level transition is triggered: The engine retrieves the Dest Loc value from the script object, loads the destination map, then looks for an object containing a Start Loc property with the same value. It then places the player at the position of that object.

But what about multiplayer? You don't want up to four players all appearing in the same spot. That's where landing point markers come in. Level start markers use landing point markers to control where the player(s) appear in the destination level. A landing point marker is any object linked to from the level start marker. The links must be flavor LandingPoint, with Data 1 - 4, respectively. The number indicates which player appears at which object.


Object Elevatoring

"Elevatoring" is an optional step that can be performed as part of a level transtion. It is a process by which the engine moves objects between different levels when it's sensible to do so-- for example when you drop objects in an elevator, it's expected that they'll stay in the elevator even when traveling between decks.

The area of effect for elevatoring is controlled by room brushes. Everything within a single room brush of the source level is removed from the level, then copied into a single room brush of the destination level, in the same relative positions. If it isn't possible to place an object in the same relative position, it is dropped near the player's feet.

Source and destination room brushes are selected as follows:

• Source brush: The brush containing the object with the script that initiated the level change.
• Destination brush: The brush containing the requested landing point marker (see "Destination Locations" above).

The initiating script object and landing point object must be unambiguously within a SINGLE room brush in their respective levels. If either is within multiple overlapping brushes, it is impossible to predict which room brushes the engine will select.

Only objects with the property MultiLevel/Elevator-able?:TRUE are subject to elevatoring.

Warning: The presence of identical Multilevel/Dest Level & Multilevel/Dest Loc properties on any other objects in the level will apparently cause elevatoring to fail. So don't try keeping any old backup triggers around.


Testing Elevatoring
To allow level transitions from DromEd, you must select Game -> Allow Endgame from the DromEd menu bar. Always save the mission before doing this, and reload the mission afterward.

Always delete the contents of the "current" folder every time before entering game mode. Otherwise you'll have undesired objects showing up, including duplicates of the player avatar.

Elevatoring from a Tripwire
The only level transition script designed to work as a tripwire, TrapTripLevel, does not perform elevatoring. To perform elevatoring from a tripwire-triggered level transition, we'll have to use the LevelChangeButton script. This can be done most easily with NVScript. After installing and loading NVScript, create the tripwire as follows:

• Create a tripwire from the base tripwire archetype (-305).
  
• Add Scripts: NVTrigOBB
• Add Scripts: LevelChangeButton
• Delete Scripts: TrapNewTripwire
• Check Scripts: Don't Inherit
• Add Script/Objlist Arg: NVTrigOBBPlayer=1; NVTrigOBBTOn="FrobWorldEnd"; NVTrigOBBTOff="Null"; NVTrigOBBTDest="[Me]";
• Add MultiLevel/Dest Level: [filename of destination level, without extension]
• Add MultiLevel/Dest Loc: [location ID#]

This creates a tripwire that, when entered by the player, will transmit a FrobWorldEnd message to itself. This message is received by the LevelChangeButton script, which then initiates the level transition.


Level Transition Scripts

ElevatorButton
Activation message: FrobWorldEnd
Performs Elevatoring: Yes
Default script on: Master Elevator Button (-1723)
Used on Von Braun elevators. Brings up elevator GUI, allows player to select destination or cancel.
Properties:

• Destinations:
• Maps: Defined in Editors -> GameSys Parameters -> Elev Levels
• Map Locations: MultiLevel/Dest Loc: [location ID#]
• Map Locations: MultiLevel/Start Loc: [location ID#]
• Button labels: Defined in MISC.STR by ElevLevel1 - ElevLevel5.
• Access: Controlled by the QB "ElevState". It takes the following values:
• 0: Offline; GUI will appear but only display a power icon
• 1: Only first 3 decks accessible; attempting to access decks 4 or 5 displays the MISC.STR string ElevBlocked ("Error!  Shaft inaccessible!")
• 2: Full access

LevelChangeButton
Activation message: FrobWorldEnd
Performs Elevatoring: Yes
Properties:

• MultiLevel/Dest Level: [map filename]
• MultiLevel/Dest Loc: [location ID#]

Default script on: Level Change Button (-2473)
Used mostly on bulkhead door buttons.

SimpleLevelChangeButton
Activation message: FrobWorldEnd
Performs Elevatoring: No
Properties:

• MultiLevel/Dest Level: [map filename]
• MultiLevel/Dest Loc: [location ID#]

Default script on: [none]
Used on Rickenbacker elevators and elevator between Rec and Command.

TrapTripLevel
Activation message: TurnOn
Performs Elevatoring: No
Properties:

• MultiLevel/Dest Level: [map filename]
• MultiLevel/Dest Loc: [location ID#]

Default script on: Tripwire Level (-2472)
Used to automatically trigger level transition when player enters an area.

ChooseService
Activation message: TurnOn
Performs Elevatoring: No
Properties:

• MultiLevel/Dest Level: [map filename]
• MultiLevel/Dest Loc: [location ID#]
• Player/Service: Marines, Navy, OSA

Default script on: [none]
Used in earth.mis for service selection doors.

ChooseMission
Activation message: TurnOn
Performs Elevatoring: No
Properties:

• MultiLevel/Dest Level: [map filename]
• MultiLevel/Dest Loc: [location ID#]
• Player/Char Gen Room: 0, 1, 2

Default script on: [none]
Used in station.mis to manage training sequence. After all three years of training, loads specified level.

[663680dd72334ZylonBane]

Did a little editing to hopefully better explain the use of StartLoc/DestLoc, and more fully documented the main elevator script.