Lua API

This page documents the lewdware global table and all types available in a mode's Lua environment. Annotations follow the LuaLS convention.

Functions

lewdware

spawn_image_popup()

function lewdware.spawn_image_popup(image: Image, opts?: SpawnImageOpts): ImageWindow

Spawn a popup displaying an image.

Parameter	Type	Description
image	Image
opts?	SpawnImageOpts

Returns: ImageWindow

spawn_video_popup()

function lewdware.spawn_video_popup(video: Video, opts?: SpawnVideoOpts): VideoWindow

Spawn a popup containing a video.

Parameter	Type	Description
video	Video
opts?	SpawnVideoOpts

Returns: VideoWindow

play_audio()

function lewdware.play_audio(audio: Audio, opts?: PlayAudioOpts): AudioHandle

Play an audio file.

Parameter	Type	Description
audio	Audio
opts?	PlayAudioOpts

Returns: AudioHandle

set_wallpaper()

function lewdware.set_wallpaper(image: Image, opts?: SetWallpaperOpts)

Set the current wallpaper.

Parameter	Type	Description
image	Image
opts?	SetWallpaperOpts

spawn_prompt()

function lewdware.spawn_prompt(opts?: SpawnPromptOpts): PromptWindow

Spawn a prompt popup. This will allow the user to submit text via a text input.

Parameter	Type	Description
opts?	SpawnPromptOpts

Returns: PromptWindow

spawn_choice()

function lewdware.spawn_choice(opts?: SpawnChoiceOpts): ChoiceWindow

Spawn a choice popup. This will present the user with one or more options to click.

Parameter	Type	Description
opts?	SpawnChoiceOpts

Returns: ChoiceWindow

open_link()

function lewdware.open_link(url: string)

Open a URL in the browser

Parameter	Type	Description
url	string

show_notification()

function lewdware.show_notification(notification: Notification)

Show a notification

Parameter	Type	Description
notification	Notification

after()

function lewdware.after(duration: number, fun: fun()): Timer

Call a function after a certain period of time.

Parameter	Type	Description
duration	number	The amount of time to wait for, in milliseconds.
fun	fun()	The function to run.

Returns: Timer

every()

function lewdware.every(duration: number, fun: fun()): Interval

Periodically run a function

Parameter	Type	Description
duration	number	The function will be run every `duration` milliseconds.
fun	fun()	The function to run.

Returns: Interval

exit()

function lewdware.exit()

Stop completely.

lewdware.media

get()

function lewdware.media.get(name: string): Image | Video | Audio | nil

Get a specific file.

Parameter	Type	Description
name	string	The name of the file.

Returns: Image | Video | Audio | nil

get_image()

function lewdware.media.get_image(name: string): Image | nil

Get a specific image file.

Parameter	Type	Description
name	string	The name of the file.

Returns: Image | nil

get_video()

function lewdware.media.get_video(name: string): Video | nil

Get a specific video file.

Parameter	Type	Description
name	string	The name of the file.

Returns: Video | nil

get_audio()

function lewdware.media.get_audio(name: string): Audio | nil

Get a specific audio file.

Parameter	Type	Description
name	string	The name of the file.

Returns: Audio | nil

list()

function lewdware.media.list(opts?: QueryMediaOpts): (Image | Video | Audio)[]

List all files in the pack.

Parameter	Type	Description
opts?	QueryMediaOpts

Returns: (Image | Video | Audio)[]

list_images()

function lewdware.media.list_images(opts?: { tags?: string[], }): Image[]

List all image files in the pack.

Parameter	Type	Description
opts?	{ tags?: string[], }

Returns: Image[]

list_videos()

function lewdware.media.list_videos(opts?: { tags?: string[], }): Video[]

List all video files in the pack.

Parameter	Type	Description
opts?	{ tags?: string[], }

Returns: Video[]

list_audio()

function lewdware.media.list_audio(opts?: { tags?: string[], }): Audio[]

List all audio files in the pack.

Parameter	Type	Description
opts?	{ tags?: string[], }

Returns: Audio[]

random()

function lewdware.media.random(opts?: QueryMediaOpts): Image | Video | Audio | nil

Get a random media file.

Parameter	Type	Description
opts?	QueryMediaOpts

Returns: Image | Video | Audio | nil

random_image()

function lewdware.media.random_image(opts?: QueryMediaOpts): Image | nil

Get a random image file

Parameter	Type	Description
opts?	QueryMediaOpts

Returns: Image | nil

random_video()

function lewdware.media.random_video(opts?: { tags?: string[], }): Video | nil

Get a random video file

Parameter	Type	Description
opts?	{ tags?: string[], }

Returns: Video | nil

random_audio()

function lewdware.media.random_audio(opts?: { tags?: string[], }): Audio | nil

Get a random audio file

Parameter	Type	Description
opts?	{ tags?: string[], }

Returns: Audio | nil

lewdware.monitors

list()

function lewdware.monitors.list(): Monitor[]

Get all available monitors
The available monitors may change while a mode is running. Try not to store this value for too
long.

Returns: Monitor[]

primary()

function lewdware.monitors.primary(): Monitor

Get the user's primary monitor
The primary monitor may change while a mode is running. Try not to store this value for too
long.

Returns: Monitor

Types

Media

Fields

Field	Type	Description
id	number	A unique identifier for the file.
name	string	The name of the file.

Image extends Media

Fields

Field	Type	Description
type	'"image"'
width	number	The width of the image, in pixels.
height	number	The height of the image, in pixels.

Video extends Media

Fields

Field	Type	Description
type	'"video"'
width	number	The width of the video, in pixels.
height	number	The height of the video, in pixels.
duration	number	The duration of the video, in seconds.

Audio extends Media

Fields

Field	Type	Description
type	'"audio"'
duration	number	The duration of the audio file, in seconds.

Window

Fields

Field	Type	Description
id	number	A unique identifier for the window.
width	number	The width of the window, in pixels.
height	number	The height of the window, in pixels.
outer_width	number	The width of the window, including the border and decorations, if present.
outer_height	number	The height of the window, including the border and decorations, if present.
x	number	The x coordinate (in pixels) of the top left coordinate of the window.
y	number	The y coordinate (in pixels) of the top left coordinate of the window.
monitor	Monitor	The monitor that the window is located on.
closed	boolean	Whether the window is currently closed.
visible	boolean	Whether the window is currently visible.

Methods

function Window:close()

Close the window

function Window:on_close(cb: fun())

Execute a function when the window is closed.

Parameter	Type	Description
cb	fun()

function Window:move(opts?: MoveOpts, cb?: fun())

Move a window to a specific position.
Calling this function will cancel any existing move operations.
This means you can call this function with no arguments to stop moving a window.

Parameter	Type	Description
opts?	MoveOpts
cb?	fun()	Called when the window finished moving.

function Window:set_visible(visible: boolean)

Set the visibility of a window.
Making a window invisible instead of closing it can be a good idea if you want to use it again,
or you want to avoid the fade-out animation that occurs when a window is closed normally.
Making a window invisible will stop the user from interacting with it, but e.g. video windows
will continue to play, so you should consider calling [VideoWindow:pause](lua://VideoWindow.pause). Always remember
to close windows that you are no longer using.

Parameter	Type	Description
visible	boolean

function Window:set_title(title: string?)

Set the text displayed in the header.

Parameter	Type	Description
title	string?

MoveOpts

Fields

Field	Type	Description
x?	Coord	The horizontal coordinate to move the window to (by default, the window will not be moved horizontally).
y?	Coord	The vertical coordinate to move the window to.
anchor?	Anchor	Where to place the window relative to the specified coordinates. By default, "top-left" is used, meaning that the top-left corner of the window is placed at the specified coordinates.
relative?	boolean	If true, then `x` and `y` are considered to be relative to the current position of the window. By default, this is false.
duration?	number	How long the movement should take. By default, the move happens instantly.
easing?	Easing	How the movement is animated.

ImageWindow extends Window

Fields

Field	Type	Description
type	"'image'"
image	Image	The image being shown on the window.

VideoWindow extends Window

Fields

Field	Type	Description
type	"'video'"
video	Video	The video being played on the window.

Methods

function VideoWindow:pause()

Pause the video being played on the window.

function VideoWindow:play()

Resume playback of the video on the window.

function VideoWindow:set_loop(loop: any)

Set whether a video window should loop when the video ends (see also the `loop` option in `spawn_video_popup()`). Non-looping videos close when they end.

Parameter	Type	Description
loop	any

PromptWindow extends Window

Fields

Field	Type	Description
type	"'prompt'"
title?	string
text?	string
value	string	The value that the user has typed. This is only updated when the user submits the text, so it's better to use `on_submit()` to get this value.

Methods

function PromptWindow:on_submit(cb: fun(text: string))

Call a function every time the user submits a value.

Parameter	Type	Description
cb	fun(text: string)	A function that takes the value that the user has submitted.

function PromptWindow:set_text(text?: string)

Set the text/subtitle of the window.

Parameter	Type	Description
text?	string

function PromptWindow:set_value(value?: string)

Change the value in the text box of the window.

Parameter	Type	Description
value?	string

ChoiceWindow extends Window

Fields

Field	Type	Description
type	"'choice'"
title?	string
text?	string
options	{ id: string, label: string }[]

Methods

function ChoiceWindow:on_select(cb: fun(id: string))

Call a function when the user clicks on one of the choice buttons.

Parameter	Type	Description
cb	fun(id: string)	A function taking the id of the choice that the user submitted.

function ChoiceWindow:set_text(text?: string)

Set the text/subtitle of the window.

Parameter	Type	Description
text?	string

function ChoiceWindow:set_options(options?: { id: string, label: string }[])

Set the choices that the user has to choose from.

Parameter	Type	Description
options?	{ id: string, label: string }[]

QueryMediaOpts

Fields

Field	Type	Description
type?	MediaType |	(MediaType)[] The type of media to include in the result. By default, all media will be included (including audio).
tags?	string[]	If specified, only media with these tags will be included in the result.

SpawnWindowOpts

Options that can be passed into any of spawn_image_popup(), spawn_video_popup(), spawn_prompt() and spawn_choice().

Fields

Field	Type	Description
x?	Coord	The horizontal coordinate to spawn the window at. By default, the coordinates of the window will be chosen at random, ensuring that the window remains entirely visible.
y?	Coord	The vertical coordinate to spawn the window at.
anchor?	Anchor	Where to place the window relative to the specified coordinates. By default, "top-left" is used, meaning that the top-left corner of the window is placed at the specified coordinates.
width?	Coord	The width of the window. Defaults to the width of the image, or a third of the monitor width if the image is too big.
height?	Coord	The height of the window. Defaults to the height of the image, or a third of the monitor height if the image is too big.
monitor?	Monitor	The monitor to spawn the window on. By default, chooses a monitor at random.
decorations?	boolean	Whether to spawn the window with a header and border (defaults to true). Note that windows without a header will not be able to be closed manually by the user.
title?	string	The text displayed in the header. Can be set dynamically using `Window:set_title()`. If `decorations` is false, this will be ignored.
closeable?	boolean	Whether the header should include a close button. Defaults to true. If this is false, then the user will not be able to close the window manually. If `decorations` is false, this will be ignored.
visible?	boolean	Whether to make the window start off visible (defaults to true). See `Window:set_visible()`.

SpawnImageOpts extends SpawnWindowOpts

Options for `spawn_image()`.

SpawnVideoOpts extends SpawnWindowOpts

Options for `spawn_video()`.

Fields

Field	Type	Description
loop?	boolean	Whether to loop the video (defaults to true). If false, the window will be closed when the video ends.
audio?	boolean	Whether to play the video's audio (if there is any). Defaults to true.

PlayAudioOpts

Fields

Field	Type	Description
loop	boolean	Whether to loop the audio. If true, the audio will loop forever until you stop it.

AudioHandle

Fields

Field	Type	Description
id	number	A unique identifier for the audio handle.
audio	Audio	The audio file that is being played.

Methods

function AudioHandle:on_finish(cb: fun())

Run a function when an audio track finishes. If the audio file is set to loop, this will be
called every time the audio file loops.

Parameter	Type	Description
cb	fun()

function AudioHandle:pause()

Pause the audio track.

function AudioHandle:play()

Resume the audio track.

SetWallpaperOpts

Fields

Field	Type	Description
mode?	"center" |	"crop" | "fit" | "span" | "stretch" | "tile"

SpawnPromptOpts extends SpawnWindowOpts

Options that can be passed into `spawn_prompt()`.

Fields

Field	Type	Description
text?	string	Text that is displayed at the top of the prompt.
placeholder?	string	A placeholder value that is shown in the text input before the user has typed anything.
initial_value?	string	An initial value for the text input.

SpawnChoiceOpts extends SpawnWindowOpts

Options that can be passed into `spawn_choice()`.

Fields

Field	Type	Description
text?	string
options	{ id: string, label: string }[]	The list of options, which determine the buttons to present to the user. Only the label is displayed, the id is used in `on_select()`.

Notification

Fields

Field	Type	Description
summary?	string
body	string

Timer

Fields

Field	Type	Description
duration	number

Methods

function Timer:stop()

Stop a timer from running

Interval

Fields

Field	Type	Description
duration	number	How often (in milliseconds) the function is executed.

Methods

function Interval:stop()

Stop/cancel an interval from running.

function Interval:set_duration(duration: number)

Change the duration of an interval (e.g. to speed up or slow down how often the function is called).

Parameter	Type	Description
duration	number

Monitor

Fields

Field	Type	Description
id	number
primary	boolean

Aliases

Anchor

"center" | "bottom-right"

"top-left" |

Easing

"linear""ease_in""ease_out""ease_in_out"