SMNTC

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.

The Problem

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.

Quick Start

Install

npm install smntc three

# JSR (Deno / Bun)
deno add jsr:@smntc/core

CDN (No Build)

<script type="module">
  import * as THREE from 'https://unpkg.com/[email protected]/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>

5 Lines to Topographic Waves

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);

React (React-Three-Fiber)

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>
  );
}

R3F Material Element

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>
  );
}

Web Component (No Framework)

<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>

CLI

npx smntc init       # Create smntc.config.json
npx smntc add hero   # Create a preset template
npx smntc preview    # Copy demo to smntc-preview/

Semantic Tokens

SMNTC replaces shader math with a Semantic Token Dictionary. You set intent, the engine resolves constants.

Surface (Visual Structure)

| 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 |

Vibe (Motion Character)

| 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 |

Reactivity (User Interaction)

| 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 |

Palette (Color Identity)

| 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 |

Fidelity (Rendering Quality)

| Token | Segments | Target | |---|---|---| | low | 64×64 | Mobile / low-power | | medium | 128×128 | Balanced default | | high | 256×256 | Desktop | | ultra | 512×512 | Presentation-grade |

API Reference

SMNTCKernel

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
});

Methods

| 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 |

React Components

// 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' });

Plugins & Presets

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' });

Architecture

┌─────────────────────────┐
│    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
└─────────────────────────┘

Key Engineering Decisions

• 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.

Performance Tips

• Fidelity first: Start with fidelity="medium" and only move to high/ultra when needed.
• Use auto-scaling: Keep thermalGuard: true and allow the auto-scaler to protect FPS.
• Wireframe cost: wireframe: true looks 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.

Running the Demo

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

Templates & Playgrounds

• Vanilla starter: templates/vanilla (Vite + Three.js + SMNTC)
• StackBlitz: https://stackblitz.com/github/NAME0x0/SMNTC

Building from Source

npm install
npm run build        # Production build → dist/
npm run dev          # Watch mode
npm run typecheck    # Type-check without emitting

Project Structure

smntc/
├── 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.json               # JSON Schema for SMNTCConfig
├── 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

For LLMs

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.json | Machine-validatable JSON Schema for SMNTCConfig |

Token values are also exported as runtime constants for programmatic discovery:

import { SURFACES, VIBES, REACTIVITIES, FIDELITIES, PALETTES } from 'smntc';
// Each is a frozen readonly array of valid string values

Specification

See 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)

Contributing

See CONTRIBUTING.md for development setup, architecture overview, and the process for adding new semantic tokens.

License

MIT