StoryboardObject - frankhjwx/osu-storyboard-engine GitHub Wiki

Object(file_name, object_type='Sprite', layer='Foreground', origin='Centre', x=320, y=240, frame_count=0, frame_delay=0, loop_type='')

Object is a smallest item for a piece of element in storyboard.
This can create a single Object for storyboards.

file_name: The file name of the object, relative path in the song folder.
layer: The layer of the object, it's 'Foreground' as default.
origin: The origin of the object, it's 'Centre' as default.
x: The original x position of the object, it's 320 as default.
y: The original y position of the object, it's 240 as default.
frame_count: The frame count of an Animation object, only triggered when object_type = 'Animation'.
frame_delay: The frame delay of an Animation object, only triggered when object_type = 'Animation'.
loop_type: The loop type of an Animation object, only triggered when object_type = 'Animation'.

For more infomation of this part, please refer to osu!wiki/Storyboard Objects

Examples:

# create a sakura object with all default settings
sakura = Object('SB/sakura.png')

# create a white background with origin='CentreLeft' and x=-107
white = Object('SB/w.png', origin='CentreLeft', x=-107, y=240)

# create an Animation with frame_count=24, frame_delay=40, loop_type='LoopForever'
bird = Object('SB/bird.png', object_type='Animation', frame_count=24, frame_delay=40, loop_type='LoopForever')

Methods

append(something)

It can add some new commands to the Object.

something can be a single Code or a list of Codes.

Examples:

# add a Move command M,0,1000,2000,320,240
sakura.append(Move(1000,2000,320,240))

# add 2 codes code1 and code2
sakura.append([code1, code2])

Move(*args)

Generate a M command for Object, we support 5 definitions for Move, which are

Move(easing, start_t, end_t, start_x, start_y, end_x, end_y)
Move(start_t, end_t, start_x, start_y, end_x, end_y) , this one takes 0 as default easing
Move(start_t, end_t, start_x, start_y)
Move(start_t, start_x, start_y)
Move(start_x, start_y)

Check Examples for more. Official definition of Move Command is here.

Warning: Move(start_x, start_y) can only be used when the Object has at least one code defining start time.

Examples:

# generate M,1,1000,2000,100,100,200,200
obj.Move(1, 1000, 2000, 100, 100, 200, 200)

# generate M,0,1000,2000,100,100,200,200
obj.Move(1000, 2000, 100, 100, 200, 200)

# generate M,0,1000,2000,100,100
obj.Move(1000, 2000, 100, 100)

# generate M,0,1000,,100,100
obj.Move(1000, 100, 100)

Vector(*args)

Generate a V command for Object, which can scale an object in two directions. We support 5 definitions for Vector, which are

Vector(easing, start_t, end_t, start_x, start_y, end_x, end_y)
Vector(start_t, end_t, start_x, start_y, end_x, end_y) , this one takes 0 as default easing
Vector(start_t, end_t, start_x, start_y)
Vector(start_t, start_x, start_y)
Vector(start_x, start_y)

Check Examples for more. Official definition of Vector Command is here.

Warning: Vector(start_x, start_y) can only be used when the Object has at least one code defining start time.

Examples:

# generate V,1,1000,2000,0,0,1.5,2
obj.Vector(1, 1000, 2000, 0, 0, 1.5, 2)

# generate V,0,1000,2000,0,0,1.5,2
obj.Vector(1000, 2000, 0, 0, 1.5, 2)

# generate V,0,1000,2000,854,480
obj.Vector(1000, 2000, 854, 480)

# generate V,0,1000,,854,480
obj.Vector(1000, 854, 480)

MoveX(*args)

Generate a MX command for Object, we support 5 definitions for MoveX, which are

MoveX(easing, start_t, end_t, start_x, end_x)
MoveX(start_t, end_t, start_x, end_x) , this one takes 0 as default easing
MoveX(start_t, end_t, start_x)
MoveX(start_t, start_x)
MoveX(start_x)

Check Examples for more. Official definition of MoveX Command is here.

Warning: MoveX(start_x) can only be used when the Object has at least one code defining start time.

Examples:

# generate MX,2,1000,2000,100.5,200, note that our parser can recognize format automatically.
obj.MoveX(2, '00:01:000', 2000.1, 100.5, 200)

# generate MX,0,1000,2000,100,200
obj.MoveX(1000, 2000, 100, 200)

# generate MX,0,1000,2000,100
obj.MoveX(1000, 2000, 100)

# generate MX,0,62123,,100
obj.MoveX('01:02:123', 100)

MoveY(*args)

Generate a MY command for Object, we support 5 definitions for MoveY, which are

MoveY(easing, start_t, end_t, start_y, end_y)
MoveY(start_t, end_t, start_y, end_y) , this one takes 0 as default easing
MoveY(start_t, end_t, start_y)
MoveY(start_t, start_y)
MoveY(start_y)

Check Examples for more. Official definition of MoveY Command is here.

Warning: MoveY(start_y) can only be used when the Object has at least one code defining start time.

Examples:

# generate MY,1,1000,2000,100,200
obj.MoveY(1, 1000, 2000, 100, 200)

# generate MY,0,1000,2000,100,200
obj.MoveY(1000, 2000, 100, 200)

# generate MY,0,1000,2000,100
obj.MoveY(1000, 2000, 100)

# generate MY,0,1000,,100
obj.MoveY(1000, 100)

VectorX(*args)

Generate a VX command for Object, we support 5 definitions for VectorX, which are

VectorX(easing, start_t, end_t, start_x, end_x)
VectorX(start_t, end_t, start_x, end_x) , this one takes 0 as default easing
VectorX(start_t, end_t, start_x)
VectorX(start_t, start_x)
VectorX(start_x)

Check Examples for more. Sorry but there's no official definition for VX, VX does a scale for a object only in x direction.

Warning: VectorX(start_x) can only be used when the Object has at least one code defining start time.

Examples:

# generate VX,1,1000,2000,0,1.5
obj.VectorX(1, 1000, 2000, 0, 1.5)

# generate VX,0,1000,2000,0,1.5
obj.VectorX(1000, 2000, 0, 1.5)

# generate VX,0,1000,2000,400
obj.VectorX(1000, 2000, 400)

# generate VX,0,1000,,400
obj.VectorX(1000, 400)

VectorY(*args)

Generate a VY command for Object, we support 5 definitions for VectorY, which are

VectorY(easing, start_t, end_t, start_y, end_y)
VectorY(start_t, end_t, start_y, end_y) , this one takes 0 as default easing
VectorY(start_t, end_t, start_y)
VectorY(start_t, start_y)
VectorY(start_t, start_y)

Check Examples for more. Sorry but there's no official definition for VY, VY does a scale for a object only in y direction.

Warning: VectorY(start_y) can only be used when the Object has at least one code defining start time.

Examples:

# generate VY,1,1000,2000,0,1.5
obj.VectorY(1, 1000, 2000, 0, 1.5)

# generate VY,0,1000,2000,0,1.5
obj.VectorY(1000, 2000, 0, 1.5)

# generate VY,0,1000,2000,400
obj.VectorY(1000, 2000, 400)

# generate VY,0,1000,,400
obj.VectorY(1000, 400)

Rotate(*args)

Generate a R command for Object, we support 5 definitions for Rotate, which are

Rotate(easing, start_t, end_t, start_r, end_r)
Rotate(start_t, end_t, start_r, end_r) , this one takes 0 as default easing
Rotate(start_t, end_t, start_r)
Rotate(start_t, start_r)
Rotate(start_r)

Note that start_r and end_r should be radian value instead of degree value. Here 2π ≈ 6.28318 means a cycle.

Check Examples for more. Official definition of Rotate Command is here.

Warning: Roatate(start_r) can only be used when the Object has at least one code defining start time.

Examples:

# generate R,2,0,500,0,6.28318
obj.Rotate(1, 0, 500, 0, 2*math.pi)

# generate R,2,0,500,0,6.28318
obj.Rotate(0, 500, 0, 2*math.pi)

# generate R,0,1000,2000,0.3
obj.Rotate(1000, 2000, 0.3)

# generate R,0,1000,,0.3
obj.Rotate(1000, 0.3)

Scale(*args)

Generate a S command for Object, we support 5 definitions for Scale, which are

Scale(easing, start_t, end_t, start_s, end_s)
Scale(start_t, end_t, start_s, end_s) , this one takes 0 as default easing
Scale(start_t, end_t, start_s)
Scale(start_t, start_s)
Scale(start_s)

Check Examples for more. Official definition of Scale Command is here.

Warning: Scale(start_s) can only be used when the Object has at least one code defining start time.

Examples:

# generate S,1,1000,2000,0,1.5
obj.Scale(1, 1000, 2000, 0, 1.5)

# generate S,0,1000,2000,0,1.5
obj.Scale(1000, 2000, 0, 1.5)

# generate S,0,1000,2000,400
obj.Scale(1000, 2000, 400)

# generate S,0,1000,,400
obj.Scale(1000, 400)

Fade(*args)

Generate a F command for Object, we support 5 definitions for Fade, which are

Fade(easing, start_t, end_t, start_f, end_f)
Fade(start_t, end_t, start_f, end_f) , this one takes 0 as default easing
Fade(start_t, end_t, start_f)
Fade(start_t, start_f)
Fade(start_f)

Check Examples for more. Official definition of Fade Command is here.

Warning: Fade(start_f) can only be used when the Object has at least one code defining start time.

Examples:

# generate F,2,1000,2000,1,0
obj.Fade(2, 1000, 2000, 1, 0)

# generate F,0,1000,2000,0,1
obj.Fade(1000, 2000, 0, 1)

# generate F,0,1000,2000,1
obj.Fade(1000, 2000, 1)

# generate F,0,1000,,0
obj.Fade(1000, 0)

Color(*args)

Generate a C command for Object, we support several definitions for Color, but generally there're 5, which are

Color(easing, start_t, end_t, start_c, end_c)
Color(start_t, end_t, start_c, end_c) , this one takes 0 as default easing
Color(start_t, end_t, start_c)
Color(start_t, start_c)
Color(start_c)

Note that start_c and end_c should be a list for colors, for red it will be [255, 0, 0]. However, we also support directly tap r,g,b values for a Color.

Check Examples for more. Official definition of Color Command is here.

Warning: Color(start_c) can only be used when the Object has at least one code defining start time.

Examples:

# generate C,1,1000,2000,255,0,0,255,255,255
Red = [255, 0, 0]
White = [255, 255, 255]
obj.Color(1, 1000, 2000, Red, White)

# generate C,0,1000,2000,255,255,255,0,255,255
obj.Color(1000, 2000, White, 0, 255, 255)

# generate C,0,1000,2000,255,0,0
obj.Color(1000, 2000, Red)

# generate C,0,1000,,0,0,255
obj.Color(1000, [0, 0, 255])

Parameter(*args)

Generate a P command for Object, we support 4 definitions for Parameter, which are

Parameter(easing, start_t, end_t, parameter)
Parameter(start_t, end_t, parameter) , this one takes 0 as default easing
Parameter(start_t, parameter)
Parameter(parameter)

Supported parameters are 'H', 'V' and 'A', which means flip horizontally, flip vertically and use additive-color blending separately. Check Examples for more. Official definition of Parameter Command is here.

Warning: Parameter(parameter) can only be used when the Object has at least one code defining start time.

Examples:

# generate P,1,0,5000,A
obj.Parameter(1, 0, '00:05:000', 'A')

# generate P,0,0,5000,H
obj.Parameter(0, 5000, 'H')

# generate P,0,1000,,V
obj.Parameter(1000, 'V')

Loop(start_time, loop_count)

Generate a L command for Object, remember to use LoopOut Command when you finished setting elements in a Loop.

start_time: The timestamp at which the loop begins.
loop_count: The number of times the loop executes before stopping.

Remember all codes inside the loop uses relative time.

Check Examples for more. Official definition of Loop Command is here.

Examples:

# generate L,60000,30
obj.Loop('00:60:000', 30)

Trigger(trigger_type, start_time, end_time)

Generate a T command for Object, remember to use LoopOut Command when you finished setting elements in a Trigger.

trigger_type: It indicates a trigger condition, all types supported are listed here.
start_time: The timestamp at which the trigger becomes valid.
end_time: The timestamp at which the trigger stops being valid.

Remember all codes inside the trigger uses relative time.

Check Examples for more. Official definition of Trigger Command is here.

Examples:

# generate T,Passing,20000,40000
obj.Trigger('Passing', 20000, '00:40:000')

LoopOut()

It is used to jump out of a loop defined by Loop or Trigger Command.

Examples:

# The following code will generate these commands:
# F,0,25400,30300,1,0
# T,Hitsound,30000,40000
#  V,0,0,,0,0
# C,0,23345,,255,0,0

Red = [255, 0, 0]
obj.Fade('00:25:400', '00:30:300', 1, 0)
obj.Trigger('Hitsound', 30000, 40000)
obj.Vector(0, 0, 0)
obj.LoopOut()
obj.Color('00:23:345', Red)

remove(key)

This command will remove all commands defined by key ('M', 'F', e.t.c)

key: Short version of the codes, all supported keys: 'M', 'F', 'S', 'MX', 'MY', 'VX', 'VY', 'V', 'R', 'C', 'P'. Note that remove operation of Loop and Trigger are not supported here. (May add this feature in the future)

Examples:

# The following code will generate these commands:
# MX,0,1000,2000,320,330
obj.Move(1000, 2000, 320, 240, 330, 240)
obj.MoveX(1000, 2000, 320, 330)
obj.remove('M')

remove_by_index(index)

This command will remove a specific code from Object, count from index 1.

index: The target Code's index

get_status(timing) (Not finished, with a lot of bugs)

Get the object status at timing, it will return a dictionary containing 'M', 'F', 'S', 'V', 'MX', 'MY', 'VX', 'VY', 'R', 'C' commands.

Examples:

status = obj.get_status(5000)
# status = {'M': [300, 500], 'F': None, 'S': None, 'V': [854, 480], 'MX': None, 'MY': None, 'VX': None, 'VY': None, 'R': ['31.416'], 'C': None}