From 779893f539524f5ee049eb73672c3aa8d886c42e Mon Sep 17 00:00:00 2001 From: Naga Chiang Date: Thu, 8 Oct 2020 17:41:15 +0800 Subject: [PATCH] Add readme --- CHANGELOG.md | 4 +- README.md | 158 +++++++++++++++++++++++++++++++++++++++++++++++++-- package.json | 40 ++++++------- 3 files changed, 176 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a69249a..0c1eb82 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,10 @@ ## [Unreleased] +## [0.1.0] - 2020.10.08 + ### Added - `Ease` utilities for interpolation - `Translation`, `Rotation` and `Scale` tween support -- Pause/resume/stop tweens \ No newline at end of file +- Pause, resume and stop tweens on the entity \ No newline at end of file diff --git a/README.md b/README.md index f51fcf8..5b0b66b 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,161 @@ # Entity Tween -Entity compatible tween library for Unity ECS/DOTS. The implementation of `Ease` utilities is inspired by [Squirrel Eiserloh's talk on GDC 2015](https://www.youtube.com/watch?v=mr5xkf6zSzk). +Entity compatible tween library for Unity ECS/DOTS. -## Dependencies +## Demonstration + +![](https://i.imgur.com/3GM0RCE.gif) + +[Link to the larger gif](https://i.imgur.com/3oZnviK.gif) + +### Configuration + +- 70000 tweening entities + - `Translation` + - `Rotation` + - `NonUniformScale` +- Burst + - Leak Detection: Off + - Safety Checks: Off + - Synchronous Compilation: On + - Jobs Debugger: Off +- GPU instancing + +### Hardware + +- Intel i7-8700 @ 3.2GHz +- NVIDIA GeForce GTX 1660 Ti + +## Features + +- Supporting components + - `Translation` + - `Rotation` + - `NonUniformScale` +- Pause, resume and stop tweens on an entity +- Multiple types of active tweens on the same entity at the same time +- Ping pong +- Loop +- Ease library (inspired by [Squirrel Eiserloh's talk on GDC 2015](https://www.youtube.com/watch?v=mr5xkf6zSzk)) + - Smooth start + - Smooth stop + - Smooth step + - Cross fade + +## Dependency + +- Unity 2020.1 + - Entities 0.14.0-preview.18 + - Burst 1.3.6 + - Mathematics 1.2.1 ## Installation -## Usage +Entity Tween is a Unity package. You can [install it from the git URL](https://docs.unity3d.com/2020.1/Documentation/Manual/upm-ui-giturl.html) in Unity package manager. + +Or, you can edit `Packages/manifest.json` manually, adding git URL as a dependency: + +```json +"dependencies": { + "com.timespawn.entitytween": "https://github.com/NagaChiang/entity-tween.git" +} +``` + +To specify particular branch or tag, you can add it after the URL: + +```json +"dependencies": { + "com.timespawn.entitytween": "https://github.com/NagaChiang/entity-tween.git#develop" +} +``` + +```json +"dependencies": { + "com.timespawn.entitytween": "https://github.com/NagaChiang/entity-tween.git#v0.1.0" +} +``` + +To update existing Entity Tween package to the latest, remove the dependency on `com.timespawn.entitytween` in `Packages/packages-lock.json` then refresh: + +```json +"dependencies": { + "com.timespawn.entitytween": { + "version": "https://github.com/NagaChiang/entity-tween.git", + "depth": 0, + "source": "git", + "dependencies": {}, + "hash": "d3341cf672c26d1f0fe6e09d3bf7978c8cf22df7" + } +} +``` + +## Examples + +The main entry point of the library is the `EntityTween` class. All functionality have overloads to support `EntityManager`, `EntityCommandBuffer` and `EntityCommandBuffer.ParallelWriter`. + +### Move the entity + +```cs +float3 start = new float3(0.0f, 0.0f, 0.0f); +float3 end = new float3(1.0f, 1.0f, 1.0f); +float duration = 5.0f; +bool isPingPong = false; +int loopCount = 1; + +EntityTween.Move(entityManager, entity, start, end, duration, new EaseDesc(EaseType.SmoothStep, 2), isPingPong, loopCount); +EntityTween.Move(commandBuffer, entity, start, end, duration, new EaseDesc(EaseType.SmoothStep, 2), isPingPong, loopCount); +EntityTween.Move(parallelWriter, entity, start, end, duration, new EaseDesc(EaseType.SmoothStep, 2), isPingPong, loopCount); +``` + +### Stop the entity + +```cs +EntityTween.Stop(entityManager, entity); +``` + +### Check if the entity is tweening + +Any entity with component `Tween` is tweening; that is, to know if the entity is tweening, check if the entity has any `Tween` component in any way. + +```cs +if (EntityManager.HasComponent(entity)) +{ + Debug.Log("It's tweening!"); +} +``` + +## Workflow + +### Command + +When starting a tween by calling `EntityTween` functions (e.g. `EntityTween.Move()`), it creates a tween command component of its kind (e.g. `TweenTranslationCommand`) containing the tweening data on the target entity. + +If starting multiple tweens with the same type consequently, the command component will be overridden by the last one, which means only the last tween will be successfully triggered. + +### Generation + +`TweenGenerateSystem` is an abstract generic system, which will take the commands of its kind, then append a `Tween` with an unique tween ID to the `DynamicBuffer` of the target entity. Also, it creates another component with the same tween ID, storing the start and end information of the tween. + +Making `Tween` an `IBufferElementData` allows multiple active tweens on the same entity at the same time, while the other part of the tween data, e.g. `TweenTranslation`, is just an `IComponentData`, which ensures that there must be only one tween of the certain type. + +For example, `TweenTranslationGenerateSystem`, which inherits `TweenGenerateSystem`, will take `TweenTranslationCommand` then create `Tween` and `TweenTranslation` on the target entity. + +### Easing + +`TweenEaseSystem` iterates all `Tween` components and update the elapsed time of the tween, then calculate the progress by `Ease.CalculatePercentage()` for later use. + +### Applying + +For every type of tweens, there is a system responsible for applying the value to the target component. + +For example, `TweenTranslationSystem` takes `Tween` and `TweenTranslation` and interpolate the value depending on the eased percentage, then apply it to `Translation`. + +### Checking State + +`TweenStateSystem` iterates all `Tween` components checking if they're about to be looped, ping-ponged or destroyed. When `Tween.LoopCount == 0` after being updated means it should be looped infinitely, while `Tween.LoopCount == 255` means it's pending destroyed by `TweenDestroySystem` later. -## Concept +### Destroying -## Known Issues +`TweenDestroySystem` is also an abstract generic system for each type of tween to implement, which destroys `Tween` marked by `TweenStateSystem` earlier and its corresponding tween data component. -### Generic Jobs Not Supported in Burst \ No newline at end of file +For example, `TweenTranslationDestroySystem` will be responsible for destroying `Tween` and `TweenTranslation`. \ No newline at end of file diff --git a/package.json b/package.json index a5d46f9..f89303f 100644 --- a/package.json +++ b/package.json @@ -1,21 +1,23 @@ { - "name": "com.timespawn.entitytween", - "version": "0.1.0", - "displayName": "Entity Tween", - "description": "Tween library for Unity ECS/DOTS.", - "unity": "2020.1", - "dependencies": { - - }, - "author": { - "name": "Naga Chiang", - "email": "nagachiangdev@gmail.com", - "url": "https://nagachiang.github.io" - }, - "keywords": [ - "ECS", - "DOTS", - "Entity", - "Tween" - ] + "name": "com.timespawn.entitytween", + "version": "0.1.0", + "displayName": "Entity Tween", + "description": "Entity compatible tween library for Unity ECS/DOTS.", + "unity": "2020.1", + "dependencies": { + "com.unity.entities": "0.14.0-preview.18", + "com.unity.burst": "1.3.6", + "com.unity.mathematics": "1.2.1" + }, + "author": { + "name": "Timespawn", + "email": "nagachiangdev@gmail.com", + "url": "https://nagachiang.github.io" + }, + "keywords": [ + "ECS", + "DOTS", + "Entity", + "Tween" + ] } \ No newline at end of file