tecs.io.watcher#

Polls loaded content and dispatches changes to reload handlers.

local watcher <const> = tecs.io.watcher

if watcher.isSupported() then
    watcher.on(
        "document",
        function(change: watcher.Change)
            print("reload " .. change.path)
        end
    )
    watcher.install({intervalSeconds = 0.25})
end

An Application with watch in its configuration installs and advances the watcher. Settled changes enter a bounded queue and handlers run in the scheduler-owned Ingress phase. They never interrupt a half-completed phase, and a handler may use the same cooperative operations as an ordinary system. Game systems, plugins, and update functions do not poll.

The watcher scans only paths recorded by tecs.io.files.read and the asset loaders. It waits for a changed file's size and modification time to settle before dispatching it. Empty, missing, and directory paths do not dispatch.

Repeated queued changes to one path coalesce. Config.capacity bounds distinct pending paths; an overflow is logged and retried by a later scan instead of growing memory without limit. A handler error reaches the log and does not replace the current resource. Release builds report isSupported() == false.

Module contents#

Types#

Functions#

Types#

tecs.io.watcher.Change record#

Change describes one settled content change.

record tecs.io.watcher.Change
    path: string
    kind: string
end

tecs.io.watcher.Change.path field#

Read-only. The watcher sets path to the changed loaded path before it calls the handler.

tecs.io.watcher.Change.path: string

tecs.io.watcher.Change.kind field#

Read-only. The watcher sets kind to the content kind recorded by the original load. Built-in loaders use "image", "sound", "font", "shader" or "document"; a custom loader supplies its own kind to tecs.io.files.read.

tecs.io.watcher.Change.kind: string

tecs.io.watcher.ChangeHandler type#

ChangeHandler receives one settled change.

type tecs.io.watcher.ChangeHandler = function(Change)

tecs.io.watcher.Config record#

Config controls polling frequency, settling and path scope.

record tecs.io.watcher.Config
    intervalSeconds: number
    settle: integer
    root: string
    capacity: integer
end

tecs.io.watcher.Config.intervalSeconds field#

Caller-writable. Sets the delay between automatic polls in seconds. It defaults to 0.5. Direct calls to scan ignore this delay.

tecs.io.watcher.Config.intervalSeconds: number

tecs.io.watcher.Config.settle field#

Caller-writable. Requires this many additional matching scans after a change is first observed. It defaults to 1, so one scan observes the change and the next confirms it. Zero dispatches immediately.

tecs.io.watcher.Config.settle: integer

tecs.io.watcher.Config.root field#

Caller-writable. Limits watched paths to this root. It defaults to the content root.

tecs.io.watcher.Config.root: string

tecs.io.watcher.Config.capacity field#

Caller-writable. Limits settled changes waiting for the next logical update. Defaults to 1024. Repeated changes to one path coalesce while queued.

tecs.io.watcher.Config.capacity: integer

Functions#

tecs.io.watcher.dispatched Static#

Returns the changes dispatched since install.

function tecs.io.watcher.dispatched(): integer

Arguments#

None.

Returns#

tecs.io.watcher.install Static#

Starts watching loaded content.

The watcher records the current state of loaded paths and dispatches only later changes. It raises when the build lacks hot-reload support.

function tecs.io.watcher.install(config: watcher.Config)

Arguments#

Returns#

None.

Examples#

local watcher <const> = tecs.io.watcher

local function enableReloading()
    watcher.on(
        "document",
        function(change: watcher.Change)
            print("changed " .. change.path)
        end
    )
    watcher.install({intervalSeconds = 0.25})
end
-- The Application advances the watcher and dispatches the handler from its
-- Ingress phase. Call watcher.uninstall() to stop it.
enableReloading()

tecs.io.watcher.isInstalled Static#

Returns whether the watcher is running.

function tecs.io.watcher.isInstalled(): boolean

Arguments#

None.

Returns#

tecs.io.watcher.isSupported Static#

Returns whether this build supports hot reload.

function tecs.io.watcher.isSupported(): boolean

Arguments#

None.

Returns#

tecs.io.watcher.kinds Static#

Returns registered content kinds in sorted order.

function tecs.io.watcher.kinds(): {string}

Arguments#

None.

Returns#

tecs.io.watcher.on Static#

Registers the handler for a content kind.

Re-registering a kind replaces its handler. Nil removes it.

function tecs.io.watcher.on(
    kind: string, handler: watcher.ChangeHandler
)

Arguments#

Returns#

None.

tecs.io.watcher.scan Static#

Looks at every watched path once, whatever the interval says.

Call this directly when a headless tool or test controls poll timing.

function tecs.io.watcher.scan(): integer

Arguments#

None.

Returns#

tecs.io.watcher.uninstall Static#

Stops watching and forgets every path's state.

Registered handlers remain available for a later installation.

function tecs.io.watcher.uninstall()

Arguments#

None.

Returns#

None.

tecs.io.watcher.unsettled Static#

Returns unsettled changed paths in sorted order.

function tecs.io.watcher.unsettled(): {string}

Arguments#

None.

Returns#

tecs.io.watcher.watching Static#

Returns watched paths in sorted order.

function tecs.io.watcher.watching(): {string}

Arguments#

None.

Returns#