Fix/droplet manager

[Raild3x]

This pull request refactors and enhances the client-side droplet logic in the droplet manager system. The changes improve code organization, add new features for droplet behavior, and update APIs for clarity and flexibility. The most important changes are grouped below.

Droplet Behavior and Features

• Added new properties and methods to the Droplet class to support magnetization, settling, and collection logic, including GetMagnetizationRadius, IsSettled, and MustSettleBeforeCollect. These allow droplets to magnetize towards players and require settling before being collected. [1] [2]
• Improved magnetization and collection processes: droplets now check for player validity and distance using a configurable radius, and magnetization is started or aborted accordingly. Gravity adjustment prevents overshooting, and droplet mass is referenced from a shared utility for consistency. [1] [2] [3]

API and Code Organization

• Renamed and refactored methods for clarity, such as changing AttachModel to Attach, updating parameter handling, and adding detailed doc comments. Methods for fetching droplet data (value, metadata, resource type, position, etc.) are now more clearly documented and organized. [1] [2]
• Improved task management: timeout threads and magnetization threads are now named consistently, and the droplet's lifecycle is managed using promises for timeout logic. [1] [2] [3] [4]

Utilities and Constants

• Moved constants like PLAYER_MASS and MAX_MAGNETIZATION_RADIUS to DropletUtil for central management, and updated references throughout the codebase for consistency. [1] [2] [3]
• Refactored the ejection velocity calculation in DropletClientManager to support arbitrary directions and improved vector math for more flexible droplet launching.

Type and File Updates

• Updated type definitions for the Droplet export, and renamed files from .lua to .luau to reflect the use of Luau-specific features.
• Improved raycast filtering logic to dynamically add/remove characters and droplet folders, ensuring accurate collision filtering during gameplay.

These changes collectively improve the flexibility, maintainability, and clarity of the droplet client logic.

[Copilot]

Pull request overview

This PR refactors the DropletManager system from a singleton pattern to a module-based approach, adds new features for droplet magnetization and settling behavior, and improves code organization. The changes include enhanced droplet lifecycle management, better ejection velocity calculations with arbitrary direction support, and new configuration options for magnetization and collection behavior.

Changes:

• Refactored both server and client managers from singleton classes to static module tables
• Added new droplet properties: magnetization radius, settle-before-collect requirement, and improved settling detection
• Enhanced ejection velocity calculations to support arbitrary ejection directions with proper vector math
• Moved constants to DropletUtil for centralized configuration and added comprehensive documentation

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
wally.toml	Updated version to 0.1.0 and added new dependencies (Heap, Janitor, Signal)
init.luau	Updated lazy initialization to return modules directly instead of singleton instances
DropletServerManager.luau	Converted from singleton class to module with static state, removed BaseObject dependency
ExampleResourceTypeData.luau	Added new default properties for magnetization radius and settle requirements, updated API calls
DropletUtil.luau	Added centralized constants for player mass, magnetization limits, and default values with documentation
DropletsFolder.luau	New file creating workspace folder for droplet instances
DropletClientManager.luau	Refactored to module pattern, improved ejection velocity with orthonormal basis, added heap-based radius tracking
Droplet.luau	Added settling detection, magnetization radius methods, timeout promise handling, enhanced Attach method
README.md	Updated version number to 0.1.0

Comments suppressed due to low confidence (19)

lib/dropletmanager/src/ExampleResourceTypeData.luau:40

• The comment says "Maxiumum" which should be "Maximum".
  lib/dropletmanager/src/ExampleResourceTypeData.luau:222
• The comment says "dissapears" which should be "disappears".
  lib/dropletmanager/src/Client/Droplet.luau:206
• Indentation uses tabs instead of spaces. This is inconsistent with the rest of the file which uses spaces. Mixing tabs and spaces can cause issues with code editors and version control.
  lib/dropletmanager/src/Client/Droplet.luau:43
• The raycast filter management has a potential issue. Line 38 uses AddToFilter() which modifies the FilterDescendantsInstances array, but line 41-42 manually modifies the same array and then clones it. This creates inconsistency - either use the AddToFilter/RemoveFromFilter API consistently, or manually manage the array. Mixing both approaches can lead to unexpected behavior.
  lib/dropletmanager/src/Client/DropletClientManager.luau:105
• The module refactoring changes the API from instance methods to module-level methods, but the connection callbacks cast DropletClientManager to any to call methods with colon syntax. This is semantically incorrect - if these are module-level functions, they should be called with dot notation and not use 'self'. The casting to any bypasses type safety without actually fixing the underlying design issue.
  lib/dropletmanager/src/Server/DropletServerManager.luau:272
• The iteration has been changed from using pairs() to first collecting all keys with RailUtil.Table.Keys() and then iterating with ipairs(). This change ensures deterministic iteration order and avoids issues with modifying a table during iteration (since Claim() may modify serverData.DropletData).
  lib/dropletmanager/src/ExampleResourceTypeData.luau:32
• The comment says "dissapears" which should be "disappears".
  lib/dropletmanager/src/DropletUtil.luau:166
• The comment says "dissapears" which should be "disappears".
  lib/dropletmanager/src/Client/Droplet.luau:369
• The method now uses QueryDescendants("BasePart") which may not exist on all Roblox instance types. The correct method is GetDescendants() with a filter check. QueryDescendants is not a standard Roblox API method.
  lib/dropletmanager/src/Client/Droplet.luau:383
• The method AttachModel has been renamed to Attach, but an alias is provided at line 383 for backward compatibility. While this maintains compatibility, consider documenting this as deprecated in favor of the new name, or decide whether to keep both or only the new name for cleaner API design.
  lib/dropletmanager/src/Client/Droplet.luau:239
• The settled state is reset to 0 only in the else branch, but it should also be reset when the droplet starts moving again (velocity exceeds threshold). This logic appears incomplete - if a droplet settles, then gets disturbed, settledFor won't be reset properly if the velocity check fails.
  lib/dropletmanager/src/init.luau:167
• The type annotation shows these are typed as the module itself rather than instances. The variables Server and Client should be typed as the return types of the respective manager modules if they're meant to be singleton instances, not the module types themselves.
  lib/dropletmanager/src/ExampleResourceTypeData.luau:231
• The comment says "Maxiumum" which should be "Maximum".
  lib/dropletmanager/src/Client/Droplet.luau:559
• The export type has changed from an instance type to the module type itself. This breaks the type system as Droplet should represent an instance created by Droplet.new(), not the module table. The original typeof(Droplet.new({} :: any)) was correct.
  lib/dropletmanager/src/Server/DropletServerManager.luau:296
• The warning is now always displayed instead of being conditional on a DEBUG flag. This may produce excessive console noise in production. Consider using the DEBUG flag consistently throughout the module or removing it entirely if debug logging is no longer needed.
  lib/dropletmanager/src/Client/DropletClientManager.luau:220
• The signal name changed from "Timedout" to "TimedOut". While this improves consistency with standard casing conventions (PascalCase for compound words), this is a breaking API change that will break any external code listening to the old signal name.
  lib/dropletmanager/src/init.luau:64
• The variable name "SetupData" is used consistently in the return statement at line 64, but the earlier comment at line 60 says "Create metadata to be used in the render functions". The return statement now correctly returns "SetupData" instead of the undefined "CustomData", fixing the bug.
  lib/dropletmanager/src/Server/DropletServerManager.luau:411
• The seed generation range changed from 2^16 (65,536) to 2^20 (1,048,576). This significantly increases the seed space which reduces collision probability. However, this is a breaking change if any external systems depend on the previous seed range. Consider documenting this change in release notes.
  lib/dropletmanager/src/Server/DropletServerManager.luau:370
• OnServerCollect is invoked purely based on the client‑fired DropletCollected event, with no server‑side verification that the player actually reached or collided with the droplet. A compromised client can call DropletCollected for any droplet it is targeted for (and front‑run other players for SingleCollector droplets), causing server logic like awarding money/EXP in OnServerCollect to run even when the in‑game collection conditions were never met. To prevent this, treat the server as authoritative: derive and validate collection eligibility on the server (e.g. using the player’s character position and droplet state) before calling OnServerCollect, rather than trusting the client’s notification alone.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.