Plus Lua API

Video callbacks

This page documents the Lua callbacks exposed by LuaVideo.hx and the internal variables that control video sprite playback, placement, and cleanup.

CallbacksLua functions available for videos Video variablesInternal state and parameters Presentation videoLocal preview using present.mp4

Presentation video

The preview now uses the local file assets/videos/present.mp4. This keeps the page independent from external embeds and avoids browser blocking issues.

Video callbacks

  • playLuaVideoSprite(tag, path, x, y, front) creates and plays a video sprite.
  • pauseLuaVideo(tag) pauses the active video assigned to the tag.
  • resumeLuaVideo(tag) resumes the active video assigned to the tag.
  • removeLuaVideo(tag) requests a safe removal of the video sprite.
  • forceRemoveLuaVideo(tag) bypasses the delayed removal guard.
  • luaVideoExists(tag) checks whether the tagged video exists.
  • isLuaVideoPlaying(tag) returns the current playback state.
  • setLuaVideoVolume(tag, volume) adjusts the playback volume.
  • getLuaVideoDuration(tag) returns the full duration in seconds.
  • getLuaVideoTime(tag) returns the current playback position in seconds.

Video variables

These variables and parameters follow the same documentation style used in Psych: name first, then a direct explanation of what each one does.

tagUnique key used to store and retrieve the video sprite. pathMedia path resolved with Paths.video(path). xHorizontal position applied after the video format is ready. yVertical position applied after the video format is ready. frontIf true, the video is added above the playfield stack. volumeNormalized playback volume used by setLuaVideoVolume. activeVideosInternal map that tracks active video sprites. allowDestroyInternal guard that delays destruction until the sprite is ready. isDestroyedInternal flag that prevents double-destroy operations.

tag

Identifier used as the reference key for the video sprite. Every callback that acts on a video uses this same tag to find it again.

path

Video file path passed to playLuaVideoSprite. The engine resolves it with Paths.video(path) before loading the sprite.

x

Horizontal position of the video sprite. It is applied once the format setup callback finishes and the hitbox can be updated.

y

Vertical position of the video sprite. Like x, it is applied after the video finishes its initial setup.

front

Layering flag used by playLuaVideoSprite. When set to true, the sprite is added above the playfield stack.

volume

Normalized volume value used by setLuaVideoVolume. The callback translates it to the internal player volume.

activeVideos

Internal map that stores the currently active video sprites by tag.

allowDestroy

Internal guard that delays destruction briefly so the sprite is not removed during initialization.

isDestroyed

Internal flag that prevents the same video from being destroyed twice.

Notes

  • VIDEOS_ALLOWED must be enabled at build time.
  • onVideoFinished(tag) fires when the video reaches the end.
  • forceRemoveLuaVideo(tag) is useful when cleanup must happen immediately.
  • This documentation is ready for more video examples later.