Define a path with a spline

quick start Beginner ⏱ 5 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• Declare a spline path in a scene (entity `spline` field)
• Understand that a spline is a runtime curve for path-following
• Move an object along the curve with getPointAt

What you'll build: A CatmullRom spline path with a marker riding the curve.

Walkthrough — Define a path with a spline · generated by site/media/lessons/learn-scenefeats.lesson.ts (5 steps)

A spline is a smooth path through control points. You declare it on an entity’s spline field; the engine builds a Three.js CatmullRomCurve3 and stashes it (in userData.splineCurve) for gameplay to follow. This scene defines a closed spline and a small component rides a marker along it.

Follow along in the live web editor

▶ Open the splines scene — every step below (including Play) runs right in your browser, no install required.

Steps

1. Open the scene. The scene is already open — if you followed the link above, the splines scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/learn-splines npm run dev): the Path entity has a spline with six control points.

   

   A Path entity with a CatmullRom spline.

2. Enter play — the path renders and a marker rides it. A small SplineFollow component reads the curve, draws it as a line, and moves a gold marker along it.

   

   The CatmullRom curve, drawn as a line with a marker.

3. The marker follows the spline around the loop. curve.getPointAt(t) gives an evenly-spaced point at fraction t — increment t each frame and the marker traces the path.

   

   getPointAt(t) walks the marker along the curve.

4. It keeps tracing the closed path. With closed: true the curve loops seamlessly.

   

   A closed spline loops forever.

5. Stop play mode.

// learn-splines.vscn.json — the Path entity
"spline": { "curveType": "catmullrom", "closed": true,
  "points": [[-5,0,-3],[-2,1.5,3],[3,0,3],[5,2,-2],[1,1,-4],[-3,0.5,-1]] }

Splines are data, not visuals

At runtime a spline is just a curve in userData.splineCurve — the engine doesn’t draw it for you (the editor shows an authoring gizmo). Gameplay code reads the curve to move things, aim cameras, or lay out objects. Here SplineFollow both draws the line and rides the marker.

Recap

New functionality

• Declared a spline path in a scene
• Moved a marker along the curve

New concepts & skills

• A spline is an entity `spline` field → a THREE CatmullRomCurve3
• At runtime it's data (userData.splineCurve) for path-following, not auto-drawn
• curve.getPointAt(t) gives an evenly-spaced point to follow

Next lesson → Scenes & prefabs

On Your Own!

Extend what you built:

• Change the control points and watch the path reshape
• Set closed:false and see the marker stop at the ends
• Orient the marker along the curve tangent (getTangentAt)

See also

• Scenes & prefabs · Components in action