Put a Three.js landing ring at a world position

Disclosure: This article and demo were generated by an AI coding agent for a NixieFX marketing task. The scene is a synthetic runtime fixture. Review the technical details in your own scene before production use.

A teleport landing cue should stay attached to its world location as the camera moves. Its radius should also follow the scene's scale. A screen overlay can look convincing in one screenshot while failing both conditions.

This example uses an exported particle burst on the XZ plane, positioned at [1, 0.04, -0.5]. The host offers three cameras and three uniform scales so those assumptions can be checked directly. It implements the cue, not teleport movement or collision detection.

Caption: Actual local browser capture at scale one. The floor grid and center marker are host geometry.

Author a ring that matches the coordinate convention

The landing-ring effect targets three-world-3d. One burst emits forty particles, with a maximum capacity of forty-eight and a lifetime of 0.85 seconds. Continuous emission is zero. The spawn shape is circle, radius one, with radius thickness zero.

In the pinned runtime, circle emission lies in local XZ. The supplied definition leaves spawn rotation at zero; no quarter-turn is needed to put it on the floor. Initial vertical velocity is 0.08 units per second. The particles are small unlit cyan billboards with depth testing enabled and depth writing disabled.

The project uses NixieFX 0.1.17 and Three.js 0.185.1. Do not assume another version or backend interprets every setting identically. The export's support report is part of the integration input.

Load the compiled effect

The supplied src/bundle.js imports the compiled manifest and exported effects, builds an effectsByPath map, and calls the official loader. It requires the three3d backend and the requested effect ID before returning the definition.

const bundle = loadVfxExportBundle(
  { manifest, effectsByPath },
  { requiredBackend: 'three3d', requiredEffectIds: ['landing-ring'] }
);
const effect = bundle.effectsById.get('landing-ring');

The loader consumes compiled export envelopes. An authoring file and a compiled effect are different inputs. This asset uses the built-in procedural billboard, so it needs no texture provider.

Place and replay one instance

The host already has a scene, camera, and renderer. It creates one VFX renderer and replaces the previous instance before replay:

const vfx = new ThreeVfxRenderer({
  scene, camera, captureDebugTransforms: true
});
let instance;

function replay(scale) {
  if (instance) vfx.removeEffect(instance, true);
  instance = vfx.createEffect(effect, {
    position: [1, 0.04, -0.5],
    scale: [scale, scale, scale],
    seed: 42
  });
}

Advance vfx.update(deltaSeconds) once per host frame, then render the scene. The fixture caps individual steps at 0.05 seconds and skips simulation while the document is hidden. These are host choices, not a guarantee about simulation time during backgrounding.

The 0.04-unit offset is chosen for this floor and marker. A real landing surface may need a different offset, surface orientation, or slope handling. The example does not solve placement on arbitrary terrain.

Measure rendered scale in world space

The local check exposed a useful distinction: getParticleDebugTransforms() reports sample positions before the instance root's scale. Comparing those positions directly with a desired world radius gives the wrong measurement.

For the actual rendered centers, the fixture takes each debug matrix's translation and applies the instance root's world matrix:

const positions = instance.getParticleDebugTransforms().map(t =>
  new THREE.Vector3()
    .setFromMatrixPosition(new THREE.Matrix4().fromArray(t.matrix))
    .applyMatrix4(instance.root.matrixWorld)
    .toArray()
);

This runs after rendering has updated the world matrices. Debug capture is useful for this diagnostic and can be disabled in production. The check measures distance from the known center in XZ; it does not infer a radius from the apparent size of a billboard on screen.

Check camera, scale, and completion separately

The browser verification covered oblique, top, and low cameras at uniform scales 0.5, 1, and 2, at viewport widths of 1280 and 390 pixels. Each of the eighteen cases recorded forty active particles during the burst. The largest measured radius error was below 0.000001 world units.

After waiting for completion, the active count reached zero. The runtime reported no unsupported features, missing meshes, or missing materials. These observations establish the fixture's placement and lifecycle checks; they are not a GPU timing benchmark or a guarantee of legibility in a production scene.

Inspect the supplied camera screenshots too. The low view compresses the ring's projected footprint, and the top view exposes its distribution. Random positions around a circle do not produce evenly spaced segments, and camera-facing billboards do not form a solid ground decal.

Keep the cue's limits visible

There is no teleport controller, navmesh query, collision response, terrain projection, or light emitted onto the floor. The effect does not write depth, and it uses no bloom postprocessing. PixiJS does not provide the same GPU depth-buffer behavior as this Three.js host.

For a visual particle editor for three.js, the integration decision belongs in the real scene. The NixieFX Three.js runtime reference covers bundle loading and instance transforms used here.

The complete Day 9 source includes the authoring definition, compiled output, host code, and verification script. Open ?mode=ring, change cameras and scales, and replay. On teardown the host cancels animation, disconnects resizing, destroys VFX resources, and disposes its own geometry and materials.

Open the working demo and download the complete source.