Type Function Library package Return value Library Revision Release 2023.3686 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.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
true to this entry. In any case,
require() returns the final value of
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.
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
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" )