Semantic Engine for Motion, Animation, and Numerical Topographic Interactivity & Composition
Abstracting WebGL complexity into a Tokenized Intent Schema.
A deterministic visual compiler that translates high-level semantic intent into low-level, hardware-optimized GLSL instructions.
Creating topographic/parametric wave animations for the web currently requires:
- Deep knowledge of GLSL shaders and trigonometry
- Manual Three.js scene setup (renderer, camera, lights, materials)
- Copy-pasting complex vertex shaders from Shadertoy and "hacking" them to fit
- Per-project performance tuning for mobile/desktop
SMNTC eliminates the math. You describe the meaning, the engine provides the motion.
npm install smntc three# JSR (Deno / Bun)
deno add jsr:@smntc/core<script type="module">
import * as THREE from 'https://unpkg.com/three@0.170.0/build/three.module.js';
import { SMNTCKernel } from 'https://unpkg.com/smntc/dist/index.mjs';
const geometry = new THREE.PlaneGeometry(4, 4, 128, 128);
const mesh = new THREE.Mesh(geometry);
// ...add to scene
const kernel = new SMNTCKernel({ surface: 'fluid', vibe: 'calm' });
kernel.apply(mesh, camera, renderer.domElement);
kernel.start(renderer, scene, camera);
</script><script src="https://unpkg.com/smntc/dist/web/index.iife.global.js"></script>
<smntc-surface style="width:100%;height:60vh;display:block" surface="topographic"></smntc-surface>import { SMNTCKernel } from 'smntc';
import * as THREE from 'three';
// Your existing Three.js mesh (plane, sphere, torus, imported .glb — anything)
const geometry = new THREE.PlaneGeometry(4, 4, 128, 128);
const mesh = new THREE.Mesh(geometry);
scene.add(mesh);
// Apply SMNTC — done.
const kernel = new SMNTCKernel({ surface: 'fluid', vibe: 'calm', palette: 'monochrome' });
kernel.apply(mesh, camera, renderer.domElement);
kernel.start(renderer, scene, camera);import { Canvas } from '@react-three/fiber';
import { SMNTCSurface } from 'smntc/react';
function App() {
return (
<Canvas>
<SMNTCSurface
surface="topographic"
vibe="calm"
reactivity="magnetic"
palette="arctic"
/>
</Canvas>
);
}import React from 'react';
import { Canvas, extend, useFrame } from '@react-three/fiber';
import { SMNTCMaterial } from 'smntc';
extend({ SMNTCMaterial });
function Scene() {
const materialRef = React.useRef<SMNTCMaterial>(null);
useFrame((_state, delta) => {
materialRef.current?.update(delta);
});
return (
<mesh>
<planeGeometry args={[1, 1, 128, 128]} />
<smntcMaterial
ref={materialRef}
surface="fluid"
vibe="calm"
palette="arctic"
/>
</mesh>
);
}<script type="module">
import 'https://unpkg.com/smntc/dist/web/index.mjs';
</script>
<smntc-surface
style="width: 100%; height: 60vh; display: block;"
surface="topographic"
vibe="calm"
palette="monochrome"
reactivity="magnetic"
></smntc-surface>npx smntc init # Create smntc.config.json
npx smntc add hero # Create a preset template
npx smntc preview # Copy demo to smntc-preview/
npx smntc export css # Generate CSS + SVG filter defs from config
npx smntc export video-template # Write browser video export template
npx smntc export static-template # Write browser static export templateSMNTC replaces shader math with a Semantic Token Dictionary. You set intent, the engine resolves constants.
| Token | Effect |
|---|---|
topographic |
Parallel contour lines — layered sine displacement |
crystalline |
Sharp, faceted clustering — Voronoi noise |
fluid |
Organic, continuous flow — Simplex noise |
glitch |
Step-function displacement — quantized random |
organic |
Domain-warped simplex — slow fractal warping |
terrain |
Ridged multi-fractal — mountain-like ridgelines |
plasma |
Animated FBM — swirling energy fields |
wave |
Multi-directional Gerstner — ocean wave simulation |
| Token | Character |
|---|---|
stable |
Near-static; subtle breathing |
calm |
Slow, rhythmic oscillation |
agitated |
High-frequency, erratic shifts |
chaotic |
Stochastic vertex bursts |
breathing |
Ultra-slow inhale/exhale pulse |
pulse |
Rhythmic beating — heartbeat cadence |
drift |
Gentle lateral movement — wind-like |
storm |
Intense turbulence — wind and rain |
cinematic |
Slow sweeping motion — film-grade |
| Token | Behavior |
|---|---|
static |
No response to external inputs |
magnetic |
Surface pulls toward cursor |
repel |
Surface pushes away from cursor |
shockwave |
Click triggers a radial ripple |
| Token | Aesthetic |
|---|---|
monochrome |
White on black — classic tech |
ember |
Warm orange/amber |
arctic |
Cool blue/white |
neon |
Cyberpunk green/magenta |
phantom |
Muted grey-purple stealth |
ocean |
Deep blue/teal — underwater |
sunset |
Orange-pink horizon gradient |
matrix |
Terminal green on black |
vapor |
Vaporwave pink/cyan pastels |
gold |
Luxury gold/bronze |
infrared |
Thermal imaging red/yellow |
aurora |
Northern lights green/purple |
midnight |
Deep indigo/violet |
| Token | Segments | Target |
|---|---|---|
low |
64×64 | Mobile / low-power |
medium |
128×128 | Balanced default |
high |
256×256 | Desktop |
ultra |
512×512 | Presentation-grade |
The core engine class.
const kernel = new SMNTCKernel({
surface: 'topographic', // Visual structure
vibe: 'calm', // Motion character
reactivity: 'magnetic', // Cursor interaction
fidelity: 'high', // Vertex density
palette: 'monochrome', // Color scheme
wireframe: true, // Wireframe rendering
intensity: 1.0, // Amplitude multiplier [0-2]
speed: 1.0, // Speed multiplier [0-5]
contourLines: 16, // Contour line count [4-64]
angle: 0, // Displacement rotation [0-360°]
grain: 0, // Film grain intensity [0-1]
glow: 0, // Bloom / glow strength [0-2]
chromatic: 0, // Chromatic aberration [0-1]
vignette: 0, // Edge darkening [0-1]
blur: 0, // Depth blur simulation [0-1]
thermalGuard: true, // Pause animation when tab hidden
});Canonical v2 config (SMNTCConfigV2) also supports source, pattern, and layers:
const configV2 = {
surface: 'fluid',
vibe: 'calm',
palette: 'arctic',
pattern: { type: 'hexagon', scale: 6, weight: 0.25, opacity: 0.35 },
source: { type: 'text', content: 'SMNTC', font: '/fonts/inter.ttf', extrude: 0.1, segments: 24 },
layers: [
{
opacity: 0.35,
blend: 'screen',
animation: { palette: 'ember', pattern: { type: 'waves', weight: 0.3 } },
},
],
};| Method | Description |
|---|---|
apply(mesh, camera?, domElement?) |
Inject SMNTC material onto a Three.js mesh |
start(renderer?, scene?, camera?) |
Start self-managed animation loop (or call update() manually) |
stop() |
Stop the animation loop |
update() |
Advance one frame (call in your own rAF loop) |
setVibe(vibe) |
Spring-interpolated vibe transition |
setSurface(surface) |
Switch surface mode |
setReactivity(reactivity) |
Change interaction model |
setPalette(palette) |
Spring-interpolated color transition |
setIntensity(n) |
Set amplitude multiplier |
setSpeed(n) |
Set speed multiplier |
setAngle(n) |
Set displacement rotation angle |
setGrain(n) |
Set film grain intensity |
setGlow(n) |
Set bloom/glow strength |
setChromatic(n) |
Set chromatic aberration |
setVignette(n) |
Set edge vignette darkness |
setBlur(n) |
Set depth blur simulation |
configure(config) |
Bulk-update any config properties |
getMaterial() |
Access the underlying ShaderMaterial |
getBackgroundColor() |
Get palette background as THREE.Color |
dispose() |
Release all GPU and DOM resources |
// Declarative surface — handles geometry, material, and animation loop
<SMNTCSurface
geometry="plane" // 'plane' | 'sphere' | 'torus'
surface="fluid"
vibe="calm"
reactivity="magnetic"
palette="monochrome"
scale={[4, 4, 4]}
position={[0, 0, 0]}
rotation={[-Math.PI/2, 0, 0]}
/>// Hook — for custom mesh control
const kernel = useSMNTC({ surface: 'fluid', vibe: 'calm' });Extend SMNTC at runtime by registering new token definitions or presets.
import { defineSurface, definePreset, applyPreset } from 'smntc';
defineSurface('aurora', { mode: 4, noiseScale: 1.8 });
const corporate = definePreset({
name: 'corporate',
defaults: { surface: 'topographic', vibe: 'stable', palette: 'monochrome' },
allowedSurfaces: ['topographic', 'fluid'],
});
const config = applyPreset(corporate, { vibe: 'calm' });┌─────────────────────────┐
│ Semantic Tokens │ Developer / LLM Input
│ { vibe: "agitated" } │ (JSON / React Props)
└───────────┬─────────────┘
│
▼
┌─────────────────────────┐
│ SMNTC-Translate │ Deterministic Lookup
│ Token → Constants │ "agitated" → ω=2.5, A=0.2
└───────────┬─────────────┘
│
▼
┌─────────────────────────┐
│ Spring Bank │ Damped Harmonic Oscillator
│ F = -k·x - c·v │ Smooth state transitions
└───────────┬─────────────┘
│
▼
┌─────────────────────────┐
│ SMNTC-Kernel │ GPU Uber-Shader
│ Vertex Displacement │ + Finite-Difference Normals
│ + Reactivity Proxy │ + Performance Auto-Scaler
└─────────────────────────┘
- Spring Physics: All state transitions use a damped harmonic oscillator (F = -kx - cv). No direct value mutation. Every "vibe" or "palette" change feels physically earned.
- Finite-Difference Normals: Displacing vertices breaks lighting. The shader recalculates normals using finite differences, ensuring correct specular/diffuse even on moving waves.
- Uber-Shader: All 8 surface modes compile into a single shader with branching. One draw call, O(1) overhead regardless of mode.
- Post-Processing Pipeline: Film grain, glow/bloom, chromatic aberration, vignette, and depth blur — all in-shader, no extra render passes.
- Thermal Guard: Animation pauses on
visibilitychange— zero battery drain on background tabs. - Auto-Scaler: Monitors frame delta and automatically downgrades fidelity to maintain 60 FPS.
- Fidelity first: Start with
fidelity="medium"and only move tohigh/ultrawhen needed. - Use auto-scaling: Keep
thermalGuard: trueand allow the auto-scaler to protect FPS. - Wireframe cost:
wireframe: truelooks great but is more expensive; disable for dense scenes. - Manual loop: For advanced scenes, call
kernel.update()in your own render loop for tighter control. - Static mode: Set
reactivity="static"when interactivity is not needed.
Open examples/basic/index.html in any browser. No build step required — loads Three.js from CDN.
Also available: examples/hero/, examples/ambient/, examples/product/, examples/web-component/, examples/cinema4d/, examples/aftereffects/, examples/generative/.
# Or serve locally:
npx serve examples/basic- Vanilla starter:
templates/vanilla(Vite + Three.js + SMNTC) - StackBlitz: https://stackblitz.com/github/NAME0x0/SMNTC
npm install
npm run build # Production build → dist/
npm run dev # Watch mode
npm run typecheck # Type-check without emittingsmntc/
├── src/
│ ├── index.ts # Public barrel export
│ ├── kernel/
│ │ ├── SMNTCKernel.ts # Core orchestrator class
│ │ ├── uniforms.ts # Uniform bridge (TS → GLSL)
│ │ └── shaders/
│ │ ├── uber.vert.ts # Vertex shader (GLSL as TS string)
│ │ └── uber.frag.ts # Fragment shader
│ ├── semantic/
│ │ ├── tokens.ts # Type definitions + const arrays
│ │ ├── dictionary.ts # Token → constant mapping
│ │ ├── registry.ts # Token registry + presets
│ │ └── transformer.ts # Semantic middleware
│ ├── physics/
│ │ └── spring.ts # Damped harmonic oscillator
│ ├── material/
│ │ └── SMNTCMaterial.ts # ShaderMaterial subclass
│ ├── reactivity/
│ │ └── input-proxy.ts # Pointer/touch capture
│ ├── performance/
│ │ └── auto-scaler.ts # Adaptive LOD controller
│ ├── web/
│ │ ├── SMNTCSurfaceElement.ts # Web Component implementation
│ │ └── index.ts # Web Component entry
│ └── react/
│ ├── index.ts # React barrel export
│ ├── useSMNTC.ts # Hook
│ ├── useSMNTCMaterial.ts # Material hook
│ └── SMNTCSurface.ts # Declarative component
├── examples/
│ ├── basic/
│ │ └── index.html # Zero-build-step demo
│ ├── hero/
│ │ └── index.html # Hero background demo
│ ├── ambient/
│ │ └── index.html # Calm dashboard demo
│ ├── product/
│ │ └── index.html # Palette-switching demo
│ ├── web-component/
│ │ └── index.html # <smntc-surface> demo
│ ├── cinema4d/
│ │ └── index.html # C4D/Octane-inspired viewport
│ ├── aftereffects/
│ │ └── index.html # NLE-style compositor
│ └── generative/
│ └── index.html # Generative art playground
├── templates/
│ └── vanilla/ # Vite + Three + SMNTC starter
├── src/cli/ # CLI entry
├── .github/
│ ├── workflows/ci.yml # GitHub Actions CI
│ ├── workflows/release.yml # Publish + GitHub Release
│ └── FUNDING.yml # GitHub Sponsors
│ └── ISSUE_TEMPLATE/ # Bug & feature templates
├── SMNTC-SPEC.md # Technical specification
├── SECURITY.md # Security policy
├── CODE_OF_CONDUCT.md # Community guidelines
├── llms.txt # LLM context (concise)
├── llms-full.txt # LLM context (complete)
├── smntc.schema.v2.json # Canonical JSON Schema for SMNTCConfigV2
├── smntc.schema.json # Legacy v1 schema (compatibility)
├── jsr.json # JSR registry config
├── stackblitz.json # StackBlitz playground config
├── CHANGELOG.md # Release changelog
├── CONTRIBUTING.md # Contribution guide
├── LICENSE # MIT License
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md
SMNTC is designed to be consumed by both humans and language models. The following files are optimized for LLM context injection:
| File | Purpose |
|---|---|
llms.txt |
Concise context — enough to generate correct SMNTC code |
llms-full.txt |
Complete API surface, all valid tokens, patterns, and gotchas |
smntc.schema.v2.json |
Canonical machine-validatable schema for SMNTCConfigV2 |
smntc.schema.json |
Legacy v1 schema for compatibility/migration |
Token values are also exported as runtime constants for programmatic discovery:
import {
SURFACES,
VIBES,
REACTIVITIES,
FIDELITIES,
PALETTES,
PATTERNS,
PATTERN_BLENDS,
LAYER_BLEND_MODES,
} from 'smntc';
// Each is a frozen readonly array of valid string valuesSee SMNTC-SPEC.md for the full technical specification including:
- Complete semantic token dictionary with mathematical mappings
- Spring physics model and transition rules
- Hardware constraints and performance budgets
- Hardening measures (Z-fighting, float overflow, Moiré, thermal throttling)
See CONTRIBUTING.md for development setup, architecture overview, and the process for adding new semantic tokens.