Particles

particles is the most parameter-heavy built-in object type. It covers two different modes:

emitter-style motion
instanced layouts and model-backed distributions

If the goal is a field, swarm, morph, or distributed silhouette rather than one solid mesh, particles is usually the right object.

When to use it

Use particles when:

motion is procedural rather than skeletal
the shape should disperse, gather, or morph
you want an instanced cloud driven by a model or primitive distribution
a single mesh would feel too rigid

Runtime contract

Activation

HTML

<div string="3d" string-3d="particles"></div>

Core CSS variables

--particles-mode
--particles-count
--particles-size
--particles-color
--particles-opacity
--particles-spread
--emit-rate
--emit-burst
--particle-life
--particle-speed
--particle-direction
--particle-gravity
--instance-shape
--instance-model
--instance-scale
--instance-scale-variation
--instance-rotation-speed
--instance-jitter
--instance-flow
--instance-disperse
--instance-scatter

Instanced model example

HTML

<div
  string="3d"
  string-3d="particles"
  style="
    width: 65%;
    aspect-ratio: 2.5 / 1;
    --particles-mode: instanced;
    --particles-count: 4000;
    --particles-fit: 1;
    --instance-shape: model;
    --instance-model: 'https://hls.penev.tech/blasters/blaster-a.glb';
    transition:
      --instance-model 0.8s ease,
      --rotate-y 1.2s cubic-bezier(.16, 1, .3, 1);
  "
></div>

TypeScript

import * as THREE from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { String3D, ThreeJSProvider } from 'string-tune-3d';

String3D.setProvider(new ThreeJSProvider(THREE, { gltf: GLTFLoader }));

Emitter example

HTML

<div
  string="3d"
  string-3d="particles"
  style="
    width: 320px;
    height: 320px;
    --particles-mode: emitter;
    --particles-count: 220;
    --particles-size: 4;
    --particles-color: #ff6b2b;
    --particles-spread: 140;
    --emit-rate: 36;
    --particle-life: 2.2;
    --particle-speed: 40;
  "
></div>

What the runtime does

In emitter mode, the particle system updates state every frame.
In instanced mode, the runtime distributes instances from a primitive or imported model geometry.
The synchronizer reads particle config from computed styles, not from a separate imperative particle API.
Model morph timing is keyed off the CSS transition declared for --instance-model.

Practical note

If the particles are meant to describe a recognizable silhouette, start with instanced mode. If the particles are meant to describe energy, atmosphere, or flow, start with emitter mode.