vfs

The vfs namespace — 18 functions.

globals/vfs/clearPlayShadow

globals/vfs/clearPlayShadow() -> boolean

Forget the entire play-shadow set after a bulk promote or discard. Tracking only — never touches the bytes.

globals/vfs/evict

globals/vfs/evict(path: string, opts: VfsOpts?) -> boolean

Drop the in-memory bytes for path from the writable MemFs layer without removing the asset. Use after processing large binaries to reclaim RAM.

globals/vfs/exists

globals/vfs/exists(path: string, opts: VfsOpts?) -> boolean

Is the path known to the VFS? Checks the Stage-1 metadata (.meta sidecar / ManifestView) — NOT "are the bytes locally cached?". Use vfs.read(path) ~= nil to confirm bytes are reachable.

globals/vfs/list

globals/vfs/list(path: string?) -> { VfsListEntry }

List entries in a VFS directory.

globals/vfs/mkdir

globals/vfs/mkdir(path: string, opts: VfsOpts?) -> boolean

Create a directory. mkdir -p semantics — idempotent. Errors if a file already exists at the same path.

globals/vfs/move

globals/vfs/move(src: string, dst: string, opts: { quiet: boolean? }?) -> (boolean, string?)

Move a file from src to dst. By default fires the destination's write side effects; pass opts.quiet = true to suppress them.

globals/vfs/pendingWrites

globals/vfs/pendingWrites() -> { string }

List the /source paths with an in-flight local write the synced manifest has not reflected yet — the read-your-writes frontier. A just-written file appears here until its upload round-trips and the synced dirty state catches up; world.vcsStatus unions these so a fresh edit reads back as dirty immediately. Empty when fully synced.

globals/vfs/playShadowPaths

globals/vfs/playShadowPaths() -> { string }

List the /source paths edited during running play that are currently held as copy-on-write SHADOWS (MemFs-only, on-disk original untouched) — the universal play shadow-copy set. These are the in-play edits persist promotes over the originals on confirm, or drops on a guarded discard. Empty outside play or when nothing was edited.

globals/vfs/promotePlayShadow

globals/vfs/promotePlayShadow(path: string) -> (boolean, string?)

Promote a single play-shadow edit into a canonical write. Re-asserts the live overlay bytes through the full write pipeline with the play write lock released, then unmarks the path. The bytes stay in the engine end to end, so binary content promotes exactly. Requires play to be paused.

globals/vfs/read

globals/vfs/read(path: string, opts: VfsOpts?) -> string?

Read a file from the virtual filesystem. Binary-safe. Returns file contents as a string, or nil if the file is not known. Relative paths resolve under opts.root (default /source/). When called from a coroutine and the bytes aren't locally cached, transparently yields the coroutine while the lazy fetch runs.

globals/vfs/readAsync

globals/vfs/readAsync(path: string, opts: VfsOpts?) -> string

Asynchronous binary-safe read. Returns a promise ID that resolves to the file contents. Useful for reading render textures from the main thread without blocking.

globals/vfs/reload

globals/vfs/reload(modulePath: string?) -> boolean

Clear entries from the require() cache so the next require(name) re-runs the module's source. Pass a single module identity to drop only that entry; call with no arguments to drop every cached module.

globals/vfs/remove

globals/vfs/remove(path: string, opts: VfsOpts?) -> (boolean, string?)

Remove a file. Refuses to remove directories unless opts.recursive = true. Refuses protected system roots.

globals/vfs/revertPlayShadow

globals/vfs/revertPlayShadow(path: string) -> (boolean, string?)

Revert a single play-shadow edit: restore the pre-play copy captured at the first play-mode write (the last edit-mode state, unstaged edits included) into the live slot — or remove the file when it did not exist at that moment — then unmark the path. Hot-reload picks the original back up, so the running session actually reverts. Requires play to be paused.

globals/vfs/unmarkPlayShadow

globals/vfs/unmarkPlayShadow(path: string) -> boolean

Forget a single play-shadow path after it has been promoted (saved over source) or discarded. Tracking only — never touches the bytes.

globals/vfs/unwatch

globals/vfs/unwatch(watcherId: number) -> boolean

TRUSTED ONLY. Remove a previously registered VFS watcher.

globals/vfs/watch

globals/vfs/watch(path: string, callback: (string, string) -> ()) -> number

TRUSTED ONLY. Register a callback that fires when a VFS path is written or removed. Two match modes: exact, or folder/prefix (key ends with /). Callback signature: function(path: string, kind: "write" | "remove"). Returns a watcher id for vfs.unwatch.

globals/vfs/write

globals/vfs/write(path: string, content: string, opts: VfsOpts?) -> (boolean, string?)

Write content to a file. Binary-safe. Overwrites existing files by default — pass opts.overwrite = false to refuse to clobber. Locked in play mode (returns (false, errmsg)).