File Cache

Bake a node chain's output to disk so downstream evaluation is a file read instead of a GPU graph walk — textures AND geometry. Primary use: make stateful simulations, slow chains, and AI-node outputs playable at real-time.

Category: Utility Menu path: Utility > File Cache

Ports

Port	Type	Direction	Description
in	imageRgba16f / shape / points	input	Upstream output to cache. Polymorphic — connecting a shape or points source switches both ports to that type (like Transform2D).
out	matches in	output	Cached data (or upstream, depending on mode)

Parameters

Param	Type	Default	Description
mode	enum	Auto	Cache behavior — see Modes below

Modes

Mode	Behavior
Auto	Serve the on-disk cache if a file exists for this frame; otherwise evaluate the upstream chain and serve that. Never auto-writes.
Read	Always serve from disk. Transparent frame + warning on miss. Useful when you know the cache is complete and want to guarantee zero upstream work.
Bypass	Pure passthrough. Never touches disk. Use to temporarily disable the cache without deleting files.
Rebake	Every rendered frame evaluates upstream AND writes to disk. Use briefly to update the cache, then switch back to Auto or Read.

How It Works

FileCache writes one file per frame to <project_dir>/cache/file_cache/<node_id>/<NNNNNNNN>.caddis-fc. Each file holds a 48-byte header (magic, dimensions, format code, frame, upstream hash) plus a payload:

• Texture payloads are 16-bit-float RGBA, byte-shuffled and zstd-compressed. Typical motion-design frames (flat regions, alpha, gradients) land at 5–25% of raw size; photographic/noisy content compresses less. Legacy uncompressed (pre-v2) files are still readable.
• Geometry payloads (points / shapes) store the full data — positions, IDs, per-point and per-path attributes — as compressed JSON. They are tiny compared to renders: caching geometry before the Draw step is dramatically cheaper than caching the rasterized result, and downstream Draw nodes stay live (you can still tweak point size, color, stroke, etc. against the cached geometry).

On a cache hit (Auto/Read with a file present), the entire upstream chain is skipped — it's pruned from evaluation, the pre-pass, and bounds computation. Decoded frames are also kept in an in-memory LRU (512 MB textures / 128 MB geometry), so scrubbing back over cached frames doesn't even touch disk.

Projects that have never been saved fall back to the OS temp dir — baked frames survive until the OS cleans temp. Save the project to get stable, project-local caching.

The Bake Range button in the Parameters panel flips the node to Rebake for the preview range (or the full comp if no preview range is set), renders every frame, then restores the original mode. Clear deletes every cache file for the node.

Usage Examples

Real-time playback of a heavy simulation (geometry cache)

PointAdvect through a 200k-particle field stalls frame eval. Insert a FileCache between PointAdvect and DrawPoints, click Bake Range once, leave mode on Auto. The sim never re-runs — each frame is a few-MB geometry read — and DrawPoints stays fully editable (size, color, attributes) against the baked positions.

Real-time playback of a heavy render (texture cache)

A long effects chain (OpticalFlow, LensBlur stacks, AI nodes) renders slowly. Insert a FileCache after the chain, Bake Range, leave on Auto. Playback becomes a decompress + GPU upload.

Lock in a generative result

Running a slow AI-node chain (or anything randomized you want to freeze): bake once, flip to Read. Upstream can change, edit, or break — downstream keeps serving the baked version until you re-bake.

Tips

• Cache geometry, not pixels, when you can. A baked particle sim is typically 100–1000× smaller as a points cache than as a rendered-frame cache, and keeps the look editable downstream.
• Texture file size varies with content: flat/graphic frames compress to a few MB at 1080p; noisy footage compresses least. The node's status row shows the real on-disk total.
• Upstream edits are not auto-detected. Bake stores an upstream_hash in each file's header for future staleness warnings, but today the node happily serves stale data until you Clear + Rebake. The amber dot in the Parameters panel flags "edited since bake". Design intent: caches are user-controlled, not automatic — auto-invalidation would defeat the purpose.
• Selecting the FileCache node doesn't disable it. (It used to: inspecting the node re-evaluated the whole upstream chain every frame.)
• Project moves are safe. Paths are derived from project_dir at load time, not stored in the .caddis file. Move a project folder with its cache/ subdirectory and FileCache finds everything.
• .gitignore: the cache/ folder is intentionally local-only. Commit baked results by copying elsewhere.

Limitations

• Text data has no cacheable payload yet (shape/points only — run TextToShape first if needed).
• No timeMode (Shift / Freeze / Loop) yet — coming with Time Manipulation in Tier 5.
• No cancellable bake.

Related Nodes

• Dot — Pure passthrough (what FileCache-Bypass acts like)
• Debug — Different passthrough — reports values into the perf HUD