@@ -483,34 +483,44 @@ functions:
483483 If a string path is provided instead, it is first resolved to a
484484 `Class.ModuleScript` relative to the script that called
485485 `Global.LuaGlobals.require()`, mimicking the Unix-like semantics of Luau's
486- `require()` expression. For example, each pair of
487- `Global.LuaGlobals.require()` expressions in the example below contains
488- two functionally equivalent calls.
489-
490- ```lua
491- -- "./" is equivalent to script.Parent
492- require(script.Parent.ModuleScript)
493- require("./ModuleScript")
494-
495- -- "../" is equivalent to script.Parent.Parent
496- require(script.Parent.Parent.ModuleScript)
497- require("../ModuleScript")
498- ```
486+ `require()` expression.
499487
500488 Specifically, require-by-string's resolution semantics are as follows:
501489
502- - String paths must begin with either `./` or `../`, where `./` is
503- equivalent to `script.Parent` and `../` is equivalent to
504- `script.Parent.Parent`.
505- - If the resolved path points to an `Class.Instance` that is not a
506- `Class.ModuleScript`, `Global.LuaGlobals.require()` will attempt to find
507- a `Class.ModuleScript` named `Init` or `init` parented to that
508- `Class.Instance` and use it instead, if it exists.
490+ - Paths with the `./` prefix begin resolution at `script.Parent`.
491+ - Paths with the `../` prefix begin resolution at `script.Parent.Parent`.
492+ - Paths with the `@self/` prefix begin resolution at `script`.
493+ - Each non-prefix component in a given path corresponds to a child
494+ instance of the previous component. The exception to this is the `..`
495+ component, which corresponds to the parent of the previous component.
509496 - If the desired `Class.ModuleScript` is not present at the time that
510497 `Global.LuaGlobals.require()` is called, the call will fail and throw an
511498 error. In other words, require-by-string is non-blocking: it does not
512499 implicitly wait for a `Class.ModuleScript` to be created.
513500
501+ To illustrate this, each pair of `Global.LuaGlobals.require()` expressions
502+ in the example below contains two functionally equivalent calls.
503+ Redundant parentheses have been added to clarify exactly how each path
504+ component maps onto an instance.
505+
506+ ```lua
507+ -- "./" prefix is equivalent to script.Parent
508+ require("./MySibling")
509+ require((script.Parent).(MySibling))
510+
511+ -- "../" prefix is equivalent to script.Parent.Parent
512+ require("../SiblingOfMyParent")
513+ require((script.Parent.Parent).(SiblingOfMyParent))
514+
515+ -- "../" can be chained to go up multiple levels
516+ require("../../SiblingOfMyGrandparent")
517+ require((script.Parent.Parent).(Parent).(SiblingOfMyGrandparent))
518+
519+ -- "@self" prefix corresponds to the script itself
520+ require("@self/MyChild")
521+ require((script).(MyChild))
522+ ```
523+
514524 Once the return object is created by an **initial**
515525 `Global.LuaGlobals.require()` call of a `Class.ModuleScript`, future
516526 `Global.LuaGlobals.require()` calls for the same `Class.ModuleScript` (on
0 commit comments