rules

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

@@ -0,0 +1,166 @@
+# 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: Debris
+type: class
+memory_category: Instances
+summary: |
+  Allows scheduling the guaranteed destruction of an object without yielding.  
+  .
+description: |
+  The **Debris** service allows scheduling guaranteed destruction of an object
+  without yielding.
+
+  #### Advantages
+
+  Besides creating a bit of a mess, objects that are no longer required can use
+  up system memory and cause an experience to run slower over time. For this
+  reason, it's always advised to call `Class.Instance:Destroy()` on objects you
+  no longer need. In some cases, however, an object may have a specific period
+  of utility before it can be destroyed.
+
+  Consider a wall being smashed into individual bricks. If you want a brick to
+  linger for 3 seconds before being destroyed, you can use the following code:
+
+  ```lua
+  task.wait(3)
+  brick:Destroy()
+  ```
+
+  However, waiting causes the thread to yield which may be undesired. To avoid
+  yielding, a callback function can be scheduled to run on a new thread after 3
+  seconds:
+
+  ```lua
+  task.delay(3, function()
+  	brick:Destroy()
+  end)
+  ```
+
+  Or in one line:
+
+  ```lua
+  task.delay(3, brick.Destroy, brick)
+  ```
+
+  While this now avoids yielding, it has a potential drawback in that the
+  scheduled callback will never run if the script is disabled or destroyed
+  before the callback runs.
+
+  This is where `Class.Debris` has a specific advantage, as it does not yield
+  the current thread and runs outside the context of the script, guaranteeing
+  the instance is eventually destroyed even if the script is disabled or
+  destroyed. The following code does not yield and guarantees the instance will
+  be destroyed:
+
+  ```lua
+  Debris:AddItem(brick, 3)
+  ```
+
+  Note that `Class.Debris` has a hardcoded maximum of 1,000 objects, so if more
+  than 1,000 items are added, the oldest debris will be destroyed instantly to
+  make room for new debris.
+code_samples:
+  - Debris-AddItem
+inherits:
+  - Instance
+descendants: []
+tags:
+  - NotCreatable
+  - Service
+deprecation_message: ''
+properties:
+  - name: Debris.MaxItems
+    summary: |
+      The maximum number of items that can be assigned to the `Class.Debris`
+      service at one time.
+    description: |
+      The maximum number of items that can be assigned to the Debris service at
+      one time.
+
+      If this number is exceeded, objects are automatically destroyed in order
+      from oldest to newest until the amount is less than or equal to MaxItems.
+
+      This property is currently restricted and will error if set. The value is
+      hardcoded to 1,000 items.
+    code_samples: []
+    type: int
+    tags:
+      - Deprecated
+    deprecation_message: |
+      This property is deprecated and should not be used in new work.
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Data
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - Basic
+methods:
+  - name: Debris:AddItem
+    summary: |
+      Schedules a given `Class.Instance` for destruction within the specified
+      lifetime.
+    description: |
+      Schedules a given `Class.Instance` for destruction within the specified
+      lifetime. After the `lifetime` argument has elapsed, the object is
+      destroyed in the same manner as `Class.Instance:Destroy()`. Note that the
+      `lifetime` argument is optional and defaults to 10 seconds.
+
+      Note that `Class.Debris` has a hardcoded maximum of 1,000 objects, so if
+      more than 1,000 items are added, the oldest debris will be destroyed
+      instantly to make room for new debris. This means you should treat the
+      `lifetime` parameter as a **maximum** lifetime, not an exact lifetime.
+    code_samples:
+      - Debris-AddItem
+    parameters:
+      - name: item
+        type: Instance
+        default:
+        summary: |
+          The `Class.Instance` to add to `Class.Debris`.
+      - name: lifetime
+        type: double
+        default: 10
+        summary: |
+          Number of seconds before the `Class.Instance` should be destroyed.
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    deprecation_message: ''
+    security: None
+    thread_safety: Unsafe
+    capabilities:
+      - Basic
+  - name: Debris:addItem
+    summary: ''
+    description: ''
+    code_samples: []
+    parameters:
+      - name: item
+        type: Instance
+        default:
+        summary: ''
+      - name: lifetime
+        type: double
+        default: 10
+        summary: ''
+    returns:
+      - type: ()
+        summary: ''
+    tags:
+      - Deprecated
+    deprecation_message: |
+      This function is a deprecated variant of `Class.Debris:AddItem()` which
+      should be used instead.
+    security: None
+    thread_safety: Unsafe
+    capabilities:
+      - Basic
+events: []
+callbacks: []