# 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: []