Skip to content

SceneEngine UserGuide

Jump to bottom
Bradley Brown edited this page Aug 13, 2026 · 1 revision

Scene Engine — User Guide

Companion pages: User Index · developer-facing counterpart: Scene Engine Architecture · project roadmap: Scene Engine Roadmap.

The Scene Engine is the cinematic layer of Fracturing Fog. Where a region saves a single frozen view and an animation wiggles the numbers behind one view, a Scene strings several views together into a timeline, flies a camera around the 3-D fractals, fades between shots, ramps the exposure across the whole clip, and — when you are ready — renders the result to a video file.

If you have ever wanted the app to make a little film instead of just showing you a picture, this is the page for you.

What is a Scene, in plain words?

Think of a Scene as a shot list for a short film:

  • A Scene is the whole film.
  • A Shot is one continuous clip inside it — one fractal, one palette, for a set number of seconds.
  • A Camera track is the path the camera flies along during a 3-D shot.
  • A Transition is how one shot hands over to the next — a hard cut, a cross-fade, a wipe.
  • A Global track is a change applied to the whole Scene on top of every shot — for example, fading the exposure up from black over the opening.

You author and preview a Scene inside the app in real time, then export it to an MP4 (or a folder of PNG frames) at whatever quality your machine can manage, taking as long as it needs.

The Scene Editor with a two-shot timeline and a camera keyframe row.

Note

Scenes reference your existing assets by name — they do not copy them. A Scene that uses the region "Seahorse Deep" simply remembers the name; if you later re-paint that region, the Scene picks up the new look automatically. If you delete or rename the region, the shot quietly falls back to a default rather than crashing.

The two ways a Scene is shown: preview vs. export

This is the single most important idea on the page, so it comes first.

Preview (realtime) Export (offline)
Goal stay smooth while you author look as good as possible
Speed keeps up with the clock, dropping quality if it must renders each frame to completion, however long that takes
Transitions cuts only — shots hard-cut between each other full cross-fades, wipes, and morphs
Motion blur none optional, silky
Output the live window an MP4 / PNG sequence

Why the split? A cross-fade needs two fractals drawn at once. For two live 3-D raymarchers that is more work than a mid-range machine can do without stuttering, and Fracturing Fog refuses to bog down your computer to keep the promise (see Resource use below). So realtime preview cuts between shots, and the pretty transitions appear only in the exported video, where the renderer can take its time and draw both sides.

Important

If you preview a Scene and the cross-fades look like hard cuts, nothing is broken — that is by design. Export the Scene and the fades will be there.

Opening the Scene Editor

There are two doors into the editor:

  1. Floating menu → Edit Scene… Press M to raise the floating menu, then click Edit Scene…. This opens the editor on a blank Scene (or the last one you were editing).
  2. Asset Manager → Scenes. Open the Asset Manager, expand the Scenes node, and click any Scene row. Built-in demo Scenes live here too.

Either way you land in the same editor.

A five-minute first Scene

Let us build a Scene from scratch — a single flying orbit of a Mandelbulb.

  1. Press M → Edit Scene…. Click New to start with an empty Scene.

  2. Type a Name — say My First Orbit.

  3. Click Add Shot. A shot row appears.

  4. In the shot, set Fractal type to Mandelbulb and Duration to 20 seconds. Leave Region blank — a blank region just renders the fractal type with its default look, which is perfect for a first try.

  5. Because Mandelbulb is a 3-D type, a Camera section appears under the shot. Add four camera keys:

    Time (s) Distance θ (theta) φ (phi) Ease
    0 2.6 0.0 0.35 None
    5 2.3 1.57 0.9 None
    10 2.3 3.14 0.9 None
    20 2.6 6.28 0.35 None

    That sweeps the camera one full circle (θ goes 0 → 6.28, which is 2π, one turn), rising up over the top (φ climbs then settles) and pushing in a little at the far side.

  6. Click Play. The live window flies the orbit and loops. Click Stop to halt it.

  7. Click Save. Your Scene is now in the library, ready to export.

That is the whole loop. Everything below is refinement.

Tip

Not sure what numbers to type? Load the built-in "Mandelbulb Orbit" Scene and read its camera keys — it is exactly this orbit, hand-tuned. Copy it, rename it, and tweak.

Understanding the camera: distance, θ, φ

The 3-D fractals are viewed with an orbit camera — imagine the fractal floating at the centre of a globe and the camera riding on the globe's surface, always looking inward at the centre. Three numbers place the camera:

  • Distance — how far the camera sits from the centre. Smaller = closer = the fractal fills more of the frame (a dolly in). Larger = further away.
  • θ (theta) — the azimuth: how far around the globe, measured in radians. 0 is the front, 1.57 (≈ π/2) is a quarter-turn, 3.14 (≈ π) is the back, 6.28 (≈ 2π) is all the way around to the front again.
  • φ (phi) — the elevation: how far up or down. Small values look from near the equator; larger values climb toward the top pole.

Note

Radians, not degrees. One full turn is 2π ≈ 6.283. Handy values: quarter-turn 1.571, half-turn 3.142, three-quarter 4.712, full turn 6.283. Want two full turns? Use 12.566. The camera follows your numbers literally — asking for θ = 12.566 really does orbit twice.

A camera track is just a list of these poses at different times, and the engine smoothly flies the camera through them.

Why an orbit can look like a spin (and how to fix it)

If you sweep only θ at a fixed distance and elevation, a centred, roughly symmetric fractal looks like it is spinning in place rather than the camera flying around it — there is nothing else in the frame to tell your eye which is moving. The cure is to also change φ (rise up and over) and distance (loom in) as you orbit. The parallax that creates reads unmistakably as the camera flying around a solid object. Every built-in orbit does this; copy the pattern.

Path shape: Linear, Catmull-Rom, Bezier

Each camera track has one interpolation setting that decides how the camera flies between your keys:

Setting Feel When to use
Linear constant speed, a slight jolt of direction at each key mechanical, deliberate moves
Catmull-Rom (default) smooth curved path that still passes exactly through every key almost everything — the natural cinematic choice
Bezier eases to a gentle stop at every key, then accelerates away shot-to-shot moves that pause on each pose

Catmull-Rom is the default and the right answer most of the time. It gives you a flowing path with no visible "corners" at the keyframes.

Tip

Catmull-Rom can overshoot slightly on a sharp change of direction — the camera bulges a hair past a key before curving back. Usually this looks great (it is how a real crane move behaves). If you need the camera to hit a pose dead-on with no overshoot, add an extra key just before it, or switch that track to Linear.

Per-key easing: accelerate and decelerate

Interpolation shapes the path in space; easing shapes the speed along it. Every camera key carries an Ease setting that controls how the camera accelerates out of that key toward the next one:

Ease Behaviour
None (default) steady speed across the segment
Ease In slow start, speeding up (accelerate out of the pose)
Ease Out fast start, slowing down (decelerate into the next pose)
Ease In-Out slow at both ends, quick in the middle — the classic "settle"

Because easing and path-shape are independent, you can combine them freely — a Catmull-Rom path with Ease In-Out keys glides and breathes.

Tip

A push-in that starts slow, accelerates, then eases to a stop feels far more expensive than a constant dolly. Set the first key to Ease In and the last key to Ease Out (or use Ease In-Out on both).

Transitions between shots

When a Scene has more than one shot, each shot (after the first) has a Transition that decides how it arrives:

Transition What it does Realtime preview Exported video
Cut instant switch on the next frame cut cut
Cross-fade one shot dissolves into the next cut dissolve
Light-sweep a soft-edged wipe sweeps left→right cut wipe
Param-morph the fractal's shape morphs from one shot into the next cut shape morph*

* Param-morph only morphs the shape when both shots are the same fractal type (so there is a shape to morph between). If the two shots are different types, it automatically falls back to a cross-fade in the export.

Each non-cut transition also has a length in seconds — how long the fade or wipe takes. It overlaps into the tail of the previous shot.

Important

Remember: every transition except Cut looks like a Cut in the live preview. The fades and wipes are drawn only when you Export. This is not a bug — it is how Fracturing Fog protects your machine (see below).

Per-shot tone-map

Each shot can pin its own HDR tone-map operator — the curve that squashes the bright, high-dynamic-range render down to something your screen can show:

Operator Character
(inherit) use whatever the shot's region already uses (default)
None clip highlights hard — punchy, can blow out
Reinhard gentle, rolls off highlights softly
Reinhard Extended Reinhard with a white point you can push
ACES filmic, cinematic contrast — a common "movie" look

Leave it on inherit unless you specifically want one shot to look different from its region's normal grade. This is a per-shot look decision, so it lives next to the region/theme pickers, not on a keyframe track.

Global tracks: changing the whole Scene at once

A global track keyframes one look-setting across the entire Scene, on top of whatever every shot is doing. It is sampled at global Scene time, so it sweeps continuously even across shot boundaries. Available targets:

Target What it controls
Exposure overall brightness before tone-mapping (1 = neutral, <1 darker, >1 brighter)
Bloom strength how much the bright parts glow
Bloom threshold how bright a pixel must be before it glows (lower = more glow)
Vignette darkening toward the frame edges (0 = none)
Chromatic aberration coloured-fringe lens look (0 = off)

Global tracks use the same keyframe/easing/interpolation vocabulary as the camera track — a list of (time, value, ease) keys with a path shape (default Linear, because a look-ramp usually wants a steady, predictable sweep).

The built-in "Exposure Ramp" Scene is the reference example: a Mandelbulb orbit that fades up out of near-black, over-exposes to a bright bloom, then falls back toward black — driven entirely by one Exposure global track.

Note

Where do I edit global tracks? The graphical global-track row is still on the polish list. Today you author them either by starting from the built-in "Exposure Ramp" Scene, or by hand-editing the Scene's JSON in the Asset Manager (global tracks round-trip as readable text — see Hand-editing scenes.json).

Playing, previewing, saving

The editor's buttons:

  • New — start a blank Scene.
  • Load — pull an existing Scene from the library into the editor.
  • Revert — throw away unsaved edits, reloading the saved version.
  • Save — write the Scene to your library (scenes.json).
  • Delete — remove the Scene from the library.
  • Preview (per shot) — apply just that one shot's region + theme + animation to the live view, so you can frame it. This is a single static framing, not sequenced playback.
  • Play — run the whole Scene live on the main window, cut-sequenced, and loop it. Stop halts it (so does closing the editor).
  • Export… — render the Scene to a video (see next section).

Exporting a Scene to video

Click Export… in the editor. You are offered a group of output knobs:

Knob Meaning Typical
Width / Height output resolution in pixels 1920 × 1080
FPS frames per second 30 (or 60 for silky motion)
Motion-blur sub-frames extra samples averaged per frame for motion blur (1 = off) 1, or 8–16 for blur
Encode video format preset h264hq

Choose an output file, and the app renders every frame to completion on a background thread — this is the offline path, so it is slower than realtime and that is expected. When it finishes you get the video, with all the cross-fades, wipes, morphs, and motion blur that the live preview could not show.

Note

No ffmpeg? Video encoding uses ffmpeg. If it is not installed, the export still succeeds — it keeps the rendered PNG frame sequence in the output folder and tells you so. Install ffmpeg and you can encode the folder later, or the app will encode automatically next time.

Motion blur, explained

With motion-blur sub-frames set above 1, each output frame is rendered several times at slightly different moments across the frame's duration and the results are averaged — exactly how a real camera's shutter smears fast motion. It is only affordable in the offline export (never in realtime), and it makes camera moves look dramatically more expensive. The shutter fraction (exposed in the headless CLI, default 0.5 ≈ a 180° film shutter) controls how far across each frame the samples are spread.

Tip

Motion blur costs render time linearly: 8 sub-frames means roughly 8× the work per frame. Author and preview with it off; turn it up only for the final export.

Rendering Scenes from the command line

Everything the Export… button does is also available headless, for batch jobs and scripting:

dotnet run --project FracturingFogCLD.csproj -c Release -- `
  --batch --mode scene --scene "Mandelbulb Orbit" `
  --fps 30 --motion-blur 8 --shutter 0.5 `
  --width 1920 --height 1080 --encode h264hq `
  --out Videos\mandelbulb-orbit.mp4
Flag Meaning
--scene NAME the saved Scene to render (from scenes.json)
--fps N output frame rate (default 30)
--motion-blur N accumulation motion-blur sub-frames, 1–64 (1 = off)
--shutter F open-shutter fraction 0 < F ≤ 1 (default 0.5)
--encode TYPE h264hq (default) · h264 (lossless) · ffv1 (lossless MKV)
--width / --height output resolution
--out PATH output file (or folder)
--keep-frames keep the intermediate PNG sequence after encoding

This is the same engine the GUI export uses, so the output is identical.

Using the example Scenes

Fracturing Fog ships four hand-authored example Scenes alongside this guide, each demonstrating one feature. They live in Docs/Examples/Scenes/ as importable files.

Example file Shows off
push-in-ease-demo.json a dolly-in with Ease In-Out keys
elevation-reveal.json a φ (elevation) sweep rising up over a Kleinian
transition-showcase.json Light-sweep + Cross-fade between shots (export to see them)
bloom-breath.json two global tracks — a bloom swell and a closing vignette

To use one:

  1. Open the Asset Manager → Scenes node.
  2. Use Import… and pick the example .json file, or hand-merge its contents into your scenes.json (see below).
  3. The Scene now appears in the editor's Load list. Load it, Play it, and read its shots and keys to learn the pattern.

See the examples index for a walkthrough of each.

Hand-editing scenes.json

Scenes are stored as human-readable JSON at:

%APPDATA%\FracturingFog\scenes.json

(On Windows that expands to something like C:\Users\<you>\AppData\Roaming\FracturingFog\scenes.json.) The file is a list of Scenes; every enum is written as a readable string ("Mandelbulb", "CatmullRom", "EaseInOut"), so you can safely edit it by hand. A minimal one-shot orbit looks like this:

[
  {
    "Name": "Hand-Edited Orbit",
    "Category": "User",
    "Description": "A single Mandelbulb orbit, authored by hand.",
    "Tags": [ "demo", "3D" ],
    "Shots": [
      {
        "Name": "Orbit",
        "RegionName": "",
        "FractalType": "Mandelbulb",
        "DurationSeconds": 20.0,
        "Transition": "Cut",
        "TransitionSeconds": 1.0,
        "Camera": {
          "Interpolation": "CatmullRom",
          "Keys": [
            { "Time": 0.0,  "State": { "Distance": 2.6, "Theta": 0.0,  "Phi": 0.35 }, "Ease": "None" },
            { "Time": 10.0, "State": { "Distance": 2.3, "Theta": 3.14, "Phi": 0.9  }, "Ease": "None" },
            { "Time": 20.0, "State": { "Distance": 2.6, "Theta": 6.28, "Phi": 0.35 }, "Ease": "None" }
          ]
        }
      }
    ]
  }
]

Warning

Edit scenes.json while the app is closed, or your changes may be overwritten when the app next saves. Keep a backup copy before large hand edits — a malformed file is skipped on load (you lose the custom Scenes in it, but the app still starts and the built-in demos still appear).

A note on resource use and speed tiers

Fracturing Fog is built to never crash your computer to draw a fractal. It aims to leave headroom — roughly a 90 % ceiling on processor and memory — and it watches itself while previewing. On a laptop it turns quality down to keep the window responsive; on a powerful desktop it deliberately uses more of the machine to look its best. Same target, opposite intent.

For Scene authoring, the two consequences you will actually feel are:

  1. Realtime preview cuts between shots (it will not run two 3-D fractals at once) — the fades appear in export.
  2. Preview may soften under load (lower resolution, fewer effects) to hold a smooth framerate. The export always renders at full quality regardless of your machine, just more slowly.

None of this needs configuration to author a Scene. If you want to bias the preview toward smoothness or fidelity, that lives in the app's performance settings, not the Scene Editor.

Troubleshooting

Symptom Likely cause & fix
Cross-fades look like cuts in preview Working as intended — export to see them.
No camera section on a shot The shot's fractal type is 2-D. Only the eight 3-D raymarch types (Mandelbulb, Mandelbox, KIFS, Quaternion Julia/Mandelbrot, Kleinian, Bicomplex, User Bulb) have an orbit camera.
Orbit looks like the object spinning in place Add φ (elevation) and distance changes to your keys, not just θ. See Why an orbit can look like a spin.
"This scene has no shots with a positive duration to play." Every shot has a duration of 0 (or less). Give at least one shot a positive Duration.
Camera whips around unexpectedly θ interpolates literally. A jump from 6.0 back to 0.1 unwinds a whole turn. Keep θ monotonic (always increasing) for a clean orbit.
Export produced PNGs but no MP4 ffmpeg is not installed. Install it, then re-encode the frame folder (or the app encodes next time).
A Scene's shot renders the "wrong" fractal The named region was renamed/deleted, so the shot fell back to a default. Re-point the shot's Region in the editor.

See also

Clone this wiki locally