# 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. | <a href="/demos/start_triangle.html"><strong>Play</strong></a> | Web, Vulkan |
| [`start_bouncing_ball.py`](examples/start_bouncing_ball.md) | Colourful balls bouncing off screen edges. | <a href="/demos/start_bouncing_ball.html"><strong>Play</strong></a> | Web, Vulkan |
| [`start_rotating_cube.py`](examples/start_rotating_cube.md) | Simple 3D rotating cube using the node system. | <a href="/demos/start_rotating_cube.html"><strong>Play</strong></a> | Web, Vulkan |

## 2D Games

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

## 3D Games

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

## 2D Features

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| [`2d_sprite.py`](examples/2d_sprite.md) | PNG textures as 2D quads via draw_texture(). | <a href="/demos/2d_sprite.html"><strong>Play</strong></a> | Web, Vulkan |
| [`2d_tilemap.py`](examples/2d_tilemap.md) | GPU-rendered tilemap with multi-layer and player-follow camera. | <a href="/demos/2d_tilemap.html"><strong>Play</strong></a> | Web (TileMap rendering not yet supported on web.), Vulkan |
| [`2d_light.py`](examples/2d_light.md) | Coloured point lights with shadow-casting occluders. | <a href="/demos/2d_light.html"><strong>Play</strong></a> | Web (2D lighting not composited on web — only occluder outlines and light markers render.), Vulkan (2D lighting not composited on web.) |
| [`2d_navigation.py`](examples/2d_navigation.md) | A* pathfinding -- click-to-move character on a grid. | <a href="/demos/2d_navigation.html"><strong>Play</strong></a> | Web, Vulkan |
| [`2d_ninepatch.py`](examples/2d_ninepatch.md) | 9-slice sprite scaling via draw_texture_region(). | <a href="/demos/2d_ninepatch.html"><strong>Play</strong></a> | Web, Vulkan |
| [`2d_joints.py`](examples/2d_joints.md) | 2D physics joints (pendulum chain). | <a href="/demos/2d_joints.html"><strong>Play</strong></a> | Web, Vulkan |
| [`2d_path_follow.py`](examples/2d_path_follow.md) | Path following with Curve2D and PathFollow2D. | <a href="/demos/2d_path_follow.html"><strong>Play</strong></a> | Web, Vulkan |
| [`2d_trail.py`](examples/2d_trail.md) | Trail rendering behind moving objects. | <a href="/demos/2d_trail.html"><strong>Play</strong></a> | Web, Vulkan |

## 3D Features

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| [`3d_lighting.py`](examples/3d_lighting.md) | Directional, point, and spot lights. | <a href="/demos/3d_lighting.html"><strong>Play</strong></a> | Web, Vulkan |
| `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`](examples/3d_fog.md) | Fog and colour grading via WorldEnvironment. | <a href="/demos/3d_fog.html"><strong>Play</strong></a> | Web (Fog renders differently than desktop (no tonemap exposure on web).), Vulkan |
| [`3d_ibl.py`](examples/3d_ibl.md) | Image-based lighting with metallic spheres. | <a href="/demos/3d_ibl.html"><strong>Play</strong></a> | Web (Skybox and image-based lighting not yet supported on web.), Vulkan |
| [`3d_particles.py`](examples/3d_particles.md) | CPU + GPU particle effects with sub-emitters, collision, trails. | <a href="/demos/3d_particles.html"><strong>Play</strong></a> | Web (No particles render on web.), Vulkan (GPUParticles3D not rendered on web; CPU emitters still work.) |
| `3d_model_viewer.py` | Load glTF models with PBR textures and orbit camera. | | Vulkan |
| [`3d_animation_blend.py`](examples/3d_animation_blend.md) | BlendSpace1D, crossfade, and keyframe events. | <a href="/demos/3d_animation_blend.html"><strong>Play</strong></a> | Web, Vulkan |
| `3d_motion_blur.py` | Camera-based motion blur. | | Vulkan |
| [`3d_multimesh.py`](examples/3d_multimesh.md) | 1600 instanced cubes via MultiMeshInstance3D. | <a href="/demos/3d_multimesh.html"><strong>Play</strong></a> | Web, Vulkan |
| [`3d_noise.py`](examples/3d_noise.md) | Perlin, Simplex, Value, and Cellular noise side by side. | <a href="/demos/3d_noise.html"><strong>Play</strong></a> | Web, Vulkan |
| `3d_picking.py` | Mouse picking -- click cubes to change colour. | | — |
| `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_mesh_parenting.py`](examples/3d_mesh_parenting.md) | MeshInstance3D rendering inside different parent node types. | <a href="/demos/3d_mesh_parenting.html"><strong>Play</strong></a> | Web |
| `3d_text.py` | Text textures on 3D geometry + MSDF overlay. | | — |
| [`3d_csg.py`](examples/3d_csg.md) | CSG boolean operations (union, subtract, intersect). | <a href="/demos/3d_csg.html"><strong>Play</strong></a> | Web, Vulkan |
| [`3d_joints.py`](examples/3d_joints.md) | 3D physics joints (pin, hinge). | <a href="/demos/3d_joints.html"><strong>Play</strong></a> | Web (HingeJoint3D angular limits not enforced — door rotates full 360°.), Vulkan (HingeJoint3D angular limits not enforced.) |
| [`3d_navigation.py`](examples/3d_navigation.md) | 3D pathfinding with NavigationAgent3D. | <a href="/demos/3d_navigation.html"><strong>Play</strong></a> | Web, Vulkan |
| `3d_skeletal.py` | Skeletal animation with bone deformation. | | — |
| `3d_path_follow.py` | 3D path following (camera rail). | | — |
| `3d_custom_shader.py` | ShaderMaterial API preview — visual effect blocked on renderer integration. | | Vulkan (ShaderMaterial not yet applied on web — shapes render with default materials.) |
| `3d_feature_showcase.py` | Interactive 3D showcase: PBR, collisions, raycasting, DebugDraw. | | — |

## UI

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| [`ui_widget_showcase.py`](examples/ui_widget_showcase.md) | Comprehensive UI showcase with DemoRunner. | <a href="/demos/ui_widget_showcase.html"><strong>Play</strong></a> | Web |
| `ui_text_input.py` | Character input, focus routing, and scissor clipping. | | — |
| [`ui_menus.py`](examples/ui_menus.md) | MenuBar with PopupMenu dropdowns and z-ordering. | <a href="/demos/ui_menus.html"><strong>Play</strong></a> | Web |
| [`ui_tree.py`](examples/ui_tree.md) | Live scene tree inspector with expand/collapse. | <a href="/demos/ui_tree.html"><strong>Play</strong></a> | Web |
| `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). | | — |

## Debug

| Example | Description | Demo | Platforms |
|---------|-------------|------|-----------|
| `debug_draw.py` | Wireframe boxes, spheres, axes, and rays. | | — |
| `debug_overlay.py` | F3 debug overlay with feature cycling. | | — |

```{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_pad_grid
examples/game_planet_explorer
examples/game_deep_sea_aquarium
examples/2d_sprite
examples/2d_tilemap
examples/2d_light
examples/2d_navigation
examples/2d_ninepatch
examples/2d_joints
examples/2d_path_follow
examples/2d_trail
examples/3d_lighting
examples/3d_fog
examples/3d_ibl
examples/3d_particles
examples/3d_animation_blend
examples/3d_multimesh
examples/3d_noise
examples/3d_mesh_parenting
examples/3d_csg
examples/3d_joints
examples/3d_navigation
examples/ui_widget_showcase
examples/ui_menus
examples/ui_tree
```