Utility 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 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 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);

clearAnimations(bot: (string | Bot | (string | Bot)[]), tag?: (string | string[])): void

Cancels the animations that are running on the given bot(s). If a tag is specified then only animations for the given tag will be canceled.

The first parameter is a (string | Bot | (string | Bot)[]) and is the bot, bot ID, or list of bots that should cancel their animations.

The second parameter is optional and is a (string | string[]) and is the tag or list of tags that the animations should be canceled for.