{"id":"hysteriabee/gg-camerashake","name":"gg-camerashake","scope":"hysteriabee","platform":"roblox","description":"Camerashake for Roblox/Luau.","version":"1.1.4","latest":"1.1.4","versions":["1.1.4"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"46d52cc6dd6bcd64e2ccb95bf63887df4accd1f675167a013bf7de6220d059ba","likes":0,"downloads":0,"install":"forest install hysteriabee/gg-camerashake","url":"https://forest.dev/p/roblox/hysteriabee/gg-camerashake","files":"https://api.forest.dev/ai/package/roblox/hysteriabee/gg-camerashake/files","readme":"# GG Camera Shake\r\nA port of GasGiant's [camera shake](https://github.com/gasgiant/Camera-Shake) from Unity for Roblox/Luau. Strictly typed.\r\n\r\n__Features__:\r\n* One line of code shake with presets\r\n* Several shake algorithms suitable for a wide range of use cases\r\n* Change strength and direction of the shake depending on  \r\nposition of the shake source\r\n* Easy to write custom shakes\r\n\r\n[__Watch GasGiant's video!__](https://youtu.be/fn3hIPLbSn8)\r\n![Thumbnail](https://i.imgur.com/n0ndQ9x.png \"Video thumbnail\")\r\n\r\nMost of the info below is taken from gasgiant's repo, as well... this is literally his module ported to Luau. All of the references are their updated Luau counterparts.\r\n\r\n## Table of Contents\r\n1. [Installation](#installation)\r\n2. [Usage](#usage)\r\n    * [Setup](#setup)\r\n    * [Using Presets](#using-presets)\r\n    * [Without Presets](#without-presets)\r\n\t* [Handling Offset](#handling-offset)\r\n  \t* [List of the Functions](#functions)\r\n2. [Presets](#presets)\r\n2. [PerlinShake](#perlinshake)\r\n2. [BounceShake](#bounceshake)\r\n2. [KickShake](#kickshake)\r\n2. [Displacement](#displacement)\r\n2. [Time Envelope](#time-envelope)\r\n2. [Spatial Attenuation](#spatial-attenuation)\r\n2. [Writing Custom Shakes](#writing-custom-shakes)\r\n\r\n## Installation\r\n\r\n**Wally**\r\n```\r\nGG-CameraShake = \"hysteriabee/gg-camerashake@*\"\r\n```\r\n\r\n**Get the latest release** ([.rbxm](https://github.com/HysteriaBee/GG-CameraShake/releases/latest)).\r\n\r\nSince I am not ID-verified, I cannot make this public on the Roblox creator store.\r\n\r\n\r\n## Usage\r\n### Setup\r\n\r\nRequire the module\r\n```luau\r\nlocal Shaker = require(path.to.GGCameraShaker)\r\n```\r\n\r\n### Using Presets\r\n\r\nIt is incredibly simple to use this module with presets. All it takes is one line.\r\n\r\n```luau\r\nShaker.Shake(Shaker.Presets.Explosion3D())\r\n```\r\n\r\n### Without Presets\r\n\r\nSimply create a preset in the CameraShakePresets module! You can choose from (#presets) and just fill in whatever's necessary! Take a look at current presets if you're stuck.\r\nOtherwise, just require one of three modules: `PerlinShake, BounceShake, or KickShake` and do as seen below (Details on these shake types are here: #perlinshake, #bounceshake, #kickshake):\r\n\r\n```luau\r\nShaker.Shake(Shaker.PerlinShake.New(...fill in the parameters! or not and leave it as default...))\r\n```\r\n\r\n### Handling Offset\r\n\r\nFor guns or scripts that require the cursor or camera's position you'll need to add the camera offset from the shaker. This is because otherwise scripts using the camera's position/rotation do not see the changes made by the shaker. Here is an example implementation for correcting a raycast using mouse location.\r\n\r\n```luau\r\nlocal UserInputService = game:GetService(\"UserInputService\")\r\nlocal Shaker = require(path.to.GGCameraShaker)\r\n\r\nlocal raycastParams = RaycastParams.new()\r\nraycastParams.FilterType = Enum.RaycastFilterType.Exclude\r\nraycastParams.IgnoreWater = true\r\n\r\nlocal function RayCast()\r\n\tlocal mouse = UserInputService:GetMouseLocation()\r\n\tlocal ray = game.Workspace.CurrentCamera:ViewportPointToRay(mouse.X, mouse.Y)\r\n\r\n\t-- Main focus --\r\n\tlocal offset = Shaker.GetOffset() -- Getting offset\r\n\tlocal correctedRay = offset:VectorToWorldSpace(ray.Direction) * 1000 -- Applying that offset to correct the raycast\r\n\t\r\n\tlocal result = workspace:Raycast(ray.Origin, correctedRay, raycastParams)\r\n\r\n\tif result == nil then\r\n\t\treturn ray.Origin + correctedDir\r\n\telse\r\n\t\treturn result.Position\r\n\tend\r\nend\r\n```\r\n\r\nFor correcting CFrame.\r\n\r\n```luau\r\nlocal Shaker = require(path.to.GGCameraShaker)\r\nlocal CameraCFrame = workspace.CurrentCamera.CFrame\r\nlocal CorrectedCFrame = CameraCFrame * Shaker.GetOffset()\r\n```\r\n\r\n## Functions\r\n\r\n```luau\r\n-- Shakes the camera with the passed through shake instance (created with the .New() constructor).\r\nfunction CameraShaker.Shake(shake: ICameraShake)\r\n```\r\n\r\n```luau\r\n-- Set the strength scale of all shakes. Preferred over enable/disable methods. This allows for more fine tuned customization.\r\nfunction CameraShaker.SetStrengthScale(scale: number)\r\n```\r\n\r\n```luau\r\n-- Enables the shaker if it was disabled. Equivalent to SetStrengthScale(1).\r\nfunction CameraShaker.Enable()\r\n```\r\n\r\n```luau\r\n-- Disables the shaker if it was enabled. Equivalent to SetStrengthScale(0).\r\nfunction CameraShaker.Disable()\r\n```\r\n\r\n```luau\r\n-- Returns the camera offset produced by the camera shaker. See #handling-offset for more details.\r\nfunction CameraShaker.GetOffset(): CFrame\r\n```\r\n\r\n\r\n## Presets\r\n\r\n__ShortShake3D__  \r\nSuitable for short and snappy shakes in 3D. Rotates camera in all three axes. Uses `BounceShake` algorithm.\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| strength: number?     | Strength of the shake.|\r\n| freq: number?     | Frequency of shaking.|\r\n| numBounces: number?     | Number of vibrations before stop.|\r\n\r\n```luau\r\nfunction CameraShakePresets.ShortShake3D(strength: number?, freq: number?, numBounces: number?): BounceShake\r\n```\r\n\r\n---\r\n\r\n__ShortShake2D__  \r\nSuitable for short and snappy shakes in 2D. Moves camera in X and Y axes and rotates it in Z axis. Uses `BounceShake` algorithm.\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| positionStrength: number?     | Strength of motion in X and Y axes.|\r\n| rotationStrength : number?    | Strength of rotation in Z axis.|\r\n| freq: number?     | Frequency of shaking.|\r\n| numBounces: number?     | Number of vibrations before stop.|\r\n\r\n```luau\r\nfunction CameraShakePresets.ShortShake2D(positionStrength: number?, rotationStrength: number?, freq: number?, numBounces: number?): BounceShake\r\n```\r\n\r\n---\r\n\r\n__Explosion3D__  \r\nSuitable for longer and stronger shakes in 3D. Rotates camera in all three axes. Uses `PerlinShake` algorithm.\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| strength: number?     | Strength of the shake.|\r\n| duration: number?     | Duration of the shake.|\r\n\r\n```luau\r\nfunction CameraShakePresets.Explosion3D(strength: number?, duration: number?, sourcePosition: Vector3?): PerlinShake\r\n```\r\n\r\n---\r\n\r\n__Explosion2D__  \r\nSuitable for longer and stronger shakes in 2D. Moves camera in X and Y axes and rotates it in Z axis. Uses `PerlinShake` algorithm.\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| positionStrength: number?     | Strength of motion in X and Y axes.|\r\n| rotationStrength: number?     | Strength of rotation in Z axis.|\r\n| duration: number?     | Duration of the shake.|\r\n\r\n```luau\r\nfunction CameraShakePresets.Explosion2D(positionStrength: number?, rotationStrength: number?, duration: number?): PerlinShake\r\n```\r\n\r\n---\r\n\r\n__GunFire3D__  \r\nSuitable for gun recoil. Rotates camera in two axes: vertical, and horizontal. Uses `KickShake` algorithm.\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| verticalStrength: number?     | Strength of rotation in X axis.|\r\n| horizontalStrength: number?     | Strength of rotation in Y axis.|\r\n| attack: number?     | Duration of the recoil attack.|\r\n| recover: number?     | Duration for camera to return to normal.|\r\n| forceEnabled: boolean?     | If enabled then it is unaffected by strengthMultiplier changes (enabled by default for fair play reasons).|\r\n\r\n```luau\r\nfunction CameraShakePresets.GunFire3D(strength: {verticalStrength: number, horizontalStrength: number}?, duration: {attack: number, recover: number}?, forceEnabled: boolean?): KickShake\r\n```\r\n\r\n---\r\n\r\n## PerlinShake\r\n`PerlinShake` combines layers of Perlin noise with different frequencies to create smooth and nuanced shake. Works better for longer shakes. For very short shakes consider using `BounceShake`.\r\n### Constructor\r\n\r\n```luau\r\nfunction PerlinShake.New(parameters: Params?, maxAmplitude: number?, sourcePosition: Vector3?, manualStrengthControl: boolean?, forceEnabled: boolean?): PerlinShake\r\n```\r\n\r\n| Parameter        |   |  Description | \r\n| :------------- |:-------------|:-------------|\r\n| parameters: Params?     | | Parameters of the shake. |\r\n| maxAmplitude: number?     | | Maximum amplitude of the shake.|\r\n| sourcePosition: Vector3?\t\t| | World position of the source of the shake. |\r\n| manualStrengthControl: boolean?\t\t| false | Play shake once automatically. |\r\n|  | true| Manually control strength over time. |\r\n| forceEnabled: boolean? | | If true, then remain unaffected by strengthMultiplier changes. |\r\n\r\nFor more details on `maxAmplitude` and `manualStrengthControl` see [Time Envelope](#time-envelope).\r\n\r\n### Params\r\n\r\n```luau\r\nfunction PerlinShake.GetDefaultParams(): Params\r\n```\r\n\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| strength: Displacement     | Strength of the shake for each axis. |\r\n| noiseModes: {{freq: number, amplitude: number}}     | Layers of Perlin noise with different frequencies. |\r\n| envelope: EnvelopeParams     | Strength of the shake over time. |\r\n| attenuation: StrengthAttenuationParams     | How strength falls with distance from the shake source. |\r\n\r\nFor more details on `envelope` see [Time Envelope](#time-envelope). For more details on `attenuation` see [Spatial Attenuation](#spatial-attenuation).\r\n\r\n## BounceShake\r\n`BounceShake` is useful for short and precise shakes. Unlike `PerlinShake`, it will provide reliable shake strength. Consider using `PerlinShake` for longer and stronger shakes.\r\n\r\n### Constructor\r\n\r\n```luau\r\nfunction BounceShake.New(parameters: Params?, initialDirection: Displacement?, sourcePosition: Vector3?, forceEnabled: boolean?): BounceShake\r\n```\r\n\r\n#### BounceShake\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| parameters: Params?     | Parameters of the shake. |\r\n| initialDirection: Displacement?     | Initial direction of the shake motion. |\r\n| sourcePosition: Vector3?     | World position of the source of the shake. |\r\n| forceEnabled: boolean?\t\t| If true, then remain unaffected by strengthMultiplier changes. |\r\n\r\n### Params\r\n\r\n```luau\r\nfunction BounceShake.GetDefaultParams(): Params\r\n```\r\n\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| positionStrength: number     | Parameters of the shake. |\r\n| rotationStrength: number     | Strength of the shake for rotational axes. |\r\n| axesMultiplier: Displacement     | Preferred direction of shaking. |\r\n| freq: number     | Frequency of shaking. |\r\n| numBounces: number     | Number of vibrations before stop. |\r\n| randomness: number     | Randomness of motion. |\r\n| attenuation: StrengthAttenuationParams     | How strength falls with distance from the shake source. |\r\n\r\n For more details on `attenuation` see [Spatial Attenuation](#spatial-attenuation).\r\n\r\n## KickShake\r\nMakes one kick in specified direction. Useful for recoil.\r\n\r\n### Constructors\r\n\r\n```luau\r\nfunction KickShake.New(parameters: Params?, overload: Overload, forceEnabled: boolean?): KickShake\r\n```\r\n\r\n### KickShake\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| parameters: Params?     | Parameters of the shake. |\r\n| forceEnabled: boolean?\t\t| If true, then remain unaffected by strengthMultiplier changes. |\r\n\r\n#### First Overload (optional)\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| direction: Displacement     | Direction of the kick. |\r\n\r\n#### Second Overload (optional)\r\nCreates an instance of KickShake in the direction from the source to the camera.\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| sourcePosition: Vector3     | World position of the source of the shake. |\r\n| attenuateStrength: boolean     | Change strength depending on distance from the camera? |\r\n\r\nLeaving the overload nil will default to direction being equal to Displacement.New(Vector3.zero, Vector3.new(1,1,0))\r\n\r\n### Params\r\n\r\n```luau\r\nfunction KickShake.GetDefaultParams(): Params\r\n```\r\n\r\n```luau\r\ntype AnimationCurve = (t: number) -> number\r\n```\r\n\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| strength: Displacement     | Strength of the shake for each axis. |\r\n| attackTime: number     | How long it takes to move forward. |\r\n| attackCurve: AnimationCurve    | Forward motion curve. |\r\n| releaseTime: number     | How long it takes to move back. |\r\n| releaseCurve: AnimationCurve     | Back motion curve. |\r\n| attenuation: StrengthAttenuationParams     | How strength falls with distance from the shake source. |\r\n\r\n For more details on `attenuation` see [Spatial Attenuation](#spatial-attenuation).\r\n\r\n ## Displacement\r\nClass `Displacement` is composed of position and eulerAngle (both Vector3).\r\n\r\n```luau\r\nfunction Displacement.New(position: Vector3, eulerAngles: Vector3): Displacement\r\n```\r\n\r\n ## Time Envelope\r\nClass `Envelope` controls amplitude of the shake over time. It can work in two modes. In automatic mode it plays the shake ones with selected `maxAmplitude`. \r\n\r\n```luau\r\nfunction Envelope.New(pars: EnvelopeParams, initialTargetAmplitude: number, controlMode: EnvelopeControlMode): Envelope\r\n```\r\n\r\n```luau\r\n--Set the target amplitude for an envelope.\r\nfunction Envelope.SetTargetAmplitude(self: Envelope, value: number)\r\n```\r\n\r\n```luau\r\n-- Set an envelope to finish.\r\nfunction Envelope.Finish(self: Envelope)\r\n```\r\n\r\n```luau\r\n-- Set an envelope to finish immediately.\r\nfunction Envelope.FinishImmediately(self: Envelope)\r\n```\r\n\r\nIn manual mode you can keep the reference to the `PerlinShake` and change amplitude whenever you like.\r\n```luau\r\nlocal Shaker = require(path.to.GGCameraShaker)\r\nlocal PerlinShake = require(path.to.GGCameraShaker.PerlinShake)\r\nlocal ICameraShake = require(path.to.ICameraShake)\r\n\r\nlocal params = PerlinShake.GetDefaultParams()\r\nparams...--your params here, or pass through nothing in PerlinShake.New() if you want the default params.\r\n\r\ntype ICameraShake = ICameraShake.ICameraShake\r\n\r\nlocal function Start()\r\n\tshake = PerlinShake.New(params);\r\n\tShaker.Shake(shake);\r\nend\r\n\r\nlocal function Vibrate(shake: ICameraShake, amplitude: number)\r\n\tshake.AmplitudeController:SetTargetAmplitude(amplitude);\r\nend\r\n```\r\n\r\n\r\n### EnvelopeParams\r\n\r\n```luau\r\nfunction Envelope.GetDefaultParams(): EnvelopeParams\r\n```\r\n\r\n[See interactive demonstration.](https://www.desmos.com/calculator/e9wxr78uu2)\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| attack: number     | How fast the amplitude increases. |\r\n| sustain: number     | How long in seconds the amplitude holds maximum value. |\r\n| decay: number     | How fast the amplitude decreases. |\r\n| degree: number     | Power in which the amplitude is raised to get intensity. |\r\n\r\n## Spatial Attenuation\r\n\r\nClass `Attenuator` provides methods for changing strength and direction of the shake depending on position of the shake source relative to the camera.\r\n\r\n\r\n### StrengthAttenuationParams\r\n\r\n```luau\r\nfunction Attenuator.GetDefaultParams(): StrengthAttenuationParams\r\n```\r\n\r\n[See interactive demonstration.](https://www.desmos.com/calculator/iivcfrotk8)\r\n| Parameter        | Description | \r\n| :------------- |:-------------|\r\n| clippingDistance: number     | Radius in which shake doesn't lose strength. |\r\n| falloffScale: number     | How fast strength falls with distance. |\r\n| falloffDegree: number     | Power of the falloff function. |\r\n| axesMultiplier: Vector3     | Contribution of each axis to distance. E. g. (1, 1, 0) for a 2D game in XY plane. |\r\n\r\n\r\n## Writing Custom Shakes\r\n`CameraShaker` works with any class that implements `ICameraShake` interface. \r\n\r\n```luau \r\nexport type ICameraShake = {\r\n\t-- Represents current position and rotation of the camera according to the shake.\r\n\tCurrentDisplacement: Displacement.Displacement,\r\n\t\r\n\t-- Shake system will dispose the shake on the first frame when this is true.\r\n\tIsFinished: boolean,\r\n\t\r\n\t-- CameraShaker calls this when the shake is added to the list of active shakes.\r\n\tInitialize: (self: any, cameraCFrame: CFrame) -> (),\r\n\t\r\n\t-- CameraShaker calls this every frame on active shakes.\r\n\tUpdate: (self: any, deltaTime: number, cameraCFrame: CFrame) -> (),\r\n\r\n\t-- Bypasses IsEnabled = false","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/hysteriabee/roblox/gg-camerashake/1.1.4/readme"}