1. Build A Scene in Python¶

Vuer uses a client-server architecture where you write Python code to control a 3D scene rendered in the browser. This guide will teach you the fundamentals of creating and managing 3D scenes.

By the end of this tutorial series, you’ll be able to create rich 3D scenes like this:

Expected scene: a complete scene with diverse geometry, materials, textures, and dramatic lighting

But we’ll start simple. In this guide, you’ll learn to build your first basic scene:

a simple box

Simple Box

How Vuer Works¶

Vuer uses a client-server architecture:

  • Python Server: Where you write your logic and control the scene

  • Web Client: Renders the 3D scene in the browser using Three.js

  • WebSocket: Real-time bidirectional communication

Vuer Architecture

Each browser connection creates an independent session, allowing multiple users to view different scenes simultaneously.

Creating a Scene¶

Here’s a complete example that creates a simple scene with box:

from vuer import Vuer, VuerSession
from vuer.schemas import Scene, Box, AmbientLight, DirectionalLight, OrbitControls

app = Vuer()

@app.spawn(start=True)
async def main(session: VuerSession):
    # Create a simple starting scene
    session.set @ Scene(
        # Center piece: simple box
        Box(
            args=[1.2, 1.2, 1.2],           # width, height, depth
            position=[0.4, 0.5, -2],          # x, y, z position
            rotation=[0, 0, 0],
            materialType="basic",
            key="simple-box",
        ),
        # Coordinate system: y-up (default)
        up=[0, 1, 0],
        grid=False,
    )

    # Keep the session alive
    await session.forever()

Understanding the Code:

  • app = Vuer(): Creates the server instance

  • @app.spawn(start=True): Binds the function to handle client connections and starts the server

  • session.set @ Scene(...): Initializes the 3D scene for this client

  • Box(...): Creates a 3D box with position, rotation, and material

  • await session.forever(): Keeps the connection alive

Run the script and you’ll see the simple box scene shown at the beginning:

Visit: https://vuer.ai?ws=ws://localhost:8012

Next Steps¶

Now that you can create basic scenes, learn about: