Quick Start
PyBevy is in an early and experimental stage. The API is incomplete, subject to breaking changes without notice, and you should expect bugs. Many features are still under development.
Get started with pybevy in minutes. This guide will walk you through installation, creating your first 3D scene, and experiencing the power of hot-reloading.
Prerequisites
- Python 3.12+ installed on your system
- pip for installing packages
Setting Up a Virtual Environment (Recommended)
Before installing, it's highly recommended to create a virtual environment. This isolates your project dependencies and prevents conflicts with other Python projects on your system.
1. Create the environment
This creates a .venv folder in your project directory.
2. Activate the environment
On macOS and Linux:
On Windows:
Your shell prompt will usually change to indicate that the virtual environment is active.
Installation
Pre-compiled wheels are provided for major platforms (Windows, macOS, Linux), so installation is straightforward:
This will install the latest version of pybevy and all its dependencies.
Your First 3D Scene
Let's create a simple 3D scene with a cube sitting on a circular platform. Create a new file called main.py:
Running with Hot-Reload
The magic of pybevy is its hot-reload capability. Instead of running your script directly, use the pybevy watch command:
This starts your application in hot-reloading mode. Now try this:
- Keep the application window open
- Open
main.pyin your editor - Change the cube's color, for example:
- Save the file
- Watch the cube change color instantly without restarting! 🎉
Hot-Reload Tip: This feature dramatically accelerates development. Tweak parameters, adjust positions, change colors, and see results instantly without the tedious restart cycle.
Understanding the Code
The App Structure
Every pybevy application starts with an @entrypoint-decorated function that receives an App. You add plugins (like DefaultPlugins for windowing, rendering, input) and systems (functions that run at specific points in the game loop).
Systems
Systems are Python functions with type-hinted parameters. PyBevy automatically provides the resources you need based on the type hints. Commands lets you spawn entities, ResMut[Assets[...]] provides mutable access to asset stores for meshes and materials.
Entities and Components
Entities are created with commands.spawn(). You pass components (like Mesh3d, Transform) that define what the entity is and does. This is the core of Bevy's Entity Component System (ECS) architecture.
Want to see more? Check out the Learn section for detailed tutorials on building applications with PyBevy.
Next Steps
Troubleshooting
Import Errors
Make sure you've installed pybevy: pip install pybevy --upgrade
Window Doesn't Appear
Ensure you're using Python 3.12 or later and that your graphics drivers are up to date.
Hot-Reload Not Working
Verify you're using pybevy watch instead of running Python directly. Check the terminal for any error messages.
Crashes or Bugs
PyBevy is in beta. Report issues on GitHub.
Ready to Build Something Amazing?
You've just scratched the surface of what's possible with pybevy. Whether you're building games, simulations, or visualizations, you now have the tools to iterate quickly and leverage both Python's ecosystem and Bevy's performance.
Happy coding! 🚀