dialogbox_sprite_EN

Sprite (Standing Picture) Feature

Starting from v2.3.0, dialogbox supports rendering character sprites!

Demo Video

Declaring Characters

sayori = dokibox.Avatar(name="Sayori", emotes={
    "normal": ["images\\sayori\\1l.png",
               "images\\sayori\\1r.png",
               "images\\sayori\\a.png"]
})

dokibox.Avatar initializes a character sprite. See avatar_test.py in the repository for a full example.

Parameter	Type	Default	Description
name	str	""	Content displayed in the dialogbox name tag
emotes	dict	—	A dictionary where keys are emote names and values are lists of images. You can place any number of sprite images — they can be file path strings or bytes objects. dokibox composites all provided images into one and renders them together.

Rendering Sprites

A typical sprite dialogbox call looks like this:

dokibox.dialogbox("Wow, the scenery here is so relaxing!", name=sayori, sprites=[sayori("center", "happy")])

Parameter	Type	Default	Description
name	str or dokibox.Avatar	""	If an Avatar is passed, dialogbox treats that character as the speaker and scales them up by 10%.
sprites	list	None	A list of dokibox.Avatar calls (not recommended to exceed 6). Call the avatar variable as a magic method directly.
sprite_allow_cover	bool	False	If True, sprites at the same position are allowed to overlap. When False, sprites sharing a position are automatically spread apart.

About dokibox.Avatar Magic Call

The full magic call signature, using the sayori character declared earlier:

sayori(position="center", emote="happy", animation="shocked", width=200, height=300, sprite_allow_cover=True)

Parameter	Type	Default	Description
position	str	—	Must be one of left, center, or right. Represents the sprite's position on stage. Multiple sprites can share a position — the program adjusts them automatically.
emote	str	—	Must match a key in the emotes dictionary declared when creating the character. Represents the sprite's expression for this dialogbox.
animation	str	None	See the About Animation Parameter section below.
width	int	None	Sprite width. When only one of width or height is set, the other is scaled proportionally based on the original image aspect ratio. When both are set, the sprite is stretched to the exact dimensions.
height	int	None	Sprite height. Same proportional scaling rules as width.
sprite_allow_cover	bool	False	If True, this specific sprite ignores the averaging/spreading algorithm and overlays directly at its position.

About Animation Parameter

Name	Behavior
thanks	Sprite moves down and then bounces back up, like a bow.
sad	Sprite moves down and stays there until the next dialogbox call.
shocked	Sprite quickly bounces upward.

Multi-sprite example:

dokibox.dialogbox("So that's it! No wonder it's so lush everywhere — it's so beautiful!", name=sayori, sprites=[sayori("left", "happy"), yuri("right", "smiled")])

dokibox.dialogbox("Yeah, such a healing place deserves to be visited together. Looks like we're on the same wavelength!", name=monika, sprites=[sayori("center", "happy"), monika("center", "happy2"), yuri("center", "shocked"), natsuki("center", "mild")])

dokibox.dialogbox("Hello!",name=monika,sprites=[sayori("left", "shocked"),monika("center", "normal", sprite_allow_cover=True),yuri("right", "shocked"),natsuki("center", "shocked")])

About Continuous Calls

When the expression and position haven't changed, you can omit the sprites parameter or pass None — this reuses the previous dialogbox configuration:

dokibox.dialogbox("So that's it! No wonder it's so lush everywhere — it's so beautiful!", name=sayori, sprites=[sayori("left", "happy"), yuri("right", "smiled")])
dokibox.dialogbox("Such a cozy place... if only we had some sweet cookies, it'd be perfect! Ehehe~", name=sayori)

This is equivalent to:

dokibox.dialogbox("So that's it! No wonder it's so lush everywhere — it's so beautiful!", name=sayori, sprites=[sayori("left", "happy"), yuri("right", "smiled")])
dokibox.dialogbox("Such a cozy place... if only we had some sweet cookies, it'd be perfect! Ehehe~", name=sayori, sprites=[sayori("left", "happy"), yuri("right", "smiled")])

About Sprite Exit

Use the hide() method to make a sprite leave the stage:

dokibox.dialogbox("Everyone looks at me in surprise, and I stare back at them", name="MC", sprites=[monika.hide(), sayori.hide(), yuri.hide(), natsuki.hide()])  # all leave

Notes When Using Alongside Other Qt Windows

After your story/dialogue ends, it's recommended to set fdst=True on the last dialogbox call to properly destroy the window. This is a known workaround for window cleanup when integrating with other Qt-based applications.