Scene performance and troubleshooting

Needs MNodes 1.1.5 or newer

Scene and all of its nodes are new in MNodes 1.1.5. They do not exist in older versions, so a project that uses them will not work there until you update.

Start with the problem you can see

Problem	First thing to try
Empty Scene	Check Object → Objects, or Shader Code → Code. Pin pictures.
Very dark 3D object	On View, choose Environment = Studio and check Surroundings Light. No extra lights are needed.
Control will not move	Turn Edit Objects and Edit Zones off.
Slider moves but sound does not	Connect its Value to the sound parameter too.
Text is blurry	Set Scene Resolution = Full.
Animation is too expensive	Try 30 fps before reducing resolution.
First load takes a moment	Let preparation finish. Unchanged prepared shaders can be reused.

Scene uses the graphics card to draw. Sound, scripts and loading still use the CPU. The sections below explain what to check next.

What is cached

Work	Reuse behaviour
An unchanged Scene picture	Retains its last rendered image
Identical shader preparation in the same process	Shares a bounded cache and in-flight work
Supported compiled shader data on Windows	Persists in the local shader cache across launches
Surface material expressions	Share cached immutable programs; parameter edits use the fixed material evaluator
Model/texture preparation	Runs in background queues; completed assets are reused
Closing/reopening the editor or switching view	Reuses the retained Scene picture while the node remains alive
Groups and clones of a 3D world that did not change	Keep where they were placed and how they are drawn; only what moved, and the groups it is in, is worked out again

More about shader loading and the cache

The cache is an optimization, not part of the project. Source changes require new preparation. Code that has not changed stays compiled after an update of MNodes, so a Scene or a Shader opens at once the first time after it. A damaged or unwritable cache falls back to compilation. Do not distribute cache files as a substitute for Shader Code.

On Windows the shader cache lives under the user's application-data folder at MNodes/ShaderCache/v1. A first-ever load still needs preparation, but a Scene with a lot of code shows within seconds in a quick version while the optimized one is prepared in the background and takes its place; the next time the project opens, the optimized one is there straight away. A warm shader cache does not remove model parsing, image decoding, graph loading or all GPU resource creation.

Scene shader jobs use a shared queue with two low-priority workers. Asset preparation has its own bounded worker pool. Closing a Scene cancels queued obsolete work without waiting for a running compile; running work owns its inputs and can finish into the cache. Rapid code edits discard outdated queued versions.

Reduce the right cost

Symptom	First changes to try
High GPU use from a large animated background	Lower Scene Resolution or Frame Rate; reduce per-pixel loops
High cost from reflections/shadows/bloom	Lower the 3D View quality and simplify those effects
Slow loading of complex geometry	Reduce imported mesh/detail, subdivision or joining complexity
Repeated Script work without visible changes	Disable unnecessary Tick, update only changed properties
A big 3D world with a few things moving	Put what never moves in groups, apart from what moves: a group nothing in it changed costs almost nothing
High audio CPU when holding many notes	Inspect voices, oversampling and per-voice effects in the sound graph
Dark materials	Add appropriate environment/light; inspect roughness and exposure
Soft text or controls	Use Full resolution and avoid unnecessarily enlarging a low-resolution rendered surface

Half/Quarter resolution calculate fewer pixels but soften the picture. Keep Full for close-up control text where possible. Frame Rate is an upper limit for animation, not a promise that every display refresh needs a fresh render. A static scene can reuse its picture.

A shader that reads time, audio or retained buffers generally requires ongoing frames while visible. If the effect is static, remove unused animation dependencies rather than merely freezing its visible result. For audio displays, connect sound only where it is needed. Scene/Shader taps with no connected audio now keep silent rings without rewriting every sample each block; they still publish control values.

Surface expressions run per pixel on the GPU. Fractal/Voronoi noise and triplanar textures cost more than a constant or one planar sample. Reuse shared branches. Keep within 32 unique operations / 4 distinct Surface images per material. More objects or more pixels still mean more rendering work even when the expression program is cached.

Separate graphics cost from sound cost

Compare the same patch with Scene bypassed, then with its animation simplified. Keep the same notes, voice count and audio buffer size while comparing. If audio CPU remains high, inspect the instrument graph: multiple long release tails, per-voice reverbs or expensive oscillators can dominate independently of the interface.

A Windows GPU regression test does not establish how a complete DAW session behaves on every driver or on macOS. Measure your actual patch and host with a repeatable passage before claiming an overall CPU improvement.

A blank or incomplete Scene

Check	Why it matters
MNodes 1.1.5 or later	Earlier versions cannot instantiate the new node types
Shader Code wired to Code	A picture source must reach the Scene
Object → View → Scene for 3D	Geometry needs a camera/view before it can display
Material vs Surface sockets	A Fresnel expression cannot enter Objects
Bypass, Visible and opacity	Any of these can hide an otherwise valid result
Camera position, Distance, scale and clipping	The object may be outside the view
Shader error message	Invalid first-load code has no last working picture
External asset paths	Missing models, images or fonts must be located or packaged
Asynchronous first preparation	Large assets can still need time even with warm shader data

If the material browser is dark, try its Studio environment and a roughness above zero. Confirm Apply material rather than only selecting a candidate. A preset changes node settings; connected maps may continue to override the corresponding settings.

Controls look right but do not respond

Turn off Edit Objects and Edit Zones, and check Ignore Clicks. For a shader control, enable Show Zones and confirm the hit region matches the drawing. For a native control, confirm its Object branch reaches the visible Scene.

If a control moves but the sound does not, trace its numeric output and check units. If a DAW lane moves but the drawing does not, check exposure/bindings and whether an incoming CV stream overrides the stored value. Use the automation lesson to isolate host behaviour.

Share a useful bug report

Include the smallest project that reproduces the issue, application build, operating system, GPU/driver, and exact steps. For missing assets, export the project portably. For shader errors, keep the source and full error text. For audio CPU, include sample rate, buffer size, preset and number of held notes. Settings → General links to the support log folders.

Continue with the Scene node reference, or return to Scene Studio.