Your First Project

In this tutorial, you'll create a simple physics playground: a ball that bounces on a rotating platform. Along the way, you'll learn core concepts like entities, components, physics, and scripting — the building blocks of every game in Web Engine.

Step 1: Create a New Project#

Start by creating a fresh project:

1. Open the Studio and go to the Project Hub
2. Click New Project
3. Name it "Bouncing Ball" and select the Empty template
4. Click Create

You'll see an empty scene with just a default camera. Let's add some objects!

Step 2: Create the Ground Platform#

First, we need a surface for our ball to bounce on:

1. Right-click in the Hierarchy Panel → 3D Object → Cube
2. Rename it to "Ground" by double-clicking the name or pressing F2
3. In the Inspector, set the Transform component values:
   • Position: (0, -0.5, 0)
   • Rotation: (0, 0, 0)
   • Scale: (10, 1, 10)

This creates a flat, wide platform centered at the origin. Now let's add physics so the ball can interact with it:

Add Physics to Ground#

1. With "Ground" selected, click Add Component at the bottom of the Inspector
2. Search for and add RigidBody
3. In the RigidBody component:
   • Set type to Fixed (static, immovable object)
   • Set mass to 1.0 (doesn't matter for fixed bodies)
4. Add another component: Collider
5. In the Collider component:
   • Set type to Box
   • Set size to (5, 0.5, 5) — these are half-extents

Step 3: Create the Ball#

Now let's add a bouncing ball above the platform:

1. Right-click in Hierarchy → 3D Object → Sphere
2. Rename it to "Ball"
3. Set Transform Position: (0, 5, 0) — 5 units above the ground

Add Physics to Ball#

Add physics components to make the ball fall and bounce:

1. With Ball selected, add RigidBody component
2. In the RigidBody component:
   • Set type to Dynamic (affected by gravity and forces)
   • Set mass to 1.0
   • Set restitution to 0.8 (bounciness - higher = more bounce)
   • Set friction to 0.3
3. Add Collider component
4. In the Collider component:
   • Set type to Sphere
   • Set radius to 0.5

Let's also give the ball a bright color so it's easy to see:

1. In the Inspector, find the Material component
2. Click the color swatch next to albedoColor
3. Choose a bright color like red, blue, or yellow

Step 4: Test the Physics#

Let's see our ball in action:

1. Press Ctrl/Cmd + P or click the Play button (▶) in the toolbar
2. Watch the ball fall due to gravity, hit the ground, and bounce!
3. It should bounce several times before coming to rest on the platform
4. Press Ctrl/Cmd + P again to stop Play Mode

If the ball falls through the ground, double-check your collider settings. Both the Ground and Ball need colliders, and the Ground's RigidBody must be set to Fixed.

Step 5: Add a Rotation Script#

Now let's make things interesting by rotating the platform. We'll write a simple JavaScript script to do this:

1. Select the "Ground" entity in the Hierarchy
2. Click Add Component in the Inspector
3. Search for and add Script
4. In the Script component, click Create New Script
5. Name it "PlatformRotator" and click Create

The script editor will open. Replace the default code with:

/**
 * PlatformRotator Script
 * Rotates the entity continuously around the Y axis
 *
 * @param {ScriptAPI} api - The script API for this entity
 */
export default (api) => {
  // Rotation speed in radians per second
  // 0.5 radians/sec ≈ 28.6 degrees/sec
  const rotationSpeed = 0.5;
 
  /**
   * Update function - called every frame
   * @param {number} dt - Delta time in seconds since last frame
   * @param {number} time - Total elapsed time in seconds
   */
  return (dt, time) => {
    // Get current rotation
    const rotation = api.rotation;
 
    // Increment Y rotation based on delta time
    // Multiplying by dt ensures rotation is frame-rate independent
    rotation.y += rotationSpeed * dt;
 
    // Apply the updated rotation back to the entity
    api.rotation = rotation;
  };
};

Save the script with Ctrl/Cmd + S and close the script editor.

Step 6: Test the Complete Scene#

Now let's see everything working together:

1. Press Ctrl/Cmd + P to enter Play Mode
2. The platform rotates slowly around the Y axis
3. The ball falls and bounces on the rotating platform
4. As the platform tilts, the ball rolls around due to physics!
5. Watch the ball's dynamic behavior as it interacts with the rotating surface

Step 7: Add Visual Polish#

Let's make the scene look better with lighting and materials:

Add a Directional Light#

1. Right-click in Hierarchy → Light → Directional Light
2. Set Position: (5, 10, 5)
3. Set Rotation: (-45, 45, 0) to angle it down toward the scene
4. In the Light component:
   • Enable castShadows for realistic shadows
   • Set intensity to 1.0
   • Set color to white or a warm tint

Add Environment Sky#

1. Right-click in Hierarchy → Create Empty
2. Rename it to "Environment"
3. Add an Environment component
4. In the Environment component:
   • Set preset to Sunset, Studio, or your preferred preset
   • Or set backgroundColor to a solid color

Improve Materials#

Make the platform look more interesting:

1. Select the Ground entity
2. In the Material component:
   • Set albedoColor to a neutral gray or blue
   • Set metalness to 0.2
   • Set roughness to 0.7

Step 8: Add More Balls (Challenge)#

Want to make it more fun? Add multiple balls:

1. Select the Ball entity in the Hierarchy
2. Press Ctrl/Cmd + D to duplicate it
3. Move the duplicate to a different position, e.g., (2, 6, 0)
4. Change its color to distinguish it from the first ball
5. Repeat to add 3-5 balls at different heights and positions

Enter Play Mode and watch the chaos as multiple balls bounce and roll on the rotating platform!

Step 9: Save Your Project#

1. Press Ctrl/Cmd + S to save the scene
2. Your project auto-saves to browser storage
3. For a backup, use File → Export Project to download a .webengine file

What You Learned#

Congratulations! In this tutorial you learned:

• How to create a new project from scratch
• How to add 3D primitives (Cube, Sphere) to your scene
• How to configure physics components (RigidBody, Collider)
• Understanding of dynamic vs fixed rigid bodies
• How to write a custom JavaScript script to control entity behavior
• Using the Script API to modify entity transforms
• How to test your scene in Play Mode
• How to add lighting and environment for visual polish
• How to duplicate entities and build complex scenes

Advanced Challenges#

Ready to take it further? Try these challenges:

• Variable Speed: Modify the script to speed up or slow down over time using time
• Reverse Direction: Make the platform change rotation direction every 5 seconds
• Ball Launcher: Create a script that applies an upward impulse to the ball when you press Space
• Color Change: Change the ball's color each time it bounces
• Obstacle Course: Add walls, ramps, and obstacles to create a complex physics playground

Next Steps#