HPL3/SOMA/Areas/MapTransfer Area

A MapTransfer Area is a named volume used by SOMA's map-streaming functions to identify the player and objects that should be preserved while the current map is unloaded and the next map is activated.

Important: A MapTransfer Area does not initiate a map change when the player enters it. SOMA's area script has no interaction or automatic collision behavior. A map script must pass the area's name to the map-deload and map-change functions.

Create the transfer volume

1. In the Level Editor, select Area EditMode and choose MapTransfer.
2. Place and scale the volume so it contains the player and every object that must survive the transition at the moment the script runs.
3. Give it a clear name. SOMA's campaign commonly names a pair after the adjoining maps, such as Transfer2122 for the transition from 02_01 to 02_02.
4. Create a matching transfer volume in the adjoining map when following the campaign's paired-area pattern.
5. Use that exact name in the transition script.

The SOMA class inherits the common BasicArea properties but adds no MapTransfer-specific editor variables. Its placement, size, orientation, active state, and name therefore define its role.

Use it from a map script

Include the map helper:

#include "helpers/helper_map.hps"

For a streamed transition, pass the same area name to Map_Deload and the five-argument Map_ChangeMap overload:

Map_Deload("Transfer2122");

// Call after the destination has finished preloading.
Map_ChangeMap("02_02_ms_curie_inside.hpm", "", "Transfer2122", "", "");

These calls are shortened from SOMA's Curie Outside transition. The shipped script begins preloading first and waits until Map_IsPreloadCompleted() before changing maps. See Level Streaming for that complete sequence.

Argument	Role
Map_Deload(asTransferArea)	Deloads the current map while preserving objects inside the named transfer area.
Map_ChangeMap(..., asTransferArea, ...)	Passes the named transfer area to the native map-change operation. The helper's source describes this as the area used to transfer objects and the player from one map to another.

Using the four-argument Map_ChangeMap overload supplies an empty transfer-area name, so it performs a normal change rather than this named transfer workflow.

Shipped SOMA pattern

The inspected campaign contains 36 MapTransfer instances with 17 distinct names. Most transition names occur in both adjoining maps. For example, Transfer2122 exists in:

• maps/chapter02/02_01_ms_curie_outside/02_01_ms_curie_outside.hpm_Area; and
• maps/chapter02/02_02_ms_curie_inside/02_02_ms_curie_inside.hpm_Area.

The source map calls both Map_Deload("Transfer2122") and Map_ChangeMap(..., "Transfer2122", ...). Other paired campaign names include Transfer0102, Transfer0203, Transfer2324, and transfer4142.

SOMA also uses a larger PreTransfer0102 volume for an earlier partial deload, followed later by Transfer0102 for the final transition. This demonstrates that a transfer volume can support staged unloading as well as the final map change.

Test the transition

1. Verify that the named volume exists and is active in the source map. SOMA reports an error and does not deload the level if the requested transfer area cannot be found.
2. Enter the volume with every object that should survive the transition.
3. Trigger the preload/deload/change sequence and wait for the destination map.
4. Confirm that the player and intended objects transfer, while unrelated parts of the old map are unloaded.
5. Test from a fresh launch and from a save made before the transition.

Some props can explicitly disallow map transfer through SetAllowMapTransfer(false). If a prop inside the volume does not survive, check its script or interaction state before assuming the area bounds are wrong.

Troubleshooting

• Nothing happens on entry: this is expected. Add or connect the script that starts preloading and eventually calls Map_ChangeMap.
• “Map Transfer Area not found” appears: verify the area name in the map and every script call. Use the exact spelling used by the placed object.
• Objects disappear during deload: confirm they are inside the transfer volume when Map_Deload runs and that they allow map transfer.
• The destination loads without the transferred state: use the five-argument overload and pass the transfer-area name; the four-argument overload passes an empty name internally.
• The transition runs before streaming is ready: wait for Map_IsPreloadCompleted(), as in the stock Level Streaming example.

See also

• Level Streaming
• Map Helper
• SOMA areas