Skip to content

API Documentation v5 Migration

Jump to bottom
Exopandora edited this page Jun 11, 2026 · 4 revisions

Migration from version 4

Version 5 of Shoulder Surfing Reloaded introduces major changes to the API. The most significant change is the switch from callbacks to an event system. The following sections show you how to migrate an existing plugin for Shoulder Surfing Reloaded 4 to Shoulder Surfing Reloaded 5.

Package changes

The following api classes were moved to a different package:

Previous package name New package name
com.github.exopandora.shouldersurfing.api.client.ICameraEntityRenderer com.github.exopandora.shouldersurfing.api.client.renderer.ICameraEntityRenderer
com.github.exopandora.shouldersurfing.api.client.IClientConfig com.github.exopandora.shouldersurfing.api.client.config.IClientConfig
com.github.exopandora.shouldersurfing.api.client.ICrosshairRenderer com.github.exopandora.shouldersurfing.api.client.renderer.ICrosshairRenderer
com.github.exopandora.shouldersurfing.api.client.IObjectPicker com.github.exopandora.shouldersurfing.api.client.world.phys.IObjectPicker
com.github.exopandora.shouldersurfing.api.client.ShoulderSurfing com.github.exopandora.shouldersurfing.api.ShoulderSurfing
com.github.exopandora.shouldersurfing.api.model.CameraDistanceAttributeMode com.github.exopandora.shouldersurfing.api.client.CameraDistanceAttributeMode
com.github.exopandora.shouldersurfing.api.model.Couple com.github.exopandora.shouldersurfing.api.util.Couple
com.github.exopandora.shouldersurfing.api.model.CrosshairType com.github.exopandora.shouldersurfing.api.client.CrosshairType
com.github.exopandora.shouldersurfing.api.model.CrosshairVisibility com.github.exopandora.shouldersurfing.api.client.CrosshairVisibility
com.github.exopandora.shouldersurfing.api.model.DynamicPickContext com.github.exopandora.shouldersurfing.api.client.world.phys.DynamicPickContext
com.github.exopandora.shouldersurfing.api.model.ObstructionPickContext com.github.exopandora.shouldersurfing.api.client.world.phys.ObstructionPickContext
com.github.exopandora.shouldersurfing.api.model.OffsetPickContext com.github.exopandora.shouldersurfing.api.client.world.phys.OffsetPickContext
com.github.exopandora.shouldersurfing.api.model.Perspective com.github.exopandora.shouldersurfing.api.client.Perspective
com.github.exopandora.shouldersurfing.api.model.PickContext com.github.exopandora.shouldersurfing.api.client.world.phys.PickContext
com.github.exopandora.shouldersurfing.api.model.PickOrigin com.github.exopandora.shouldersurfing.api.client.world.phys.PickOrigin
com.github.exopandora.shouldersurfing.api.model.PickVector com.github.exopandora.shouldersurfing.api.client.world.phys.PickVector
com.github.exopandora.shouldersurfing.api.model.TurningMode com.github.exopandora.shouldersurfing.api.client.TurningMode
com.github.exopandora.shouldersurfing.api.model.ViewBobbingMode com.github.exopandora.shouldersurfing.api.client.ViewBobbingMode

Plugin registration

The format of shouldersurfing_plugin.json has changed. Instead of an entrypoint field, it now contains a entrypoints field, which of JSON array type. This allows the specification of multiple entrypoints for a single mod file.

{
-    "entrypoint": "com.example.ExamplePlugin"
+    "entrypoints": [
+        "com.example.ExamplePlugin"
+    ]
}

API Changes

Migrating callbacks to events

Shoulder Surfing Reloaded 5 replaces the callback system with a new event system. Events need be registered to the event bus in the register method of a Shoulder Surfing plugin (see Plugins). Instead of an IShoulderSurfingRegistrar instance, the register method now receives a single IEventBus instance:

public class ExamplePlugin implements IShoulderSurfingPlugin {
    @Override
-    public void register(IShoulderSurfingRegistrar registrar) {
+    public void register(IEventBus eventBus) {
    }
}

Registration is outlined in the Events section of the documentation. The following table provides a mapping of legacy callback methods to events:

Callback class Callback method Event
IAdaptiveItemCallback isHoldingAdaptiveItem ComputePlayerAimStateEvent
ICameraCouplingCallback isForcingCameraCoupling ComputeCameraCouplingEvent
ICameraEntityTransparencyCallback getCameraEntityAlpha ComputeCameraEntityTransparencyEvent
ICameraRotationSetupCallback pre SetupCameraRotationEvent
ICameraRotationSetupCallback post SetupCameraRotationEvent
IPlayerInputCallback isForcingVanillaMovementInput ForceVanillaPlayerInputEvent
IPlayerStateCallback isAttacking ComputePlayerAttackStateEvent
IPlayerStateCallback isInteracting ComputePlayerInteractionStateEvent
IPlayerStateCallback isPicking ComputePlayerPickStateEvent
IPlayerStateCallback isUsingItem ComputePlayerUseItemStateEvent
IPlayerStateCallback isRidingBoat ComputePlayerRideBoatStateEvent
ITargetCameraOffsetCallback pre ComputeTargetCameraOffsetEvent
ITargetCameraOffsetCallback post ComputeTargetCameraOffsetEvent
ITickableCallback tick TickEvent

Config changes

The IClientConfig interface was split into multiple interfaces, providing getter methods for their instances instead. Additionally, the following config getters were renamed:

Previous name New name
doCenterPlayerSounds isPlayerSoundCentered
isUnlimitedOffsetX isOffsetXUnlimited
isUnlimitedOffsetY isOffsetYUnlimited
isUnlimitedOffsetZ isOffsetZUnlimited
doDynamicallyAdjustOffsets isOffsetDynamic
showObstructionIndicatorWhenAiming isObstructionIndicatorShownWhenAiming
useCustomRaytraceDistance isCustomRaytraceDistanceEnabled
replaceDefaultPerspective isThirdPersonReplaced
doRememberLastPerspective isPerspectivePersistent
turnPlayerTransparentWhenAiming isPlayerTransparentWhenAiming
shouldPlayerXRotFollowCamera isPlayerXRotFollowingCamera
shouldPlayerYRotFollowCamera isPlayerYRotFollowingCamera
shouldPlayerZRotFollowCamera isPlayerZRotFollowingCamera

Wiki

API Documentation

Clone this wiki locally