Preloader

Parameters

filename

string

The file to execute. For custom paths outside of game files, see PreloadGenEnd.

comment

Runs the filename as a preload script, only if the filename has an extension.

If the preload file needs to be read from disk, this happens only once per map load/restart. Subsequent calls will execute old data (tested v2.0.3.22988).

Any syntax errors - whether in Jass or (for Lua mode) Jass/converted Lua code - will crash the game.

Example (from blizzard.j):

if (doPreload) then
        call Preloader( "scripts\\HumanMelee.pld" )
endif

note

The capabilities within the context of a preload file are very restricted. You do not have access to your map context (global variables etc.) and "Blizzard.j" is not loaded at all. Only "common.j" functions are available and these can be used to transfer data via modifications of the game state.

note

It is possible to add Lua code to Preload files (which are supposed to be in Jass) using dirty hacks or manual editing. When the map runs in Lua mode, the Jass code is compiled using Jass2Lua before execution.

note

On pre-Reforged (version?) this only works if you have enabled the usage of local files in your registry. The registry key is HKEY_CURRENT_USER\Software\Blizzard Entertainment\Warcraft III\ (DWORD) Allow Local Files = 1 to allow.

note

Here are some ways to get the data out of the preload file into your map: To store multiple integers you can use SetPlayerTechMaxAllowed to have a good 2d-array. Read via GetPlayerTechMaxAllowed.

For strings SetPlayerName is suited. To read use GetPlayerName.

Further reading: https://www.hiveworkshop.com/threads/exploring-file-i-o-tricks-and-techniques.307710/ by Lizreu

Inside the preload script you can also use ExecuteFunc to call your map-defined functions and interleave the preload script with your functions.

note

If you use Preloader to load some values into your map, these values are very likely to be different for each player (since the player might not even have local files enabled), so treat them as async values.

note

Also see the documentation of Preload to see how to properly get the data into the preload script.

bug

1.33.0 and above: Due to aggressive file caching by the game, the preload file is only loaded and read once from disk. This means, updates to the saved preload file cannot be reloaded and old contents will be executed until you restart Warcraft III.

This was fixed either in January 2023 or 2024 (1.35.0 - 1.36.1). Since then any map reload or restart clears the preload caches. https://us.forums.blizzard.com/en/warcraft3/t/bug-preload-files-are-being-cache%E2%80%99d/29413/35

note

See: Preload, PreloadEnd, PreloadStart, PreloadRefresh, PreloadEndEx, PreloadGenClear, PreloadGenStart, PreloadGenEnd.

patch

1.00

Source

common.j (suggest an edit or discuss on Github)

return type

nothing

Source code

native Preloader        takes string filename returns nothing