Core API Reference
A Java-doc-style map of the Wave3D types and methods you will use first—paired with short explanations, safe examples, returns, and common traps.
On this page
Reference scope
This page intentionally documents a small, useful center of the Wave3D authoring surface. The official declaration file contains thousands of entries and is the complete machine-readable source of truth. Where declarations have little or no prose, the explanations here are tutorial guidance—not additional vendor guarantees.
Evidence labels used here
Official API reproduces a public declaration or allowed value. Declaration-checked example means the code matches those declarations; it does not mean the example was Clean-Run inside the current WaveStudio runtime.
For a quick lookup, type a class, method, concept, or value below. Filtering happens only on this page.
No matching API entries. Try a shorter term such as move, terrain, or color.
Primitive geometry
The canonical public classes use constructors. WaveStudio also exposes the shorter cube(), sphere(), and cylinder() functions through its separate Studio-alias declaration file. This handbook teaches the canonical new wave… forms because their type ownership is unambiguous.
waveCube
Class · primitive geometry · official API
class waveCube extends waveGeometry
constructor(
width?: number,
height?: number,
depth?: number,
widthSegments?: number,
heightSegments?: number,
depthSegments?: number
);Creates a box-shaped geometry entity. The first three optional values describe its base dimensions; the final three control segmentation.
| Item | Meaning |
|---|---|
width, height, depth | Optional numeric base dimensions. |
*Segments | Optional subdivision counts for the matching axis. |
| Returns | A new waveCube, inheriting entity, transform, model, material, and physics surfaces. |
| Availability | Public WaveStudio global declarations. The cube() factory is a separate Studio-only alias. |
const block = new waveCube(3, 1, 2)
.setName("Blue block")
.setColor(PALETTE.BLUE)
.placeAt(0, 0.5, 0);Gotcha: there is no required options object. Constructor arguments are positional, so label complex dimensions with variables if their meaning is not obvious.
Official declaration
waveSphere
Class · primitive geometry · official API
class waveSphere extends waveGeometry
constructor(radius?: number, segments?: number);Creates a sphere geometry entity. radius controls size and segments controls geometric subdivision.
| Item | Meaning |
|---|---|
radius? | Optional radius of the new sphere. |
segments? | Optional segment count. |
| Returns | A new waveSphere. |
| Related | asDome(), asIcoSphere(), and asSphere() are declared on the class. |
const sun = new waveSphere(1.4, 24)
.setName("Sun")
.setColor(PALETTE.GOLD)
.placeAt(0, 5, 0);Gotcha: higher subdivision counts usually imply more geometry. The declarations do not prescribe a performance budget.
Official declaration
waveCylinder
Class · primitive geometry · official API
class waveCylinder extends waveGeometry
constructor(
height?: number,
diameterTop?: number,
diameterBottom?: number,
tessellation?: number,
heightSegments?: number
);Creates a cylinder-like geometry entity. Different top and bottom diameters can describe a tapered form.
| Item | Meaning |
|---|---|
height? | Optional total height. |
diameterTop?, diameterBottom? | Optional end diameters. |
tessellation? | Optional radial subdivision count. |
heightSegments? | Optional vertical subdivision count. |
| Returns | A new waveCylinder. |
const tower = new waveCylinder(4, 1.5, 2, 24, 1)
.setName("Tower")
.setColor(PALETTE.TERRACOTTA)
.placeAt(0, 2, 0);Gotcha: the constructor begins with height, not radius. Both diameter arguments come before tessellation.
Official declaration
Entity basics
The primitive classes inherit a broad surface. The useful ownership chain is waveCube → waveGeometry → waveProp → wave3DObject → wave3DAbstract → WaveObject → WaveEntity. Methods such as setName() come from WaveEntity; transforms come from wave3DAbstract; visuals and physics are exposed by wave3DObject.
WaveEntity
Abstract class · lifecycle foundation · official API
abstract class WaveEntity<TState = unknown>
readonly id: number;
get name(): string;
get typeName(): string;
get isEnabled(): boolean;
get isDestroyed(): boolean;
get isSpawned(): boolean;
get scene(): WaveScene;The shared entity foundation provides identity, scene access, lifecycle, delayed actions, state helpers, components, cloning, and update callbacks.
| Member | Returns | Use |
|---|---|---|
id | number | Read-only numeric identity. |
name | string | Current authored name. |
scene | WaveScene | The owning scene. |
isEnabled | boolean | Whether the entity is enabled. |
isDestroyed | boolean | Whether destruction has occurred. |
Gotcha: WaveEntity is abstract. Beginners normally receive its methods through a concrete object such as waveCube.
Official declaration
setName()
WaveEntity method · official API
setName(name: string): this;Assigns the entity’s authored name and returns the same entity for chaining.
| Parameter | Type | Description |
|---|---|---|
name | string | The new name. |
| Returns | this | The same concrete entity type. |
| Availability | WaveEntity and its descendants. | |
const gem = new waveSphere(0.6).setName("Treasure gem");Gotcha: a JavaScript variable name such as gem and the entity’s Wave3D name are separate things.
Official declaration
setColor()
waveGeometry / wave3DObject method · official API
setColor(
color: Parameters<cmp_visual3DModel["setColor"]>[0]
): this;Sets the visual color. The public declaration reuses the visual-model component’s input type; PALETTE values are the simplest documented inputs to teach.
| Item | Description |
|---|---|
color | The declared visual-model color input. |
| Returns | this for the immediate overload. |
| Advanced overloads | Snapshot and Animate overloads return material-property builders. |
| Availability | waveGeometry and wave3DObject. |
const leaf = new waveSphere(0.4)
.setColor(PALETTE.EMERALD);Gotcha: do not guess hexadecimal swatches for named palette colors. Use an official PALETTE key or an official color constructor.
Official declaration
Transforms
Transform methods live on wave3DAbstract and return the same concrete type in their immediate overloads. That is why creation, naming, color, placement, movement, turning, and scaling can be chained.
placeAt()
wave3DAbstract method · official API
placeAt(target: TransformReferenceLike | WavePointInput): this;
placeAt(x: number, y: number, z: number): this;Places an object at a target point or at numeric x, y, and z coordinates.
| Overload | Use | Returns |
|---|---|---|
placeAt(target) | Place at a supported transform reference or point input. | this |
placeAt(x, y, z) | Place at explicit 3D coordinates. | this |
const moon = new waveSphere(0.8).placeAt(4, 3, -2);
const tinyMoon = new waveSphere(0.2).placeAt(moon);Gotcha: this is 3D spatial placement. Screen-space and 2D objects use different transform types and overloads.
Official declaration
Movement methods
wave3DAbstract methods · official API
moveBy(direction: DirectionInput, distance: number): this;
moveForward(distance: number): this;
moveBackward(distance: number): this;
moveLeft(distance: number): this;
moveRight(distance: number): this;
moveUp(distance: number): this;
moveDown(distance: number): this;
moveTo(target: TransformReferenceLike | WavePointInput): this;Moves an object by a direction and distance, by a named relative direction, or to a target. The immediate overloads return this; additional Snapshot and Animate overloads are present in the full declarations.
| Family | Meaning |
|---|---|
moveBy(direction, distance) | Relative movement using a DirectionInput. |
moveForward … moveDown | Convenient named relative movement. |
moveTo(target) | Move to a supported target reference or point. |
| Returns | this for each immediate overload shown here. |
const ship = new waveCube(2, 0.5, 4)
.moveBy(Direction.Up, 1)
.moveForward(3)
.moveRight(2);No generic move() method is part of this beginner surface. Use the exact verbs above.
Official declaration
Rotation methods
wave3DAbstract methods · official API
turnLeft(degrees: number): this;
turnRight(degrees: number): this;
turnTo(target: TransformReferenceLike | WavePointInput): this;
turnToward(direction: DirectionInput): this;Turns an object by degrees, toward a target, or toward a declared direction.
| Method | Input | Returns |
|---|---|---|
turnLeft, turnRight | Degrees as a number. | this |
turnTo | A transform reference or point. | this |
turnToward | A DirectionInput. | this |
const arrow = new waveCylinder(2, 0.2, 0.7)
.turnRight(45)
.turnToward(Direction.Forward);Gotcha: the core verb is not turn(). Use turnLeft(), turnRight(), turnTo(), or turnToward().
Official declaration
Scale methods
wave3DAbstract methods · official API
scaleBy(value: number | Vector3Like): this;
scaleTo(value: number | Vector3Like): this;
setScale(scale: Vector3Like): this;
setScale(uniform: number): this;
setScale(x: number, y: number, z: number): this;
setUniformScale(scale: number): this;scaleBy() applies a relative factor. scaleTo() and setScale() set a scale value. The setScale(uniform: number) overload explicitly names uniform behavior; vector and three-number overloads can vary by axis. The declarations accept a number for scaleBy() and scaleTo() without naming its per-axis semantics.
| Method | Intent | Returns |
|---|---|---|
scaleBy(value) | Relative scaling. | this |
scaleTo(value) | Target scale. | this |
setScale(...) | Set uniform, vector, or per-axis scale. | this |
const cloud = new waveSphere(1)
.scaleBy(1.5)
.setScale(2, 0.7, 1.2);Gotcha: there is no generic beginner method named scale(). Choose a declared scale verb.
Official declaration
Time and input
Wave3D exposes authored time units, delayed entity actions, and scene-director input callbacks as typed global surfaces.
after().do()
WaveEntity delayed action · official API
after(duration: WaveTimeSpan): DelayedEntityProxy<this>;
after(value: number, unit: WaveTimeUnit): DelayedEntityProxy<this>;
do(callback: (entity: TEntity) => void): TEntity;Creates a delayed proxy and then schedules a callback. The callback receives the original typed entity.
| Part | Meaning |
|---|---|
value | Numeric amount of time. |
unit | A WaveTimeUnit, such as the global Seconds unit. |
callback | Receives the delayed entity as its parameter. |
| Returns | after() returns a delayed proxy; do() returns the entity. |
const light = new waveSphere(0.5).setColor(PALETTE.BLUE);
light.after(2, Seconds).do((target) => {
target.setColor(PALETTE.ORANGE);
});Gotcha: entity.after(Seconds(2)) is not the same signature. Calling Seconds(2) creates a WaveTimePoint; the two-argument delayed-action overload expects after(2, Seconds).
Official declaration
Seconds
Global time-unit function · official API
const Seconds: {
(value: number): WaveTimePoint;
readonly kind: WaveTimeUnitKind;
};Seconds has two roles in the type surface: it is callable to make a time point, and it carries a kind so it can be passed as a time-unit reference.
| Form | Result | Typical context |
|---|---|---|
Seconds(2) | WaveTimePoint | APIs that ask for a point in time. |
2, Seconds | Number plus unit arguments | APIs with a (value, unit) overload. |
Gotcha: read the receiving method’s signature before choosing between these forms.
Official declaration
Keyboard
Global enum · official API
enum Keyboard {
A = "KeyA",
ArrowDown = "ArrowDown",
ArrowLeft = "ArrowLeft",
ArrowRight = "ArrowRight",
ArrowUp = "ArrowUp",
Enter = "Enter",
Escape = "Escape",
Space = "Space",
W = "KeyW"
// …additional declared keys
}Names supported keyboard codes without relying on handwritten strings. The enum includes A–Z, digits, arrows, modifiers, navigation keys, punctuation, space, and F1–F12.
| Examples | Declared value |
|---|---|
Keyboard.Space | "Space" |
Keyboard.W | "KeyW" |
Keyboard.ArrowUp | "ArrowUp" |
Keyboard.Num1 | "Digit1" |
Gotcha: use the enum member name—not a guessed browser key string—when an API asks for Keyboard.
Official declaration excerpt
director.whenPress()
waveSceneDirector method · official API
whenPress(
key: Keyboard | undefined,
callback: InputCallback<KeyboardInputData, this>,
options?: Omit<CallbackOptions, "filter">
): CallbackHandle;Registers a keyboard-press callback on the scene director and returns a callback handle.
| Parameter | Use |
|---|---|
key | A Keyboard member or undefined. The declaration accepts both; it does not document what the undefined case means at runtime. |
callback | Receives an InputCallbackContext containing data and owner. |
options? | Callback options excluding filter. |
| Returns | CallbackHandle. |
const playerCube = new waveCube(1, 1, 1);
myScene.director.whenPress(Keyboard.Space, () => {
playerCube.moveUp(1);
});Related: myScene.director.sensing.whenPress(...) is also typed. The direct director method is the smaller core form.
Official declaration
Scene and terrain
The scene provides runtime output and world systems. Terrain has separate authoring, runtime-brush, and query surfaces.
myScene.print()
WaveScene method · official API
print(
text: unknown,
fontSize?: number,
color?: ColorInput | string,
options?: WaveScenePrintOptions
): void;Accepts a value plus optional font size, color, and print options, and returns void. The declaration does not specify how or where the value is displayed.
| Parameter | Type | Required |
|---|---|---|
text | unknown | Yes |
fontSize | number | No |
color | ColorInput | string | No |
options | WaveScenePrintOptions | No |
| Returns | void | — |
myScene.print("Space moves the cube", 18, PALETTE.WHITE);Gotcha: this method returns void, so it is not a fluent chain from the scene.
Official declaration
terrain.runtime.noise()
Runtime terrain builder · official API
get terrain(): WaveTerrainFacade<WaveScene<TEngine>>;
get runtime(): WaveTerrainRuntimeFacade<TTerminal>;
noise(): WaveTerrainBrushBuilder<TTerminal>;
at(value: WaveTerrainRuntimePoint): this;
at(x: number, z: number): this;
radius(value: number): this;
amount(value: number): this;
frequency(value: number): this;
octaves(value: number): this;
falloff(value: "smooth" | "linear" | "hard"): this;
apply(): TTerminal;Starts a runtime terrain noise brush, configures its location and shape, and commits it with apply().
| Builder step | Meaning |
|---|---|
at({ x, z }) | Brush center in the terrain plane. |
radius(value) | Brush radius. |
amount(value) | Noise amount. |
frequency(value) | Noise frequency. |
octaves(value) | Noise octave count. |
falloff(value) | Exactly "smooth", "linear", or "hard". |
apply() | Applies the built operation and returns the terminal type. |
myScene.terrain.runtime
.noise()
.at({ x: 0, z: 0 })
.radius(640)
.amount(6)
.frequency(0.015)
.octaves(3)
.falloff("smooth")
.apply();Gotcha: at() uses terrain-plane x and z, not a 3D x, y, z position.
Official declaration and shipped WaveStudio starter
Terrain queries
WaveTerrainFacade / WaveTerrainQueryFacade · official API
// WaveTerrainFacade
heightAt(x: number, z: number): number | null;
normalAt(x: number, z: number): SurfaceQueryResult["normal"] | null;
query(): WaveTerrainQueryFacade;
// WaveTerrainQueryFacade
query(x: number, z: number): SurfaceQueryResult | null;
surfaceAt(x: number, z: number): SurfaceQueryResult | null;
isReady(): boolean;Reads terrain height, normal, or a fuller surface result at an x, z location. Query methods can return null.
const x = 12;
const z = -4;
const groundY = myScene.terrain.heightAt(x, z);
if (groundY !== null) {
const marker = new waveSphere(0.25).placeAt(x, groundY, z);
}Gotcha: always handle null. The signatures permit it but do not state which runtime conditions produce it.
Official declaration
Object systems
These surfaces are useful after the fundamentals. They are included as concise maps; consult the full declarations for every option type and overload.
Visibility and lifecycle
wave3DObject / WaveEntity · official API
// wave3DObject
hide(options?: Wave3DObjectHideOptions): this;
show(): this;
// WaveEntity
setEnabled(value: boolean): this;
destroy(): void;
get isEnabled(): boolean;
get isDestroyed(): boolean;
onCreated(
callback: EntityLifecycleCallback<this>,
nameOrOptions?: EntityLifecycleCallbackNameOrOptions,
options?: WaveAuthoredCallbackOptions
): this;
onDestroyed(
callback: EntityLifecycleCallback<this>,
nameOrOptions?: EntityLifecycleCallbackNameOrOptions,
options?: WaveAuthoredCallbackOptions
): this;hide() and show() control a 3D object’s presentation. setEnabled() controls entity enablement. destroy() ends the entity lifecycle and returns void.
| Operation | Reversible? | Returns |
|---|---|---|
hide() / show() | Paired presentation operations. | this |
setEnabled(false) | Can be followed by setEnabled(true). | this |
destroy() | Terminal lifecycle operation. | void |
const secret = new waveCube(1, 1, 1).hide();
secret.show();
secret.onDestroyed(() => {
myScene.print("The secret was removed");
});Gotcha: hiding, disabling, and destroying are distinct operations. Do not use destroy() when you merely intend to hide something temporarily.
Official declaration
whenClickedOn()
wave3DObject interaction method · official API
whenClickedOn(
callback: InteractionCallback<this>,
options?: InteractionCallbackOptions
): CallbackHandle;
type InteractionCallback<TOwner extends WaveEntity = WaveEntity> =
(ctx: InteractionContext<TOwner>) => void;Registers a click callback. The context contains owner, the typed object that owns the callback, and data, the interaction details.
const buttonBlock = new waveCube(1, 0.3, 1);
buttonBlock.whenClickedOn(({ owner }) => {
owner.setColor(PALETTE.GOLD);
});Gotcha: this callback receives a context object, not the entity directly. Destructure owner or read ctx.owner.
Official declaration
Models
wave3DObject visual model methods · official API
constructor(modelAsset?: Visual3DModelAuthoringInput);
useModel(
model: Visual3DModelAuthoringInput,
options?: Visual3DModelUseOptions
): this;
removeModel(): this;
get modelName(): cmp_visual3DModel["modelName"];A general wave3DObject can receive a visual model at construction or through useModel().
const sculpture = new wave3DObject()
.setName("Sculpture")
.useModel("my-model")
.placeAt(0, 0, 0);Gotcha: a string is compatible with the authoring type, but the declaration does not guarantee how that string is resolved—or whether it produces a runtime model. Confirm asset resolution in the current Studio project.
Official declaration
Physics overview
wave3DObject physics methods · official API
enablePhysics(options?: EnablePhysicsOptions): this;
disablePhysics(options?: DisablePhysicsOptions): this;
useDynamicBody(options?: EnablePhysicsOptions): this;
useKinematicBody(options?: EnablePhysicsOptions): this;
useStaticBody(options?: EnablePhysicsOptions): this;
setMass(value: number): this;
setGravityFactor(factor: number): this;
get hasPhysicsBody(): boolean;The core object surface can enable or disable physics and choose a dynamic, kinematic, or static body intent. Properties such as mass and gravity factor are fluent setters.
| Body helper | Teaching description |
|---|---|
useDynamicBody() | Choose the declared dynamic-body helper. |
useKinematicBody() | Choose the declared kinematic-body helper. |
useStaticBody() | Choose the declared static-body helper. |
hasPhysicsBody | Read whether a physics body is present. |
const ball = new waveSphere(0.5)
.placeAt(0, 5, 0)
.useDynamicBody()
.setMass(1);Gotcha: the declarations establish the callable surface, not the active physics backend, collider quality, or runtime tuning. Test physics projects in WaveStudio.
Official declaration
Global values
Enums and typed singletons help avoid guessed strings and magic numbers.
Direction
Global enum and namespace · official API
enum Direction {
Backward = "backward",
Down = "down",
Forward = "forward",
Left = "left",
Right = "right",
Up = "up",
X = "x",
Y = "y",
Z = "z"
}Provides the nine declared named direction or axis values. The merged Direction namespace also declares helpers such as random(), mix(), and randomInCone().
const rover = new waveCube(2, 0.5, 3)
.moveBy(Direction.Forward, 6)
.turnToward(Direction.Left);Gotcha: DirectionInput is broader than the enum. This entry lists the exact enum values, not every accepted direction-like type.
Official declaration
PALETTE
Global WaveColorSingleton · official API
const PALETTE: WaveColorSingleton;
type PaletteColorMap = Record<PaletteColorKey, number>;A typed color singleton with 103 verified named keys plus constructors and color utilities. The names below are copied from the public PaletteColorKey union; this page deliberately does not invent visual swatches or hexadecimal values.
| Group | Declared keys |
|---|---|
| Neutrals | BLACK, WHITE, IVORY, WARM_WHITE, GRAY, LIGHT_GRAY, DARK_GRAY, COOL_GRAY, WARM_GRAY, CHARCOAL, SAND, SOFT_TAUPE, BONE |
| Reds and oranges | RED, CARMINE, CRIMSON, SCARLET, VERMILION, BRICK, RUST, WINE, MAROON, CORAL, ORANGE, TANGERINE, PUMPKIN, AMBER, COPPER, TERRACOTTA, PERSIMMON |
| Yellows and greens | YELLOW, LEMON, CANARY, GOLDENROD, MUSTARD, MAIZE, GREEN, MINT, SAGE, OLIVE, MOSS, FOREST, EMERALD, JADE |
| Blues | CYAN, TURQUOISE, BLUE, SKY, AZURE, CERULEAN, COBALT, ROYAL, NAVY, PRUSSIAN, SLATE, MIDNIGHT, INDIGO |
| Purples and pinks | PURPLE, MAGENTA, FUCHSIA, PINK, LAVENDER, LILAC, AMETHYST, VIOLET, PLUM, ORCHID, AUBERGINE |
| Earth and accents | BROWN, WALNUT, STRAW, TEAL, LIME, CELADON, CHARTREUSE, RAW_UMBER, BURNT_UMBER, RAW_SIENNA, BURNT_SIENNA, SEPIA, OCHRE, CHESTNUT, ESPRESSO, TUSCAN_TAN, ESPRESSO_DARK, OLIVE_DRAB, SKY_DEEP, CERULEAN_DARK |
| Metals and skin tones | SILVER, GOLD, BRASS, BRONZE, ROSE_GOLD, PLATINUM, PORCELAIN, FAIR, BEIGE, ALMOND, HONEY, CARAMEL, BRONZE_SKIN, UMBER_DEEP, KHAKI |
const ocean = new waveCube(8, 0.2, 8)
.setColor(PALETTE.CERULEAN);
const customColor = PALETTE.rgb(90, 180, 240);
ocean.setColor(customColor);Selected utilities: the singleton declares rgb(), rgba(), hsv(), fromHexString(), lighten(), darken(), mix(), withAlpha(), and conversion helpers.
Gotcha: named entries are uppercase and underscore-separated. PALETTE.WARM_WHITE is declared; PALETTE.warmWhite is not.
Official declaration and allowed key union
Source boundary and completeness
This reference is designed for learning, not exhaustive coverage. Public signatures can evolve. When this page and the current editor disagree, use WaveStudio autocomplete and the latest official declaration files as the authority.
| Official source | What it establishes |
|---|---|
| Global declaration file | Public classes, interfaces, globals, overloads, enums, and return types. |
| Entity-alias declaration file | WaveStudio convenience factories such as cube(), sphere(), and cylinder(). |
| WaveStudio | The current public web editor and its runtime. |
| Wave3D engine overview | Official public product context. |