The Wave3D Tutorial

Chapter 1

Your first object

A primitive is a basic 3D form. Wave3D exposes canonical classes for several primitives. To create one, write new, the class name, and parentheses containing its starting measurements.

Official API

constructor(
  width?: number,
  height?: number,
  depth?: number,
  widthSegments?: number,
  heightSegments?: number,
  depthSegments?: number
);

setName(name: string): this
setColor(color: Parameters<cmp_visual3DModel["setColor"]>[0]): this
placeAt(x: number, y: number, z: number): this

Declaration-checked example

const block = new waveCube(2, 2, 2)
  .setName("blue-block")
  .setColor(PALETTE.BLUE)
  .placeAt(0, 1, 0);

What each line says

• const block creates a code label for this object.
• new waveCube(2, 2, 2) requests width 2, height 2, and depth 2.
• setName("blue-block") gives the scene entity a readable name.
• PALETTE.BLUE uses one of the declared palette keys.
• placeAt(0, 1, 0) sets x, y, and z coordinates.

Tutorial guidance

Lab: make a tall block

1. Run the example unchanged.
2. Change the constructor to new waveCube(2, 4, 2).
3. Change the color to another declared key, such as PALETTE.CORAL.
4. Change the y coordinate if you want to reposition the taller object.

Expected result

You should see one colored box. After the lab it should be taller, and the palette change should be visible. Exact framing and lighting depend on the current scene and Studio defaults.

Common mistakes

• Leaving out new before the canonical class.
• Writing wavecube; TypeScript names are case-sensitive.
• Forgetting quotes around "blue-block".
• Inventing a palette name. Type PALETTE. and use the editor’s suggestions.
• Assuming the Studio-only cube() alias is the canonical public class. This handbook uses new waveCube(...).

Sources for this chapter

• Official global declarations: waveCube, waveGeometry.setColor, entity naming, transforms, and PALETTE.
• Official Studio alias declarations: convenience alias boundary.

Chapter 2

Reading Wave TypeScript

WaveStudio code is TypeScript. TypeScript is JavaScript with a vocabulary for describing what kinds of values are allowed. In a signature such as moveUp(distance: number): this, the parameter named distance expects a number, and the method returns the current object.

Declaration-checked example

const marker: waveCube = new waveCube(1, 1, 1)
  .setName("marker")
  .setColor(PALETTE.YELLOW)
  .placeAt(0, 0.5, 0);

function lift(object: waveCube, amount: number): void {
  object.moveUp(amount);
}

lift(marker, 2);

Why chains work

Many Wave authoring methods declare : this as their return type. That means the call hands the same object back, ready for another dot. These two forms express the same sequence:

// Chained
marker.setColor(PALETTE.YELLOW).moveUp(1);

// Step by step
marker.setColor(PALETTE.YELLOW);
marker.moveUp(1);

Tutorial guidance

Lab: write a reusable move

Change lift(marker, 2) to lift(marker, 4). Then rename the function to raise in both its definition and call. Finally, remove the explicit : waveCube on the variable and notice that the editor can infer the constructor’s result.

Expected result

The yellow marker moves higher when you pass a larger amount. Renaming the function changes no behavior as long as both names match.

Common mistakes

• Changing the function’s name but not the call below it.
• Passing text such as "two" where a number is required.
• Reading this as a parameter. It appears after the colon because it is the return type.
• Assuming every API returns this. Check the signature before chaining.

Sources for this chapter

• Official global declarations: return types for entity, geometry, and transform methods.

Chapter 3

Geometry & composition

Complex 3D art often begins as a collection of simple forms. A sphere can become a head, a cylinder a body, and a flattened cube a platform. Composition is the art of choosing their proportions and positions so the viewer reads them as one idea.

Official API

// waveCube
constructor(
  width?: number,
  height?: number,
  depth?: number,
  widthSegments?: number,
  heightSegments?: number,
  depthSegments?: number
);

// waveSphere
constructor(radius?: number, segments?: number);

// waveCylinder
constructor(
  height?: number,
  diameterTop?: number,
  diameterBottom?: number,
  tessellation?: number,
  heightSegments?: number
);

Declaration-checked example

const platform = new waveCube(6, 0.5, 6)
  .setName("platform")
  .setColor(PALETTE.SLATE)
  .placeAt(0, -0.25, 0);

const body = new waveCylinder(3, 1.5, 1.5, 32)
  .setName("robot-body")
  .setColor(PALETTE.CYAN)
  .placeAt(0, 1.5, 0);

const head = new waveSphere(1, 32)
  .setName("robot-head")
  .setColor(PALETTE.YELLOW)
  .placeAt(0, 3.8, 0);

Tutorial guidance

Lab: turn the robot into a lighthouse

1. Change the body’s bottom diameter to 2.2 while keeping its top diameter 1.5.
2. Change the body color to PALETTE.WHITE.
3. Change the head color to PALETTE.RED.
4. Move the head up or down until it sits where you want.

Expected result

Three separate primitives should read together as a small character. After the lab, the wider cylinder base and red sphere should suggest a stylized lighthouse.

Common mistakes

• Using radius values for waveCylinder even though its constructor asks for diameters.
• Giving two top-level constants the same name in one experiment.
• Putting every object at exactly the same coordinates and hiding one inside another.
• Expecting names alone to group objects. Here the forms are a visual composition, not yet a WaveGroup.

Sources for this chapter

• Official global declarations: waveCube, waveSphere, and waveCylinder constructors.

Chapter 4

Spatial language & transforms

A transform describes position, rotation, and scale. placeAt puts an object at a target coordinate. Movement verbs change where it is from its current state. Turning changes orientation. Scaling changes size.

Official API

Declaration-checked example

const tower = new waveCube(2, 3, 2)
  .setName("moving-tower")
  .setColor(PALETTE.PURPLE)
  .placeAt(0, 1.5, 0);

tower
  .moveRight(3)
  .moveUp(1)
  .turnLeft(45)
  .scaleBy(0.75);

By, to, and set

The names signal intent: by usually describes a change from the current value, while to or set describes a target value. That reading is a useful authoring rule, but the exact runtime frame and animation behavior depend on the selected overload and current Wave3D implementation.

Tutorial guidance

Lab: choreograph four transforms

1. Run only the constructor chain and observe the starting placement.
2. Add tower.moveLeft(2); and run again.
3. Add tower.turnRight(90);.
4. Finish with tower.setScale(1, 2, 1); to use different x, y, and z scale values.

Expected result

The tower starts at one known coordinate, then moves, turns, and changes size in the order your calls are evaluated. With setScale(1, 2, 1), it should be stretched along one scale component.

Common mistakes

• Confusing placeAt with moveBy. One targets a place; the other expresses a change.
• Writing turnLeft(0.5) while thinking in radians. The signature names the unit degrees.
• Using an undeclared generic method because another 3D library has one.
• Changing several transforms at once before checking which call caused an unexpected result.

Sources for this chapter

• Official global declarations: cmp_transform placement, movement, rotation, and scale overloads.

Chapter 5

Time & delayed actions

A delayed action has two parts: a delay and the work to do after that delay. Wave entities expose an after proxy whose do callback receives the target entity.

Official API

after(value: number, unit: WaveTimeUnit): DelayedEntityProxy<this>

interface DelayedActionSurface<TEntity extends object> {
  do(callback: (entity: TEntity) => void): TEntity;
}

type DelayedEntityProxy<TEntity extends object> =
  TEntity & DelayedActionSurface<TEntity>;

declare const Seconds: {
  (value: number): WaveTimePoint;
  readonly kind: WaveTimeUnitKind;
};

Declaration-checked example

const signal = new waveCube(1, 3, 1)
  .setName("signal")
  .setColor(PALETTE.BLUE)
  .placeAt(0, 1.5, 0);

signal.after(1, Seconds).do((target) => {
  target.moveUp(2);
});

signal.after(2, Seconds).do((target) => {
  target.turnRight(45).setColor(PALETTE.ORANGE);
});

Read the callback

The arrow => introduces a callback. Wave calls that function later and supplies target. Inside the braces, target is the entity whose delayed proxy you created. Choosing the name target is a readable habit, not a required keyword.

Tutorial guidance

Lab: make a three-beat signal

Add a third delayed action at three seconds. In it, move the target down by 2 and change it to PALETTE.GREEN. Before running, write down what you expect at 0, 1, 2, and 3 seconds.

Expected result

The signal begins blue. One scheduled callback moves it upward; another turns it and changes it to orange. Your third callback should move it down and turn it green. Exact timing should be confirmed in the current Studio.

Common mistakes

• Writing Seconds(2) where the overload expects a span.
• Leaving out .do(...), so no delayed action is supplied.
• Using signal inside every callback when target makes ownership clearer.
• Expecting a sequence just because calls appear on later lines. Each after call states its own delay.

Sources for this chapter

• Official global declarations: entity after, DelayedEntityProxy, DelayedActionSurface, and Seconds.

Chapter 6

Keyboard interaction

Interaction turns a static scene into something a visitor can influence. The scene director declares key events, including whenPress. Its first argument accepts Keyboard | undefined; the examples intentionally use a Keyboard member. Its second argument is a callback.

Official API

myScene.director.whenPress(
  key: Keyboard | undefined,
  callback: InputCallback<KeyboardInputData, this>,
  options?: Omit<CallbackOptions, "filter">
): CallbackHandle

Declaration-checked example

const player = new waveCube(1, 1, 1)
  .setName("player")
  .setColor(PALETTE.LIME)
  .placeAt(0, 0.5, 0);

myScene.director.whenPress(Keyboard.ArrowUp, () => {
  player.moveForward(1);
});

myScene.director.whenPress(Keyboard.ArrowLeft, () => {
  player.turnLeft(15);
});

myScene.director.whenPress(Keyboard.ArrowRight, () => {
  player.turnRight(15);
});

myScene.print("Arrow keys move and turn", 18, PALETTE.WHITE);

The public declarations also type myScene.director.sensing.whenPress(...). This tutorial uses the shorter direct myScene.director.whenPress(...) form as its core pattern.

Tutorial guidance

Lab: add a jump key

Add this fourth handler. Then run the scene, click or focus the scene view if needed, and press Space.

myScene.director.whenPress(Keyboard.Space, () => {
  player.moveUp(1);
});

Expected result

Each press triggers its matching callback. Up Arrow calls moveForward(1), Left and Right Arrow turn the object by 15 degrees, and Space moves it upward by one unit. The declarations do not state the coordinate frame used by moveForward. Input focus and capture behavior are Studio UI concerns and may vary.

Common mistakes

• Using "Space" as plain text instead of the declared Keyboard.Space enum member.
• Calling the movement immediately instead of putting it inside the callback braces.
• Needing explicit hold behavior but only inspecting whenPress. The director separately declares whenHolding; the declarations do not specify key-repeat behavior for whenPress.
• Testing while keyboard focus is still in the code editor rather than the scene view.

Sources for this chapter

• Official global declarations: waveSceneDirector.whenPress, cmp_sensing.whenPress, Keyboard, and WaveScene.print.

Core path project

Build a moving color sculpture

This project deliberately uses only the vocabulary from Chapters 1–6. Start it as a fresh experiment so earlier constants and event handlers do not collide.

Declaration-checked project

const plinth = new waveCylinder(0.5, 5, 5, 32)
  .setName("sculpture-plinth")
  .setColor(PALETTE.SLATE)
  .placeAt(0, 0.25, 0);

const dancer = new waveCube(1.5, 4, 1.5)
  .setName("color-dancer")
  .setColor(PALETTE.CYAN)
  .placeAt(0, 2.5, 0);

const crown = new waveSphere(1, 32)
  .setName("sculpture-crown")
  .setColor(PALETTE.GOLD)
  .placeAt(0, 5.3, 0);

dancer.after(2, Seconds).do((target) => {
  target.turnRight(45).setColor(PALETTE.MAGENTA);
});

myScene.director.whenPress(Keyboard.Space, () => {
  dancer.moveUp(1).turnLeft(15);
  crown.moveUp(1);
});

myScene.print("Press Space to lift the sculpture", 18, PALETTE.WHITE);

Build checklist

1. Run the static geometry.
   Temporarily stop before the delayed action and confirm that three forms read as one sculpture.
2. Add the two-second change.
   Predict which object will turn and change color, then run it.
3. Add Space interaction.
   Confirm which two objects move and which one turns on each press.
4. Personalize one dimension and two colors.
   Keep a copy of the working version so you can compare.

Expected result

A short cylinder supports a tall cube and a sphere. After two seconds, the cube should turn and become magenta. Each Space press should lift both upper forms, while the cube also turns left. The text prompt should appear in the scene.

Challenge extensions

• Add Arrow Left and Arrow Right handlers that turn the crown.
• Schedule a third color after four seconds.
• Make a second sculpture at a different x coordinate, using different constant names.
• Write a function that accepts a waveCube and a numeric lift amount.

Debug checklist

• Is every opening parenthesis, brace, and quote closed?
• Does each constant have a unique code name?
• Do palette keys come from editor suggestions?
• Is the delay written after(2, Seconds)?
• Are input actions inside callback braces?

Chapters 7–14

Continue on the advanced track

The public WaveStudio declarations contain thousands of entries across rendering, assets, UI, physics, sensing, world systems, XR, audio, and more. A responsible first edition should not pretend that a signature dump is a finished tutorial. The map below tells you what to study next and where this handbook has enough evidence to help.

myScene.terrain.runtime
  .noise()
  .at({ x: 0, z: 0 })
  .radius(640)
  .amount(6)
  .frequency(0.015)
  .octaves(3)
  .falloff("smooth")
  .apply();

How to study a new API safely

1. Find the exact symbol.
   Use the curated reference, then follow its raw declaration source.
2. Read every overload.
   Argument order, optional values, and return types often reveal the intended chain.
3. Make the smallest experiment.
   Create one object and call one unfamiliar method.
4. Clean-Run and observe.
   Write down Studio version/date, code, result, and any error.
5. Add one concern at a time.
   Only then combine assets, animation, input, physics, or UI.

Sources for the advanced map

• Official global declarations: complete captured public TypeScript surface.
• Official alias declarations: Studio conveniences and canonical targets.
• Public WaveStudio app: current authoring environment and shipped starter material.
• Published agent SDK README: automation and agent-facing package context.