Skip to main content

DropletUtil

Internal utility functions for droplets

Types​

WeightedArray<T>​

</>
type WeightedArray<T> = {{
Weight: number,
Value: T
}}

A table of values with weights. The weights are used to calculate the probability of a value being chosen. The weights do not need to add up to 1. See ProbabilityDistributor for more information.

NumOrRange​

</>
type NumOrRange = number | NumberRange

NumOrRangeOrWeightedArray​

</>
type NumOrRangeOrWeightedArray = NumOrRange | WeightedArray<NumOrRange>

ResourceTypeData​

</>
interface ResourceTypeData {
Defaults: table
SetupDroplet: (droplet: Droplet) → any?
OnRenderUpdate: ((
droplet: Droplet,
renderTime: number
) → (CFrame?))?
OnDropletTimeout: ((droplet: Droplet) → ())?
OnClientClaim: ((
playerWhoCollected: Player,
droplet: Droplet
) → ())?
OnClientCollect: ((
playerWhoCollected: Player,
droplet: Droplet
) → ())?
OnServerCollect: ((
playerWhoCollected: Player,
value: any,
metadata: any
) → ())?
}

  • [Defaults] is a table of default values for the droplet. This can be left empty. The values in this table are used to fill in any missing values in the ResourceSpawnData when a droplet is spawned as well as overriding certain behaviors internally for things like magnetization.

  • CollectionRadius - Distance from the player's center that the droplet must be to be collected

  • MagnetizationRadius - Distance from the player at which the droplet starts moving towards them

  • MustSettleBeforeCollect - If true, droplet must come to a complete stop before it can be claimed

  • [SetupDroplet] is called when a new droplet is created. Use this to setup your visuals and any variables you need to keep track of. All parts within this should be Anchored = false, CanCollide = false, and Massless = true. The return value of this function can be accessed via Droplet:GetSetupData()

  • [OnRenderUpdate] is called every frame that the droplet is within render range of the LocalPlayer's Camera. Use this to update the visuals of your droplet. The return value, if one is given, must be a CFrame and is used for offsetting the droplet.

  • [OnDropletTimeout] is called when the droplet times out. Use this to perform/cleanup any visual effects you may have.

  • [OnClientClaim] is called when the server acknowledges that the droplet has been claimed.

  • [OnClientCollect] is called when the droplet hits the player and is considered collected. It should be used for collection effects and other client side things.

  • [OnServerCollect] is called once the server is informed by a client that the droplet has been collected. This is where you should perform any server side logic like actually giving things like Money or Exp.

ResourceSpawnData​

</>
interface ResourceSpawnData {
ResourceType: string--

The registered name of the resource type

Value: any | NumOrRangeOrWeightedArray--

The value of the droplet

Metadata: any?--

The metadata of the droplet

SpawnLocation: Vector3 | CFrame | PVInstance--

The location to spawn the droplet

CollectorMode: CollectorMode?--

The behavior of how the droplet is claimed

PlayerTargets: Player | {Player}?--

The players that can collect the droplet

LifeTime: NumOrRange?--

The time before the droplet dissapears

Count: NumOrRangeOrWeightedArray?--

The number of droplets to spawn

EjectionDuration: NumOrRangeOrWeightedArray?--

The time it takes to spew out all the droplets

EjectionHorizontalVelocity: NumOrRangeOrWeightedArray?--

The horizontal velocity of the droplets when they are ejected (perpendicular to ejection direction)

EjectionVerticalVelocity: NumOrRangeOrWeightedArray?--

The vertical velocity of the droplets when they are ejected (along ejection direction)

EjectionDirection: Vector3?--

The direction to eject droplets towards (defaults to Vector3.yAxis)

}
Special Behaviors

Any index that takes a NumOrRangeOrWeightedArray will be parsed and calculated ahead of time internally so that the client and server are synced. For example, if you pass in a NumberRange for Value, the server will calculate a random decimal number between the min and max, this number would then be accessed by Droplet:GetValue() on the client.

CollectorMode​

</>
type CollectorMode = "MultiCollector" | "SingleCollector"

The behavior of how the droplet is claimed.

  • MultiCollector - Many players can collect this droplet, each has their own individual instance

  • SingleCollector - Only one player can collect this droplet

Properties​

Enums​

</>
DropletUtil.Enums: {CollectorMode: {
MultiCollector: CollectorMode,
SingleCollector: CollectorMode
}}

DEFAULT_COLLECTOR_MODE​

This item only works when running on the server. Server
</>
DropletUtil.DEFAULT_COLLECTOR_MODE: CollectorMode

The default collector mode for droplets

DEFAULT_COUNT​

This item only works when running on the server. Server
</>
DropletUtil.DEFAULT_COUNT: NumOrRangeOrWeightedArray

The default number of droplets to spawn

DEFAULT_LIFETIME​

This item only works when running on the server. Server
</>
DropletUtil.DEFAULT_LIFETIME: NumOrRangeOrWeightedArray

The default lifetime for droplets

DEFAULT_EJECTION_DURATION​

This item only works when running on the server. Server
</>
DropletUtil.DEFAULT_EJECTION_DURATION: number

The default ejection duration for droplets.

DEFAULT_COLLECTION_RADIUS​

This item only works when running on the client. Client
</>
DropletUtil.DEFAULT_COLLECTION_RADIUS: number

The default radius within which droplets are marked for collection.

MAX_MAGNETIZATION_RADIUS​

This item only works when running on the client. Client
</>
DropletUtil.MAX_MAGNETIZATION_RADIUS: number

The radius within which droplets are allowed to magnetize towards players. Beyond this radius, droplets will not magnetize and will just be instantly collected. This is to prevent wildly swinging droplets that gain tons of acceleration from far away.

RENDER_RADIUS​

This item only works when running on the client. Client
</>
DropletUtil.RENDER_RADIUS: number

The radius within which droplets will have their render functions called

PLAYER_MASS​

This item only works when running on the client. Client
</>
DropletUtil.PLAYER_MASS: number

The default player mass for gravitational calculations

Show raw api
{
    "functions": [
        {
            "name": "parse",
            "desc": "",
            "params": [
                {
                    "name": "v",
                    "desc": "",
                    "lua_type": "NumOrRangeOrWeightedArray | any"
                },
                {
                    "name": "numGen",
                    "desc": "",
                    "lua_type": "Random"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "private": true,
            "source": {
                "line": 355,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "calculateDropletValues",
            "desc": "",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any | NumOrRangeOrWeightedArray"
                },
                {
                    "name": "count",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "seed",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "lifeTime",
                    "desc": "",
                    "lua_type": "NumOrRangeOrWeightedArray"
                }
            ],
            "returns": [],
            "function_type": "static",
            "private": true,
            "source": {
                "line": 369,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Enums",
            "desc": "",
            "lua_type": "{CollectorMode: {MultiCollector: CollectorMode, SingleCollector: CollectorMode}}",
            "source": {
                "line": 238,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "DROPLET_COLLISION_GROUP",
            "desc": "The default collision group for droplets",
            "lua_type": "string",
            "private": true,
            "source": {
                "line": 266,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "DEFAULT_COLLECTOR_MODE",
            "desc": "The default collector mode for droplets",
            "lua_type": "CollectorMode",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 274,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "DEFAULT_COUNT",
            "desc": "The default number of droplets to spawn",
            "lua_type": "NumOrRangeOrWeightedArray",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 282,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "DEFAULT_LIFETIME",
            "desc": "The default lifetime for droplets",
            "lua_type": "NumOrRangeOrWeightedArray",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 290,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "DEFAULT_EJECTION_DURATION",
            "desc": "The default ejection duration for droplets.",
            "lua_type": "number",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 298,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "DEFAULT_COLLECTION_RADIUS",
            "desc": "The default radius within which droplets are marked for collection.",
            "lua_type": "number",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 306,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "MAX_MAGNETIZATION_RADIUS",
            "desc": "The radius within which droplets are allowed to magnetize towards players. Beyond this\nradius, droplets will not magnetize and will just be instantly collected. This is to prevent\nwildly swinging droplets that gain tons of acceleration from far away.",
            "lua_type": "number",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 316,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "RENDER_RADIUS",
            "desc": "The radius within which droplets will have their render functions called",
            "lua_type": "number",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 324,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "PLAYER_MASS",
            "desc": "The default player mass for gravitational calculations",
            "lua_type": "number",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 332,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        }
    ],
    "types": [
        {
            "name": "WeightedArray<T>",
            "desc": "A table of values with weights. The weights are used to calculate the probability\nof a value being chosen. The weights do not need to add up to 1. See `ProbabilityDistributor`\nfor more information.",
            "lua_type": "{ {Weight: number, Value: T} }",
            "source": {
                "line": 72,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "NumOrRange",
            "desc": "",
            "lua_type": "number | NumberRange",
            "source": {
                "line": 78,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "NumOrRangeOrWeightedArray",
            "desc": "",
            "lua_type": "NumOrRange | WeightedArray<NumOrRange>",
            "source": {
                "line": 84,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "ResourceTypeData",
            "desc": "- `[Defaults]` is a table of default values for the droplet. This can be left empty.\nThe values in this table are used to fill in any missing values in the ResourceSpawnData\nwhen a droplet is spawned as well as overriding certain behaviors internally for things\nlike magnetization.\n\n- `CollectionRadius` - Distance from the player's center that the droplet must be to be collected\n- `MagnetizationRadius` - Distance from the player at which the droplet starts moving towards them\n- `MustSettleBeforeCollect` - If true, droplet must come to a complete stop before it can be claimed\n\n- `[SetupDroplet]` is called when a new droplet is created. Use this to setup your visuals and\nany variables you need to keep track of. All parts within this should be\n`Anchored = false, CanCollide = false, and Massless = true`.\nThe return value of this function can be accessed via Droplet:GetSetupData()\n\n- `[OnRenderUpdate]` is called every frame that the droplet is within render range of the\nLocalPlayer's Camera. Use this to update the visuals of your droplet.\nThe return value, if one is given, must be a CFrame and is used for offsetting the droplet.\n\n- `[OnDropletTimeout]` is called when the droplet times out. Use this to perform/cleanup\nany visual effects you may have.\n\n- `[OnClientClaim]` is called when the server acknowledges that the droplet has been claimed.\n\n- `[OnClientCollect]` is called when the droplet hits the player and is considered collected.\nIt should be used for collection effects and other client side things.\n\n- `[OnServerCollect]` is called once the server is informed by a client that the droplet has\nbeen collected. This is where you should perform any server side logic like actually\ngiving things like Money or Exp.",
            "fields": [
                {
                    "name": "Defaults",
                    "lua_type": "table",
                    "desc": ""
                },
                {
                    "name": "SetupDroplet",
                    "lua_type": "(droplet: Droplet) -> any?",
                    "desc": ""
                },
                {
                    "name": "OnRenderUpdate",
                    "lua_type": "((droplet: Droplet, renderTime: number) -> (CFrame?))?",
                    "desc": ""
                },
                {
                    "name": "OnDropletTimeout",
                    "lua_type": "((droplet: Droplet) -> ())?",
                    "desc": ""
                },
                {
                    "name": "OnClientClaim",
                    "lua_type": "((playerWhoCollected: Player, droplet: Droplet) -> ())?",
                    "desc": ""
                },
                {
                    "name": "OnClientCollect",
                    "lua_type": "((playerWhoCollected: Player, droplet: Droplet) -> ())?",
                    "desc": ""
                },
                {
                    "name": "OnServerCollect",
                    "lua_type": "((playerWhoCollected: Player, value: any, metadata: any) -> ())?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 127,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "ResourceSpawnData",
            "desc": ":::caution Special Behaviors\nAny index that takes a `NumOrRangeOrWeightedArray` will be parsed and calculated\nahead of time internally so that the client and server are synced. For example,\nif you pass in a `NumberRange` for `Value`, the server will calculate a random\ndecimal number between the min and max, this number would then be accessed by\n`Droplet:GetValue()` on the client.\n:::",
            "fields": [
                {
                    "name": "ResourceType",
                    "lua_type": "string",
                    "desc": "The registered name of the resource type"
                },
                {
                    "name": "Value",
                    "lua_type": "any | NumOrRangeOrWeightedArray",
                    "desc": "The value of the droplet"
                },
                {
                    "name": "Metadata",
                    "lua_type": "any?",
                    "desc": "The metadata of the droplet"
                },
                {
                    "name": "SpawnLocation",
                    "lua_type": "Vector3 | CFrame | PVInstance",
                    "desc": "The location to spawn the droplet"
                },
                {
                    "name": "CollectorMode",
                    "lua_type": "CollectorMode?",
                    "desc": "The behavior of how the droplet is claimed"
                },
                {
                    "name": "PlayerTargets",
                    "lua_type": "Player | {Player}?",
                    "desc": "The players that can collect the droplet"
                },
                {
                    "name": "LifeTime",
                    "lua_type": "NumOrRange?",
                    "desc": "The time before the droplet dissapears"
                },
                {
                    "name": "Count",
                    "lua_type": "NumOrRangeOrWeightedArray?",
                    "desc": "The number of droplets to spawn"
                },
                {
                    "name": "EjectionDuration",
                    "lua_type": "NumOrRangeOrWeightedArray?",
                    "desc": "The time it takes to spew out all the droplets"
                },
                {
                    "name": "EjectionHorizontalVelocity",
                    "lua_type": "NumOrRangeOrWeightedArray?",
                    "desc": "The horizontal velocity of the droplets when they are ejected (perpendicular to ejection direction)"
                },
                {
                    "name": "EjectionVerticalVelocity",
                    "lua_type": "NumOrRangeOrWeightedArray?",
                    "desc": "The vertical velocity of the droplets when they are ejected (along ejection direction)"
                },
                {
                    "name": "EjectionDirection",
                    "lua_type": "Vector3?",
                    "desc": "The direction to eject droplets towards (defaults to Vector3.yAxis)"
                }
            ],
            "source": {
                "line": 181,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        },
        {
            "name": "CollectorMode",
            "desc": "The behavior of how the droplet is claimed.\n\n- `MultiCollector` - Many players can collect this droplet, each has their own individual instance\n\n- `SingleCollector` - Only one player can collect this droplet",
            "lua_type": "\"MultiCollector\" | \"SingleCollector\"",
            "source": {
                "line": 250,
                "path": "lib/dropletmanager/src/DropletUtil.luau"
            }
        }
    ],
    "name": "DropletUtil",
    "desc": "Internal utility functions for droplets",
    "source": {
        "line": 8,
        "path": "lib/dropletmanager/src/DropletUtil.luau"
    }
}