============readme.md=============001
FAF LUA Code
------------
master|develop
------------ | -------------
[![Build Status](
https://travis-ci.org/FAForever/fa.svg?branch=master)](
https://travis-ci.org/FAForever/fa) | [![Build Status](
https://travis-ci.org/FAForever/fa.svg?branch=develop)](
https://travis-ci.org/FAForever/fa)
Current patch is: 3656
Changelog can be found [here](changelog.md).
Contributing
------------
See guidelines for contributing [here](CONTRIBUTING.md).
Running the game with your changes
----------------------------------
When FA starts without any command line arguments, it looks for a file called `SupComDataPath.lua`.
This file is a normal lua-file, that is allowed to use FA's IO operations to load directories and compressed directories (zip files) into the virtual file system.
The normal file looks like this:
mount_contents(SHGetFolderPath('PERSONAL') .. 'My Games\\Gas Powered Games\\Supreme Commander Forged Alliance\\mods', '/mods')
mount_contents(SHGetFolderPath('PERSONAL') .. 'My Games\\Gas Powered Games\\Supreme Commander Forged Alliance\\maps', '/maps')
mount_dir(InitFileDir .. '\\..\\gamedata\\*.scd', '/')
mount_dir(InitFileDir .. '\\..', '/')
Where `mount_contents` is a helper function defined also in that file.
This loads all maps and mods in your `~\Documents\My Games\...` folder, followed by the core game files that are located in compressed `.scd` files.
What's important to note about the load order is that if two directories contain the same file, the *first loaded* takes precedence. There are ways to get around this using hooks, that I'll explain in the end.
FAF extends the loading mechanism of FA, by using different initialization files: One for each featured mod.
`init_faf.lua` contains a whitelist of files that it allows to be loaded, this whitelist is implemented using the function `mount_dir_with_whitelist`, which is just like the helper function from the normal FA init file, except for the whitelist which only allows the given named files to be loaded.
The actual loading in `init_faf.lua` is done here:
-- these are the classic supcom directories. They don't work with accents or other foreign characters in usernames
mount_contents(SHGetFolderPath('PERSONAL') .. 'My Games\\Gas Powered Games\\Supreme Commander Forged Alliance\\mods', '/mods')
mount_contents(SHGetFolderPath('PERSONAL') .. 'My Games\\Gas Powered Games\\Supreme Commander Forged Alliance\\maps', '/maps')
-- these are the local FAF directories. The My Games ones are only there for people with usernames that don't work in the uppder ones.
mount_contents(InitFileDir .. '\\..\\user\\My Games\\Gas Powered Games\\Supreme Commander Forged Alliance\\mods', '/mods')
mount_contents(InitFileDir .. '\\..\\user\\My Games\\Gas Powered Games\\Supreme Commander Forged Alliance\\maps', '/maps')
mount_dir_with_whitelist(InitFileDir .. '\\..\\gamedata\\', '*.nxt', '/')
mount_dir_with_whitelist(InitFileDir .. '\\..\\gamedata\\', '*.nx2', '/')
-- these are using the newly generated path from the dofile() statement at the beginning of this script
mount_dir_with_whitelist(fa_path .. '\\gamedata\\', '*.scd', '/')
mount_dir(fa_path, '/')[/code]
After adding all maps and mods to the search path, all `.nxt` compressed directories are loaded (as filtered by the whitelist). This currently includes: murderparty, labwars, avanced strategic icons and texturepack. They are loaded in alphabetical order.
Followed by `.nxt` files, `.nx2` files are loaded. These comprise compressed directories for each subdirectory of the FA virtual file system: effects, env, loc, lua, modules, schook, projectiles, units, textures and meshes.
After all FAF-files have been loaded, the init file loads the base-game .scd files. Since these are loaded _last_, files that are in the FAF-directories take precedence and _shadow_ the base game files.
Hooking
-------
Hooking with the FA virtual file system simply means `concatenating files`.
Given the following directories and load-order:
*cool_mod* directory containing:
- `/hook/lua/file.lua`
*FAF.scd* containing:
- `/lua/file.lua`
- `/schook/lua/file.lua`
*FA.scd* containing:
- `/lua/file.lua`
What ends up in the actual filesystem used by FA is:
`/lua/file.lua` = `FAF.scd/lua/file.lua` + `cool_mod/hook/lua/file.lua` + `FAF.scd/schook/lua/file.lua`
Where "`fileA` + `fileB`" means that `fileB` has been appended to `fileA`.
The directory that is used for hooks can be configured in the init.lua file, and it customizable for each mod in the `mod_info.lua` file.