A real-time visualization tool built in Godot 4.6 (Forward+) for creating low-poly meshes, GPU particle flow fields, crumpled-cloth surfaces, and interactive influence fields. Everything is procedural and driven from a live parameter panel, so you can sculpt a scene, tweak it in real time, and export stills or image sequences.
 Petal Storm — a heavily displaced, bloom-lit mesh |
 Dye Pool — an interactive reaction-diffusion field you paint into |
 PolyCloth — a domain-warped drape with punched holes |
 Music Sphere — an audio-reactive mesh in a bass-reactive spark aura |
Screenshots live in
docs/screenshots/— see the manifest there for the expected filenames.
- Procedural visualizations, each fully parameterized in a side panel:
- PolyMesh — displaced low-poly icosphere with solid / wireframe / lattice render modes, colormaps, rim light, posterize, and LOD.
- PolyParticles —
GPUParticles3Dcurl-noise flow field with multiple emitter and particle shapes, color palettes, and an auto-budget mode. - PolyCloth — sprawling domain-warped cloth sheet that folds, drapes, varies its crumple height, bends into 3D forms, and can be punched with holes.
- Influence — movable attract/repel field that dents meshes and cloth and steers particles; can follow the mouse or an OptiTrack rigid body.
- Live parameter panel — every control is generated from each object's schema, with undo/redo, collapsible sections, and a fullscreen clean view.
- Built-in presets — load a complete scene from the dropdown (see below).
- Save / load compositions to JSON, and duplicate objects.
- Capture — screenshots (with optional 2× upscale) and PNG image-sequence recording, with an optional HUD logo watermark.
- OptiTrack / NatNet motion-capture input (Windows, via the bundled plugin).
- Godot Engine 4.6 (Forward+ renderer).
- No external dependencies — the OptiTrack plugin is bundled under
addons/.
The OptiTrack GDExtension ships a Windows x86_64 debug DLL only, so live motion-capture streaming works when running from the editor on Windows. The rest of the app runs on any platform Godot 4.6 supports — OptiTrack features simply no-op when the plugin or a Motive connection is unavailable.
- Clone the repository:
git clone https://github.com/<your-org>/Poly-Vis.git
- Open in Godot — launch Godot 4.6, click Import, and select the
project.godotfile in the project root. - Run the project (F5).
scenes/Main.tscnis the main scene. - Use the panel on the right to add objects, load a preset, and tweak parameters. Orbit the camera with the middle mouse button.
To try a complete scene immediately, pick one from the Presets… dropdown at the top of the panel.
| Action | Control |
|---|---|
| Orbit (yaw / pitch) | Middle-drag |
| Pan the target | Shift + middle-drag |
| Zoom | Scroll wheel |
| Drag the selected influence | Left-drag |
| Key | Action |
|---|---|
| Tab | Cycle object selection |
| 1–9 | Select object by index |
| F | Focus camera on the selected object |
| Space | Toggle animation on the selected mesh |
| H | Hide / show the parameter panel |
| F11 | Fullscreen clean view (hide all options) |
| Delete / Backspace | Remove the selected object |
| Ctrl+D | Duplicate the selected object |
| Ctrl+S | Save composition |
| Ctrl+Z / Ctrl+Shift+Z | Undo / redo |
The right-docked panel drives the whole app, top to bottom:
- Object selector + add (
+ Mesh,+ Pts,+ Cloth,+ Inf) / remove. - Presets / Save / Load / Duplicate.
- Capture / Record with a frame-rate selector.
- Global modules — camera, scene environment (background color / animated noise / loaded skybox / aurora sky + bloom), HUD logo, selection ring, and LED wall (physical size + resolution for real-world mapping).
- Per-object controls for the currently selected object.
The ⛶ button (or F11) collapses the panel to a corner chip and fullscreens the window for a clean, presentation-ready view.
Pick any of these from the Presets… dropdown:
| Preset | What it shows |
|---|---|
| Default | A single displaced PolyMesh |
| Neon Rain | Layered particle rain + spark fountain in a dark bloom-lit room |
| Muted Rain | Neon Rain with finer, denser particles and a dusty desaturated palette |
| Petal Storm | Animated, heavily displaced mesh |
| Draped Silk | Calm two-tone cloth drape (pink + periwinkle) |
| Sculpted Drape | Dramatic crumpled, flowing cloth with holes |
| Glacier Drape | Calm cloth drape (teal + amber) |
| Dune Drape | Wide low cloth sheet (purple-yellow + blue) |
| Crystal Lattice | Metallic wireframe-lattice mesh |
| Lava Flow | Glowing posterized mesh + ember particles |
| Aurora | Turbulent green-teal particle field over an animated aurora night sky |
| Void Sphere | Dark rim-lit mesh with a repel influence |
- Capture / 2× save a PNG screenshot (UI hidden) to the project's
user://directory. - ● Rec writes a numbered PNG sequence to
user://sequence_*/. Encode it to video with ffmpeg, e.g.:ffmpeg -r 24 -i frame_%05d.png -c:v libx264 output.mp4
The HUD logo (configured under the panel's HUD Logo section) stays visible in captures as a watermark.
An Influence object can be driven by an OptiTrack rigid body streamed from Motive over NatNet. In the influence's OptiTrack panel section:
- Set the Server IP (Motive host) and Client IP (this machine), and choose multicast or unicast.
- Click Connect / Reconnect.
- Enable Track Rigid Body and set the Rigid Body Asset ID to a streamed asset.
- Optionally enable Project to View to lock the tracked position to the current camera view (screen-space with fixed depth), or Map to Wall to map the object's physical position onto the LED wall (see below).
Connection settings save and load with the composition. The editor's OptiTrack
dock and addons/optitrack_plugin/optitrack_settings.tres are an alternative
place to configure the connection.
For installations that render onto an LED wall with a tracked object moving in front of it, the panel's LED Wall section describes the wall so real-world positions map correctly:
- Physical width / height — the wall's real size in metres.
- Pixel width / height — the wall's native resolution. Apply Resolution to Window resizes the app window to match. Fit to Current Monitor instead fills whichever monitor the window is on (borderless fullscreen, rendered 1:1).
- Origin — the wall's physical centre in the OptiTrack coordinate space.
With an influence set to Track Rigid Body + Map to Wall, the tracked object's metres are converted to a wall pixel and then onto the view, so the influence acts exactly where the object is in front of the wall. The wall settings save and load with the composition.
scripts/ GDScript source — one class per file
shaders/ GLSL shaders — one per visual system
scenes/ Main.tscn (app), ParticleDemo.tscn (standalone demo)
resources/ Bundled assets (HUD logos, etc.)
addons/ Third-party plugins (optitrack_plugin)
CLAUDE.md Architecture reference / developer docs
For a deep dive into the architecture — class responsibilities, the shader uniform conventions, the serialization format, and how to add a new visualization type or parameter — see CLAUDE.md.