⚠️ Beta State

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.

Loading 3D Models

Load and display a 3D model from a glTF file.

Introduction

While creating shapes from code is useful, most complex 3D scenes are built in modeling software like Blender and exported to formats like glTF (.gltf or .glb). pybevy can load these files directly.

This example replaces the primitive cube from the previous lesson with a more detailed "Flight Helmet" model.

from pybevy.prelude import *

The Setup System

The setup is very similar to the previous example. The key difference is how we spawn the main object.

asset_server.load_scene("models/FlightHelmet/FlightHelmet.gltf#Scene0"): This tells the asset server to load our model. The #Scene0 part specifies which scene to load from the file, as glTF files can contain multiple scenes.
commands.spawn(SceneRoot(...)): Instead of spawning a Mesh3d and MeshMaterial3d directly, we spawn a SceneRoot. This special component tells PyBevy to take the loaded scene data and spawn all of its entities into our world as children of this entity.

def setup(commands: Commands, asset_server: AssetServer):
    # Spawn a camera
    commands.spawn(
        Camera3d(),
        Transform.from_xyz(0.7, 0.7, 1.0).looking_at(Vec3(0.0, 0.3, 0.0), Vec3.Y),
    )
 
    # Spawn a light
    commands.spawn(DirectionalLight(shadows_enabled=True))
 
    # Spawn the glTF scene
    commands.spawn(
        SceneRoot(asset_server.load_scene("models/FlightHelmet/FlightHelmet.gltf#Scene0"))
    )

Running the App

When you run this, PyBevy will load the glTF file in the background. Once it's ready, the helmet will appear in the scene, fully textured and lit.

@entrypoint
def main(app: App) -> App:
    return app.add_plugins(DefaultPlugins).add_systems(Startup, setup)
 
if __name__ == "__main__":
    main().run()