Preload

Parameters

filename

string

Text string, supposed to be a file path to be preloaded. Max length: 259 characters (see Windows MAX_PATH). NULL characters terminate the string and are stripped from output. Backslashes \ (0x5c) are always escaped as \\ so they read correctly when interpreted as a Jass string. All other characters are output as is. Be careful with double quotes (0x22) and line feed (0x0a), carriage return (0x0d).

comment

It does two things:

1. Try to read the file, and if "Allow Local Files" is enabled then also searches in the game folder
   • The order of priority is roughly this: local files, map MPQ, and finally game files as fallback
2. Append filename to preload buffer

Preloading exists to remove the stutter when you use a file/model/whatever for the first time.

note

The game only reads to cache these files, does not load them. The reading is done in a separate thread and does not freeze the game. One file is not read twice, no matter how often you call Preload().

note

Trick: It does not escape double-quotes " on purpose (approved not a bug, it's a feature). It is possible to inject custom code in Preload files this way (Lua):

PreloadGenClear()
PreloadGenStart()
Preload(' ")\ncall otherFunction("123")\n//')
PreloadGenEnd("its-a-feature.txt")

Results in the following preload file code (Jass):

function PreloadFiles takes nothing returns nothing

        call PreloadStart()
        call Preload( " ")
call otherFunction("123")
//" )
        call PreloadEnd( 754.6 )

endfunction

note

Game folder: - Reforged: Warcraft III\_retail_\somefile.txt, instead of _retail_ there's also a _ptr_ game version currently. - Classic: ?

note

Mini tutorial:

What are Preload files?

Preload files instruct the game to pre-read a file/resources to avoid freezes/stutter during gameplay. It's done to move the file into OS cache. Blizzard used preload files to load all required files at map init. See blizzard.j or campaign maps.

Create a preload file (Lua)

PreloadGenClear()
PreloadGenStart()
-- call Preload("filename.ext") as often as you need, one call per file you add
Preload("Textures\\Knight.blp")
PreloadGenEnd("MyPreloadFile.txt")

How to run a preload file

This must be done manually:

Preloader("MyPreloadFile.txt")

Lua code in preload files?

It is possible although in a very hacky way, described here.

You need to use "//! beginusercode" to start a section containing Lua code and end it using "//! endusercode". It works because the code is compiled on the fly with Jass2Lua.

note

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

note

Also see the documentation for Preloader for more info on the generated files.

patch

1.00

Source

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

return type

nothing

Source code

native Preload          takes string filename returns nothing