Core concepts
Scenes, objects, components, scripts, physics, assets, materials, and variables — the model behind every Vibe Games project.
If you built Roll-a-Ball, you already used most of the ideas on this page. Here's the vocabulary so the editor and the docs make sense.
The model splits in two:
Per-object building blocks — a scene holds objects; each object is a bag of components plus any scripts.
Project-level resources — assets, materials, and variables live on the project, not on a single object. Any scene or object can pull from this shared pool.
Scene
A scene is one self-contained world — its objects, lights, camera, and background. A project can have several scenes (a menu, a level, a game-over screen) and switch between them at runtime with ctx.send("scene:switchTo", { sceneId }). Roll-a-Ball used a single scene.
Object
An object is a single thing in the scene: the ball, a wall, a pickup, the camera, a light, a piece of UI. Objects can be nested — an object can have child objects that move with it.
Every object has:
- a name (what you see in the Hierarchy) and a unique id
- a set of components (below)
- zero or more scripts
Component
Components are the capabilities you bolt onto an object. An object with a mesh is visible; add physics and it collides; add light and it lights the scene. You mix and match them in the Inspector with Add Component.
The main ones:
| Component | What it does |
|---|---|
transform | Position, rotation, and scale. Almost every object has one. |
mesh | A visible shape — box, sphere, cylinder, terrain, imported 3D models, and more. Wears a material. |
physics | Makes the object collide, fall, or act as a trigger. See Physics. |
camera | Renders the scene from this object's point of view. |
light | A light source (ambient, directional, point, spot, hemisphere). |
ui | On-screen or in-world interface — text, buttons, images. |
audio | Plays a sound from an audio asset. |
particle | Emits particles. |
background | The scene's backdrop — a flat color or a skybox (lives on the scene itself). |
In Roll-a-Ball the ball had transform + mesh + physics; the score readout had a ui component.
Script
A script is JavaScript attached to an object. The engine calls three optional functions: init() once at start, update() every frame, and onMessage(message) when the object receives an event.
/** @type {ScriptUpdate} */
function update() {
// runs ~60 times a second — movement, input, game logic
}The functions take no ctx parameter — ctx is a global that's always available, your handle to input, time, the scene, other objects, variables, and messaging.
Physics
Add a physics component and an object joins the simulation. The key setting is Body Type:
- Fixed — never moves. Floors, walls.
- Dynamic — fully simulated; falls and responds to forces. The ball.
- Kinematic — moves only when a script drives it, by position (
kinematicPosition) or by velocity (kinematicVelocity). Moving platforms, character controllers.
Scripts push bodies around by sending messages:
ctx.send("physics:applyForce", { objectId, force });
ctx.send("physics:applyImpulse", { objectId, impulse });
ctx.send("physics:setLinearVelocity", { objectId, velocity });
ctx.send("physics:setAngularVelocity", { objectId, velocity });
ctx.send("physics:teleport", { objectId, position });Triggers and collisions
Turn on Trigger and an object stops blocking things but reports when something enters it. The engine delivers these to onMessage:
| Message type | Fires when… |
|---|---|
physics:onTriggerEnter | A body enters a trigger volume. |
physics:onTriggerExit | A body leaves a trigger volume. |
physics:onCollisionEnter | Two solid bodies start touching. |
physics:onCollisionExit | They stop touching. |
Each carries payload.source (the object the script is on) and payload.other (what it touched). That's how the Roll-a-Ball pickup knew the ball had reached it.
Assets
An asset is any external file your project uses — uploaded, generated, or pulled from the library. They live in the Assets panel and come in four kinds:
| Kind | Examples | Used by |
|---|---|---|
| Image | PNG, JPG, SVG, WebP | ui images, material textures |
| Audio | MP3, WAV, OGG | the audio component |
| Model | GLB, OBJ, FBX | a mesh of type "model" |
| Background | HDR, EXR | the scene background |
Objects never embed a file directly — a component references an asset by id. Upload a model once and any number of mesh components can point at it.
Materials
A material is a reusable surface definition — what a mesh looks like. They live in the Materials panel, so you can define a look once and reuse it across objects. Four types:
- Standard — physically based: color, metallic, roughness, opacity, optional texture and emissive.
- Basic — unlit flat color (and optional texture). Cheap, ignores lighting.
- Emissive — self-illuminating color with an adjustable strength.
- Custom Shader — your own GLSL vertex and fragment shaders.
A mesh component references a material by id and can add per-instance overrides — tweak the color or roughness on one object without touching the shared material.
Textures tie the two resources together:
image asset → material texture → mesh that wears the material
Variables
ctx.variables is a shared store any script can read or write. It's how separate objects coordinate without knowing about each other — the pickup wrote ctx.variables.score, and the HUD read it:
// pickup
ctx.variables.score = (ctx.variables.score ?? 0) + 1;
// HUD, every frame
ctx.entity.components.ui.text = "Score: " + (ctx.variables.score ?? 0);