@rbxts/falldown 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 irishfix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/out/index.d.ts

@@ -0,0 +1,103 @@
+import { Signal } from "@rbxts/beacon";
+/**
+ * Interface representing an active ragdoll instance. Users receive pre-constructed instances from {@linkcode Falldown.RagdollCharacter}.
+ * @interface
+ * @see {@linkcode Falldown}
+ * @see {@linkcode Falldown.RagdollCharacter}
+ */
+export interface IActiveRagdoll {
+    /** The character `Model` that is currently ragdolled. */
+    readonly Character: Model;
+    /** The `Humanoid` instance of the ragdolled character. */
+    readonly Humanoid: Humanoid;
+    /** Signal that fires when the ragdoll is destroyed. Fires after character removal, manual {@linkcode Destroy} call, or automatic duration expiry.
+     * @see {@linkcode IActiveRagdoll.Destroy}
+     */
+    readonly Destroyed: Signal<void>;
+    /** Signal that fires when the ragdoll's getup animation completes and the character is restored to normal control. Fires before {@linkcode Destroyed}.
+     * @see {@linkcode IActiveRagdoll.Destroyed}
+     */
+    readonly Ended: Signal<void>;
+    /**
+     * Applies velocity to the ragdolled character using different distribution modes.
+     * @param velocity - The velocity vector to apply (in studs/second)
+     * @param mode - The velocity distribution mode from {@linkcode Falldown.VelocityMode}
+     * @see {@linkcode Falldown.VelocityMode}
+     * @see {@linkcode IActiveRagdoll.AddRandomVelocity}
+     */
+    AddVelocity(velocity: Vector3, mode: (typeof Falldown.VelocityMode)[keyof typeof Falldown.VelocityMode]): void;
+    /**
+     * Applies random velocity to each body part independently in all directions. Each part receives random velocity with components in range `[-maxVelocity, maxVelocity]`.
+     * @param maxVelocity - Maximum velocity magnitude for each axis (in studs/second)
+     * @see {@linkcode IActiveRagdoll.AddVelocity}
+     */
+    AddRandomVelocity(maxVelocity: number): void;
+    /**
+     * Manually ends the ragdoll state and restores the character to normal control. Plays the appropriate getup animation, removes ragdoll constraints, positions character upright, and fires {@linkcode Ended} and {@linkcode Destroyed} signals.
+     * @see {@linkcode IActiveRagdoll.Ended}
+     * @see {@linkcode IActiveRagdoll.Destroyed}
+     * @see {@linkcode Falldown.UnragdollCharacter}
+     */
+    Destroy(): void;
+}
+/**
+ * Main Falldown class providing static methods for ragdolling characters in Roblox. Creates realistic ragdoll physics by replacing Motor6Ds with constraints, managing collision groups, and providing smooth getup animations.
+ * @static
+ * @see {@linkcode IActiveRagdoll}
+ * @see {@linkcode Falldown.VelocityMode}
+ */
+export declare class Falldown {
+    /**
+     * Enum used to represent how velocity should be distributed across a ragdolled character's body parts.
+     * @static
+     * @readonly
+     * @enum {number}
+     * @see {@linkcode IActiveRagdoll.AddVelocity}
+     */
+    static VelocityMode: {
+        /** Applies velocity only to the HumanoidRootPart. Most efficient for general movement like falling or launching. */
+        readonly RootOnly: 0;
+        /** Applies the full velocity vector to every body part independently. Creates the strongest force, useful for powerful impacts. */
+        readonly AllEqual: 1;
+        /** Divides the velocity magnitude evenly across all body parts. Total momentum remains constant regardless of part count. Good for realistic physics. */
+        readonly SplitEqual: 2;
+        /** Each part gets a random velocity from 0 to the specified magnitude in the same direction. Creates varied motion, useful for explosions. */
+        readonly RandomMax: 3;
+    };
+    private static readonly _activeRagdolls;
+    private static MakeProxies;
+    private static CreateActiveRagdollR6;
+    private static CreateActiveRagdollR15;
+    /**
+     * Converts a character into a ragdoll with physics-based movement. Detects R6/R15 rig automatically, replaces Motor6Ds with constraints, creates collision proxies, and sets up automatic recovery.
+     * @static
+     * @param character - The character `Model` to ragdoll. Must have a Humanoid.
+     * @param standupFadeTime - Duration (in seconds) for the fade clone to remain visible after standing up. Recommended: 0.3-0.7 seconds.
+     * @param automaticDuration - Optional. If provided, the ragdoll will automatically end after this many seconds. If omitted, you must manually call {@linkcode IActiveRagdoll.Destroy} to end the ragdoll.
+     * @param getupFront - Optional. Animation to play when getting up while facing forward (belly down). If not provided, character snaps to standing.
+     * @param getupBack - Optional. Animation to play when getting up while facing backward (back down). If not provided, character snaps to standing.
+     * @returns An {@linkcode IActiveRagdoll} interface if successful, or `undefined` if character is already ragdolled, has no Humanoid, or is missing required body parts.
+     * @see {@linkcode IActiveRagdoll}
+     * @see {@linkcode Falldown.UnragdollCharacter}
+     * @see {@linkcode Falldown.VelocityMode}
+     */
+    static RagdollCharacter(character: Model, standupFadeTime: number, automaticDuration?: number, getupFront?: Animation, getupBack?: Animation): IActiveRagdoll | undefined;
+    /**
+     * Manually ends the ragdoll state for a specific character. Equivalent to calling {@linkcode IActiveRagdoll.Destroy} on the ragdoll instance. If the character is not currently ragdolled, this method does nothing.
+     * @static
+     * @param character - The character `Model` to un-ragdoll
+     * @param delayTime - Optional. If provided, delays the un-ragdoll by this many seconds. If omitted, un-ragdolls immediately.
+     * @see {@linkcode IActiveRagdoll.Destroy}
+     * @see {@linkcode Falldown.RagdollCharacter}
+     * @see {@linkcode Falldown.UnragdollAllCharacters}
+     */
+    static UnragdollCharacter(character: Model, delayTime?: number): void;
+    /**
+     * Ends the ragdoll state for ALL currently ragdolled characters. Useful for game-wide effects like round resets or emergency cleanup. Each character performs their getup animation independently.
+     * @static
+     * @param delayTime - Optional. If provided, delays the un-ragdoll by this many seconds for all characters. If omitted, un-ragdolls all immediately.
+     * @see {@linkcode Falldown.UnragdollCharacter}
+     * @see {@linkcode Falldown.RagdollCharacter}
+     */
+    static UnragdollAllCharacters(delayTime?: number): void;
+}