SyncTween🔗 - Rich TweenService Replication Module

[bewarethepaws (creaco)]

Created by @creaco - November 8th, 2024

Licensed under the GNU GPLv3 License

SyncTween is a tweening library designed to help server-to-client animations, with several features that other modules do not offer.

---

---

If you find the module useful and want to support my work, you can make a small donation directly in the game. It is greatly appreciated!

---

Links

• More information on TweenService found here.
• If you are unfamiliar with how replication works, please look at this DevForum post.
• This project was inspired by TweenService2, although not built onto it.

---

Advantages

1. Lower Server Load
   By handling animations on the client side, SyncTween reduces the processing burden on the server.

2. Smoother animations
   Compared to the server, the client runs at a faster clock, meaning the animations will not be “choppy”.

Key Features

1. Syncing Animations
   SyncTween allows animations to be synchronized across all clients. Here’s the definition of “synchronization”:

   • Synchronization ensures that all clients see the animations in the same state at the same time.
   • By default, all tweens will end at the same time, this means it compensates for server lag.

2. Custom Animations
   You can define custom animations on the client side. Check out the Custom module for examples.
   You can also use other Tweening modules combined with this module using a custom animation.

3. Support for Streaming Enabled & Streaming Out
   SyncTween works with Streaming Enabled and Streaming Out via CollectionService.

4. Selective Replication
   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.

5. Selective Framerate
   Make certain animations run at a lower framerate to decrease the client load.

Current Limitations

1. Custom animations cannot be paused.

---

How to Use SyncTween

To construct a SyncTween, use the following syntax:

SyncTween.new(
    object: Instance,                                       -- The object you want to animate.
    tweenInfo: (TweenInfo | TweenArray | string)?,          -- TweenInfo of the animation.
    properties: { [string]: any }?,                         -- Properties you want to animate.
    replicate: boolean?,                                    -- Should the animation be replicated to the server?
    sync: (boolean | number)?,                              -- Synchronize all clients / set framerate.
    additional: { [string]: any }?,                         -- Additional data for custom animations.
    uuid: string?                                           -- UUID of the animation (optional).
)

Parameter Notes:

• tweenInfo: Accepts a TweenInfo, a TweenArray, or a string.
  • If a string is provided, it will be treated as a custom animation.
  • A TweenArray looks like:

    { Time = 1, EasingStyle = Enum.EasingStyle.Linear, EasingDirection = Enum.EasingDirection.InOut }
    

  • It’s recommended to use TweenInfo to avoid confusion, the change was necessary for replication purposes.

Examples:

1. Animate a part’s position:

   SyncTween.new(workspace.Part, TweenInfo.new(1), { Position = Vector3.new(0, 10, 0) }):Play()
   

   This will animate the part to the position (0, 10, 0) over 1 second.

2. Animate a color for a specific player:

   SyncTween.new(workspace.Part, nil, { Color = Color3.new(1, 0, 0) }, false):Play({Player1})
   

   This will turn the part red only for Player1.

3. Play a custom “Rainbow” animation at 10 FPS:

   SyncTween.new(workspace.Part.Highlight, "Rainbow", true, 10):Play()
   

---

Global Methods

• SyncTween.get(object: Instance, player: Player): { Sync }
  Retrieve all animations currently playing on the specified object.
  On the client, this will return everything that is playing, on the server, it will return only Syncs that the player can view.

---

SyncTween Class Methods

• Play(players: { Player }?)
  Start the animation.
  Ability to set the scope on who receives the animation.

• Pause(delta: number?)
  Pause the animation.
  (Does not apply to custom animations)

• Cancel()
  Cancel the animation.

---

Summary

You 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:

• tweenInfo
• replicate
• sync
• uuid

This module is great for having animations replicate to various clients without the downside of server lag.
This module also supports settings like framerate, which gives more freedom on how expensive animations should be.

The module is written in --!strict mode, and the Sync type is exported for use.

---

If you have any questions regarding the module, feel free to drop comments below this thread. I will do my best to get back as soon as possible. If there any issue with the module feel free to let me know here. Thank you!

[bewarethepaws (creaco)]

I know, from looking at other threads, that Synchronization can be a hard subject to grasp. To combat this and to hopefully clear up any confusion, I will try to explain the method further in depth.

This module offers 2 main ways to animate your Tweens:

1. Synchronized (Same state across clients)
2. Unsynchronized (State varies across clients)

They both end at the same time, however the way they get to the end is different.
To better explain, I have made a visual comparison:

Both Synchronized and Unsynchronized account for server lag. Where they differ is how they handle this delay

1. Synchronized prefers to jump in time to be sure that the current state is the same across clients, this means that it may visually jump at the start.
2. Unsynchronized prefers to speed up the animation by removing the delay, this means that it may visually appear faster.

Hope this clears up any confusion!

[Yiannis123]

Really cool resource. Is there a Wally package I can use?

[Carenderias (kero)]

For server replication, it currently waits for the tweensync to be finished and then the end result will get replicated on the server.

I’m trying to make a moving laser part where it also detects players and damages them with this, is there a way I can do that? if not, do you have an idea? note: I don’t wanna do damage detection on client though. so basically, server sided, but smooth animation on the client.

[bewarethepaws (creaco)]

Hello Yiannis123, I have updated the post with the Wally link, thank you for your suggestion.

[bewarethepaws (creaco)]

@Carenderias

I’m trying to make a moving laser part where it also detects players and damages them with this, is there a way I can do that? if not, do you have an idea? note: I don’t wanna do damage detection on client though. so basically, server sided, but smooth anim

If you plan on moving a laser and want to do server checks I advise you to simply use TweenService in this case. Unless (like you said), you make the verification on the client.

Reason being this module avoids updates on the server to avoid lag, so on the server the laser would not be moving.

Best,
Creaco.

[proudCdthekitten (temmie)]

basically im using this to tween the players walkspeed when running, just to make it seem more like a speedup instead of an immediate speed change, but for example when the player starts running then stops running before the first tween finishes, the tweens overlap and sometimes when the player isnt running, the walkspeed is still kept as the running speed, any help?

[bewarethepaws (creaco)]

(Sorry for duplicate comment, DevForum bugged out)

I have tried recreating the issue you mentionned, but I was unable to recreate the issue.
Could you please provide a file to recreate it?

Meanwhile, I have just sent a patch for an issue regarding overlapping synchronized animations, this may have been your problem, let me know if it persists.
I have also included one more example inside of the test place.

[spookwallyjungle]

I really like this mODULE, i have a suggestion, you could make a additional tween?, let’s say, i want to change the position and rotation of a object at the same time, like , i want it to move but also rotate, you can make a additional function for this, because if i do this even on a normal tween or right now, the rotation will overwrite the position and viceversa, making it buggy

[bewarethepaws (creaco)]

Great catch!

I have updated the module once again to take this into consideration. If you come across any other issues concerning this please let me know.

[bewarethepaws (creaco)]

Version 1.0.4 is out, fixed some bugs concerning Pausing and should now work as intended.

:Cancel() -- does not take any arguments anymore 
:Pause(delta: number?) -- now takes a delta argument (which is completely optional)

[WhiteBar]

Hello! Is there documentation for the custom animations module. I am not familiar with it.