package asset

import "git.teletypegames.org/engines/inkwell/inkbase/asset"

Package asset provides the filesystem abstraction, the image cache and the audio player for inkbase games.

Files

Every file is opened through OpenAsset, which reads from AssetFS — an embed.FS set before the game runs, to ship the assets inside the binary — or from the operating system's filesystem while AssetFS is nil.

Images

An inkbase.Asset is only a spec, a Name and a Path. LoadedAssets opens the file the first time a picture is asked for, decodes it (PNG and JPEG) and caches it by Asset pointer. A missing or unreadable file falls back to a deterministic placeholder colour derived from the name (PlaceholderImage) and is marked as such, so the game runs without any art — useful for prototyping and CI — and LoadedAssets.IsPlaceholder lets a widget draw a stylised figure instead of a flat rectangle.

Audio

AudioPlayer plays the three things a game is heard through: a Music track (streamed from disk, looping when asked, unchanged when the same track is asked for again), a recorded Voice line (whose duration it reports, so speech can last exactly as long) and a one-shot Sound (over everything else). The shared Ebitengine audio context is made lazily at 48 kHz, or taken over when a host process already made one. Voices and sounds are decoded once and cached. WAV, Ogg Vorbis and MP3 are read, picked by file extension. Every failure — a missing file, an unsupported codec, no audio device — degrades to a log line and silence, and a file that failed is not tried again.

Index

Variables

var AssetFS fs.FS

AssetFS is the filesystem asset files are read from. While it is nil they come from the OS filesystem; set it to an embed.FS before Run to ship them inside the binary.

Functions

func LoadImageFile

func LoadImageFile(path string) *ebiten.Image

LoadImageFile reads and decodes the PNG or JPEG at path through OpenAsset. It returns nil when the file is missing or does not decode, and does not cache.

func OpenAsset

func OpenAsset(path string) (fs.File, error)

OpenAsset opens an asset file honoring AssetFS.

func PlaceholderImage

func PlaceholderImage(seed string, w, h int) *ebiten.Image

PlaceholderImage creates a deterministic colored rectangle for missing assets.

Types

type AudioPlayer

type AudioPlayer struct {
	// contains filtered or unexported fields
}

AudioPlayer plays music, recorded lines and one-shot sound effects through Ebiten's audio subsystem. Fail-soft: missing files degrade to no-ops.

func NewAudioPlayer
func NewAudioPlayer(logf func(string, ...any)) *AudioPlayer

NewAudioPlayer returns an idle AudioPlayer. logf receives a line for every missing or undecodable file and every music change; it may be nil. The audio context is made, or Ebitengine's current one taken, on first play.

func (*AudioPlayer) PlayMusic
func (a *AudioPlayer) PlayMusic(music *inkbase.Music)

PlayMusic switches the background track to music, looping it when music.Loop is set. Asking for the track already playing does nothing; any other track is stopped first. A nil music, or one whose file is missing or does not decode (.wav, .ogg and .mp3 are read), leaves silence, and a failed file is not tried again.

func (*AudioPlayer) PlaySound
func (a *AudioPlayer) PlaySound(sound *inkbase.Sound)

PlaySound plays sound once, on top of whatever else is sounding. The decoded file is cached, so a sound played again starts at once; a nil sound or a file that cannot be read stays silent.

func (*AudioPlayer) PlayVoice
func (a *AudioPlayer) PlayVoice(voice *inkbase.Voice) float64

PlayVoice plays a recorded line once and reports its duration in seconds.

func (*AudioPlayer) StopMusic
func (a *AudioPlayer) StopMusic()

StopMusic stops the background track and forgets it, so the next PlayMusic starts from the beginning.

func (*AudioPlayer) StopVoice
func (a *AudioPlayer) StopVoice()

StopVoice cuts off the recorded line playing, if any.

type LoadedAssets

type LoadedAssets struct {
	// contains filtered or unexported fields
}

LoadedAssets is the runtime cache for decoded image resources.

func NewLoadedAssets
func NewLoadedAssets(w, h int) *LoadedAssets

NewLoadedAssets returns an empty image cache whose placeholders, for a nil or unreadable asset, are w by h pixels.

func (*LoadedAssets) Image
func (la *LoadedAssets) Image(a *inkbase.Asset) *ebiten.Image

Image loads an asset's picture once and hands back the same *ebiten.Image after. An asset that cannot be read gets a flat placeholder.

func (*LoadedAssets) IsPlaceholder
func (la *LoadedAssets) IsPlaceholder(a *inkbase.Asset) bool

IsPlaceholder reports whether the named image fell back to a generated rectangle.