sonolus.script.runtime¶
BasicRuntimeUiLayout
¶
Bases: Record
The layout of a UI element in preview or tutorial mode.
update(anchor: Vec2 | None = None, pivot: Vec2 | None = None, dimensions: Vec2 | None = None, rotation: float | None = None, alpha: float | None = None, background: bool | None = None)
¶
Update the layout.
Arguments left as None do not change the corresponding property.
HorizontalAlign
¶
Bases: IntEnum
Horizontal alignment.
LevelLifeData
¶
Bases: Protocol
The level life configuration returned by level_life.
consecutive_good_increment: float
instance-attribute
¶
The life gained at each consecutive-good step.
consecutive_good_step: float
instance-attribute
¶
The number of consecutive good judgments required for each life increment.
consecutive_great_increment: float
instance-attribute
¶
The life gained at each consecutive-great step.
consecutive_great_step: float
instance-attribute
¶
The number of consecutive great judgments required for each life increment.
consecutive_perfect_increment: float
instance-attribute
¶
The life gained at each consecutive-perfect step.
consecutive_perfect_step: float
instance-attribute
¶
The number of consecutive perfect judgments required for each life increment.
initial: int
instance-attribute
¶
The life at the start of the level.
maximum: int
instance-attribute
¶
The upper limit for life.
update(consecutive_perfect_increment: float | None = None, consecutive_perfect_step: float | None = None, consecutive_great_increment: float | None = None, consecutive_great_step: float | None = None, consecutive_good_increment: float | None = None, consecutive_good_step: float | None = None, initial: int | None = None, maximum: int | None = None)
¶
Update the level life configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
consecutive_perfect_increment
|
float | None
|
The life gained at each consecutive-perfect step. |
None
|
consecutive_perfect_step
|
float | None
|
The number of consecutive perfect judgments required for each life increment. |
None
|
consecutive_great_increment
|
float | None
|
The life gained at each consecutive-great step. |
None
|
consecutive_great_step
|
float | None
|
The number of consecutive great judgments required for each life increment. |
None
|
consecutive_good_increment
|
float | None
|
The life gained at each consecutive-good step. |
None
|
consecutive_good_step
|
float | None
|
The number of consecutive good judgments required for each life increment. |
None
|
initial
|
int | None
|
The life at the start of the level. |
None
|
maximum
|
int | None
|
The upper limit for life. |
None
|
LevelScoreData
¶
Bases: Protocol
The level score configuration returned by level_score.
consecutive_good_cap: float
instance-attribute
¶
The maximum consecutive-good count used to calculate the multiplier.
consecutive_good_multiplier: float
instance-attribute
¶
The score multiplier gained at each consecutive-good step.
consecutive_good_step: float
instance-attribute
¶
The number of consecutive good judgments required for each multiplier increase.
consecutive_great_cap: float
instance-attribute
¶
The maximum consecutive-great count used to calculate the multiplier.
consecutive_great_multiplier: float
instance-attribute
¶
The score multiplier gained at each consecutive-great step.
consecutive_great_step: float
instance-attribute
¶
The number of consecutive great judgments required for each multiplier increase.
consecutive_perfect_cap: float
instance-attribute
¶
The maximum consecutive-perfect count used to calculate the multiplier.
consecutive_perfect_multiplier: float
instance-attribute
¶
The score multiplier gained at each consecutive-perfect step.
consecutive_perfect_step: float
instance-attribute
¶
The number of consecutive perfect judgments required for each multiplier increase.
good_multiplier: float
instance-attribute
¶
The score multiplier for a good judgment.
great_multiplier: float
instance-attribute
¶
The score multiplier for a great judgment.
perfect_multiplier: float
instance-attribute
¶
The score multiplier for a perfect judgment.
update(perfect_multiplier: float | None = None, great_multiplier: float | None = None, good_multiplier: float | None = None, consecutive_perfect_multiplier: float | None = None, consecutive_perfect_step: float | None = None, consecutive_perfect_cap: float | None = None, consecutive_great_multiplier: float | None = None, consecutive_great_step: float | None = None, consecutive_great_cap: float | None = None, consecutive_good_multiplier: float | None = None, consecutive_good_step: float | None = None, consecutive_good_cap: float | None = None)
¶
Update the level score configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
perfect_multiplier
|
float | None
|
The score multiplier for a perfect judgment. |
None
|
great_multiplier
|
float | None
|
The score multiplier for a great judgment. |
None
|
good_multiplier
|
float | None
|
The score multiplier for a good judgment. |
None
|
consecutive_perfect_multiplier
|
float | None
|
The score multiplier gained at each consecutive-perfect step. |
None
|
consecutive_perfect_step
|
float | None
|
The number of consecutive perfect judgments required for each increase. |
None
|
consecutive_perfect_cap
|
float | None
|
The maximum consecutive-perfect count used to calculate the multiplier. |
None
|
consecutive_great_multiplier
|
float | None
|
The score multiplier gained at each consecutive-great step. |
None
|
consecutive_great_step
|
float | None
|
The number of consecutive great judgments required for each increase. |
None
|
consecutive_great_cap
|
float | None
|
The maximum consecutive-great count used to calculate the multiplier. |
None
|
consecutive_good_multiplier
|
float | None
|
The score multiplier gained at each consecutive-good step. |
None
|
consecutive_good_step
|
float | None
|
The number of consecutive good judgments required for each increase. |
None
|
consecutive_good_cap
|
float | None
|
The maximum consecutive-good count used to calculate the multiplier. |
None
|
PreviewRuntimeCanvas
¶
Bases: Protocol
The preview canvas configuration returned by canvas.
scroll_direction: ScrollDirection
instance-attribute
¶
The direction in which the canvas scrolls.
size: float
instance-attribute
¶
The length of the canvas along its scrolling axis.
update(scroll_direction: ScrollDirection | None = None, size: float | None = None)
¶
Update the preview canvas configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scroll_direction
|
ScrollDirection | None
|
The direction in which the canvas scrolls. |
None
|
size
|
float | None
|
The length of the canvas along its scrolling axis. |
None
|
RuntimeUi
¶
Bases: Record
Holds the layouts for different UI elements across all modes.
combo_config: UiConfig
property
¶
The configuration for the combo UI element.
Available in play and watch mode.
combo_text: UiLayout
property
¶
The layout of the combo text UI element.
Available in play and watch mode.
combo_value: UiLayout
property
¶
The layout of the combo value UI element.
Available in play and watch mode.
instruction: UiLayout
property
¶
The layout of the instruction UI element.
Available in tutorial mode.
instruction_config: UiConfig
property
¶
The configuration for the instruction UI element.
Available in tutorial mode.
judgment: UiLayout
property
¶
The layout of the judgment UI element.
Available in play and watch mode.
judgment_config: UiConfig
property
¶
The configuration for the judgment UI element.
Available in play and watch mode.
menu: UiLayout
property
¶
The layout of the menu UI element.
Available in play, watch, preview, and tutorial mode.
menu_config: UiConfig
property
¶
The configuration for the menu UI element.
Available in play, watch, preview, and tutorial mode.
navigation_config: UiConfig
property
¶
The configuration for the navigation UI element.
Available in tutorial mode.
next: UiLayout
property
¶
The layout of the next navigation UI element.
Available in tutorial mode.
previous: UiLayout
property
¶
The layout of the previous navigation UI element.
Available in tutorial mode.
primary_metric_bar: UiLayout
property
¶
The layout of the primary metric bar UI element.
Available in play and watch mode.
primary_metric_config: UiConfig
property
¶
The configuration for the primary metric UI element.
Available in play and watch mode.
primary_metric_value: UiLayout
property
¶
The layout of the primary metric value UI element.
Available in play and watch mode.
progress: UiLayout
property
¶
The layout of the progress UI element.
Available in watch and preview mode.
progress_config: UiConfig
property
¶
The configuration for the progress UI element.
Available in watch and preview mode.
progress_graph: UiLayout
property
¶
The layout of the progress graph UI element.
Available in watch mode.
secondary_metric_bar: UiLayout
property
¶
The layout of the secondary metric bar UI element.
Available in play and watch mode.
secondary_metric_config: UiConfig
property
¶
The configuration for the secondary metric UI element.
Available in play and watch mode.
secondary_metric_value: UiLayout
property
¶
The layout of the secondary metric value UI element.
Available in play and watch mode.
RuntimeUiConfig
¶
RuntimeUiLayout
¶
Bases: Record
The layout of a UI element in play or watch mode.
update(anchor: Vec2 | None = None, pivot: Vec2 | None = None, dimensions: Vec2 | None = None, rotation: float | None = None, alpha: float | None = None, horizontal_align: HorizontalAlign | None = None, background: bool | None = None)
¶
Update the layout.
Arguments left as None do not change the corresponding property.
ScrollDirection
¶
Bases: IntEnum
The scroll direction of the preview canvas.
Touch
¶
Bases: Record
Data of a touch event.
angle: float
instance-attribute
¶
The angle of the touch's movement.
delta: Vec2
instance-attribute
¶
The change in position of the touch.
ended: bool
instance-attribute
¶
Whether the touch has ended this frame.
id: int
instance-attribute
¶
The unique identifier of the touch.
position: Vec2
instance-attribute
¶
The current position of the touch.
prev_position: Vec2
property
¶
The previous position of the touch.
speed: float
instance-attribute
¶
The speed of the touch's movement.
start_position: Vec2
instance-attribute
¶
The position the touch started.
start_time: float
instance-attribute
¶
The time the touch started.
started: bool
instance-attribute
¶
Whether the touch has started this frame.
time: float
instance-attribute
¶
The time of the touch event.
May remain constant while there is no movement.
total_angle: float
property
¶
The total angle of the touch's movement.
total_delta: Vec2
property
¶
The total change in position of the touch.
velocity: Vec2
instance-attribute
¶
The velocity of the touch.
UiConfig
¶
UiLayout
¶
Bases: Record
The layout of a UI element.
is_available: bool
property
¶
Whether the layout is available in the current mode.
update(anchor: Vec2 | None = None, pivot: Vec2 | None = None, dimensions: Vec2 | None = None, rotation: float | None = None, alpha: float | None = None, horizontal_align: HorizontalAlign | None = None, background: bool | None = None)
¶
Update the layout properties if it's available in the current mode and do nothing otherwise.
In preview and tutorial mode, horizontal_align has no effect, as the underlying layout doesn't support it.
add_life_scheduled(value: int, time: float)
¶
Schedule adding life at a specific time.
Only valid in the preprocess callback in play and watch mode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
The amount of life to add. |
required |
time
|
float
|
The time to add the life at. |
required |
aspect_ratio() -> float
¶
Get the aspect ratio of the game.
Since the screen is two units tall, this is also the x coordinate of the right edge of the screen. See
screen for the coordinate system.
audio_offset() -> float
¶
Get the audio offset of the game.
Returns 0 in preview mode.
background() -> Quad
¶
Get the background quad.
Not available in preview mode.
canvas() -> PreviewRuntimeCanvas
¶
Get the PreviewRuntimeCanvas configuration.
Only available in preview mode.
delta_time() -> float
¶
Get the time elapsed since the last frame.
Returns 0 in preview mode.
input_offset() -> float
¶
Get the input offset of the game.
Returns 0 in preview mode and tutorial mode.
is_debug() -> bool
¶
Check if the game is running in debug mode.
is_multiplayer() -> bool
¶
Check if the game is running in multiplayer mode.
Returns False if not in play mode.
is_play() -> bool
¶
Check if the game is running in play mode.
is_preprocessing() -> bool
¶
Check if the game is in the preprocessing stage.
Returns True if the current callback is one of preprocess, spawn_order, spawn_time, or despawn_time.
is_preview() -> bool
¶
Check if the game is running in preview mode.
is_replay() -> bool
¶
Check if the game is running in replay mode.
Returns False if not in watch mode.
is_skip() -> bool
¶
Check if there was a time skip this frame.
Returns False in preview and tutorial modes.
is_tutorial() -> bool
¶
Check if the game is running in tutorial mode.
is_watch() -> bool
¶
Check if the game is running in watch mode.
level_life() -> LevelLifeData
¶
Get the LevelLifeData for the level.
Only available in play and watch mode.
level_score() -> LevelScoreData
¶
Get the LevelScoreData for the level.
Only available in play and watch mode.
navigation_direction() -> int
¶
Get the navigation direction of the tutorial.
Returns 0 if not in tutorial mode.
offset_adjusted_time() -> float
¶
Get the current time of the game adjusted by the input offset.
Returns 0 in preview mode and the current time without adjustment in tutorial mode.
particle_transform() -> Transform2d
¶
Get the global particle transform.
Not available in preview mode.
prev_time() -> float
¶
Get the time of the previous frame.
Returns 0 in preview mode.
runtime_ui() -> RuntimeUi
¶
Get the runtime UI configuration.
safe_area() -> Rect
¶
Get the safe area boundaries as a rectangle.
scaled_time() -> float
¶
Get the current time of the game affected by the time scale.
Returns the unscaled time in tutorial mode and 0 in preview mode.
screen() -> Rect
¶
Get the screen boundaries as a rectangle.
The screen spans from 1 at the top to -1 at the bottom, and from -aspect_ratio() on the left to
aspect_ratio() on the right. The origin is therefore at the center of the screen, and y increases upward.
set_background(value: Quad)
¶
Set the background quad.
Not available in preview mode.
set_particle_transform(value: Transform2d)
¶
Set the global particle transform.
Not available in preview mode.
set_skin_transform(value: Transform2d)
¶
Set the global skin transform.
skin_transform() -> Transform2d
¶
Get the global skin transform.
time() -> float
¶
Get the current time of the game.
Returns 0 in preview mode.
touches() -> ArrayLike[Touch]
¶
Get the current touches of the game.
Returns an empty array if not in play mode.