Type Function Library package Return value Library Revision Release 2024.3703 Keywords module, require See also package.loaded
Loads the given module.
The function starts by looking into the package.loaded table to determine whether modname is already loaded. If it is, require() returns the value stored at package.loaded[modname]. Otherwise, it tries to find a loader for the module.
To find a loader, require() is guided by the package.loaders array. By changing this array, you can change how require() looks for a module. The following explanation is based on the default configuration for package.loaders.
First, require() queries package.preload[modname]. If it has a value, this value (which should be a function) is the loader. Otherwise, require() searches for a Lua loader using the path stored in package.path. If that also fails, it tries an
Once a loader is found, require() calls the loader with a single argument of modname. If the loader returns any value, require() assigns the returned value to package.loaded[modname]. If the loader returns no value and has not assigned any value to package.loaded[modname], require() assigns true to this entry. In any case, require() returns the final value of package.loaded[modname].
If there is any error loading or running the module, or if it cannot find any loader for the module, require() signals an error.
There are critical differences in behavior depending on whether your code is running in the Simulator or on device. These differences are a result of fundamental OS differences between file system behavior.
On many systems, the OS file system is not case sensitive. Therefore, modules will load correctly even though the actual file name and the Lua string passed to require() have different case. On devices, however, the file name is typically case sensitive. In this case, the modules will fail to load if the case of the actual file name and the Lua string do not match.
The module string can't have any . characters except when specifying subdirectories (iOS only). For example, the following will load the bar.lua file from the foo subdirectory:
local fooBar = require( "foo.bar" )
On iOS, you cannot name the subdirectory resources or you will get a code signing error when you do a build. This is not a problem on Android, but it's best to avoid using this directory name.
local name = require( "moduleName" ) local name = require "moduleName"
String. The name of the module to load. Do not append the .lua extension to this string.
-- Require the physics library and assign it to the local variable "physics" local physics = require( "physics" )