Initial commit

2025-11-30 09:05:02 +08:00
commit 265175ed82
23 changed files with 3329 additions and 0 deletions
--- a/docs/tutorials/basics/setting-a-scene.md
+++ b/docs/tutorials/basics/setting-a-scene.md
@@ -0,0 +1,111 @@
+# Setting Up Your First Scene in Vuer
+
+## Overview
+This tutorial guides you through creating a basic 3D scene using Vuer, a Python framework for building interactive 3D visualizations. The example demonstrates how to establish a server, add scene components, lighting, and interactive elements.
+
+## Step 1: Initialize the Vuer Server
+
+Begin by importing and instantiating the application:
+
+```python
+from vuer import Vuer
+
+app = Vuer(
+    queries=dict(
+        reconnect=True,
+        collapseMenu=True,
+    ),
+)
+```
+
+The queries parameter configures the scene via URL parameters. Launch the server with `app.run()`, which produces output showing the local connection URL.
+
+## Step 2: Create an Async Session
+
+The framework uses WebSocket sessions to connect clients with the Python server. Bind an async function to handle each session using the spawn decorator:
+
+```python
+@app.spawn
+async def session(sess: VuerSession):
+    print("Example: we have started a websocket session!")
+```
+
+## Step 3: Build Your Scene
+
+Within the session, construct the scene by setting Scene objects containing various components:
+
+```python
+sess.set @ Scene(
+    Box(
+        args=[0.1, 0.1, 0.1, 101, 101, 101],
+        position=[0, 0.05, 0],
+        color="red",
+        materialType="standard",
+        material=dict(color="#23aaff"),
+        key="fox-1",
+    ),
+    ...
+)
+```
+
+## Key Components
+
+### Box
+A 3D cube primitive with position, color, and material properties.
+
+### SpotLight
+Provides directional lighting within the scene, wrapped in a Movable component to allow interactive repositioning.
+
+### Movable
+Enables user interaction, allowing scene elements to be dragged and manipulated in the 3D viewport.
+
+## Essential Pattern
+
+Always include `await asyncio.sleep(0.0)` after scene modifications to ensure proper asynchronous handling and client synchronization.
+
+## Complete Example
+
+```python
+from vuer import Vuer
+from vuer.schemas import Scene, Box, SpotLight, Movable
+import asyncio
+
+app = Vuer(
+    queries=dict(
+        reconnect=True,
+        collapseMenu=True,
+    ),
+)
+
+@app.spawn
+async def session(sess):
+    print("Example: we have started a websocket session!")
+
+    sess.set @ Scene(
+        Box(
+            args=[0.1, 0.1, 0.1, 101, 101, 101],
+            position=[0, 0.05, 0],
+            color="red",
+            materialType="standard",
+            material=dict(color="#23aaff"),
+            key="fox-1",
+        ),
+        Movable(
+            SpotLight(
+                intensity=3.0,
+                distance=10.0,
+                decay=0.0,
+                position=[0, 2, 0],
+                key="spotlight",
+            ),
+        ),
+    )
+
+    await asyncio.sleep(0.0)
+
+app.run()
+```
+
+## Source
+
+Documentation: https://docs.vuer.ai/en/latest/tutorials/basics/setting_a_scene.html