Bouncing Ball 3D

The 3D viewer lets you map simulation state to a live Three.js scene. Instead of reading plots, you watch the physics unfold in three dimensions. This tutorial walks through the viewer API using the same bouncing-ball model from the Getting Started section.

How the viewer works

The viewer script exposes a ctx object with two callback hooks:

• ctx.onInit(api) — called once when the viewer mounts. Use it to set up lighting, create meshes, and store references in api.state.
• ctx.onFrame(api) — called on every animation frame during playback. Use api.getValue(name, api.sampleIndex) to read the current value of any simulation variable, then update your Three.js objects.

The api argument gives you access to api.THREE (the Three.js library), api.state (a persistent object shared between init and frame callbacks), and api.state.scene (the root Three.js scene). Press Play to start the animation, or scrub the timeline to jump to any point in the simulation.

Walking through the script

onInit receives the api object and uses api.THREE to build the scene. The directional light and ambient light ensure the sphere is properly shaded. The floor and grid helper provide spatial context. Every object you want to update later should be stored on api.state — this object persists across frames.

onFrame is where the simulation meets the visuals. The call api.getValue("h", api.sampleIndex) returns the value of the Modelica variable h at the current playback time. We map that directly to the ball's Y coordinate. The Number.isFinite guard protects against NaN or undefined values at the edges of the time series.

Use the playback controls beneath the 3D viewport to play, pause, and scrub through the simulation. The next tutorial extends this pattern to a more complex scene with orbital mechanics.