{"id":"creacowo/synctween","name":"synctween","scope":"creacowo","platform":"roblox","description":"A rich TweenService replication module.","version":"1.0.8","latest":"1.0.8","versions":["1.0.0","1.0.1","1.0.2","1.0.3","1.0.4","1.0.5","1.0.6","1.0.7","1.0.8"],"license":"GPL-3.0","licenseRating":"unsafe","licenseCaveats":["Strong copyleft: shipping this in your game plausibly requires releasing your game's entire source under GPL-3.0. Not recommended for closed-source projects."],"licenseVerified":false,"dependencies":{},"integrity":"e46f3d03b43236423c6af989b5bd185009455b924758e62d8b020095d86e0895","likes":0,"downloads":0,"install":"forest install creacowo/synctween","url":"https://forest.dev/p/roblox/creacowo/synctween","files":"https://api.forest.dev/ai/package/roblox/creacowo/synctween/files","readme":"# SyncTween\n\n### Created by @creaco - November 8th, 2024  \n*Licensed under the GNU GPLv3 License*\n\n**SyncTween** is a tweening library designed to help server-to-client animations, with several features that other modules do not offer.\n\n---\n\n## Links\n- More information on TweenService found [here](https://create.roblox.com/docs/reference/engine/classes/TweenService).\n- If you are unfamiliar with how replication works, please look at [this](https://devforum.roblox.com/t/client-replication-101-the-guide-to-replicating-effects-to-clients) DevForum post.\n- This project was inspired by [TweenService2](https://github.com/Steadyon/TweenServiceV2), although not built onto it.\n\n---\n\n## Advantages\n1. **Lower Server Load**  \n   By handling animations on the client side, SyncTween reduces the processing burden on the server.\n\n2. **Smoother animations**  \n    Compared to the server, the client runs at a faster clock, meaning the animations will not be \"choppy\".\n    \n## Key Features\n1. **Syncing Animations**  \n   SyncTween allows animations to be synchronized across all clients. Here's the definition of \"synchronization\":\n   - Synchronization ensures that all clients see the animations in the same state at the same time.\n   - By default, all tweens will end at the same time, this means it compensates for server lag.\n\n2. **Custom Animations**  \n   You can define custom animations on the client side. Check out the `Custom` module for examples.\n   You can also use other Tweening modules combined with this module using a custom animation.\n\n3. **Support for Streaming Enabled & Streaming Out**  \n   SyncTween works with **Streaming Enabled** and **Streaming Out** via `CollectionService`.\n\n4. **Selective Replication**  \n   Make animations visible to selected clients without replicating them to the server. For example, hide a door for User X but keep it visible for others.\n\n5. **Selective Framerate**\n   Make certain animations run at a lower framerate to decrease the client load.\n\n## Current Limitations\n1. Custom animations cannot be paused.\n\n---\n\n## How to Use SyncTween\n\nTo construct a SyncTween, use the following syntax:\n\n```lua\nSyncTween.new(\n    object: Instance,                                       -- The object you want to animate.\n    tweenInfo: (TweenInfo | TweenArray | string)?,          -- TweenInfo of the animation.\n    properties: { [string]: any }?,                         -- Properties you want to animate.\n    update: boolean?,                                       -- Should the animation be updated to the server?\n    sync: (boolean | number)?,                              -- Synchronize all clients / set framerate.\n    additional: { [string]: any }?,                         -- Additional data for custom animations.\n    uuid: string?                                           -- UUID of the animation (optional).\n)\n```\n\n### Parameter Notes:\n- `tweenInfo`: Accepts a `TweenInfo`, a `TweenArray`, or a `string`.\n  - If a string is provided, it will be treated as a custom animation.\n  - A `TweenArray` looks like:  \n    ```lua\n    { Time = 1, EasingStyle = Enum.EasingStyle.Linear, EasingDirection = Enum.EasingDirection.InOut }\n    ```\n  - It’s recommended to use `TweenInfo` to avoid confusion, the change was necessary for replication purposes.\n\n### Examples:\n1. Animate a part's position:\n    ```lua\n    SyncTween.new(workspace.Part, TweenInfo.new(1), { Position = Vector3.new(0, 10, 0) }):Play()\n    ```\n    This will animate the part to the position `(0, 10, 0)` over 1 second.\n\n2. Animate a color for a specific player:\n    ```lua\n    SyncTween.new(workspace.Part, nil, { Color = Color3.new(1, 0, 0) }, false):Play({Player1})\n    ```\n    This will turn the part red only for Player1.\n\n3. Play a custom \"Rainbow\" animation at 10 FPS:\n    ```lua\n    SyncTween.new(workspace.Part.Highlight, \"Rainbow\", true, 10):Play()\n    ```\n\n---\n\n## Global Methods\n- `SyncTween.get(object: Instance, player: Player): { Sync }`  \n  Retrieve all animations currently playing on the specified object.\n  On the client, this will return everything that is playing, on the server, it will return only Syncs that the player can view.\n\n---\n\n## SyncTween Class Methods\n- `Play(players: { Player }?)`  \n  Start the animation.  \n  Ability to set the scope on who receives the animation.\n\n- `Pause(delta: number?)`  \n  Pause the animation.  \n  (Does not apply to custom animations)\n\n- `Cancel()`  \n  Cancel the animation.\n\n---\n\n## Summary\nYou can create a SyncTween (or \"Sync\") using `SyncTween.new()`. This class inherits the usual tween methods (`:Play()`, `:Pause()`, `:Cancel()`) while offering additional configuration options, such as:\n- `tweenInfo`\n- `update`\n- `sync`\n- `uuid`\n\nThis module is great for having animations replicate to various clients without the downside of server lag.\nThis module also supports settings like framerate, which gives more freedom on how expensive animations should be.\n\nThe module is written in `--!strict` mode, and the `Sync` type is exported for use.\n","readmeTruncated":false}