Skip to content

sonolus.script.sprite

EmptySkin

A skin with no sprites, used as the default when a mode declares none.

RenderMode

Bases: StrEnum

Render mode for sprites.

DEFAULT = 'default' class-attribute instance-attribute

Use the user's preferred render mode.

LIGHTWEIGHT = 'lightweight' class-attribute instance-attribute

Use the lightweight render mode with projective interpolation of textures.

STANDARD = 'standard' class-attribute instance-attribute

Use the standard render mode with bilinear interpolation of textures.

Sprite

Bases: Record

Skin sprite.

Usage 
Sprite(id: int)

is_available: bool property

Whether the sprite is available.

draw(quad: QuadLike, z: ZIndex = 0.0, a: float = 1.0)

Draw the sprite.

Parameters:

Name Type Description Default
quad QuadLike

The quad to draw the sprite on.

 required
z ZIndex

The z-index of the sprite. May be a single value or a tuple containing one to four values, where later values break ties on earlier ones.

 0.0
a float

The alpha of the sprite.

 1.0

draw_curved_b(quad: QuadLike, cp: Vec2, n: float, z: ZIndex = 0.0, a: float = 1.0)

Draw the sprite with a curved bottom with a quadratic Bézier curve.

Parameters:

Name Type Description Default
quad QuadLike

The quad to draw the sprite on.

 required
cp Vec2

The control point of the curve.

 required
n float

The number of segments to approximate the curve (higher is smoother but more expensive).

 required
z ZIndex

The z-index of the sprite. May be a single value or a tuple containing one to four values, where later values break ties on earlier ones.

 0.0
a float

The alpha of the sprite.

 1.0

draw_curved_bt(quad: QuadLike, cp1: Vec2, cp2: Vec2, n: float, z: ZIndex = 0.0, a: float = 1.0)

Draw the sprite with a curved bottom and top with a cubic Bézier curve.

Parameters:

Name Type Description Default
quad QuadLike

The quad to draw the sprite on.

 required
cp1 Vec2

The control point of the bottom curve.

 required
cp2 Vec2

The control point of the top curve.

 required
n float

The number of segments to approximate the curve (higher is smoother but more expensive).

 required
z ZIndex

The z-index of the sprite. May be a single value or a tuple containing one to four values, where later values break ties on earlier ones.

 0.0
a float

The alpha of the sprite.

 1.0

draw_curved_l(quad: QuadLike, cp: Vec2, n: float, z: ZIndex = 0.0, a: float = 1.0)

Draw the sprite with a curved left side with a quadratic Bézier curve.

Parameters:

Name Type Description Default
quad QuadLike

The quad to draw the sprite on.

 required
cp Vec2

The control point of the curve.

 required
n float

The number of segments to approximate the curve (higher is smoother but more expensive).

 required
z ZIndex

The z-index of the sprite. May be a single value or a tuple containing one to four values, where later values break ties on earlier ones.

 0.0
a float

The alpha of the sprite.

 1.0

draw_curved_lr(quad: QuadLike, cp1: Vec2, cp2: Vec2, n: float, z: ZIndex = 0.0, a: float = 1.0)

Draw the sprite with a curved left and right side with a cubic Bézier curve.

Parameters:

Name Type Description Default
quad QuadLike

The quad to draw the sprite on.

 required
cp1 Vec2

The control point of the left curve.

 required
cp2 Vec2

The control point of the right curve.

 required
n float

The number of segments to approximate the curve (higher is smoother but more expensive).

 required
z ZIndex

The z-index of the sprite. May be a single value or a tuple containing one to four values, where later values break ties on earlier ones.

 0.0
a float

The alpha of the sprite.

 1.0

draw_curved_r(quad: QuadLike, cp: Vec2, n: float, z: ZIndex = 0.0, a: float = 1.0)

Draw the sprite with a curved right side with a quadratic Bézier curve.

Parameters:

Name Type Description Default
quad QuadLike

The quad to draw the sprite on.

 required
cp Vec2

The control point of the curve.

 required
n float

The number of segments to approximate the curve (higher is smoother but more expensive).

 required
z ZIndex

The z-index of the sprite. May be a single value or a tuple containing one to four values, where later values break ties on earlier ones.

 0.0
a float

The alpha of the sprite.

 1.0

draw_curved_t(quad: QuadLike, cp: Vec2, n: float, z: ZIndex = 0.0, a: float = 1.0)

Draw the sprite with a curved top with a quadratic Bézier curve.

Parameters:

Name Type Description Default
quad QuadLike

The quad to draw the sprite on.

 required
cp Vec2

The control point of the curve.

 required
n float

The number of segments to approximate the curve (higher is smoother but more expensive).

 required
z ZIndex

The z-index of the sprite. May be a single value or a tuple containing one to four values, where later values break ties on earlier ones.

 0.0
a float

The alpha of the sprite.

 1.0

SpriteGroup

Bases: Record, ArrayLike[Sprite]

A group of sprites.

Does not support negative indexes.

Usage 
SpriteGroup(start_id: int, size: int)

__getitem__(index: int) -> Sprite

Return the sprite at the given index.

Parameters:

Name Type Description Default
index int

The index of the sprite. Must be an integer between 0 and len(self) - 1.

 required

__len__() -> int

Return the number of sprites in the group.

__setitem__(index: int, value: Sprite) -> None

Raise a compile-time error; sprite groups are read-only.

get_unchecked(index: Num) -> Sprite

Return the sprite at the given index, possibly without bounds checking.

StandardSprite

Standard skin sprites.

pad_z_indexes(values: ZIndex) -> tuple[float, float, float, float]

Pad a z-index into a 4-tuple, filling unsupplied values with 0.

skin(cls: type[T]) -> T | Skin

Decorator to define a skin.

Usage 
@skin
class Skin:
    render_mode: RenderMode = RenderMode.LIGHTWEIGHT

    note: StandardSprite.NOTE_HEAD_RED
    other: Sprite = sprite("other")
    group_1: SpriteGroup = sprite_group(["one", "two", "three"])
    group_2: SpriteGroup = sprite_group(f"name_{i}" for i in range(10))

sprite(name: str) -> Any

Define a sprite with the given name.

sprite_group(names: Iterable[str]) -> Any

Define a sprite group with the given names.