PlayerMouse2, a modern alternative to the legacy PlayerMouse

Bulletin Board
#1

Preface

The Roblox PlayerMouse is legacy. I imagine it being deprecated within the next few years, and Roblox has been encouraging us to use the newer alternatives they provide, such as ContextActionService and UserInputService. These services do what the PlayerMouse did but better and more. For this reason I made PlayerMouse2. It uses UserInputService and recreates most properties of the old PlayerMouse without actually using it at all.

Documentation

Events

PlayerMouse2.Button1Down ( bool engine_processed )

Fired when the left mouse button is pressed. The engine_processed argument determines if the engine processed this input.

PlayerMouse2.Button2Down ( bool engine_processed )

Fired when the right mouse button is pressed. The engine_processed argument determines if the engine processed this input.

PlayerMouse2.Button1Up ( bool engine_processed )

Fired when the left mouse button is released. The engine_processed argument determines if the engine processed this input.

PlayerMouse2.Button2Up ( bool engine_processed )

Fired when the right mouse button is released. The engine_processed argument determines if the engine processed this input.

PlayerMouse2.Moved ( bool engine_processed )

Fired when the mouse is moved. The engine_processed argument determines if the engine processed this input.

PlayerMouse2.WheelScrolled ( int direction, bool engine_processed )

Fired when the mouse wheel is scrolled. The direction argument is an integer, and will have value 1 if the mouse was scrolled in the forward direction; otherwise -1 if scrolled backwards. The engine_processed argument determines if the engine processed this input.

PlayerMouse2.WheelDown ( bool engine_processed )

Fired when the mouse wheel is pressed. The engine_processed argument determines if the engine processed this input.

PlayerMouse2.WheelUp ( bool engine_processed )

Fired when the mouse wheel is released. The engine_processed argument determines if the engine processed this input.

Properties

int PlayerMouse2.X

The 2D X-coordinate of the mouse.

int PlayerMouse2.Y

The 2D Y-coordinate of the mouse. Accounts for the topbar inset. So subtract by 36 to remove this. This property may be updated in the future to no longer account for the inset.

Vector3 PlayerMouse2.Position

The position of the mouse in the 3D world. The PlayerMouse’s Hit property is a CFrame, however it is usually only used for its Position.

Instance<BasePart> PlayerMouse2.Target

The BasePart the mouse is currently hovering over. This value is nil if the mouse is not pointing at a BasePart, e.g the sky.

CFrame PlayerMouse2.Origin

The CFrame that determines where the mouse originated from. Its position is at the camera’s CFrame.Position and rotated towards the mouse’s Position.

Ray PlayerMouse2.UnitRay

A normalized ray whose origin is the camera’s CFrame.Position, directed towards the mouse Position.

bool PlayerMouse2.Enabled

Boolean that determines whether or not the mouse icon is enabled.

table PlayerMouse2.TargetFilter

List of instances (and its descendants) to be ignored by PlayerMouse2.Target and PlayerMouse2.Position.

Caveats

  • Does not support changing the mouse Icon. I could slap a ScreenGui and an ImageLabel however this means when you hover your mouse over the player list, purchase prompts, etc. they will bury the icon. So this seems to be the only caveat so far. A secondary solution would be to just use the mouse for its Icon property however that completely goes against the goal of this module.

  • Does not support ViewSizeX and ViewSizeY. I don’t even consider this a caveat because it just doesn’t seem appropriate for these members to be a part of mouse. The Camera has a ViewportSize property which seems to replicate this.

Code Example

local PlayerMouse2 = require(Path.To.PlayerMouse2.Module)

PlayerMouse2.WheelScrolled:Connect(function(direction)
    print(direction == 1 and "The wheel scrolled forward!" or "The wheel scrolled backward!")
end)

PlayerMouse2.Button2Down:Connect(function(engine_processed)
    print("Right button down!", engine_processed)
end)

Licensing

This module is licensed under the MIT License.

6 Likes
#2

I think EgoMoose already made an alternative to PlayerMouse: UserInputService Mouse

Do tell me if this module is different from his though, and when to use this one or EgoMoose’s.

Also, is the documentation complete yet? I don’t see TargetFilter, which may be useful in a lot of scripts. And if you do plan on adding TargetFilter(if it wasn’t done yet), would it be possible to make it an array instead of only one object? One of the biggest problems with the PlayerMouse is that the TargetFilter can only be one object.

Hope this helped!

#3

I think mine is easier to use. And EgoMoose’s module is object-oriented for some reason. I don’t think OOP fits into something like this. It also doesn’t seem like this module is updated frequently (last update was over a year ago).

For now, yes. However I will be adding more events/properties in the future.

Yeah I definitely have seen many other people want TargetFilter to be a table as well. And I overlooked this while making the module. I have just implemented this now.

1 Like
#4

EgoMoose’s version is pretty much a recreation of the original PlayerMouse (except better) just like yours, so I don’t see how it’s any easier to use yours. It doesn’t really need to be updated often. It does use OOP by default, but by adding 6 characters (.new()) to the end of the module, it’ll pretty much remove the OOP aspect, so I don’t think that’s a big issue by any means whatsoever.

There’s also @EmeraldSlash’s RbxMouse module, which isn’t mean to mimic the original api and is fairly feature rich for anyone who wants an upgrade from the original PlayerMouse api. I personally recommend this module over EgoMoose’s since the api is nicer, since it’s not a copy of the original api.

#5

I haven’t looked at the module but is it cross-platform may I ask? Mouse.Hit is easily replicated by UserInputService:GetMouseLocation() with some extra code since it’s Vector2 but how would you handle mobile & Xbox for instance?