Feature: Camera/Input locking API (#4332)

Adds API methods to control player cameras - including fancy transitions,  color fades, or simple input locks.

api/build.gradle.kts

@@ -4,4 +4,5 @@ plugins {
 
 dependencies {
     api(libs.base.api)
+    api(libs.math)
 }

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraData.java

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) 2019-2023 GeyserMC. http://geysermc.org
+ *
+ * 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.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.bedrock.camera;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.geyser.api.connection.GeyserConnection;
+
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * This interface holds all the methods that relate to a client's camera.
+ * Can be accessed through {@link GeyserConnection#camera()}.
+ */
+public interface CameraData {
+
+    /**
+     * Sends a camera fade instruction to the client.
+     * If an existing camera fade is already in progress, the current fade will be prolonged.
+     * Can be built using {@link CameraFade.Builder}.
+     * To stop a fade early, use {@link #clearCameraInstructions()}.
+     *
+     * @param fade the camera fade instruction to send
+     */
+    void sendCameraFade(@NonNull CameraFade fade);
+
+    /**
+     * Sends a camera position instruction to the client.
+     * If an existing camera movement is already in progress,
+     * the final camera position will be the one of the latest instruction, and
+     * the (optional) camera fade will be added on top of the existing fade.
+     * Can be built using {@link CameraPosition.Builder}.
+     * To stop reset the camera position/stop ongoing instructions, use {@link #clearCameraInstructions()}.
+     *
+     * @param position the camera position instruction to send
+     */
+    void sendCameraPosition(@NonNull CameraPosition position);
+
+    /**
+     * Stops all sent camera instructions (fades, movements, and perspective locks).
+     * This will not stop any camera shakes/input locks/fog effects, use the respective methods for those.
+     */
+    void clearCameraInstructions();
+
+    /**
+     * Forces a {@link CameraPerspective} on the client. This will prevent the client
+     * from changing their camera perspective until it is unlocked via {@link #clearCameraInstructions()}.
+     * <p>
+     * Note: You cannot force a client into a free camera perspective with this method.
+     * To do that, send a {@link CameraPosition} via {@link #sendCameraPosition(CameraPosition)} - it requires a set position
+     * instead of being relative to the player.
+     *
+     * @param perspective the {@link CameraPerspective} to force
+     */
+    void forceCameraPerspective(@NonNull CameraPerspective perspective);
+
+    /**
+     * Gets the client's current {@link CameraPerspective}, if one is currently forced.
+     * This will return {@code null} if the client is not currently forced into a perspective.
+     * If a perspective is forced, the client will not be able to change their camera perspective until it is unlocked.
+     *
+     * @return the forced perspective, or {@code null} if none is forced
+     */
+    @Nullable CameraPerspective forcedCameraPerspective();
+
+    /**
+     * Shakes the client's camera.
+     * <p>
+     * If the camera is already shaking with the same {@link CameraShake} type, then the additional intensity
+     * will be layered on top of the existing intensity, with their own distinct durations.<br>
+     * If the existing shake type is different and the new intensity/duration are not positive, the existing shake only
+     * switches to the new type. Otherwise, the existing shake is completely overridden.
+     *
+     * @param intensity the intensity of the shake. The client has a maximum total intensity of 4.
+     * @param duration the time in seconds that the shake will occur for
+     * @param type the type of shake
+     */
+    void shakeCamera(float intensity, float duration, @NonNull CameraShake type);
+
+    /**
+     * Stops all camera shakes of any type.
+     */
+    void stopCameraShake();
+
+    /**
+     * Adds the given fog IDs to the fog cache, then sends all fog IDs in the cache to the client.
+     * <p>
+     * Fog IDs can be found <a href="https://wiki.bedrock.dev/documentation/fog-ids.html">here</a>
+     *
+     * @param fogNameSpaces the fog IDs to add. If empty, the existing cached IDs will still be sent.
+     */
+    void sendFog(String... fogNameSpaces);
+
+    /**
+     * Removes the given fog IDs from the fog cache, then sends all fog IDs in the cache to the client.
+     *
+     * @param fogNameSpaces the fog IDs to remove. If empty, all fog IDs will be removed.
+     */
+    void removeFog(String... fogNameSpaces);
+
+    /**
+     * Returns an immutable copy of all fog affects currently applied to this client.
+     */
+    @NonNull
+    Set<String> fogEffects();
+
+    /**
+     * (Un)locks the client's camera, so that they cannot look around.
+     * To ensure the camera is only unlocked when all locks are released, you must supply
+     * a UUID when using method, and use the same UUID to unlock the camera.
+     *
+     * @param lock whether to lock the camera
+     * @param owner the owner of the lock, represented with a UUID
+     * @return if the camera is locked after this method call
+     */
+    boolean lockCamera(boolean lock, @NonNull UUID owner);
+
+    /**
+     * Returns whether the client's camera is locked.
+     *
+     * @return whether the camera is currently locked
+     */
+    boolean isCameraLocked();
+}

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraEaseType.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2019-2023 GeyserMC. http://geysermc.org
+ *
+ * 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.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.bedrock.camera;
+
+/**
+ * These are all the easing types that can be used when sending a {@link CameraPosition} instruction.
+ * When using these, the client won't teleport to the new camera position, but instead transition to it.
+ * <p>
+ * See <a href="https://easings.net/">https://easings.net/</a> for more information.
+ */
+public enum CameraEaseType {
+    LINEAR("linear"),
+    SPRING("spring"),
+    EASE_IN_SINE("in_sine"),
+    EASE_OUT_SINE("out_sine"),
+    EASE_IN_OUT_SINE("in_out_sine"),
+    EASE_IN_QUAD("in_quad"),
+    EASE_OUT_QUAD("out_quad"),
+    EASE_IN_OUT_QUAD("in_out_quad"),
+    EASE_IN_CUBIC("in_cubic"),
+    EASE_OUT_CUBIC("out_cubic"),
+    EASE_IN_OUT_CUBIC("in_out_cubic"),
+    EASE_IN_QUART("in_quart"),
+    EASE_OUT_QUART("out_quart"),
+    EASE_IN_OUT_QUART("in_out_quart"),
+    EASE_IN_QUINT("in_quint"),
+    EASE_OUT_QUINT("out_quint"),
+    EASE_IN_OUT_QUINT("in_out_quint"),
+    EASE_IN_EXPO("in_expo"),
+    EASE_OUT_EXPO("out_expo"),
+    EASE_IN_OUT_EXPO("in_out_expo"),
+    EASE_IN_CIRC("in_circ"),
+    EASE_OUT_CIRC("out_circ"),
+    EASE_IN_OUT_CIRC("in_out_circ"),
+    EASE_IN_BACK("in_back"),
+    EASE_OUT_BACK("out_back"),
+    EASE_IN_OUT_BACK("in_out_back"),
+    EASE_IN_ELASTIC("in_elastic"),
+    EASE_OUT_ELASTIC("out_elastic"),
+    EASE_IN_OUT_ELASTIC("in_out_elastic"),
+    EASE_IN_BOUNCE("in_bounce"),
+    EASE_OUT_BOUNCE("out_bounce"),
+    EASE_IN_OUT_BOUNCE("in_out_bounce");
+
+    private final String id;
+
+    CameraEaseType(String id) {
+        this.id = id;
+    }
+
+    public String id() {
+        return this.id;
+    }
+}

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraFade.java

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2019-2023 GeyserMC. http://geysermc.org
+ *
+ * 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.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.bedrock.camera;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.common.value.qual.IntRange;
+import org.geysermc.geyser.api.GeyserApi;
+
+import java.awt.Color;
+
+/**
+ * Represents a coloured fade overlay on the camera.
+ * <p>
+ * Can be sent with {@link CameraData#sendCameraFade(CameraFade)}, or with a {@link CameraPosition} instruction.
+ */
+public interface CameraFade {
+
+    /**
+     * Gets the color overlay of the camera.
+     * Bedrock uses an RGB color system.
+     *
+     * @return the color of the fade
+     */
+    @NonNull Color color();
+
+    /**
+     * Gets the seconds it takes to fade in.
+     * All fade times combined must take at least 0.5 seconds, and at most 30 seconds.
+     *
+     * @return the seconds it takes to fade in
+     */
+    float fadeInSeconds();
+
+    /**
+     * Gets the seconds the overlay is held.
+     * All fade times combined must take at least 0.5 seconds, and at most 30 seconds.
+     *
+     * @return the seconds the overlay is held
+     */
+    float fadeHoldSeconds();
+
+    /**
+     * Gets the seconds it takes to fade out.
+     * All fade times combined must take at least 0.5 seconds, and at most 30 seconds.
+     *
+     * @return the seconds it takes to fade out
+     */
+    float fadeOutSeconds();
+
+    /**
+     * Creates a Builder for CameraFade
+     *
+     * @return a CameraFade Builder
+     */
+    static CameraFade.Builder builder() {
+        return GeyserApi.api().provider(CameraFade.Builder.class);
+    }
+
+    interface Builder {
+
+        Builder color(@NonNull Color color);
+
+        Builder fadeInSeconds(@IntRange(from = 0, to = 10) float fadeInSeconds);
+
+        Builder fadeHoldSeconds(@IntRange(from = 0, to = 10) float fadeHoldSeconds);
+
+        Builder fadeOutSeconds(@IntRange(from = 0, to = 10) float fadeOutSeconds);
+
+        CameraFade build();
+    }
+}

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraPerspective.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2019-2023 GeyserMC. http://geysermc.org
+ *
+ * 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.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.bedrock.camera;
+
+/**
+ * Represents a camera perspective that a player's camera can take.
+ * All perspectives except for {@link #FREE} are locked to the player's head,
+ * and are therefore relative to the player's position and rotation.
+ */
+public enum CameraPerspective {
+    FIRST_PERSON("minecraft:first_person"),
+    FREE("minecraft:free"),
+    THIRD_PERSON("minecraft:third_person"),
+    THIRD_PERSON_FRONT("minecraft:third_person_front");
+
+    private final String id;
+
+    CameraPerspective(String id) {
+        this.id = id;
+    }
+
+    public String id() {
+        return this.id;
+    }
+}

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraPosition.java

@@ -0,0 +1,150 @@
+/*
+ * Copyright (c) 2019-2023 GeyserMC. http://geysermc.org
+ *
+ * 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.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.bedrock.camera;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.checkerframework.common.value.qual.IntRange;
+import org.cloudburstmc.math.vector.Vector3f;
+import org.geysermc.geyser.api.GeyserApi;
+
+/**
+ * This interface represents a camera position instruction. Can be built with the {@link #builder()}.
+ * <p>
+ * Any camera position instruction pins the client camera to a specific position and rotation.
+ * You can set {@link CameraEaseType} to ensure a smooth transition that will last {@link #easeSeconds()} seconds.
+ * A {@link CameraFade} can also be sent, which will transition the player to a coloured transition during the transition.
+ * <p>
+ * Use {@link CameraData#sendCameraPosition(CameraPosition)} to send such an instruction to any connection.
+ */
+public interface CameraPosition {
+
+    /**
+     * Gets the camera's position.
+     *
+     * @return camera position vector
+     */
+    @NonNull Vector3f position();
+
+    /**
+     * Gets the {@link CameraEaseType} of the camera.
+     * If not set, there is no easing.
+     *
+     * @return camera ease type
+     */
+    @Nullable CameraEaseType easeType();
+
+    /**
+     * Gets the {@link CameraFade} to be sent along the camera position instruction.
+     * If set, they will run at once.
+     *
+     * @return camera fade, or null if not present
+     */
+    @Nullable CameraFade cameraFade();
+
+    /**
+     * Gets the easing duration of the camera, in seconds.
+     * Is only used if a {@link CameraEaseType} is set.
+     *
+     * @return camera easing duration in seconds
+     */
+    float easeSeconds();
+
+    /**
+     * Gets the x-axis rotation of the camera.
+     * To prevent the camera from being upside down, Bedrock limits the range to -90 to 90.
+     * Will be overridden if {@link #facingPosition()} is set.
+     *
+     * @return camera x-axis rotation
+     */
+    @IntRange(from = -90, to = 90) int rotationX();
+
+    /**
+     * Gets the y-axis rotation of the camera.
+     * Will be overridden if {@link #facingPosition()} is set.
+     *
+     * @return camera y-axis rotation
+     */
+    int rotationY();
+
+    /**
+     * Gets the position that the camera is facing.
+     * Can be used instead of manually setting rotation values.
+     * <p>
+     * If set, the rotation values set via {@link #rotationX()} and {@link #rotationY()} will be ignored.
+     *
+     * @return Camera's facing position
+     */
+    @Nullable Vector3f facingPosition();
+
+    /**
+     * Controls whether player effects, such as night vision or blindness, should be rendered on the camera.
+     * Defaults to false.
+     *
+     * @return whether player effects should be rendered
+     */
+    boolean renderPlayerEffects();
+
+    /**
+     * Controls whether the player position should be used for directional audio.
+     * If false, the camera position will be used instead.
+     *
+     * @return whether the players position should be used for directional audio
+     */
+    boolean playerPositionForAudio();
+
+    /**
+     * Creates a Builder for CameraPosition
+     *
+     * @return a CameraPosition Builder
+     */
+    static CameraPosition.Builder builder() {
+        return GeyserApi.api().provider(CameraPosition.Builder.class);
+    }
+
+    interface Builder {
+
+        Builder cameraFade(@Nullable CameraFade cameraFade);
+
+        Builder renderPlayerEffects(boolean renderPlayerEffects);
+
+        Builder playerPositionForAudio(boolean playerPositionForAudio);
+
+        Builder easeType(@Nullable CameraEaseType easeType);
+
+        Builder easeSeconds(float easeSeconds);
+
+        Builder position(@NonNull Vector3f position);
+
+        Builder rotationX(@IntRange(from = -90, to = 90) int rotationX);
+
+        Builder rotationY(int rotationY);
+
+        Builder facingPosition(@Nullable Vector3f facingPosition);
+
+        CameraPosition build();
+    }
+}

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraShake.java

@@ -25,6 +25,9 @@
 
 package org.geysermc.geyser.api.bedrock.camera;
 
+/**
+ * Represents a camera shake instruction. Can be sent in {@link CameraData#shakeCamera(float, float, CameraShake)}
+ */
 public enum CameraShake {
     POSITIONAL,
     ROTATIONAL

api/src/main/java/org/geysermc/geyser/api/connection/GeyserConnection.java

@@ -29,8 +29,10 @@ import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.geysermc.api.connection.Connection;
+import org.geysermc.geyser.api.bedrock.camera.CameraData;
 import org.geysermc.geyser.api.bedrock.camera.CameraShake;
 import org.geysermc.geyser.api.command.CommandSource;
+import org.geysermc.geyser.api.entity.EntityData;
 import org.geysermc.geyser.api.entity.type.GeyserEntity;
 import org.geysermc.geyser.api.entity.type.player.GeyserPlayerEntity;
 
@@ -41,10 +43,29 @@ import java.util.concurrent.CompletableFuture;
  * Represents a player connection used in Geyser.
  */
 public interface GeyserConnection extends Connection, CommandSource {
+
+    /**
+     * Exposes the {@link CameraData} for this connection.
+     * It allows you to send fogs, camera shakes, force camera perspectives, and more.
+     *
+     * @return the CameraData for this connection.
+     */
+    @NonNull CameraData camera();
+
+    /**
+     * Exposes the {@link EntityData} for this connection.
+     * It allows you to get entities by their Java entity ID, show emotes, and get the player entity.
+     *
+     * @return the EntityData for this connection.
+     */
+    @NonNull EntityData entities();
+
     /**
      * @param javaId the Java entity ID to look up.
      * @return a {@link GeyserEntity} if present in this connection's entity tracker.
+     * @deprecated Use {@link EntityData#entityByJavaId(int)} instead
      */
+    @Deprecated
     @NonNull
     CompletableFuture<@Nullable GeyserEntity> entityByJavaId(@NonNegative int javaId);
 
@@ -53,11 +74,14 @@ public interface GeyserConnection extends Connection, CommandSource {
      *
      * @param emoter the player entity emoting.
      * @param emoteId the emote ID to send to this client.
+     * @deprecated use {@link EntityData#showEmote(GeyserPlayerEntity, String)} instead
      */
+    @Deprecated
     void showEmote(@NonNull GeyserPlayerEntity emoter, @NonNull String emoteId);
 
     /**
-     * Shakes the client's camera.<br><br>
+     * Shakes the client's camera.
+     * <p>
      * If the camera is already shaking with the same {@link CameraShake} type, then the additional intensity
      * will be layered on top of the existing intensity, with their own distinct durations.<br>
      * If the existing shake type is different and the new intensity/duration are not positive, the existing shake only
@@ -66,12 +90,18 @@ public interface GeyserConnection extends Connection, CommandSource {
      * @param intensity the intensity of the shake. The client has a maximum total intensity of 4.
      * @param duration the time in seconds that the shake will occur for
      * @param type the type of shake
+     *
+     * @deprecated Use {@link CameraData#shakeCamera(float, float, CameraShake)} instead.
      */
+    @Deprecated
     void shakeCamera(float intensity, float duration, @NonNull CameraShake type);
 
     /**
      * Stops all camera shake of any type.
+     *
+     * @deprecated Use {@link CameraData#stopCameraShake()} instead.
      */
+    @Deprecated
     void stopCameraShake();
 
     /**
@@ -80,19 +110,26 @@ public interface GeyserConnection extends Connection, CommandSource {
      * Fog IDs can be found <a href="https://wiki.bedrock.dev/documentation/fog-ids.html">here</a>
      *
      * @param fogNameSpaces the fog IDs to add. If empty, the existing cached IDs will still be sent.
+     * @deprecated Use {@link CameraData#sendFog(String...)} instead.
      */
+    @Deprecated
     void sendFog(String... fogNameSpaces);
 
     /**
      * Removes the given fog IDs from the fog cache, then sends all fog IDs in the cache to the client.
      *
      * @param fogNameSpaces the fog IDs to remove. If empty, all fog IDs will be removed.
+     * @deprecated Use {@link CameraData#removeFog(String...)} instead.
      */
+    @Deprecated
     void removeFog(String... fogNameSpaces);
 
     /**
      * Returns an immutable copy of all fog affects currently applied to this client.
+     *
+     * @deprecated Use {@link CameraData#fogEffects()} instead.
      */
+    @Deprecated
     @NonNull
     Set<String> fogEffects();
 }

api/src/main/java/org/geysermc/geyser/api/entity/EntityData.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2019-2023 GeyserMC. http://geysermc.org
+ *
+ * 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.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.entity;
+
+import org.checkerframework.checker.index.qual.NonNegative;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.geyser.api.connection.GeyserConnection;
+import org.geysermc.geyser.api.entity.type.GeyserEntity;
+import org.geysermc.geyser.api.entity.type.player.GeyserPlayerEntity;
+
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * This class holds all the methods that relate to entities.
+ * Can be accessed through {@link GeyserConnection#entities()}.
+ */
+public interface EntityData {
+
+    /**
+     * Returns a {@link GeyserEntity} to e.g. make them play an emote.
+     *
+     * @param javaId the Java entity ID to look up
+     * @return a {@link GeyserEntity} if present in this connection's entity tracker
+     */
+    @NonNull CompletableFuture<@Nullable GeyserEntity> entityByJavaId(@NonNegative int javaId);
+
+    /**
+     * Displays a player entity as emoting to this client.
+     *
+     * @param emoter the player entity emoting
+     * @param emoteId the emote ID to send to this client
+     */
+    void showEmote(@NonNull GeyserPlayerEntity emoter, @NonNull String emoteId);
+
+    /**
+     * Gets the {@link GeyserPlayerEntity} of this connection.
+     *
+     * @return the {@link GeyserPlayerEntity} of this connection
+     */
+    @NonNull GeyserPlayerEntity playerEntity();
+
+    /**
+     * (Un)locks the client's movement inputs, so that they cannot move.
+     * To ensure that movement is only unlocked when all locks are released, you must supply
+     * a UUID with this method, and use the same UUID to unlock the camera.
+     *
+     * @param lock whether to lock the movement
+     * @param owner the owner of the lock
+     * @return if the movement is locked after this method call
+     */
+    boolean lockMovement(boolean lock, @NonNull UUID owner);
+
+    /**
+     * Returns whether the client's movement is currently locked.
+     *
+     * @return whether the movement is locked
+     */
+    boolean isMovementLocked();
+}

api/src/main/java/org/geysermc/geyser/api/entity/type/player/GeyserPlayerEntity.java

@@ -25,7 +25,15 @@
 
 package org.geysermc.geyser.api.entity.type.player;
 
+import org.cloudburstmc.math.vector.Vector3f;
 import org.geysermc.geyser.api.entity.type.GeyserEntity;
 
 public interface GeyserPlayerEntity extends GeyserEntity {
+
+    /**
+     * Gets the position of the player.
+     *
+     * @return the position of the player.
+     */
+    Vector3f position();
 }