LML: Custom Files > Introduction

Custom Files

This is a mod requirable hack that must be required by a mod to be enabled.

This hack allows mods to provide custom files without modifying the game install.

It also allows mods to handle the game requesting files with Lua scripts which allows for a number of powerful features.

Requiring This Hack

To require this hack, add this line to your mod's Meta.ini:

RequiredHack=CustomFiles

Your mod must provide one of the following things when requiring this hack:

  • CustomFiles.ini
  • CustomFiles.lua
  • A CustomFiles folder.
  • An AdditionalFiles folder.

Configuring This Hack

To configure this hack, create a file named CustomFiles.ini and add the parameters necessary for your mod inside it.

; [Miscellaneous] Section
	; OccludedPath: Occlude a file from the game's view, this will make the game think it doesn't exist. Be careful with this. Repeat for each file.
	; ReadOnly: Prevents the game from writing to a file, but it can still read it. Repeat for each file.
	; SuppressedPath: Tries to prevent the game from loading a file. Repeat for each file.
	
; [PathRedirections] Section: Set Path Redirections for Files
	; PATH_TO_FILE: Set a path to another file, this will tell the game to use that one instead of the original. Repeat for each file.
	
; [PathHandlers] Section: Set Handlers for Files
	; PATH_TO_FILE: Set a path to a Lua script, this will allow that script to handle the file. Repeat for each file.
	
; Notes
	; * Wildcard can be used in a path to indicate anything of any length.
	; ? Wildcard can be used in a path to indicate anything of a set length.
	; OccludedPath is best used to hide introduction movies as the game will simply carry on if they are not found.

[Miscellaneous]
; Hide the Vivendi Universal Games intro movie.
OccludedPath=movies\\vuglogo.rmv
	
[PathRedirections]
; Redirect all License screens to this new one.
art\\frontend\\dynaload\\images\\license\\*.p3d=art\\license\\license.p3d

[PathHandlers]
; Handle famil_v with our script over there.
art\\cars\\family_v.p3d=Resources/scripts/handlers/famil_v.lua

Folders

CustomFiles

The main folder for this hack is one called "CustomFiles". This folder allows mods to override files in the base game.

For example, a mod with a custom version of the Family Sedan at the path CustomFiles\art\cars\famil_v.p3d will override the game's original model for it.

AdditionalFiles

Mods can also use a folder named "AdditionalFiles" is similar to "CustomFiles" but instead of overriding the files, it makes the game load the original file and the custom file.

This functionality can break the game in a number of cases such as when it is used on a sound script (.spt).

Resources

Lastly, mods that use this hack's Lua Scripting are expected to use a folder named "Resources" for any Lua scripts (besides CustomFiles.lua) and any other files that are exclusively redirected to or read by Lua scripts.

Lua Scripting

For more detailed information, see Lua Scripting.

Version History

1.23.9

  • Improved efficency of the Output Lua function for path handlers, particularly when calling it multiple times.
    • Also added a -legacyoutput command line argument to opt out of this change.
    • Also added the IsLegacyOutput Lua function to detect if that argument is in use.

1.23.8

  • Made it so the start of Lua file names are truncated instead of the end.
    • Also added -notruncateluafilenamestart to opt out of this change.
  • Made various improvements to Lua execution errors.
    • They now include the title of the mod that executed the script.
    • They now include a stack trace.
      • Also added -noluastacktrace to opt out of this addition.
    • They now get logged to the log files (when "Logging" is enabled in the "Console and Logging" hack).
  • Made various improvements to Lua load errors.
    • They now include the title of the mod that loaded the script.
    • They now get logged to the log files (when "Logging" is enabled in the "Console and Logging" hack).

1.19

General

  • Made CustomFiles.lua execute after all hacks that are supposed to be loaded are loaded.
  • Made this hack only mount "CustomFiles" folders that exist.
    • This change can dramatically improve performance if you have lots of mods enabled but only a few have CustomFiles folders (like Mod Hacks for instance).

Lua Scripting

  • Added GetLauncherVersion. This returns the current version of the Mod Launcher.
  • Added GetMainMod. This returns the InternalName of the current main mod (if there is one).
  • Added GetSettings. This returns the settings of the current mod (or the specified mod) in a Lua table.
  • Added IsTesting. This checks if the user is has the Mod Launcher's testing mode enabled.
  • Added UseCallbacks. This is an advanced function for handling files with Lua that may or may not have a use case.
  • Fixed an issue where "ComparePaths" was always case sensitive and always slash sensitive.

1.13.2

General

Fixed a crash when redirecting files loaded by frontend pages.

1.12.1

Lua Scripting

Fixed a bug where using GetSetting on an Integer type Number setting would return a number.

1.12

General

Added various Console output messages.

Lua Scripting

  • Now uses the Lua Support hack.
    • This means this version effectively upgrades from Lua 5.2.3 to 5.3.1.
    • This also makes the utf8 and coroutine libraries available in Lua scripts and removes support for compiled Lua files.

1.2 or earlier

Added this hack.