Animation Actions
animateTag(bot: (string | Bot | (string | Bot)[]), options: AnimateTagOptions): Promise<void>
Animates multiple tags on the given bot based on the specified parameters.
This works similarly to
animateTag(bot, tag, options)but instead of providing a tag name, you instead provide an object for the fromValue and toValue options which contains the tags that should be animated.Returns a promise that resolves when the animation is finished and throws an error when the animation is canceled. This is useful for gradually changing a set of tags on a bot over time. For example, moving a bot from point A to point B without teleporting it.
Unlike calling
animateTag(bot, tag, options)multiple times, animations started with this function are grouped together. This means that canceling one animation in the group will also cancel the others.This function is fully integrated with tag masks. This lets you animate tag values in the tempLocal, local, player, and shared spaces.
The first parameter is a (string | Bot | (string | Bot)[]) and is the bot, bot ID, or list of bots that the tag should be animated on.
The second parameter is a AnimateTagOptions and is the options that should be used to animate the tag. If null is used, then any active animations for the tag on these bots will be canceled.
Examples
Animate the #count tag from 0 to 1 over 5 seconds.await animateTag(bot, {
fromValue: {
homeX: 0,
homeY: 0,
},
toValue: {
homeX: 1,
homeY: 1
},
duration: 5
});
os.toast("Animation finished!");Animate tags in tempShared space.await animateTag(bot, {
fromValue: {
homeX: 0,
homeY: 0,
},
toValue: {
homeX: 5,
homeY: 5
},
duration: 2,
tagMaskSpace: 'tempShared'
});animateTag(bot: (string | Bot | (string | Bot)[]), tag: string, options: AnimateTagOptions): Promise<void>
Animates the tag on the given bot based on the specified parameters. Returns a promise that resolves when the animation is finished and throws an error when the animation is canceled. This is useful for gradually changing a tag on a bot over time. For example, moving a bot from point A to point B without teleporting it.
animateTag(bot, tag, options)is fully integrated with tag masks. This lets you animate tag values in thetempLocal,local,player, andsharedspaces.The first parameter is a (string | Bot | (string | Bot)[]) and is the bot, bot ID, or list of bots that the tag should be animated on.
The second parameter is a string and is the tag that should be animated.
The third parameter is a AnimateTagOptions and is the options that should be used to animate the tag. If null is used, then any active animations for the tag on these bots will be canceled.
Examples
Animate the #count tag from 0 to 1 over 5 seconds.await animateTag(bot, "count", {
fromValue: 0,
toValue: 1,
duration: 5
});
os.toast("Animation finished!");Run 2 animations in sequence.await animateTag(bot, "homeX", {
fromValue: 0,
toValue: 5,
duration: 2
});
await animateTag(bot, "homeY", {
fromValue: 0,
toValue: 5,
duration: 2
});Run an animation while the #loop tag is true.while(tags.loop) {
await animateTag(bot, "homeX", {
fromValue: 0,
toValue: 5,
duration: 2
});
}Run an animation with a "bouncy" easing mode.await animateTag(bot, "homeX", {
fromValue: 0,
toValue: 5,
duration: 2,
easing: {
type: "elastic",
mode: "out"
}
});Run an animation with a custom easing function that causes the animation to progress in 10 distinct steps.await animateTag(bot, "homeX", {
fromValue: 0,
toValue: 5,
duration: 2,
easing: (k) => {
return Math.floor(k * 10) / 10;
}
});Run an animation that starts in 1 second.await animateTag(bot, "homeX", {
fromValue: 0,
toValue: 5,
duration: 2,
startTime: os.localTime + 1000,
});Animate a tag in tempShared space.await animateTag(bot, "homeX", {
fromValue: 0,
toValue: 5,
duration: 2,
tagMaskSpace: 'tempShared'
});Cancel animations on the #homeX tag.animateTag(bot, "homeX", {
fromValue: 0,
toValue: 5,
duration: 2
}).then(() => {
os.toast("Animation Finished!");
}).catch(() => {
os.toast("Animation Canceled!");
});
await os.sleep(500);
animateTag(bot, "homeX", null);os.startFormAnimation(botOrBots: (string | Bot | (string | Bot)[]), nameOrIndex: (string | number), options?: StartFormAnimationOptions): Promise<void>
Starts the given animation on the given bot or list of bots using the given options. Returns a promise that resolves once the animation(s) have been started.
Triggers the
@onFormAnimationStartedand@onAnyFormAnimationStartedlisteners once the animation has started.The first parameter is a (string | Bot | (string | Bot)[]) and is the bot or list of bots that the animation should be started on.
The second parameter is a (string | number) and is the name of the animation that should be started. Additionally, it can be the index number of the animation that should be played.
The third parameter is optional and is a StartFormAnimationOptions and is the options that should be used to play the animation.
Examples
Start the "Run" animation on this botawait os.startFormAnimation(thisBot, "Run");Start the "Run" animation on every bot in the home dimensionawait os.startFormAnimation(getBots(inDimension("home")), "Run");Start an animation that loops 5 timesawait os.startFormAnimation(thisBot, "Run", {
loop: {
mode: 'repeat',
count: 5
}
});Start an animation which starts playing 5 seconds in the futureawait os.startFormAnimation(thisBot, "Run", {
startTime: os.localTime + 5000
});Start an animation which plays at half its normal speedawait os.startFormAnimation(thisBot, "Run", {
timeScale: 0.5
});os.stopFormAnimation(botOrBots: (string | Bot | (string | Bot)[]), options?: StopFormAnimationOptions): Promise<void>
Stops the animations that are running on the given bot or list of bots using the given options. Returns a promise that resolves once the animations have been stopped.
This function only works for animations that have been started by
os.startFormAnimation(botOrBots, nameOrIndex, options).Triggers the
@onFormAnimationStoppedand@onAnyFormAnimationStoppedlisteners once the animation has stopped.The first parameter is a (string | Bot | (string | Bot)[]) and is the bot or list of bots whose animations should be stopped.
The second parameter is optional and is a StopFormAnimationOptions and is the options that should be used for stopping the animations.
Examples
Stop the animations on this botawait os.stopFormAnimation(thisBot);Slowly stop the animations on this botawait os.stopFormAnimation(thisBot, {
fadeDuration: 1000 // Take 1 second to stop the animation
});Stop the current animation 5 seconds in the futureawait os.stopFormAnimation(thisBot, {
stopTime: os.localTime + 5000
});os.listFormAnimations(botOrAddress: (string | Bot)): Promise<FormAnimationData[]>
Retrieves the list of animations that are available on the given bot or GLTF mesh address. Returns a promise that resolves with the list of available animations.
The first parameter is a (string | Bot) and is the bot or address that the animation list should be retrieved from
Examples
Get the list of animations on this botconst animations = await os.listFormAnimations(thisBot);Get the list of animations for a specific addressconst animations = await os.listFormAnimations('https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Fox/glTF/Fox.gltf');os.bufferFormAddressGLTF(address: string): Promise<void>
Pre-caches the given GLTF mesh address so that it will load instantly when used on a bot later. Returns a promise that resolves once the address has been cached.
The first parameter is a string and is the address that should be cached.
Examples
Buffer a specific GLTFawait os.bufferFormAddressGLTF('https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Fox/glTF/Fox.gltf');
os.toast("Buffered!");
