Skip to content

sonolus.script.bucket

Bucket

Bases: Record

A bucket for entity judgment results.

Usage 
Bucket(id: int)

id: int instance-attribute

Bucket ID.

window: JudgmentWindow property writable

The judgment window of the bucket.

Writable only during preprocess.

BucketSprite dataclass

A positioned sprite in a bucket icon, created with bucket_sprite.

Parameters:

Name Type Description Default
id int

The skin sprite ID.

 required
fallback_id int | None

The fallback skin sprite ID, if one is defined.

 required
x float

The x-coordinate of the sprite's center.

 required
y float

The y-coordinate of the sprite's center.

 required
w float

The width of the sprite.

 required
h float

The height of the sprite.

 required
rotation float

The clockwise rotation of the sprite in degrees.

 required

EmptyBuckets

A bucket set with no buckets, used as the default when a mode declares none.

Judgment

Bases: IntEnum

The judgment of a hit.

GOOD = 3 class-attribute instance-attribute

A good hit. Breaks combo.

GREAT = 2 class-attribute instance-attribute

A great hit.

MISS = 0 class-attribute instance-attribute

A miss. Breaks combo.

PERFECT = 1 class-attribute instance-attribute

A perfect hit.

JudgmentWindow

Bases: Record

The window for judging the accuracy of a hit.

Usage 
JudgmentWindow(perfect: Interval, great: Interval, good: Interval)

end: float property

The end time of the good interval.

good: Interval instance-attribute

Interval for a good hit.

great: Interval instance-attribute

Interval for a great hit.

perfect: Interval instance-attribute

Interval for a perfect hit.

start: float property

The start time of the good interval.

__add__(other: float | int) -> JudgmentWindow

Add a scalar to the intervals.

__mul__(other: float | int) -> JudgmentWindow

Multiply the intervals by a scalar.

judge(actual: float, target: float) -> Judgment

Judge the accuracy of a hit.

Parameters:

Name Type Description Default
actual float

The actual time of the hit.

 required
target float

The target time of the hit.

 required

Returns:

Type Description
Judgment

The Judgment of the hit.

update(perfect: Interval | None = None, great: Interval | None = None, good: Interval | None = None)

Update the window with the given intervals.

Parameters:

Name Type Description Default
perfect Interval | None

The interval for a perfect hit.

 None
great Interval | None

The interval for a great hit.

 None
good Interval | None

The interval for a good hit.

 None

bucket(*, sprites: list[BucketSprite], unit: AnyText | None = None) -> Any

Define a bucket with the given sprites and unit.

Parameters:

Name Type Description Default
sprites list[BucketSprite]

The sprites that make up the bucket's icon, each drawn at its own position and size.

 required
unit AnyText | None

The unit label shown with the bucket's accuracy values, as a plain string or an AnyText localization dict. If unset, no unit is shown.

 None

bucket_sprite(*, sprite: Sprite, fallback_sprite: Sprite | None = None, x: float, y: float, w: float, h: float, rotation: float = 0) -> BucketSprite

Define a sprite for a bucket.

buckets(cls: type[T]) -> T | Buckets

Decorator to define a buckets class.

Usage 
@buckets
class Buckets:
    note: Bucket = bucket(
        sprites=[
            bucket_sprite(
                sprite=Skin.note,
                x=0,
                y=0,
                w=2,
                h=2,
            )
        ],
        unit=StandardText.MILLISECOND_UNIT,
    )