API Documentation v5 Migration

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 qualified name	New qualified 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.client.IShoulderSurfing
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
doDynamicallyAdjustOffsets	isOffsetDynamic
doOrientCameraOnTeleport	isCameraOrientedOnTeleport
doRememberLastPerspective	isPerspectivePersistent
doRenderCrosshair	isCrosshairVisible
doRenderObstructionCrosshair	isObstructionCrosshairVisible
doRenderObstructionIndicator	isCrosshairDynamic
getFollowPlayerRotations	isCameraTurningWithPlayer
getFollowPlayerRotationsDelay	getCameraTurningWithPlayerDelay
getPlayerYRotFollowAngleLimit	getPlayerYRotTurnAngleLimit
isPlayerXRotFollowingCamera	isPlayerXRotTurningWithCamera
isPlayerYRotFollowingCamera	isPlayerYRotTurningWithCamera
isUnlimitedOffsetX	isOffsetXUnlimited
isUnlimitedOffsetY	isOffsetYUnlimited
isUnlimitedOffsetZ	isOffsetZUnlimited
replaceDefaultPerspective	isThirdPersonReplaced
shouldPlayerXRotFollowCamera	isPlayerXRotFollowingCamera
shouldPlayerYRotFollowCamera	isPlayerYRotFollowingCamera
shouldPlayerZRotFollowCamera	isPlayerZRotFollowingCamera
showObstructionIndicator	isObstructionIndicatorEnabled
showObstructionIndicatorWhenAiming	isObstructionIndicatorShownWhenAiming
turnPlayerTransparentWhenAiming	isPlayerTransparentWhenAiming
useCustomRaytraceDistance	isCustomRaytraceDistanceEnabled