PyroMetal Documentation

The real-time fire, smoke & explosion studio for macOS. GPU-accelerated volumetric simulation, cinematic rendering and game-ready export — all in one app.

Get Started Export Reference

What is PyroMetal?

PyroMetal is a native macOS application for designing volumetric fire, smoke and explosion effects in real time. It runs a full 3D fluid simulation on the GPU using Metal, renders it with a cinematic volumetric ray-marcher, and exports production-ready output for film, motion graphics and game engines.

Everything is interactive: drag an emitter around the scene, spin sliders while the sim runs, keyframe a burst, and watch the explosion evolve at once. When the look is right, export a seamless-looping MP4, a flipbook sprite sheet, a PNG channel stack or a VDB volume sequence for Blender and Houdini.

Requirements

• macOS on Apple Silicon (M-series). The simulator uses Metal compute and runs entirely on the GPU.
• No internet connection, accounts or plug-ins required. Projects are self-contained .mfsproj files.

How this documentation is organized

• Start Here — install-to-first-explosion in five minutes, plus a tour of the interface.
• Scene Building — every object type you can add: emitters, force fields, effectors, colliders, lights, meshes and materials.
• Simulation — the physics: solver settings, combustion, particles, and the animation timeline.
• Look & Output — rendering, color, post effects, cameras and the export pipeline.
• Reference — performance tuning, keyboard shortcuts, and answers to common questions.

Getting Started

From launch to your first explosion in five minutes.

The launch screen

PyroMetal opens on a project browser with two tabs:

• My Projects — your saved work, shown as thumbnail cards. Click a card to open it, right-click to delete. The New Project button on the right creates a fresh scene.
• Examples — a library of 40+ ready-made effects: explosions, campfires, rockets, fireworks, dragon breath, volcanoes, spell impacts and more. Examples open with autoplay enabled, so they start simulating immediately. They are full projects — open one, inspect how it is built, and tweak anything.

Your first fire

1. Click New Project. A default scene opens with one spherical emitter already burning.
2. Press Space to play or pause the simulation. Press R to reset it to the start.
3. Drag in the viewport to orbit the camera. The selected object shows a 3-axis gizmo — drag an arrow tip to move it along that axis.
4. With the emitter selected, open the Scene tab of the right panel and find the Emission group. Raise Temperature for a brighter, more buoyant flame; raise Smoke for thicker soot.
5. Switch to the Sim tab and enable Combustion if you want the full fuel-driven burning model (most examples use it).
6. Save with ⌘S. Projects live as .mfsproj files and keep everything: objects, keyframes, render settings and export settings.

Projects, saving and autosave

• File menu: New Project ⌘N · Open… ⌘O · Recent Projects · Save ⌘S · Save As… ⌘⇧S · Home ⌘⇧H.
• Autosave runs every 2 minutes for projects that have been saved at least once — you will see a toast notification when it fires.
• Thumbnails are captured automatically while you work and shown on the project cards.
• Undo / Redo (⌘Z / ⌘⇧Z) covers object add/delete/duplicate and preset changes.

The five-minute workflow

1. Block the scene — add emitters, forces and colliders from the shelf at the bottom of the viewport.
2. Shape the motion — tune buoyancy, vorticity and emitter outflow in the Sim tab while the sim runs live.
3. Animate — keyframe emission pulses on the timeline for bursts and explosions (see Animation).
4. Light & grade — set fire colors, environment and post effects in the Render tab.
5. Frame & export — compose the shot in the Render Camera tab, then export from the Export tab (see Export).

Interface Overview

A tour of every panel in the editor.

Top bar

• Tabs — Viewport (design view), Render Camera (framing view with safe zones) and Export (output settings).
• Transport — a single master ▶︎/⏸ button (Space) drives the simulation and the animation timeline together, locked to one clock. Step advances one sim step while paused; Reset (R) rewinds both sim and timeline.
• Home returns to the project browser.

Viewport

• Orbit by dragging, zoom with scroll/pinch, pan with secondary drag.
• Selection & gizmo — click an object handle to select it. A 3-axis translate gizmo appears: X (red), Y (green), Z (blue). Drag an arrow tip to move along a single axis; drag the center circle to move in the view plane.
• Focus — F frames the selected object, ⇧F frames the whole domain.
• Ground grid and collider wireframes can be toggled from the View menu.
• The white wireframe box is the simulation domain — the region where the fluid lives.
• The HUD shows FPS, grid resolution and the active solver mode.

Scene shelf

The shelf at the bottom of the viewport adds objects — click or drag-and-drop into the scene:

• Emitters: Sphere · Box · Cylinder · Mesh (import a 3D model, voxelized as a source) · Image (a PNG/JPEG emits smoke and fire in its own shape and colors).
• Forces: wind, vortex, turbulence and more — see Force Fields.
• Colliders: sphere, box, or an imported mesh that the smoke flows around.
• Lights: point and directional lights that illuminate the volume.

Inspector (right panel)

Four tabs at the top of the right panel:

Outliner

The Scene tab lists every object in the scene. Each row has, next to the object icon and name:

• Rename — double-click the name to edit it in place. Press Return to confirm, Esc to cancel.
• Lock 🔒 — a locked object cannot be moved in the viewport (its gizmo axes disappear and dragging is ignored). You can still select it and edit its parameters. Great for keeping a finished layout safe.
• Eye 👁 — enables/disables the object. A disabled object stops affecting the simulation.
• Delete 🗑 — removes the object along with its keyframe tracks (undoable with ⌘Z).

Timeline (bottom panel)

• Keyframe lanes for every animated parameter, with a draggable playhead.
• Lane / Curve toggle — Curve mode opens the curve editor with draggable points and per-key interpolation.
• The cache cluster — Bake (⌘B), progress, and the play-from-cache toggle. See Animation & Timeline.
• Panels are resizable — drag the divider between viewport and inspector, or viewport and timeline.

Menus

• File — project management and recents.
• Edit — undo/redo, duplicate.
• View — focus commands, ground grid, collider wireframes, bake commands.
• Presets — one-click fluid presets (campfire, explosion, smoke, torch) that set the global physics to a known-good starting point.
• Help — the built-in quick guide with shortcuts.

Emitters

Emitters are the sources of your effect — they inject smoke, heat, fuel and velocity into the simulation. Every parameter below lives in the emitter's properties card in the Scene tab.

Shapes

All shapes support full position, rotation and size Keyframable ◇ — rotate a box emitter to tilt its jet, or keyframe position for a flying fireball.

Emission

The master group controlling what the source injects. Everything here is keyframable with the ◇ button next to each slider.

Emission mode

Pressure

Extra pressure the source applies to its surroundings — the "push" of an explosion, independent of emission.

Motion & cycle

Per-emitter colors

• Use own colors — gives this emitter its own Smoke color and Fire tint, independent of the global ramp.
• Colors are carried by the fluid: they flow with the smoke and blend naturally where two differently-colored sources mix — a red and a blue flame swirling produce purple in between.

Per-emitter combustion

With Custom combustion settings enabled, this emitter's fuel burns with its own character, overriding the global model locally: Ignition, Burn rate, Heat and Soot. Example: one source burns clean and fast (high burn rate, low soot) while another smolders dirty (low rate, heavy soot) — in the same scene.

Emit light

The Emit light toggle makes the emitter glow as a real light source — the surrounding smoke is illuminated by the fire itself. Ideal for muzzle flashes and explosions at night.

Particle output

Each emitter carries its own complete spark/ember system — see the dedicated Particles chapter for every parameter.

Force Fields & Effectors

Force fields push the flow around; effectors modify the smoke, heat and color fields inside a region. Both are spherical zones with a position, radius and strength.

Common parameters

Force types

Effectors

Effectors don't push the flow — they alter the fields inside their radius:

Colliders

Solid obstacles the fluid flows around — and particles bounce off.

Shapes

• Sphere / Box — analytic shapes, freely rotatable. Size range 0.03 – 0.45.
• Mesh — import any 3D model; it is voxelized into a solid the smoke navigates around. The collision mask rebuilds automatically when you move, rotate or scale the object.

Parameters

Particles interact with colliders too: sparks land on and bounce off surfaces, respecting their friction and bounce values.

Lights

Scene lights illuminate the smoke volumetrically, with self-shadowing.

Kinds

Parameters

Up to 8 lights can shine at once. If the scene has none, a default key light (from the Render tab's light card) is used. Emitters can also glow themselves via Emit light — see Emitters.

Particles

Sparks, embers and debris — a GPU particle system holding up to one million particles, fully coupled with the fluid: particles ride the flow, deposit smoke trails back into it, and bounce off colliders. All settings are per-emitter: select an emitter and open its Particle output group.

Core settings

Launch

Emission style

How new particles are distributed at birth:

Bundle count 2 – 24 sets how many bundles or strands exist (visible for Clumped/Entangled). Particles spawn from the emitter's true shape — a rotated box emitter births sparks inside that rotated box.

Debris trails

One click and every particle leaves a real smoke/fire trail in the fluid as it flies — the trail is injected into the simulation and keeps evolving with it.

Death burst & fireworks

Conditional spawning

Behavior notes

• Particles only spawn while their emitter is emitting — keyframe Emission to 0 and the sparks stop with the fire.
• Colors follow the emitter's fire tint; sparks fade and cool over their lifetime.
• The Particles only (hide volume) toggle in the Render tab isolates the particle pass for inspection.
• Particles render additively into the HDR pipeline — they bloom naturally when bright.

Simulation & Combustion

The Sim tab drives the physics: the domain, the fluid parameters, and the combustion model.

Domain

Resolution

The voxel density of the simulation, chosen as voxels per world unit: 64³ (fast preview) · 128³ (balanced) · 256³ (finest live detail). The card shows an estimated memory figure.

Physics

Combustion

A realistic fuel-driven burning model. When enabled, emitters inject fuel instead of raw smoke; fuel that gets hot enough ignites, producing glowing flame, heat and soot. Regions that exhaust their fuel cool into dark smoke — this is where the natural fire→smoke transition comes from.

Individual emitters can override the burn character locally — see Emitters → Per-emitter combustion.

Solver

Rendering

PyroMetal renders the volume with a cinematic ray-marcher: blackbody fire emission, self-shadowed smoke scattering, HDR bloom and a full post-effects suite. Everything lives in the Render tab.

Core render quality

Coloring

• Fire ramp — four color stops (cold → hot) shape the entire flame palette, with a live gradient preview. Natural fire, green witch-flame, blue plasma: all just ramps.
• Smoke color — the global scatter tint of the smoke body.
• Emitters with Use own colors override both locally, and their colors advect with the flow (see Emitters).

Visual detail

Exposure, bloom & vignette

Post-effects suite

A full grading stack applied after tonemapping:

Lighting & shadows

Advanced scattering

Environment

• Sky / Ground colors + Ambient intensity 0 – 1.5 — a procedural environment that fills shadows with believable ambient light.
• Show as background — renders the environment gradient behind the effect.
• HDRI — load an equirectangular image (EXR/HDR/PNG/JPEG); it becomes a camera-tracked backdrop and drives the ambient tint automatically. One-click presets: Studio, Sunset, Night.
• Ground plane — a floor that receives the smoke's shadow, anchoring the effect to the ground.

Viewing aids

• Particles only (hide volume) — isolates the spark pass for inspection.
• TAA — temporal anti-aliasing smooths fine grain in the live viewport (viewport only; exports are already clean).

Cameras

Two cameras: a free viewport camera for working, and a render camera for framing the final shot.

Viewport camera

• Orbit / pan / zoom freely while you design; it never affects the export.
• F focuses the selected object; ⇧F frames the whole domain.

Render camera

The Render Camera tab shows exactly what will be exported, letterboxed to the export aspect ratio with composition overlays: action-safe (5%), title-safe (10%) and rule-of-thirds guides.

The render camera's position and orbit are keyframable — animate sweeping moves around the explosion on the timeline.

Animation & Timeline

Any parameter with a ◇ button is keyframable — global physics, render settings, and every per-object property.

Keyframing

• Click the ◇ next to a parameter to add a key at the current time. A lane appears on the timeline.
• Auto-Key — with it on, moving any keyable slider drops a key automatically.
• Keys: click to select, drag to move in time (and value, in curve mode), right-click to delete or change interpolation.

Interpolation modes

The Curve editor (Lane/Curve toggle on the timeline) graphs the animation with draggable points — fine-sculpt an emission pulse's exact shape.

Playback — one clock

• The single ▶︎/⏸ (Space) drives the simulation and the timeline, locked together: the timeline advances exactly one frame per sim step, so animation can never outrun physics.
• The timeline loops at its set duration; on each loop the simulation restarts identically, so every pass through the loop is the same — what you see is what exports.
• R resets both sim and playhead to zero.

Sim cache — bake & scrub

A live simulation can't be rewound — so bake it. Bake (⌘B or the timeline button) computes the whole timeline once and stores every frame in memory:

• Drag the playhead anywhere and that frame appears instantly — no re-simulation.
• When baking completes, Play From Cache turns on automatically (green ▣). Turn it off to return to the live sim.
• A green dot means the cache is current; orange means settings changed since the bake — hit ↻ to re-bake. The label shows frame count and memory use.
• The cache clears automatically if the grid or domain changes.

Meshes, Images & Materials

Bring your own geometry: meshes can emit, collide and render with full PBR materials; images become shaped emitters.

Mesh emitters

• Import a 3D model from the shelf (Emitter → Mesh). It is voxelized into an emission mask — smoke and fire pour off the model's actual shape.
• Textured models can emit in their surface colors — a painted statue burning in its own palette.
• Transform freely; the mask rebuilds automatically.

Image emitters

• Import a PNG/JPEG (Emitter → Image): the image's silhouette emits smoke/fire in the image's own colors — logos, text, sigils.
• Transparent pixels emit nothing; bright saturated pixels emit their color.

Mesh colliders

Import a model as a collider (Collider → Mesh): it is voxelized as a solid and the flow navigates around it — smoke rolling over a statue, fire licking around an engine block. See Colliders for friction/bounce.

Surface rendering & PBR materials

Imported meshes render as real surfaces in the beauty pass, shaded with a physically-based (Cook-Torrance) material and lit consistently with the volume. Open the Material Editor to edit:

• Hide in render keeps a mesh's simulation role (emit/collide) while hiding its surface.

Export

The Export tab renders your effect offline — at its own resolution, its own simulation grid, and in multiple formats and channels. Exports run in the background with a live frame filmstrip and can be cancelled at any time.

Formats

Resolution

• Output resolution — a dropdown of presets from 512² to 8K (720p, 1080p, square variants), plus Width/Height steppers for custom sizes. When your custom size doesn't match a preset, the dropdown reads "Custom".
• Simulation resolution — a separate dropdown (64³ – 1024³). Independent of the viewport: the export simulates at this grid while rendering. 512³/1024³ are export-only grids — design light, export heavy. If memory runs out you get a clear error, not a crash.
• Frame skip (stride) 1 – 10 — advance N sim steps per exported frame: faster apparent motion and shorter renders without changing the physics.

Background

Render channels

Each selected channel exports as a separate file/sequence:

Seamless loop

Loopable export crossfades the last frames into the first, producing a perfectly seamless cycle — essential for game flipbooks and looping ambience. Combine with a keyframed emission cycle for best results.

Running an export

• Exports run on a background renderer with its own solver — the app stays responsive.
• A live thumbnail filmstrip shows frames as they render.
• Cancel any time — partial video files are properly finalized or discarded.

Performance

PyroMetal is built to stay interactive. These are the levers, roughly in order of impact.

Grid resolution

The single biggest cost. 64³-class grids are ideal for design; 128³ balances detail and speed; 256³ is the finest live grid. The Resolution card shows an estimated memory figure as you change it. Because motion is resolution-consistent, you lose nothing by designing low and exporting high.

Optimizations (viewport / render separate)

Each row has two checkboxes — one for the live Viewport, one for the Render (export):

Display pipeline

Solver & shadows

• Multigrid pressure solving with 1–4 V-cycles — accurate and fast; more cycles only if you see pressure artifacts in extreme scenes.
• Sparse/Adaptive skips computing empty voxels — identical image, faster.
• Fast shadows bakes self-shadowing once per frame — the way to run multiple lights cheaply.
• Shadow steps / Step count — the render-side quality dials; drop them while designing, raise for finals.

Particles

• Particle count scales with per-emitter Density; the system holds up to 1M. Sparks are cheap — Trail size (radius) deposits are what cost, since each particle stamps volumetric material.
• Hide sparks costs nothing — hidden particles skip drawing entirely.

Memory

• The Sim tab's Resolution card estimates solver memory live.
• Export grids of 512³/1024³ allocate only during the export; if the GPU runs out of memory you get a clear error message, never a crash.
• The sim cache reports its exact size next to the timeline (frames × grid); clear it with 🗑 when you need headroom.

Keyboard Shortcuts

Everything on one page.

Playback

Project

Editing

Outliner gestures

Tips & FAQ

Answers to the questions everyone asks, and the habits of people who get great results fast.

Why does my fire keep burning after I set Smoke to 0?

Smoke (density) and fire (temperature) are separate fields. Setting Smoke to 0 stops the soot, not the heat. To silence a source completely, take the Emission master to 0 — it scales smoke, heat, outflow and particle spawning together, and what already exists disperses naturally.

My explosion looks like a rising plume, not a blast

• Set Blast to 1 — velocity fires radially from the center instead of upward.
• Add Emission noise ≈ 0.7 so the fireball breaks into lobes.
• Enable combustion and give it Expansion (blast shock) — ignition then pushes outward like a real detonation.
• Make the emission a pulse, not a constant: keyframe Emission 2.5 → 0 over ~0.4 s.

The effect looks different when I change resolution

It shouldn't — and by design it doesn't: PyroMetal normalizes motion, emission and dissipation across grid resolutions, so the same project keeps the same height, timing and silhouette at 64³ and 256³. What changes is the amount of fine detail. If you want more turbulent detail without touching resolution, raise Detail turbulence (sim) or Detail amount (render).

How do I make a perfect loop?

1. Keyframe your effect so emission returns to its starting value by the end of the timeline.
2. Playback already restarts the sim identically on every loop — check the seam live.
3. Export with Loopable export on: the tail crossfades into the head for a mathematically seamless cycle.

What's the fastest way to a specific effect?

Open the closest Example and read it like source code: check its emitter settings, its keyframe tracks, its combustion values. The library covers explosions (ground, air, chain, nuke), fires (campfire, wall, torch, wildfire), particles (fireworks, sparks, embers), atmospherics (fog, steam, sandstorm) and stylized looks (toon, magic).

Where do the game-engine exports fit?

• Flipbooks: Sprite Sheet export + Loopable. The JSON sidecar carries the atlas layout.
• Six-way lighting: the 6-Point Lighting channel exports the two packed maps UE/Unity six-way smoke materials expect (A: R/L/T + coverage · B: B/F/B + emissive).
• Motion vectors: enable the Motion Vectors channel for flipbook frame-blending — smooth playback from far fewer frames.
• VDB: full volumetric handoff to Blender/Houdini with density, temperature and color grids.

Habits of fast PyroMetal artists

• Design at 64³. Always. Export decides final quality, not the viewport.
• One Turbulence field in every scene; vary the Seed on pressure chaos so twin emitters don't sync.
• Use Bake (⌘B) the moment timing work starts — scrubbing beats replaying.
• Lock 🔒 finished layout objects so a stray drag can't move them.
• Duplicate an emitter (⌘D) and vary its seed/colors instead of building twins from scratch.
• Grade with the fire ramp first, post-FX second — the ramp does 80% of the look.