|
1 | 1 | # Tween From Current Position |
2 | 2 |
|
3 | | -> **Temporary local SDK link.** This scene currently points its `@dcl/sdk` |
4 | | -> (and `@dcl/ecs`, `@dcl/js-runtime`, `@dcl/react-ecs`, `@dcl/sdk-commands`) |
5 | | -> devDependencies at a local `js-sdk-toolchain` build |
6 | | -> (`fix/tween-state-invalidation`) that fixes a `tweenSystem.tweenCompleted()` |
7 | | -> false-positive on retarget. **Swap these back to published/CI packages |
| 3 | +> **Temporary SDK link.** This scene points its `@dcl/sdk` and `@dcl/js-runtime` |
| 4 | +> devDependencies at a branch CI build of `js-sdk-toolchain` |
| 5 | +> (`fix/tween-state-invalidation`). **Swap these back to published packages |
8 | 6 | > before opening the PR.** |
9 | 7 |
|
10 | | -Proves that `Tween.setMove` can move an entity from its **current, live |
11 | | -position** to a new target -- including retargeting the destination while |
12 | | -the entity is still mid-travel -- as long as the tween's `start` argument is |
13 | | -built from `Transform.get(entity).position` rather than a hardcoded vector. |
| 8 | +A cube that chases the player, driven entirely by tweens aimed from the cube's |
| 9 | +**current position**. A pad switches between the two ways of carrying that |
| 10 | +motion, so the difference is visible side by side in one scene: |
14 | 11 |
|
15 | | -## Why this works |
| 12 | +- **`setMoveContinuous` (default, green)** -- smooth. |
| 13 | +- **`Move` tween re-created on every re-aim (red-orange)** -- visibly jittery. |
16 | 14 |
|
17 | | -- Unity Explorer PUTs the tweened entity's `Transform` back to the scene over |
18 | | - CRDT **every frame** a tween is active, so `Transform.get(entity).position` |
19 | | - is the live, mid-flight position of the entity (at most one frame stale). |
20 | | -- `Tween.setMove(entity, start, end, duration, easing)` uses |
21 | | - `createOrReplace` under the hood, which **always** resends the component |
22 | | - (even if the bytes are identical), and the explorer kills and rebuilds the |
23 | | - tweener the same frame it receives the update. So calling |
24 | | - `Tween.setMove(entity, Transform.get(entity).position, newTarget, ...)` |
25 | | - while a previous tween on that entity is still running retargets it |
26 | | - smoothly from wherever it currently is -- no snap, no teleport. |
27 | | -- Omitting `start` does **not** mean "use the current position" -- a missing |
28 | | - proto `Vector3` deserializes to `(0, 0, 0)` on the renderer side, which |
29 | | - teleports the entity to the world origin. `start` must always be supplied |
30 | | - explicitly. |
| 15 | +Both modes use the **same** re-aim trigger (the player moving `MOVE_THRESHOLD` |
| 16 | += 0.1m), the same `CUBE_SPEED`, and the same stop rule. Only the kind of tween |
| 17 | +differs, so whatever you see is attributable to the tween mode and not to how |
| 18 | +often the scene re-aims. |
31 | 19 |
|
32 | 20 | ## What's in the scene |
33 | 21 |
|
34 | | -1. **Centerpiece (back of the parcel).** A blue traveler cube plus 5 colored |
35 | | - pads (RED, ORANGE, YELLOW, GREEN, BLUE). Clicking any pad sends the |
36 | | - traveler there using its current live position as the tween start. |
37 | | - Duration is a generous 2.5s specifically so you have time to click a |
38 | | - *different* pad while the cube is mid-flight and watch it smoothly change |
39 | | - direction instead of snapping back anywhere. |
40 | | -2. **"Come to me" pad (magenta, near spawn).** Tweens the same traveler cube |
41 | | - from wherever it currently is to your current position (clamped to stay |
42 | | - inside the parcel). |
43 | | -3. **Arrival feedback.** A system checks `tweenSystem.tweenCompleted(traveler)` |
44 | | - every frame. On arrival the cube flashes gold and an "Arrived!" label |
45 | | - appears above it; both reset the moment a new journey starts. |
| 22 | +1. **The follow cube.** Starts at `(3, 0.5, 6)` and chases you, stopping |
| 23 | + `STOP_DISTANCE` = 1m short. Its colour shows the active mode: green for |
| 24 | + `setMoveContinuous`, red-orange for `Move`. |
| 25 | +2. **Mode pad (magenta, at `(13, 0.1, 3)` near spawn).** Click to switch modes. |
| 26 | + Switching drops the in-flight tween so the new mode starts clean. The label |
| 27 | + above it always names the active mode. `maxDistance: 20` (double the SDK |
| 28 | + default) keeps it clickable from most of the parcel. |
46 | 29 |
|
47 | | - This is also the in-world regression check for the `tweenSystem` |
48 | | - completion fix: retargeting a running tween used to make |
49 | | - `tweenCompleted()` false-positive (report "done" while the cube was still |
50 | | - mid-flight), which is why an earlier version of this scene compared the |
51 | | - live position against the target instead. With the fix, |
52 | | - `tweenCompleted()` is the correct, intended API to use here. |
| 30 | +## How to exercise it |
53 | 31 |
|
54 | | -All pads use `maxDistance: 20` -- double the SDK's default 10m click range -- |
55 | | -so every pad stays clickable from anywhere in the parcel. |
| 32 | +1. Walk around. In the default green mode the cube glides after you smoothly. |
| 33 | +2. Click the magenta pad to switch to `Move` mode -- the cube turns red-orange. |
| 34 | +3. Walk around again. The cube now visibly stutters: it lurches forward, snaps |
| 35 | + back a little, lurches again. |
| 36 | +4. Stand still in either mode. The cube settles 1m away and stops. |
56 | 37 |
|
57 | | -## How to exercise it |
| 38 | +## Why `Move` jitters and `setMoveContinuous` does not |
| 39 | + |
| 40 | +`Transform.get(cube).position` is the position the **renderer** last wrote back |
| 41 | +to the scene over CRDT, so it trails the cube's true on-screen position by the |
| 42 | +round trip (roughly 1-3 frames). `Move` mode declares that stale value as its |
| 43 | +`start`; on receiving the new tween the renderer kills the running tweener and |
| 44 | +applies that `start` immediately, so the cube snaps **backwards** to where it |
| 45 | +was a few frames ago before resuming. |
| 46 | + |
| 47 | +A single correction is imperceptible -- that is why a click-driven tween, fired |
| 48 | +seconds apart, looks perfect. But at `MOVE_THRESHOLD` = 0.1m a walking player |
| 49 | +(~3-4 m/s, so ~0.05-0.07m per frame) crosses the threshold about every **two |
| 50 | +frames**, so the cube takes roughly 30 backward corrections per second. That |
| 51 | +reads as jitter. |
| 52 | + |
| 53 | +Raising the threshold or lowering the speed only makes the stutter coarser: the |
| 54 | +frequency of replacement is the problem, not the tuning. **A `Tween` in `Move` |
| 55 | +mode describes a discrete A-to-B motion; it is not a per-frame follow |
| 56 | +primitive.** |
| 57 | + |
| 58 | +`setMoveContinuous` avoids this because it hands the renderer a *direction and |
| 59 | +a speed* rather than a start point. Continuous modes take their start from the |
| 60 | +renderer's own live transform, so replacing one mid-motion cannot snap the cube |
| 61 | +back -- there is no scene-supplied `start` to disagree with the renderer. |
| 62 | + |
| 63 | +The trade-off: a continuous tween has no destination, so it never stops on its |
| 64 | +own. The per-frame `STOP_DISTANCE` check is what ends the chase, and because |
| 65 | +that removal has to round-trip to the renderer the cube can drift slightly |
| 66 | +closer than 1m before halting. |
58 | 67 |
|
59 | | -1. Click any of the 5 colored pads -- the traveler cube glides there over |
60 | | - 2.5 seconds and flashes gold with an "Arrived!" label when it lands. |
61 | | -2. While it's still moving, click a **different** colored pad. The cube |
62 | | - should smoothly curve toward the new target from its current position -- |
63 | | - it must never jump or snap. |
64 | | -3. Click the magenta "come to me" pad at any time (including mid-travel) to |
65 | | - redirect the traveler to your own position. |
| 68 | +(The third option, moving the `Transform` directly in a system, sidesteps the |
| 69 | +round trip entirely and is the usual answer for continuous motion. It is |
| 70 | +deliberately not demonstrated here -- this scene is about what the `Tween` |
| 71 | +component can do.) |
0 commit comments