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 (raise an issue to discuss on Github or submit a PR)

return type

nothing

Source code

native Preload          takes string filename returns nothing