ShiftUnlocked

https://github.com/yiannis123git/shiftunlocked
Admin
ShiftUnlocked is a customizable third-person camera module for Roblox Studio that provides smooth...
Tokens:8,410
Snippets:102
Trust Score:3.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Wally dependency for ShiftUnlocked

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/index.md

Add this dependency to your Wally manifest to install the latest version of ShiftUnlocked.

```toml
shiftunlocked = "yiannis123git/shiftunlocked@*"
```

--------------------------------

### new

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Creates a new camera instance.

```APIDOC
## new

### Description
Creates a new camera instance.

### Method
new

### Signature
`Camera.new(): SUCamera`

### Parameters
None

### Returns
- **SUCamera** - The newly created camera instance.
```

--------------------------------

### Shake camera via ShakeWithInstance with preset and sustained instances

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Shake the camera with a prebuilt CameraShakeInstance or a preset. Pass false for Sustain to trigger a one-time shake cleanly, or true for a sustained shake. Fade-out instances to stop: StartFadeOut(0) instantly stops, StartFadeOut(2) fades over 2 seconds.

```lua
local NewCameraShakeInstance = ShiftUnlockedModule.CameraShakeInstance.new(5, 5, 0.2, 1.5)
local PresetCameraShakeInstance = ShiftUnlockedModule.CameraShakePresets.Explosion

-- One time explosion

ShiftUnlockedCamera:ShakeWithInstance(PresetCameraShakeInstance, false)

-- Sustained custom shake 

ShiftUnlockedCamera:ShakeWithInstance(NewCameraShakeInstance, true)

-- Stop Sustained/One time shakes

NewCameraShakeInstance:StartFadeOut(0) -- Instant Stop 

PresetCameraShakeInstance:StartFadeOut(2) -- Gradual stop 
```

--------------------------------

### Configure RaycastChannel with SmartRaycast and CollectionService

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/Setup.md

Creates a custom raycast channel using SmartRaycast, filtering objects based on transparency and collision, and assigns it to the camera's RaycastChannel property.

```lua
local SmartRaycast = require(PathToOurModule.smartraycast)

local function CanBeAdded(Inst)
	if Inst.Transparency == 1 or Inst.CanCollide == false then
		return true
	end
	return false
end


local CameraChannel = SmartRaycast.CreateChannel(
    "CameraChannel",
    {"OurCollectionServiceTag"},
    CanBeAdded,
    Enum.RaycastFilterType.Exclude, 
    -- ...
)

ShiftUnlockedCamera.RaycastChannel = OurChannel
```

--------------------------------

### ShakeWithInstance

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Shake the camera by providing a CameraShakeInstance. The Sustain parameter determines if the camera shake should be sustained or not.

```APIDOC
## ShakeWithInstance

### Description
Shake the camera by providing a `CameraShakeInstance`. You can create a `CameraShakeInstance` through its `.new()` constructor or by using one of the presets. The `Sustain` parameter determines if the camera shake should be sustained or not.

### Method
ShakeWithInstance

### Signature
`Camera:ShakeWithInstance(CShakeInstance: CameraShakeInstance, Sustain: boolean)`

### Parameters
- **CShakeInstance** (CameraShakeInstance) - Required - The camera shake instance to apply.
- **Sustain** (boolean) - Required - Determines if the camera shake should be sustained.

### Example
```lua
local NewCameraShakeInstance = ShiftUnlockedModule.CameraShakeInstance.new(5, 5, 0.2, 1.5)
local PresetCameraShakeInstance = ShiftUnlockedModule.CameraShakePresets.Explosion

-- One time explosion
ShiftUnlockedCamera:ShakeWithInstance(PresetCameraShakeInstance, false)

-- Sustained custom shake
ShiftUnlockedCamera:ShakeWithInstance(NewCameraShakeInstance, true)

-- Stop Sustained/One time shakes
NewCameraShakeInstance:StartFadeOut(0) -- Instant Stop
PresetCameraShakeInstance:StartFadeOut(2) -- Gradual stop
```
```

--------------------------------

### Shake

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Shake the camera by passing the properties of a CameraShakeInstance as arguments directly to the :Shake method, without the need to provide a predefined CameraShakeInstance.

```APIDOC
## Shake

### Description
Shake the camera by passing the properties of a `CameraShakeInstance` as arguments directly to the `:Shake` method, without the need to provide a predefined `CameraShakeInstance`. This is particularly useful in scenarios where a preconfigured shake is not applicable.

### Method
Shake

### Signature
`Camera:Shake(Magnitude: number, Roughness: number, Sustain: boolean?, FadeInTime: number?, FadeOutTime: number?, PositionInfluence: Vector3?, RotationInfluence: Vector3?)`

### Parameters
- **Magnitude** (number) - Required - The magnitude of the shake.
- **Roughness** (number) - Required - The roughness of the shake.
- **Sustain** (boolean) - Optional - Determines if the shake should be sustained.
- **FadeInTime** (number) - Optional - The fade-in time for the shake.
- **FadeOutTime** (number) - Optional - The fade-out time for the shake.
- **PositionInfluence** (Vector3) - Optional - The position influence of the shake.
- **RotationInfluence** (Vector3) - Optional - The rotation influence of the shake.
```

--------------------------------

### Create a new ShiftUnlocked camera object

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/Setup.md

Requires the ShiftUnlocked module and creates a new camera object using the .new() function.

```lua
-- First lets require our module by doing the folowing

local ShiftUnlockedModule = require(PathToOurModule.shiftunlocked)

-- Now we can create a camera object 

local ShiftUnlockedCamera = ShiftUnlocked.new()
```

--------------------------------

### GCWarn

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraGlobalSettings.md

A boolean setting that determines whether the module issues a warning when there is more than one camera instance in the game.

```APIDOC
## GCWarn

### Description
Whether the module should issue a warning when there is more than one camera instance in your game.

### Type
boolean

### Access
Read/Write

### Example
```lua
shiftUnlocked.GCWarn = true
```
```

--------------------------------

### Enable ShiftUnlockedCamera with SetEnabled(true)

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/UsingTheCamera.md

Call SetEnabled(true) on the ShiftUnlockedCamera object to enable it after adjusting the camera.

```lua
ShiftUnlockedCamera:SetEnabled(true)
```

--------------------------------

### Disable ShiftUnlockedCamera with SetEnabled(false)

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/UsingTheCamera.md

Pass false to SetEnabled to disable the camera.

```lua
ShiftUnlockedCamera:SetEnabled(false)
```

--------------------------------

### CameraShakePresets

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraGlobalSettings.md

A table setting that points to the CameraShakePresets module for easy use. You can change this value to point to your own presets if convenient.

```APIDOC
## CameraShakePresets

### Description
This setting points to the CameraShakePresets module for easy use. You can change this value to point to your own presets if convenient.

### Type
table

### Access
Read/Write

### Example
```lua
shiftUnlocked.CameraShakePresets = myCustomPresets
```
```

--------------------------------

### Camera.CorrectionReversion

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraProperties.md

Documentation for the CorrectionReversion property of the camera.

```APIDOC
## Camera.CorrectionReversion

### Description
Whether or not camera collision corrections will be reverted gradually or instantly.

### Property
`Camera.CorrectionReversion`

### Type
`boolean`

```

--------------------------------

### GlobalRaycastChannelName

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraGlobalSettings.md

A string setting that specifies the name of the SmartRaycast Channel to be used as a fallback if a camera's channel is not set.

```APIDOC
## GlobalRaycastChannelName

### Description
The name of the SmartRaycast [Channel](https://yiannis123git.github.io/SmartRaycast/api/Channel) to be used as a fallback if a camera's channel is not set.

### Type
string

### Access
Read/Write

### Example
```lua
shiftUnlocked.GlobalRaycastChannelName = "DefaultChannel"
```
```

--------------------------------

### Camera.ObstructionRange

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraProperties.md

Documentation for the ObstructionRange property of the camera.

```APIDOC
## Camera.ObstructionRange

### Description
If the camera moves closer to the player's character than this range, the character will start to become transparent for better camera visibility.

### Property
`Camera.ObstructionRange`

### Type
`number`

### Remarks
- Setting this property adjusts the distance at which the character becomes transparent.

```

--------------------------------

### Camera.CorrectionReversionSpeed

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraProperties.md

Documentation for the CorrectionReversionSpeed property of the camera.

```APIDOC
## Camera.CorrectionReversionSpeed

### Description
The speed at which the camera's collision correction is reverted. This value is scaled based on the current camera offset.

### Property
`Camera.CorrectionReversionSpeed`

### Type
`number`

```

--------------------------------

### Camera.TimeUntilCorrectionReversion

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraProperties.md

Documentation for the TimeUntilCorrectionReversion property of the camera.

```APIDOC
## Camera.TimeUntilCorrectionReversion

### Description
The time required for the camera correction reversal process to commence after collision corrections are no longer applied to the camera. Corrections to the camera's zoom will revert slightly more quickly than other types of corrections. This process is executed on a per-axis basis.

### Property
`Camera.TimeUntilCorrectionReversion`

### Type
`number`

```

--------------------------------

### Destroy ShiftUnlockedCamera with Destroy()

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/UsingTheCamera.md

Call Destroy() on the camera object to destroy it after finishing use.

```lua
ShiftUnlockedCamera:Destroy()
```

--------------------------------

### CameraShakeInstance

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraGlobalSettings.md

A table setting that points to the CameraShakeInstance module for easy use. This setting is not intended to be modified.

```APIDOC
## CameraShakeInstance

### Description
This setting just points to the CameraShakeInstance module for easy use.

!!! warning
    This setting is not intended to be modified.

### Type
table

### Access
Read-only (not intended to be modified)
```

--------------------------------

### ShiftUnlockedCamera:SetEnabled(true)

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/UsingTheCamera.md

Enables the camera after adjustments have been made.

```APIDOC
## ShiftUnlockedCamera:SetEnabled(true)

### Description
Enables the camera after adjustments have been made.

### Method
SetEnabled

### Parameters
- **enabled** (boolean) - Required - Pass true to enable the camera.

### Request Example
```lua
ShiftUnlockedCamera:SetEnabled(true)
```

### Response
No return value.
```

--------------------------------

### SetCharacter

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Sets a character to override the local player's character. You can use any character that contains a humanoid. The character will act as the new character that the camera uses. This feature can be used for spectating other players or NPCs. To re-enable the default behavior, use SetCharacter on the local player's character.

```APIDOC
## SetCharacter

### Description
Sets a character to override the local player's character. You can use any character that contains a humanoid. The character will act as the new character that the camera uses. This feature can be used for spectating other players or NPCs. To re-enable the default behavior, use SetCharacter on the local player's character.

### Method
SetCharacter

### Signature
`Camera:SetCharacter(Character)`

### Parameters
- **Character** (any) - Required - The character to use as the new camera target. Must contain a humanoid.
```

--------------------------------

### Disable RotateCharacter and enable AutoRotate

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraProperties.md

Sets ShiftUnlockedCamera.RotateCharacter to false and the local character's Humanoid.AutoRotate to true, allowing custom character rotation behavior while retaining camera functionality.

```lua
ShiftUnlockedCamera.RotateCharacter = false 
LocalPlayer.Character.Humanoid.AutoRotate = true
```

--------------------------------

### SetEnabled

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Enables or disables the camera based on the passed value: `true` to enable and `false` to disable the camera.

```APIDOC
## SetEnabled

### Description
Enables or disables the camera based on the passed value: `true` to enable and `false` to disable the camera.

### Method
SetEnabled

### Signature
`Camera:SetEnabled(Enabled: boolean)`

### Parameters
- **Enabled** (boolean) - Required - `true` to enable the camera, `false` to disable it.

### Notes
If `SyncZoom` is enabled, deactivation calls will yield for a short period of time.
```

--------------------------------

### CameraShakeDefaultPosInfluence

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraGlobalSettings.md

A Vector3 setting that provides the default PositionInfluence vector used as a fallback when the PositionInfluence argument of the :Shake camera method is nil.

```APIDOC
## CameraShakeDefaultPosInfluence

### Description
The `PositionInfluence` vector is used as a fallback when the `PositionInfluence` argument of the [`:Shake`](CameraMethods.md#shake) camera method is `nil`.

### Type
[Vector3](https://create.roblox.com/docs/reference/engine/datatypes/Vector3)

### Access
Read/Write

### Example
```lua
shiftUnlocked.CameraShakeDefaultPosInfluence = Vector3.new(1, 0, 0)
```
```

--------------------------------

### Destroy

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Cleans up references and connections established by the module. Once the destroy method is invoked on a camera, that camera should never be used again.

```APIDOC
## Destroy

### Description
Cleans up references and connections established by the module. Once the destroy method is invoked on a camera, that camera should never be used again.

### Method
Destroy

### Signature
`Camera:Destroy()`

### Parameters
None
```

--------------------------------

### AutoExcludeChars

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraGlobalSettings.md

A boolean setting that controls whether the module automatically excludes player characters from camera collision detection by adding them to the raycast Channel's filter list.

```APIDOC
## AutoExcludeChars

### Description
Whether or not the module should handle the exclusion of player characters from camera collision detection by adding them to the raycast [Channel](https://yiannis123git.github.io/SmartRaycast/api/Channel)'s filter list. If you are using an include filter list for your channel, this feature will be disabled.

### Type
boolean

### Access
Read/Write

### Example
```lua
shiftUnlocked.AutoExcludeChars = true
```
```

--------------------------------

### Camera.RotateCharacter

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraProperties.md

Documentation for the RotateCharacter property of the camera.

```APIDOC
## Camera.RotateCharacter

### Description
Sets whether or not the Humanoid will automatically rotate to face in the direction the camera is looking. When set to false, the character rotation will no longer be updated at all. This is done to allow you to add custom character rotation behavior while still retaining the camera functionality. If you want the character to rotate in the direction they are moving, simply set the local character's humanoid AutoRotate property to true after you disable the camera's RotateCharacter property.

### Property
`Camera.RotateCharacter`

### Type
`boolean`

### Example
```lua
ShiftUnlockedCamera.RotateCharacter = false 
LocalPlayer.Character.Humanoid.AutoRotate = true
```

```

--------------------------------

### StopShaking

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Stops all camera shakes using the FadeOutTime argument. If no FadeOutTime is provided then the camera shake's FadeInTime will be used for each camera shake.

```APIDOC
## StopShaking

### Description
Stops all camera shakes using the `FadeOutTime` argument. If no `FadeOutTime` is provided then the camera shake's `FadeInTime` will be used for each camera shake.

### Method
StopShaking

### Signature
`Camera:StopShaking(FadeOutTime: number?)`

### Parameters
- **FadeOutTime** (number) - Optional - The fade-out time for stopping the shakes. If not provided, the camera shake's `FadeInTime` will be used.
```

--------------------------------

### Adjust camera properties: MaxZoom and ZoomLocked

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/Setup.md

Sets the camera's maximum zoom value and disables zoom functionality by setting ZoomLocked to true.

```lua
-- Let's adjust the camera's maximum zoom value, as the default value is a bit too large

ShiftUnlockedCamera.MaxZoom = 100 

-- Actually, let's just disable the zoom functionality completely

ShiftUnlockedCamera.ZoomLocked = true 
```

--------------------------------

### CameraShakeDefaultRotInfluence

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraGlobalSettings.md

A Vector3 setting that provides the default RotationInfluence vector used as a fallback when the RotationInfluence argument of the :Shake camera method is nil.

```APIDOC
## CameraShakeDefaultRotInfluence

### Description
The `RotationInfluence` vector is used as a fallback when the `RotationInfluence` argument of the [`:Shake`](CameraMethods.md#shake) camera method is `nil`.

### Type
[Vector3](https://create.roblox.com/docs/reference/engine/datatypes/Vector3)

### Access
Read/Write

### Example
```lua
shiftUnlocked.CameraShakeDefaultRotInfluence = Vector3.new(0, 1, 0)
```
```

--------------------------------

### ShiftUnlockedCamera:SetEnabled(false)

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/UsingTheCamera.md

Disables the camera by passing false as the value.

```APIDOC
## ShiftUnlockedCamera:SetEnabled(false)

### Description
Disables the camera by passing false as the value.

### Method
SetEnabled

### Parameters
- **enabled** (boolean) - Required - Pass false to disable the camera.

### Request Example
```lua
ShiftUnlockedCamera:SetEnabled(false)
```

### Response
No return value.
```

--------------------------------

### SetZoom

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/CameraMethods.md

Sets the camera's zoom to the specified zoom number. The provided zoom will be constrained within the minimum and maximum zoom values.

```APIDOC
## SetZoom

### Description
Sets the camera's zoom to the specified zoom number. The provided zoom will be constrained within the minimum and maximum zoom values.

### Method
SetZoom

### Signature
`Camera:SetZoom(Zoom: number)`

### Parameters
- **Zoom** (number) - Required - The zoom value to set.
```

--------------------------------

### ShiftUnlockedCamera:Destroy()

Source: https://github.com/yiannis123git/shiftunlocked/blob/main/docs/UsingTheCamera.md

Destroys the camera object after it is no longer needed.

```APIDOC
## ShiftUnlockedCamera:Destroy()

### Description
Destroys the camera object after it is no longer needed.

### Method
Destroy

### Parameters
None.

### Request Example
```lua
ShiftUnlockedCamera:Destroy()
```

### Response
No return value.
```
Tokens:
Raw