rules

.cursor/rules/roblox/reference/engine/classes/ModuleScript.yaml

@@ -0,0 +1,110 @@
+# This file is automatically generated. Please don't edit it manually.
+# To submit a bug report on the content, see
+# https://devforum.roblox.com/c/bug-reports/documentation-issues/72
+
+name: ModuleScript
+type: class
+memory_category: Script
+summary: |
+  A script type that runs once when `Global.LuaGlobals.require()` is called with
+  it. Returns exactly one value, usually a table of functions, to used by other
+  scripts. Useful for compartmentalizing code.
+description: |
+  A `Class.ModuleScript` is a script type that returns exactly one value by a
+  call to `Global.LuaGlobals.require()`. `Class.ModuleScript|ModuleScripts` run
+  once and only once per Luau environment and return the exact same value for
+  subsequent calls to `Global.LuaGlobals.require()`.
+
+  `Class.ModuleScript|ModuleScripts` are essential objects for adhering to the
+  "Don't Repeat Yourself" (DRY) principle, allowing you to write a function only
+  once and use it everywhere. Having multiple copies of a function is
+  problematic when you need to change their behavior, so you should define
+  functions or groups of functions in `Class.ModuleScript|ModuleScripts` and
+  have your `Class.Script|Scripts` and `Class.LocalScript|LocalScripts` call
+  `Global.LuaGlobals.require()` on those modules.
+
+  It's important to know that return values from
+  `Class.ModuleScript|ModuleScripts` are independent with regards to
+  `Class.Script|Scripts` and `Class.LocalScript|LocalScripts`, and other
+  environments like the
+  [Command Bar](../../../studio/ui-overview.md#command-bar). Using
+  `Global.LuaGlobals.require()` on a `Class.ModuleScript` in a
+  `Class.LocalScript` will run the code on the client, even if a `Class.Script`
+  did so already on the server. Therefore, be careful if you're using a
+  `Class.ModuleScript` on the client and server at the same time, or debugging
+  it within Studio.
+
+  Note that the first call to `Global.LuaGlobals.require()` will not yield
+  (halt) unless the `Class.ModuleScript` yields (calls `Library.task.wait()` for
+  example), in which case the current thread that called
+  `Global.LuaGlobals.require()` will yield until the `Class.ModuleScript`
+  returns a value. If a `Class.ModuleScript` is attempting to
+  `Global.LuaGlobals.require()` another `Class.ModuleScript` that in turn tries
+  to `Global.LuaGlobals.require()` it, the thread will **hang and never halt**
+  (cyclic `Global.LuaGlobals.require()` calls do not generate errors). Be
+  mindful of your module dependencies in large projects!
+
+  If a `Class.ModuleScript` is uploaded to Roblox and the root module has the
+  name set to `MainModule`, it can be uploaded as a model and required using
+  `Global.LuaGlobals.require()` with the model's asset ID. Then it can be loaded
+  into your experience, although this logic only works on the server and will
+  error on the client. If other users want to use the module, it must be public.
+code_samples:
+  - Simple-ModuleScript-Example
+  - Simple-ModuleScript-Usage
+inherits:
+  - LuaSourceContainer
+descendants: []
+tags: []
+deprecation_message: ''
+properties:
+  - name: ModuleScript.LinkedSource
+    summary: |
+      Used to store a URL that points to an online script source. Binds the
+      online code to the script's `Class.Script.Source`.
+    description: |
+      Used to store a URL that points to an online script source. Binds the
+      online code to the script's `Class.Script.Source`.
+    code_samples: []
+    type: ContentId
+    tags:
+      - Deprecated
+    deprecation_message: |
+      This property is now replaced by
+      [packages](../../../projects/assets/packages.md) which has greater
+      functionality.
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Data
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities: []
+  - name: ModuleScript.Source
+    summary: |
+      The code to be executed.
+    description: |
+      The code to be executed.
+
+      If you want to read or modify a script that the user has open, consider
+      using the `Class.ScriptEditorService` to interact with the Script Editor
+      instead.
+    code_samples: []
+    type: ProtectedString
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Data
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - PluginOrOpenCloud
+methods: []
+events: []
+callbacks: []