Skip to main content

Sprite

const sprite = new Sprite(
    path: string,
    layer: Layer = Layer.Background,
    origin: Origin = Origin.Center,
    initialPosition: OsbVector2 = new OsbVector2(320, 480)
)

Create a new sprite. A sprite is a special component, therefore you can register it to storyboard directly, or add it to another components. However, you can not add another components to it.

  • path: path to the image file relative to the beatmap folder. For example, if you have a subfolder named sb inside your beatmap folder and your image file named background.jpg is in it then you must pass sb/background.jpg without the dot at the start.
  • layer: Layer
  • origin: Origin
  • initialPosition: the initial position of the image.

Instance methods​

Fade​

sprite.Fade(startTime: number | string, endTime: number | string, startOpacity: number, endOpacity: number, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur
  • startOpacity, endOpacity: opacity at the start/end of the animation
  • easing: Easing

FadeAtTime​

sprite.FadeAtTime(time: number | string, opacity: number)

Shorthand command for Fade when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • opacity: opacity at the given time.

Move​

sprite.Move(startTime: number | string, endTime: number | string, startPosition: OsbVector2, endPosition: OsbVector2, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • startPosition, endPosition: position at the start/end of the animation.
  • easing: Easing

MoveAtTime​

sprite.MoveAtTime(time: number | string, position: OsbVector2)

Shorthand command for Move when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • position: position at the given time.

MoveX​

sprite.MoveX(startTime: number | string, endTime: number | string, startX: number, endX: number, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • startX, endX: x position at the start/end of the animation.
  • easing: Easing

MoveXAtTime​

sprite.MoveXAtTime(time: number | string, x: number)

Shorthand command for MoveX when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • x: x position at the given time.

MoveY​

sprite.MoveY(startTime: number | string, endTime: number | string, startY: number, endY: number, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • startY, endY: y position at the start/end of the animation.
  • easing: Easing

MoveYAtTime​

sprite.MoveYAtTime(time: number | string, y: number)

Shorthand command for MoveY when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • y: y position at the given time.

Scale​

sprite.Scale(startTime: number | string, endTime: number | string, startScale: number, endScale: number, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • startScale, endScale: scale factor at the start/end of the animation.
  • easing: Easing

ScaleAtTime​

sprite.ScaleAtTime(time: number | string, scale: number)

Shorthand command for Scale when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • scale: scale factor at the given time.

ScaleVec​

sprite.Scale(startTime: number | string, endTime: number | string, startScale: OsbVector2, endScale: OsbVector2, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • startScale, endScale: scale factor at the start/end of the animation.
  • easing: Easing

ScaleVecAtTime​

sprite.ScaleAtTime(time: number | string, scale: OsbVector2)

Shorthand command for ScaleVec when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • scale: scale factor at the given time.

Rotate​

sprite.Rotate(startTime: number | string, endTime: number | string, startAngle: number, endAngle: number, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • startAngle, endAngle: angle to rotate by in radians at the start/end of the animation.
  • easing: Easing

RotateAtTime​

sprite.RotateAtTime(time: number | string, angle: number)

Shorthand command for Rotate when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • angle: angle to rotate by in radians at the given time.

Color​

sprite.Color(startTime: number | string, endTime: number | string, startColor: OsbColor, endColor: OsbColor, easing: Easing = Easing.Linear)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • startColor, endColor: color at the start/end of the animation. Sprites with (255,255,255) will be their original colour and sprites with (0,0,0) will be totally black. Anywhere in between will result in subtractive colouring.
  • easing: Easing

ColorAtTime​

sprite.ColorAtTime(time: number | string, scale: OsbColor)

Shorthand command for Color when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • color: color at the given time. Sprites with (255,255,255) will be their original colour and sprites with (0,0,0) will be totally black. Anywhere in between will result in subtractive colouring.

Parameter​

sprite.Parameter(startTime: number | string, endTime: number | string, parameter: Parameter)
  • startTime, endTime: times in milliseconds indicate when the event will occur.
  • parameter: Parameter

ParameterAtTime​

sprite.ParameterAtTime(time: number | string, parameter: Parameter)

Shorthand command for Parameter when startTime and endTime are equal.

  • time: time in milliseconds/timestamp indicates when the event will occur.
  • parameter: effect Parameter to apply.

Loop​

sprite.Loop(group: Loop)

Add a loop group to this sprite

  • group: a Loop group.

Trigger​

sprite.Trigger(group: Trigger)

Add a trigger group to this sprite

  • group: a Trigger group.

Loop group​

const loop = new Loop(startTime: number | string, count: number)

Loops can be defined to repeat a set of events constantly for a set number of iterations.

Note that events inside a loop should be timed with a zero-base. This means that you should start from 0ms for the inner event's timing and work up from there. The loop event's start time will be added to this value at game runtime.

  • startTime: time of the first loop's start.
  • count: number of times to repeat the loop.

Loop has all of Sprite's methods except Loop and Trigger.

Example:

// create a loop group
const loop = new Loop(1000, 3)
loop.Fade(0, 1000, 1, 0.5) // this means sprite will start to fade at 1000, 2000 and 3000 respectively.

// add loop group to sprite
sprite.loop(loop)

Trigger group​

const trigger = new Trigger(triggerName: TriggerName | string, startTime: number | string, endTime: number)

Trigger loops can be used to trigger animations based on play-time events. Although called loops, trigger loops only execute once when triggered.

Trigger loops are zero-based similar to normal loops. If two overlap, the first will be halted and replaced by a new loop from the beginning. If they overlap any existing storyboarded events, they will not trigger until those transformations are no in effect.

Trigger has all of Sprite's methods except for Loop and Trigger.

Example:

// create a trigger group
const trigger = new Trigger(TriggerName.HitSoundClap, 1000, 3000)
trigger.Fade(0, 1000, 1, 0.5) // this means sprite will start to fade if clap hitsound is played during the time 1000 and 3000.

// add trigger group to sprite
sprite.trigger(trigger)