new system util expressions: wrap() and remap()

[F3der1co]

Reviewed guidelines

• [X] I have read and understand the suggestion guidelines

Checked for duplicate suggestions

• [X] I checked for existing similar suggestions

Summary

wrap() and remap() are very common utility functions I use in almost any project. So having them build in would be very awesome, especially as these can be a bit tricky to implement math wise if you want to catch all edge cases.

Possible workarounds or alternatives

Create two return functions that do the math.

Proposed solution

two new system expressions: wrap(value, min, max) remap(value, inMin, inMax, outMin, outMax)

Why is this idea important?

While you can implement these Util functions yourself, the math is not trivial for a robust implementation. So given how many usecases there are I think these should be build in.

These two already exist in the engine AFAIK, so I guess you are aware how useful they are. So they would just need to have an expression added that calls them.

Additional remarks

No response

[XHXIAIEIN]

add some use cases:

Wrap

wrap a number from 0 to max.

((number + 1) + max) % max

Set index to

((index + 1) + 3) % 3

index range: 0 1 2

Usage examples

with Animation Frame

(Self.AnimationFrame + 1) % Self.AnimationFrameCount

with Array

(index + 1) % Array.Width

with String token

String = "Apple|Banana|Carrot|Mushroom"
WordCount = tokenCount(String, "|")

WordIndex = (WordIndex + 1) % WordCount
Word = tokenAt(String, WordIndex, "|")

Remap

Re-maps a number from a range to another range.

lerp(start1, stop1, unlerp(start2, stop2, value))

EXAMPLE

Mouse position converted from a value in the range of 0 to 200 into a value that ranges from the edge of the Sprite.

lerp(0, 200, unlerp(Sprite.BBoxLeft, Sprite.BBoxRight, Mouse.X))

If mouse over bboxleft, then the mapping value is 0.

lerp(0, 200, unlerp(30, 60, 30)) // 0

If mouse over bboxright, then the mapping value is 200.

lerp(0, 200, unlerp(30, 60, 60)) // 200

Notice that even if the position of the Mouse exceeds bboxright, it continues to grow at the current scale.

lerp(0, 200, unlerp(30, 60, 90)) // 400
lerp(0, 200, unlerp(30, 60, 6)) // -160

EXAMPLE 2

re map ui value to Control Animate

with Animate MappingUIAnimateController.c3p.zip

with Timeline MappingUITimelineController.c3p.zip

[XHXIAIEIN]

we can continue to support more If possible

Snap

Snap a number to gird

snap(value, step)

round(X / 16) * 16
round(Y / 16) * 16

RoundAngle

Round angle to direction

round(angle / RoundToAngle) * RoundToAngle

8 Direction Round To 45 Angle

round(angle / 45) * 45

4 Direction Round To [-90, 180] Angle

round(angle / 90) * 90

Convert [-180, 180] angle to [0, 360] angle

(angle + 360) % 360