feat: add snap to facing camera mode & update README.md (#21)

Author: RaazKH

README.md

@@ -1,14 +1,11 @@
 # Compass Camera Control
 ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/RaazKH/CompassCameraControl?include_prereleases&logo=github)
-
 A RuneLite plugin that allows you to control the camera direction by either clicking the compass orb or using customizable keybindings.
 
 ## Compass Orb Control
-
-You can cycle through cardinal directions or snap to the closest one by clicking on the compass orb.
+You can cycle through cardinal directions, snap to the closest one, or snap to your character's facing direction by clicking on the compass orb.
 
 ### Cycle Mode (default)
-
 1. If facing North, the camera will rotate to South.
 2. If facing South, it will rotate to East.
 3. If facing East, it will rotate to West.
@@ -17,23 +14,23 @@ You can cycle through cardinal directions or snap to the closest one by clicking
 The process repeats when clicking the compass orb.
 
 ### Snap to Closest Mode
-
 When clicking the compass, the camera will snap to the closest cardinal direction.
 Useful for spinning the camera manually, then aligning to the grid.
 
+### Snap to Facing Mode
+When clicking the compass, the camera will snap to face the same direction as your character.
+Works with all 8 directions (N, NE, E, SE, S, SW, W, NW).
 
 ### Shift-Click Option
-
 You can configure how the plugin responds to clicks on the compass:
-
 - **Off**: Always active, ignoring the Shift key.
 - **On Shift**: Only works when Shift is held down.
 - **Off Shift**: Works only when Shift is not held down.
 
 ## Keybindings
-
 You can set up shortcuts for quick camera control. To prevent shortcuts from appearing in the chat, enable the "Key Remapping" plugin (included with RuneLite).
 
+- **Snap to Facing**: Snap camera to your character's facing direction when pressed
 - **Snap to Closest**: Snap camera to the closest cardinal direction when pressed
 - **Cycle Cardinal**: Cycle through your custom cycle order of directions when pressed
 - **Look North Key**: Face camera North when pressed
@@ -42,21 +39,15 @@ You can set up shortcuts for quick camera control. To prevent shortcuts from app
 - **Look West Key**: Face camera West when pressed
 
 ---
-
 ### Custom Cycle Order
-
 You can specify a custom order for cycling through directions. For example, if you prefer to cycle between North and South, you can set the cycle order to `N,S`. Only `N`, `S`, `W`, and `E` are valid characters for this field, all other characters will be ignored.
 
 This field is **not** case-sensitive. Non-unique cardinal directions will be ignored. So `N,S,E,S` would cycle through `N,S,E`, the final `S` being a duplicate and thus is ignored.
 
 ---
-
 #### Issues and Feedback
-
 If you encounter any bugs, have suggestions for improvements, or would like to give feedback, please feel free to <a href="https://github.com/RaazKH/CompassCameraControl/issues">submit an issue</a>.
 
 ---
-
 #### Contributors
-
-Thanks to [LlemonDuck](https://github.com/LlemonDuck) and [insizhen](https://github.com/insizhen) for their valuable code contributions.
+Thanks to [LlemonDuck](https://github.com/LlemonDuck) and [insizhen](https://github.com/insizhen) for their valuable code contributions.

src/main/java/com/compassCameraControl/CompassCameraControlConfig.java

@@ -15,7 +15,8 @@ public interface CompassCameraControlConfig extends Config
 		name = "Mode",
 		position = 1,
 		description = "Cycle: North -> South -> East -> West (default)<br/>" +
-			"Snap to Closest: Snaps the camera to the nearest cardinal direction"
+			"Snap to Closest: Snaps the camera to the nearest cardinal direction<br/>" +
+			"Snap to Facing: Snaps the camera to the player's facing direction"
 	)
 	default ControlMode controlMode()
 	{
@@ -58,11 +59,22 @@ default ShiftMode shiftClickMode()
 	)
 	String cardinalKeybindingSnap = "cardinalKeybindingSnap";
 
+	@ConfigItem(
+			keyName = "snapFacingKey",
+			name = "Snap Facing",
+			description = "Snaps the camera to the player's facing direction on key press",
+			position = 5,
+			section = cardinalKeybindingSnap
+	)
+	default Keybind snapFacingKey() {
+		return new Keybind(KeyEvent.VK_UNDEFINED, 0);
+	}
+
 	@ConfigItem(
 			keyName = "snapCloseKey",
 			name = "Snap to Closest",
 			description = "Snaps the camera to the nearest cardinal direction on key press",
-			position = 5,
+			position = 6,
 			section = cardinalKeybindingSnap
 	)
 	default Keybind snapCloseKey() {
@@ -73,7 +85,7 @@ default Keybind snapCloseKey() {
 			keyName = "cycleCardinalKey",
 			name = "Cycle Cardinal",
 			description = "Cycles through cardinal directions on key press",
-			position = 6,
+			position = 7,
 			section = cardinalKeybindingSnap
 	)
 	default Keybind cycleCardinalKey() {
@@ -84,7 +96,7 @@ default Keybind cycleCardinalKey() {
 		keyName = "lookNorthKey",
 		name = "Look North Key",
 		description = "Face camera North on key press",
-		position = 7,
+		position = 8,
 		section = cardinalKeybindingSnap
 	)
 	default Keybind lookNorthKey() {
@@ -95,7 +107,7 @@ default Keybind lookNorthKey() {
 		keyName = "lookSouthKey",
 		name = "Look South Key",
 		description = "Face camera South on key press",
-		position = 8,
+		position = 9,
 		section = cardinalKeybindingSnap
 	)
 	default Keybind lookSouthKey() {
@@ -106,7 +118,7 @@ default Keybind lookSouthKey() {
 		keyName = "lookEastKey",
 		name = "Look East Key",
 		description = "Face camera East on key press",
-		position = 9,
+		position = 10,
 		section = cardinalKeybindingSnap
 	)
 	default Keybind lookEastKey() {
@@ -117,7 +129,7 @@ default Keybind lookEastKey() {
 		keyName = "lookWestKey",
 		name = "Look West Key",
 		description = "Face camera West on key press",
-		position = 10,
+		position = 11,
 		section = cardinalKeybindingSnap
 	)
 	default Keybind lookWestKey() {

src/main/java/com/compassCameraControl/CompassCameraControlPlugin.java

@@ -38,9 +38,13 @@ public class CompassCameraControlPlugin extends Plugin
 
 
 	private static final int NORTH_YAW = 0;
+	private static final int NORTHWEST_YAW = 256;
+	private static final int WEST_YAW = 512;
+	private static final int SOUTHWEST_YAW = 768;
 	private static final int SOUTH_YAW = 1024;
+	private static final int SOUTHEAST_YAW= 1280;
 	private static final int EAST_YAW = 1536;
-	private static final int WEST_YAW = 512;
+	private static final int NORTHEAST_YAW = 1792;
 
 	private static final Map<Character, Integer> directionMap = Map.of(
 		'N', NORTH_YAW,
@@ -49,6 +53,7 @@ public class CompassCameraControlPlugin extends Plugin
 		'W', WEST_YAW
 	);
 
+	private static final String SNAP_FACING = "Snap Facing";
 	private static final String SNAP_CARDINAL = "Snap Cardinal";
 	private static final String CYCLE_CARDINAL = "Cycle Cardinal";
 
@@ -66,6 +71,10 @@ public void onMenuEntryAdded(MenuEntryAdded event)
 			String newOption;
 			switch (config.controlMode())
 			{
+				case SNAP_TO_FACING:
+					newOption = SNAP_FACING;
+					break;
+
 				case SNAP_TO_CLOSEST:
 					newOption = SNAP_CARDINAL;
 					break;
@@ -88,6 +97,11 @@ public void onCompassAction(MenuEntry event)
 	{
 		switch (event.getOption())
 		{
+			case SNAP_FACING:
+				facingYaw();
+				client.playSoundEffect(SoundEffectID.UI_BOOP);
+				break;
+
 			case SNAP_CARDINAL:
 				alignYaw();
 				client.playSoundEffect(SoundEffectID.UI_BOOP);
@@ -188,6 +202,21 @@ private void alignYaw()
 		client.setCameraYawTarget(closestYaw);
 	}
 
+	private void facingYaw()
+	{
+		if (client.getLocalPlayer() == null)
+		{
+			return;
+		}
+
+		int playerOrientation = client.getLocalPlayer().getOrientation();
+		int direction = playerOrientation / 256;
+
+		int[] yaws = {SOUTH_YAW, SOUTHWEST_YAW, WEST_YAW, NORTHWEST_YAW, NORTH_YAW, NORTHEAST_YAW, EAST_YAW, SOUTHEAST_YAW};
+
+		client.setCameraYawTarget(yaws[direction]);
+	}
+
 	private final KeyListener keyListener = new KeyListener() {
 		@Override
 		public void keyTyped(KeyEvent event) { }
@@ -198,8 +227,9 @@ public void keyReleased(KeyEvent event) { }
 		@Override
 		public void keyPressed(KeyEvent event) {
 			boolean handledEvent = true;
-
-			if (config.snapCloseKey().matches(event)) {
+			if (config.snapFacingKey().matches(event)) {
+				facingYaw();
+			} else if (config.snapCloseKey().matches(event)) {
 				alignYaw();
 			} else if (config.cycleCardinalKey().matches(event)) {
 				cycleYaw();

src/main/java/com/compassCameraControl/ControlMode.java

@@ -8,6 +8,7 @@ public enum ControlMode
 
 	CYCLE("Cycle"),
 	SNAP_TO_CLOSEST("Snap to Closest"),
+	SNAP_TO_FACING("Snap to Facing"),
 	;
 
 	private final String name;