TiMan: Add a sourced SOMA guide with explanations and stock-script examples.

2026-10-02T12:21:40Z

Add a sourced SOMA guide with explanations and stock-script examples.

New page

{{shortPageTitle}}

Map streaming loads the next map’s assets before the transition. SOMA’s Curie Outside script shows how preloading, transfer-area preservation and a readiness check fit together.

== Follow the Curie transition ==
# Include <code>helpers/helper_map.hps</code> in the map script. The following are excerpts from <code>maps/chapter02/02_01_ms_curie_outside/02_01_ms_curie_outside.hps</code>, rather than a complete transition script.
# Begin preloading the destination:

<syntaxhighlight lang="cpp">
Map_Preload("02_02_ms_curie_inside.hpm", eWorldStreamPriority_Low);
</syntaxhighlight>

The inspected helper declares a priority argument, but only forwards the map name to <code>cLux_PreloadMap</code>. To change the priority, the stock script calls the separate helper:

<syntaxhighlight lang="cpp">
Map_SetPreloadPriority(eWorldStreamPriority_Normal);
</syntaxhighlight>

# Before changing maps, the stock transition calls:

<syntaxhighlight lang="cpp">
Map_Deload("Transfer2122");
</syntaxhighlight>

The helper’s source comment describes the named transfer area as preserving objects inside it from deloading. <code>Transfer2122</code> belongs to this stock transition; it is not a universal area name.

# The timer callback waits for readiness before changing maps. If loading is incomplete, it schedules another check after 0.55 seconds:

<syntaxhighlight lang="cpp">
if(Map_IsPreloadCompleted())
{
// Other stock transition cleanup occurs here.
Map_ChangeMap("02_02_ms_curie_inside.hpm", "", "Transfer2122", "", "");
}
else Map_AddTimer("ChangeMap", 0.55f, "PreloadTimer");
</syntaxhighlight>

This excerpt abbreviates the entity cleanup preceding <code>Map_ChangeMap</code>. The full stock script also copies global settings, fades an environment preset and changes the preload priority through its timer events.

== Understand the change-map arguments ==
The five-argument overload takes the destination map, player-start name, transfer-area name, start sound and end sound. The four-argument overload leaves out the transfer-area argument and supplies an empty name internally. Both stop the grab state before forwarding the transition to the native function.

== Adapt the pattern ==
Use destination, player-start and transfer-area names that exist in your own map setup. Keep the readiness check and its timer callback together; copying the timer call alone does not define <code>PreloadTimer</code>.

== See also ==
* [[HPL3/SOMA/Scripting/Map Helper|Map timers and helpers]]
* [[HPL3/SOMA/Areas/MapTransfer Area|MapTransfer areas]]

[[Category:English]]

HPL3/SOMA/Scripting/Level Streaming - Revision history

TiMan: Add a sourced SOMA guide with explanations and stock-script examples.