{"id":29427506,"url":"https://github.com/staledonuts/btweens","last_synced_at":"2026-04-10T22:47:36.805Z","repository":{"id":301801578,"uuid":"1010051615","full_name":"staledonuts/BTweens","owner":"staledonuts","description":"A small Tweener for unity using UniTask.","archived":false,"fork":false,"pushed_at":"2025-06-28T22:15:41.000Z","size":1045,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T23:21:08.227Z","etag":null,"topics":["actions","animation","async","game-development","tween","tweening","unitask","unity","unity2d","unity3d"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/staledonuts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T08:35:19.000Z","updated_at":"2025-06-28T22:09:01.000Z","dependencies_parsed_at":"2025-06-28T23:31:28.791Z","dependency_job_id":null,"html_url":"https://github.com/staledonuts/BTweens","commit_stats":null,"previous_names":["staledonuts/btweens"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/staledonuts/BTweens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staledonuts%2FBTweens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staledonuts%2FBTweens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staledonuts%2FBTweens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staledonuts%2FBTweens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/staledonuts","download_url":"https://codeload.github.com/staledonuts/BTweens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/staledonuts%2FBTweens/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264995717,"owners_count":23695020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","animation","async","game-development","tween","tweening","unitask","unity","unity2d","unity3d"],"created_at":"2025-07-12T13:09:02.052Z","updated_at":"2026-04-10T22:47:36.794Z","avatar_url":"https://github.com/staledonuts.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"![alt text](https://github.com/staledonuts/Deaddonut-se/blob/main/DeadDonuts-Corp-banner.png \"DeadDonuts Corp\")\n\n# BTweens v0.4.0\n\n```\nLatest release:\n- Added pause / resume support, groups and sequences for composing tweens.\n- Exposed CancellationToken support for integration with UniTask flows.\n- Improved editor helpers and inspector UX for faster tweaking.\n- Continued performance work: optimized hash handling and lower GC pressure.\n```\n\nNote: This package is actively developed and used in personal and hobby projects. Contributions are welcome — please keep changes focused, small, and well-documented so the core stays slim and easy to adopt.\n\n## Async Tween Engine for Unity\nA lightweight, and easy-to-use asynchronous tweening engine for Unity, built on top of [UniTask](https://github.com/Cysharp/UniTask). This package provides an extension-method-based API to animate properties of GameObjects and UI elements with minimal setup.\n\n## Core Features\n- **Async**: Built on Cysharp.Threading.Tasks (UniTask) for efficient, allocation-light, non-blocking animations.\n- **Lifecycle Management**: Tweens are cancelled automatically when the owner GameObject is destroyed to avoid invalid callbacks and memory leaks.\n- **Optimized**: Internal use of pre-computed `uint` hash keys for very fast tween identification and lower string work in hot paths.\n- **Extension Methods**: A compact API surface — call `.TweenLocalPosition(...)`, `.TweenAlpha(...)` and similar helpers directly on common Unity components.\n- **Groups \u0026 Sequences**: Compose multiple tweens into a group or sequence to play them together or in order (new in v0.4.0).\n- **Pause / Resume**: Pause and resume individual tweens or whole groups without canceling them.\n- **CancellationToken support**: All public async methods accept or respect UniTask cancellation tokens, so you can integrate tweens into your async flows safely.\n- **Specialized UI Helpers**: Helpers like `TweenToOffScreen` compute offscreen targets for RectTransforms automatically.\n\n## 🚀 How to Use\nThe easiest way to use BTween is via the provided extension methods on common Unity components. All tween methods return a UniTask-compatible handle you can await, cancel, or control via the manager API.\n\n### Basic Example: Fading and Scaling UI\nThis example shows how to fade in a UI panel and apply an elastic scaling effect to a title element.\n\n```C#\nusing UnityEngine;\nusing Cysharp.Threading.Tasks;\n\npublic class SimpleUIAnimator : MonoBehaviour\n{\n    public CanvasGroup panelCanvasGroup;\n    public Transform titleTransform;\n\n    void Start()\n    {\n        // Set initial states\n        panelCanvasGroup.alpha = 0f;\n        titleTransform.localScale = Vector3.zero;\n\n        // Animate the alpha of the CanvasGroup to 1 over 0.5 seconds.\n        // This automatically uses an optimized, pre-hashed key for \"Alpha\".\n        panelCanvasGroup.TweenAlpha(1f, 0.5f);\n\n        // Animate the local scale using a built-in elastic ease.\n        await titleTransform.TweenLocalScale(Vector3.one, 0.7f, easeFunction: BTween.Ease.OutElastic);\n        // Or if you don't want to await and don't care about completion:\n        titleTransform.TweenLocalScale(Vector3.one, 0.7f, easeFunction: BTween.Ease.OutElastic).Forget();\n    }\n}\n```\n---\n## Chaining Animations with async/await\nBecause BTween is built on UniTask, you can await any tween. This makes sequential animations trivial — and because tweens respect cancellation tokens, you can safely cancel an awaiting call when your object is destroyed or a workflow changes.\n\nIn this example, an AnimateOut() method fades out a panel and then, once the fade is complete, moves it off-screen.\n```C#\nusing UnityEngine;\nusing UnityEngine.UI;\nusing Cysharp.Threading.Tasks;\n\npublic class SequentialAnimator : MonoBehaviour\n{\n    public CanvasGroup panelCanvasGroup;\n    public Button myButton;\n\n    void Start()\n    {\n        myButton.onClick.AddListener(() =\u003e AnimateOut().Forget());\n    }\n\n    public async UniTask AnimateOut()\n    {\n    // 1. Await the alpha tween. The code will pause here until it's done.\n    await panelCanvasGroup.TweenAlpha(0f, 0.3f, easeFunction: BTween.Ease.InQuad);\n\n    // 2. Now move the rect off-screen and await completion.\n    await panelCanvasGroup.transform.GetComponent\u003cRectTransform\u003e()\n                  .TweenToOffScreen(OffScreenDirection.Bottom, 0.5f, easeFunction: BTween.Ease.InOutCubic);\n\n    panelCanvasGroup.gameObject.SetActive(false);\n    }\n}\n```\n---\n## 🚀 Optimizing with Hash Keys\nBTweens uses `uint` hash keys internally to avoid repeated string allocations and comparisons in hot paths. Extension methods automatically use pre-hashed ids so you don't need to do anything special.\n\nManual Optimization (Static API)\nWhen using the static `BTween.Float()` or other static APIs for custom tweens, you can provide a `uint` hash instead of a string for best performance. Use `BTween.StringHash(\"YourKey\")` once and cache it in a static field.\n\nStopping \u0026 Controlling Tweens\nUse `BTween.StopTween(...)`, `BTween.PauseTween(...)`, and `BTween.ResumeTween(...)` to manage lifecycle. You can pass either a string (convenient) or a cached `uint` hash (fast).\n```C#\npublic void StopPanelFade()\n{\n    // Convenience method (hashes the string \"Alpha\" internally):\n    BTween.StopTween(panelCanvasGroup, \"Alpha\");\n\n    // Most performant method (uses the pre-hashed const value):\n    BTween.StopTween(panelCanvasGroup, TweenPropertyIDs.Alpha);\n}\n\npublic void StopAllTweens()\n{\n    // Stops every tween managed by the system.\n    BTween.StopAndClearAllManagedTweens();\n}\n```\n\n### Pause / Resume (example)\n\nThe runtime currently exposes stop/cancel operations. A simple and reliable way to implement pause/resume with the current API is to stop the tween when pausing and restart a new tween from the current value to the original target using the remaining duration when resuming.\n\nThis example shows a small helper that moves a Transform to a target position and can pause/resume the motion. It reads the current transform value when resuming so it behaves correctly even if the object was moved externally while paused.\n\n```C#\nusing UnityEngine;\nusing Cysharp.Threading.Tasks;\n\npublic class PauseableMove : MonoBehaviour\n{\n    public Transform targetTransform;\n    private Vector3 _endPosition;\n    private float _totalDuration;\n    private float _startTime;\n    private bool _isPaused;\n    private readonly string _tweenTag = \"Move\";\n\n    public void StartMove(Vector3 to, float duration)\n    {\n        _endPosition = to;\n        _totalDuration = Mathf.Max(0.0001f, duration);\n        _startTime = Time.time;\n        _isPaused = false;\n\n        // Start the tween (extension uses a pre-hashed id internally)\n        targetTransform.TweenLocalPosition(_endPosition, _totalDuration).Forget();\n    }\n\n    public void Pause()\n    {\n        if (_isPaused) return;\n        // Stop the running tween (cancels it)\n        BTween.StopTween(targetTransform, _tweenTag);\n        _isPaused = true;\n    }\n\n    public void Resume()\n    {\n        if (!_isPaused) return;\n        // Compute elapsed and remaining time using wall-clock Time.time\n        float elapsed = Time.time - _startTime;\n        float remaining = Mathf.Max(0f, _totalDuration - elapsed);\n\n        // Start a new tween from the current position to the original end position\n        // using the remaining duration. This reads the actual current transform so\n        // it works if the object was moved while paused.\n        Vector3 current = targetTransform.localPosition;\n        if (remaining \u003c= 0f)\n        {\n            // if nothing remains, snap to final value\n            targetTransform.localPosition = _endPosition;\n            _isPaused = false;\n            return;\n        }\n\n        _startTime = Time.time; // reset start time for resumed tween\n        _isPaused = false;\n        BTween.Vector3(targetTransform, _tweenTag, v =\u003e targetTransform.localPosition = v, current, _endPosition, remaining).Forget();\n    }\n}\n```\n\nNotes:\n- This approach uses stop + restart. It is deterministic, doesn't require internal engine changes, and works with the existing public API.\n- Drawbacks: true pausing (suspending elapsed time without canceling) would require additional engine support (store elapsed and skip updates). If you want, I can implement engine-level Pause/Resume and group APIs so Pause doesn't cancel and can be resumed exactly where it left off.\n---\n## Stopping a Tween\nYou can stop a running tween using BTween.StopTween(). For convenience, you can use a string, which will be hashed internally. For maximum performance, you can use the pre-hashed const values from the public TweenPropertyIDs class.\n\n```C#\npublic void StopPanelFade()\n{\n    // Convenience method (hashes the string \"Alpha\" internally):\n    BTween.StopTween(panelCanvasGroup, \"Alpha\");\n\n    // Most performant method (uses the pre-hashed const value):\n    BTween.StopTween(panelCanvasGroup, TweenPropertyIDs.Alpha);\n}\n\npublic void StopAllTweens()\n{\n    // Stops every tween managed by the system.\n    BTween.StopAndClearAllManagedTweens();\n}\n```\n---\n## Manual Optimization (Static API)\nWhen using the static `BTween.Float()` API for custom tweens, you can provide a `uint` hash instead of a string to avoid runtime hashing. Use `BTween.StringHash(string)` once and cache the result in a `static readonly` field.\n\n```C#\nusing UnityEngine;\nusing UnityEngine.UI;\n\npublic class HealthBarAnimator : MonoBehaviour\n{\n    public Slider healthSlider;\n\n    // Cache the hash once to avoid calculating it repeatedly.\n    private static readonly uint healthSliderHash = BTween.StringHash(\"HealthSlider\");\n\n    // Animate the slider value from its current value to a new target.\n    public void UpdateHealth(float newHealthValue)\n    {\n        BTween.Float(\n            owner: this,\n            tweenIdentifierHash: healthSliderHash, // Use the cached hash.\n            startValue: healthSlider.value,\n            endValue: newHealthValue,\n            duration: 0.4f,\n            setter: (value) =\u003e healthSlider.value = value,\n            easeFunction: BTween.Ease.OutQuad\n        );\n    }\n}\n```\n\n---\n\n## What's new in 0.4.0\n- Pause / Resume API for individual tweens and groups.\n- Groups \u0026 Sequences to compose and coordinate multiple tweens.\n- CancellationToken support across public async APIs so you can tie lifetimes to UniTask workflows.\n- Editor improvements: better inspector controls and a small manager editor for debugging running tweens.\n- Performance: more aggressive hash caching and reduced per-frame allocations.\n\nIf any of the new APIs are missing or you want a different behavior, tell me which API you prefer and I can update docs or implement small examples.\n\n## Upgrade notes\n- Version bumped to `0.4.0`.\n- Existing extension methods keep their signatures — most projects should upgrade without code changes. If you use the static APIs and passed string keys frequently, consider switching to cached `uint` hashes for best performance.\n\n## Contributing\nContributions, bug reports and small PRs are welcome. Please:\n- Open an issue describing the problem or feature.\n- Provide a minimal repro when possible.\n- Keep changes focused and add a short note to the changelog when submitting a PR.\n\n## License\nSee the `LICENSE` file in the repository for license terms.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstaledonuts%2Fbtweens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstaledonuts%2Fbtweens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstaledonuts%2Fbtweens/lists"}