# Examples Gallery

All examples live in `packages/graphics/examples/`. Run any example with:

```bash
uv run python packages/graphics/examples/<filename>.py
```

## Getting Started

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| [`start_triangle.py`](examples/start_triangle.md) | Minimal 2D triangle via draw() override. | [**Play**](../demos/start_triangle.html) | Web, Vulkan |
| [`start_bouncing_ball.py`](examples/start_bouncing_ball.md) | Colourful balls bouncing off screen edges. | [**Play**](../demos/start_bouncing_ball.html) | Web, Vulkan |
| [`start_rotating_cube.py`](examples/start_rotating_cube.md) | Simple 3D rotating cube using the node system. | [**Play**](../demos/start_rotating_cube.html) | Web, Vulkan |

## 2D Games

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| [`game_pong.py`](examples/game_pong.md) | Two-player Pong with paddles, ball, and score. | [**Play**](../demos/game_pong.html) | Web (No audio), Vulkan |
| [`game_platformer.py`](examples/game_platformer.md) | CharacterBody2D with gravity, jump, and platforms. | [**Play**](../demos/game_platformer.html) | Web, Vulkan |
| [`game_asteroids2d.py`](examples/game_asteroids2d.md) | Classic arcade game with wrap-around physics. | [**Play**](../demos/game_asteroids2d.html) | Web, Vulkan |
| [`game_spaceinvaders2d.py`](examples/game_spaceinvaders2d.md) | Rows of enemies, bullets, and wave progression. | [**Play**](../demos/game_spaceinvaders2d.html) | Web, Vulkan |
| [`game_tictactoe/game.py`](examples/game_tictactoe.md) | Classic two-player game built with UI widgets. | [**Play**](../demos/game_tictactoe.html) | Web, Vulkan |
| [`games/dungeon_explorer/main.py`](examples/dungeon_explorer.md) | Top-down dungeon crawler with procedural generation, loot, skill trees, and boss fights. | [**Play**](../demos/dungeon_explorer.html) | Web |

## 3D Games

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| [`game_asteroids3d.py`](examples/game_asteroids3d.md) | Top-down arcade game with 3D objects. | [**Play**](../demos/game_asteroids3d.html) | Web, Vulkan |
| [`game_spaceinvaders3d.py`](examples/game_spaceinvaders3d.md) | Classic arcade game with 3D meshes. | [**Play**](../demos/game_spaceinvaders3d.html) | Web, Vulkan |
| [`game_physics_sandbox.py`](examples/game_physics_sandbox.md) | Visual demo of the SimVX physics engine. | [**Play**](../demos/game_physics_sandbox.html) | Web, Vulkan |
| `game_pad_grid.py` | Pad instrument with recording, loop, and training modes. | | — |
| [`game_planet_explorer.py`](examples/game_planet_explorer.md) | Infinite procedural flyover with terrain, day/night cycle, and weather. | [**Play**](../demos/game_planet_explorer.html) | Web, Vulkan |
| `game_tictactoe3d/game.py` | 3D board with animated X and O pieces. | | — |
| `game_deep_sea_aquarium/main.py` | Bioluminescent underwater world with boids, music, and bloom. | | — |

## 2D Features

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| `2d_sprite.py` | PNG textures as 2D quads via draw_texture(). | | — |
| `2d_tilemap.py` | GPU-rendered tilemap with multi-layer and camera panning. | | — |
| `2d_light.py` | Coloured point lights with shadow-casting occluders. | | — |
| `2d_navigation.py` | A* pathfinding -- click-to-move character on a grid. | | — |
| `2d_ninepatch.py` | 9-slice sprite scaling via draw_texture_region(). | | — |
| `2d_joints.py` | 2D physics joints (pendulum chain). | | — |
| `2d_path_follow.py` | Path following with Curve2D and PathFollow2D. | | — |
| `2d_trail.py` | Trail rendering behind moving objects. | | — |

## 3D Features

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| `3d_lighting.py` | Directional, point, and spot lights. | | — |
| `3d_shadows.py` | Cascade shadow maps with debug visualisation. | | — |
| `3d_point_shadows.py` | Point and spot light shadow maps. | | — |
| `3d_ssao.py` | Screen-space ambient occlusion. | | — |
| `3d_fog.py` | Fog and colour grading via WorldEnvironment. | | — |
| `3d_ibl.py` | Image-based lighting with metallic spheres. | | — |
| `3d_particles.py` | CPU + GPU particle effects with sub-emitters, collision, trails. | | — |
| `3d_model_viewer.py` | Load glTF models with PBR textures and orbit camera. | | — |
| `3d_animation_blend.py` | BlendSpace1D, crossfade, and keyframe events. | | — |
| `3d_motion_blur.py` | Camera-based motion blur. | | — |
| `3d_multimesh.py` | 1600 instanced cubes via MultiMeshInstance3D. | | — |
| `3d_noise.py` | Perlin, Simplex, Value, and Cellular noise side by side. | | — |
| `3d_picking.py` | Mouse picking -- click cubes to change colour. | | — |
| `3d_picking_grid.py` | 4x4 grid picking -- click to toggle green/red. | | — |
| `3d_raycast.py` | Ray grid with animated cubes and single/multi-hit toggle. | | — |
| `3d_render_layers.py` | Object visibility via render layer bitmasks. | | — |
| `3d_textured_cubes.py` | Checkerboard textures on cubes. | | — |
| `3d_static_body_rendering.py` | MeshInstance3D inside different physics body types. | | — |
| `3d_track_rendering.py` | Track rendering with StaticBody3D segments. | | — |
| `3d_gizmo.py` | Editor gizmo interaction demo. | | — |
| `3d_text.py` | Text textures on 3D geometry + MSDF overlay. | | — |
| `3d_csg.py` | CSG boolean operations (union, subtract, intersect). | | — |
| `3d_joints.py` | 3D physics joints (pin, hinge). | | — |
| `3d_navigation.py` | 3D pathfinding with NavigationAgent3D. | | — |
| `3d_skeletal.py` | Skeletal animation with bone deformation. | | — |
| `3d_path_follow.py` | 3D path following (camera rail). | | — |
| `3d_custom_shader.py` | Custom ShaderMaterial with animated uniforms. | | — |

## UI

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| `ui_widgets.py` | Widget rendering, input, focus, and signals. | | — |
| `ui_widget_showcase.py` | Comprehensive UI showcase with DemoRunner. | | — |
| `ui_text_input.py` | Character input, focus routing, and scissor clipping. | | — |
| `ui_menus.py` | MenuBar with PopupMenu dropdowns and z-ordering. | | — |
| `ui_tree.py` | Live scene tree inspector with expand/collapse. | | — |
| `ui_theme_demo.py` | StyleBox theming system. | | — |
| `ui_terminal.py` | Interactive terminal emulator running bash. | | — |
| `ui_audio.py` | Audio -- generate and play test tones. | | — |
| `ui_i18n.py` | Translated text and locale switching. | | — |
| `ui_undo.py` | Undo/Redo with Ctrl+Z / Ctrl+Shift+Z. | | — |
| `ui_gestures.py` | Touch gesture recognition (tap, swipe, pinch, rotate). | | — |

## Rendering Internals

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| `render_raw_vulkan.py` | Raw Vulkan -- vertex buffers, transforms, SSBOs. | | — |
| `render_wave_grid.py` | 10,000-cube wave grid -- instanced rendering stress test. | | — |

## Debug

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| `debug_draw.py` | Wireframe boxes, spheres, axes, and rays. | | — |
| `debug_overlay.py` | F3 debug overlay with feature cycling. | | — |
| `debug_coord.py` | Crosshair at mouse position with button hit zones. | | — |
| `debug_feature_showcase.py` | Interactive engine feature showcase. | | — |
| `debug_ide_layout.py` | IDE panel layout and docking. | | — |
| `debug_3d_basic.py` | Basic 3D rendering from multiple camera angles. | | — |
| `debug_text_quality.py` | MSDF vs FreeType bitmap text rendering comparison. | | — |

```{toctree}
:hidden:

examples/start_triangle
examples/start_bouncing_ball
examples/start_rotating_cube
examples/game_pong
examples/game_platformer
examples/game_asteroids2d
examples/game_spaceinvaders2d
examples/game_tictactoe
examples/dungeon_explorer
examples/game_asteroids3d
examples/game_spaceinvaders3d
examples/game_physics_sandbox
examples/game_planet_explorer
```