[DOCS] PlayerMouseEvent information

[bencres]

Documentation Issue Type

• Typo or grammatical error
• Incorrect or outdated information
• Unclear explanation or confusing content
• Missing documentation for a topic
• Broken links or images
• Code example not working
• Other (please describe)

from Zoon20X on Discord:

public class CameraDemo {
  public static final CameraDemo INSTANCE = new CameraDemo();
  
  private final EventRegistry eventRegistry = new EventRegistry(new CopyOnWriteArrayList(), () -> this.isActive, "CameraDemo is not active!", (IEventRegistry)HytaleServer.get().getEventBus());
  
  private final ServerCameraSettings cameraSettings = createServerCameraSettings();
  
  private boolean isActive;
  
  public void activate() {
    if (this.isActive)
      return; 
    this.eventRegistry.enable();
    this.isActive = true;
    this.eventRegistry.register(PlayerConnectEvent.class, event -> onAddNewPlayer(event.getPlayerRef()));
    this.eventRegistry.register(PlayerMouseButtonEvent.class, this::onPlayerMouseButton);
    this.eventRegistry.registerGlobal(PlayerInteractEvent.class, event -> event.setCancelled(true));
    Universe.get().getPlayers().forEach(this::onAddNewPlayer);
  }

so the PlayerMouseButtonEvent is directly tied and registered using the CameraDemo class, this is not registered or fired in any other class, i believe this is due to how the camera works when enabling it

typing the command /player camera demo activate puts you in a top down view in game and your mouse can freely move around and click,

private final Vector2f screenPoint; this explains what this will refer to, as it wouldn't work in a locked mouse state

[Zoon20X]

Want to add to this/ expand on it from my findings, this will also affect https://hytalemodding.dev/en/docs/guides/plugin/customizing-camera-controls

from what i have found the CameraDemo is just a demo class for the Command to show how the camera works, the way the MouseInputs are being registered requires the client to send a MouseInteract Packet to the server

    if (packet.mouseButton != null) {
      IEventDispatcher<PlayerMouseButtonEvent, PlayerMouseButtonEvent> dispatcher = HytaleServer.get().getEventBus().dispatchFor(PlayerMouseButtonEvent.class);
      if (dispatcher.hasListener()) {
        dispatcher.dispatch((IBaseEvent) new PlayerMouseButtonEvent(ref, playerComponent, playerRefComponent, packet.clientTimestamp, item, targetBlock, targetEntity, packet.screenPoint, packet.mouseButton));
      }
      cameraManagerComponent.handleMouseButtonState(packet.mouseButton.mouseButtonType, packet.mouseButton.state, targetBlock);

this code snippet is found in the InteractionModule.class, under the doMouseInteraction method
this is fired on this

  public void handle(@Nonnull MouseInteraction packet) {
    Ref<EntityStore> ref = this.playerRef.getReference();
    if (ref == null || !ref.isValid())
      return; 
    Store<EntityStore> store = ref.getStore();
    World world = ((EntityStore)store.getExternalData()).getWorld();
    world.execute(() -> {
          Player playerComponent = (Player)store.getComponent(ref, Player.getComponentType());
          assert playerComponent != null;
          InteractionModule.get().doMouseInteraction(ref, (ComponentAccessor)store, packet, playerComponent, this.playerRef);
        });
  }

being in a state that allows your mouse to be free is what triggers the packets to be sent to the server, however im still investigating what conditions are needed to allow the mouse to be free handed

taking the demo class and stripping out 90% of the code mainly from the onPlayerMouseButton and adding in a debug to log what the event data contains, the class looks like this

public class CustomCamera {
    private final EventRegistry eventRegistry = new EventRegistry(new CopyOnWriteArrayList(), () -> this.isActive, "CameraDemo is not active!", (IEventRegistry) HytaleServer.get().getEventBus());

    private ServerCameraSettings serverCameraSettings;

    private boolean isActive;

    public CustomCamera(ServerCameraSettings serverCameraSettings){
        this.serverCameraSettings = serverCameraSettings;
        activate();
    }



    public void activate() {
        if (this.isActive) {
            return;
        }
        this.eventRegistry.enable();
        this.isActive = true;
        this.eventRegistry.register(PlayerConnectEvent.class, event -> onAddNewPlayer(event.getPlayerRef()));
        this.eventRegistry.register(PlayerMouseButtonEvent.class, this::onPlayerMouseButton);
        Universe.get().getPlayers().forEach(this::onAddNewPlayer);
    }

    private void onAddNewPlayer(PlayerRef player) {
        player.getPacketHandler().writeNoCache((Packet)new SetServerCamera(ClientCameraView.Custom, true, this.serverCameraSettings));
    }


    private void onPlayerMouseButton(PlayerMouseButtonEvent event) {
        Ref<EntityStore> ref = event.getPlayerRef();
        if (!ref.isValid()) {
            return;
        }

        Logger.info("=======PlayerMouseButtonEvent=======");

        Logger.info("MouseButton: " + event.getMouseButton().mouseButtonType);
        Logger.info("MouseButtonState: " + event.getMouseButton().state);
        Logger.info("MouseClicks: " + event.getMouseButton().clicks);

        Logger.info("ScreenPoints: " + event.getScreenPoint().x + " : " + event.getScreenPoint().y);
    }

    public void updateCamera(ServerCameraSettings serverCameraSettings){
        this.serverCameraSettings = serverCameraSettings;
        Universe.get().getPlayers().forEach(this::onAddNewPlayer);

    }
}

this will give us an output of this

[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] =======PlayerMouseButtonEvent=======
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] MouseButton: Left
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] MouseButtonState: Pressed
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] MouseClicks: 1
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] ScreenPoints: 0.20833333 : -0.11701082
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] =======PlayerMouseButtonEvent=======
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] MouseButton: Left
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] MouseButtonState: Released
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] MouseClicks: 1
[2026/01/18 07:10:02   INFO]                           [SOUT] [INFO] ScreenPoints: 0.20833333 : -0.11111111
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] =======PlayerMouseButtonEvent=======
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] MouseButton: Left
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] MouseButtonState: Pressed
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] MouseClicks: 1
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] ScreenPoints: 0.083333336 : -0.14454277
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] =======PlayerMouseButtonEvent=======
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] MouseButton: Left
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] MouseButtonState: Released
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] MouseClicks: 1
[2026/01/18 07:10:03   INFO]                           [SOUT] [INFO] ScreenPoints: 0.083333336 : -0.14454277

this is all the setup needs

    @Override
    public void setup() {
        CustomCamera customCamera = new CustomCamera(createServerCameraSettings());

    }

this was more of a dig into what and why the CameraDemo class did what it did, and led to working out the main way to run and execute on the PlayerMouseButtonEvent

this also helps explain how this was achieved https://x.com/Simon_Hypixel/status/2007888131350212658?s=20