Shoulder Surfing Reloaded Mod Wiki

Shoulder Surfing Reloaded (SSR) is a comprehensive overhaul of the Minecraft third-person camera system. It replaces the standard 'behind-the-back' view with a customizable over-the-shoulder perspective, similar to modern action-adventure games. The mod is entirely client-side, meaning it does not need to be installed on servers to function, though it provides a deep API for other mods to integrate with its camera mechanics.

Key features include a decoupled camera that allows players to walk in one direction while looking in another, adaptive player transparency to prevent the character model from obstructing the view, and a corrective crosshair system that ensures projectiles and interactions land exactly where the player is aiming, regardless of the camera offset.

The mod introduces several advanced camera behaviors that differ significantly from vanilla Minecraft:

• Over-the-Shoulder View: The camera is shifted to the side of the player, providing a clearer view of the environment and interactions.
• Decoupled Camera: Players can move left, right, or backward without the camera automatically snapping to the player's facing direction. This allows for more cinematic movement and better spatial awareness.
• Free Look: By holding the designated hotkey (default Left Alt), players can rotate the camera freely around the character without changing the direction the character is moving or facing.
• Adaptive Transparency: When the camera is forced close to the player model (e.g., standing against a wall), the player model will automatically fade to transparent. This prevents the 'inside-the-head' clipping common in vanilla third-person views.
• Camera Collision: The camera intelligently reacts to the environment, zooming in when obstructed by blocks to maintain a clear line of sight to the player.

Shoulder Surfing Reloaded provides several default keybindings to adjust the camera position on the fly without opening a menu.

One of the most significant technical hurdles in third-person mods is aiming accuracy. SSR solves this with a sophisticated crosshair system:

Crosshair Types

• Static: The crosshair remains in the center of the screen. This may result in 'parallax error' where the crosshair does not align with the actual block or entity being targeted.
• Dynamic: The crosshair automatically moves on the screen to stay aligned with the exact point the player's character is aiming at, based on raytracing. This ensures that where you point is where you hit.
• Adaptive: The crosshair only appears or switches to dynamic mode when the player is holding specific items (like bows or swords) or performing specific actions (like aiming).

Obstruction Indicator

When using the static crosshair, an additional indicator can be enabled in the config to show when an object is blocking the line of sight between the camera and the target point.

The mod is highly customizable via the shouldersurfing-client.toml file or the in-game config menu. Settings are divided into several logical categories:

Camera Settings

• offset_x / offset_y / offset_z: Defines the default position of the camera relative to the player.
• camera_step_size: Determines how much the camera moves per keypress when using the arrow keys.
• keep_camera_horizontal: If enabled, the camera will not tilt vertically when looking up or down.
• replace_default_perspective: Whether the mod should override the vanilla third-person back view entirely.

Player Settings

• adjust_player_transparency: Enables the fading effect when the camera is close to the player.
• player_transparency_threshold: The distance at which the player begins to fade.
• decoupled_camera: Enables or disables the ability for the player to move independently of the camera direction.

Crosshair Settings

• crosshair_type: Choose between STATIC, DYNAMIC, or ADAPTIVE.
• custom_raytrace_distance: Sets the maximum distance the dynamic crosshair will look for targets (default is 400 blocks).
• adaptive_crosshair_hold_items: A list of item IDs (supports regex) that trigger the crosshair when held (e.g., minecraft:.*sword).
• adaptive_crosshair_use_items: A list of items that trigger the crosshair only when being used (e.g., charging a bow).

Shoulder Surfing Reloaded features a robust Plugin API for developers. This allows other mods to modify camera behavior without invasive code changes.

API Features

• IShoulderSurfingPlugin: The primary interface for creating a plugin. Developers can register custom camera behaviors or overrides.
• Custom Callbacks: Mods can hook into camera rendering events to adjust the FOV, offset, or rotation dynamically (e.g., for a 'lock-on' mechanic or cinematic scripted sequences).
• Compatibility: The mod includes built-in support for several popular mods, including:
  • Better Combat: Synchronizes attack animations and camera facing.
  • Curios API: Allows items in curios slots to trigger adaptive crosshair states.
  • Iron's Spells 'n Spellbooks: Adjusts camera behavior during spellcasting.

Developers can access the API by including the ShoulderSurfing-API jar in their development environment.

Compatibility and Performance

• Client-Side Only: This mod does not need to be installed on a server. It functions entirely on the player's computer.
• Shaders: Some shaders may conflict with the 'Adaptive Player Transparency' feature. If the player model appears black or flickers when transparent, it is recommended to disable adjust_player_transparency in the config.
• Anti-Cheat Warning: Because this mod modifies how the player's rotation and movement are handled (specifically in decoupled mode), some highly sensitive server-side anti-cheat plugins may flag the movement as suspicious. Use caution on competitive servers.

Items, Mobs, and Blocks

Shoulder Surfing Reloaded is a functional utility mod and does not add any new items, blocks, mobs, or biomes to the game. Its purpose is strictly to enhance the visual and mechanical experience of the third-person camera.