Panda3D

Common errors

• ImportError: No module named direct.showbase.ShowBase

  cause Panda3D's Python modules are not found in the Python path. This can occur if Panda3D was not installed correctly, or if a different Python interpreter (not the one configured for Panda3D) is being used.
  fix Ensure `panda3d` is installed via `pip install panda3d`. If using a system-wide Python, verify that `PYTHONPATH` or `LD_LIBRARY_PATH` (on Linux) includes the Panda3D installation directories. On Windows, older SDKs required using their bundled Python or copying a `.pth` file.

• Exception: No graphics pipe is available! Have you included a render plug-in, such as `pandagl`, in your setup.py file?

  cause This error typically occurs when Panda3D cannot find a suitable graphics API (e.g., OpenGL, DirectX) to render the scene. This can happen in packaged applications (`build_apps`) if render plugins are not included or if the system lacks necessary drivers.
  fix Ensure your environment has up-to-date graphics drivers. When deploying applications with `build_apps`, explicitly include necessary render plug-ins (e.g., `'pandagl'`) in your `setup.py` file. For debugging, use a non-optimized build (`'use_optimized_wheels': False`).

• Application window closes right away when run (especially after packaging with `build_apps`).

  cause When packaging with `build_apps`, console output might be suppressed, making it difficult to see runtime errors. The application crashes before the window can fully initialize or due to a missing dependency.
  fix For `build_apps` applications, specify a log file via `log_filename` in `setup.py` to capture error messages. Debug using a non-optimized build. Common causes are missing files or Python version incompatibilities (e.g., Python 3.8.10 fixed in Panda3D 1.10.10).

• KeyError when trying to play an animation on a model.

  cause This usually indicates that the model file (e.g., `.egg`) does not contain animation data or the specified animation name is incorrect. Animated models require both geometry and a skeleton to be exported together.
  fix Verify that the model was correctly exported with animation data. Check the animation names (case-sensitive) used in your code against those embedded in the model. Consult the Panda3D manual for details on exporting animated models.

Warnings

• deprecated The use of `import direct.directbase.DirectStart` and `from pandac.PandaModules import *` is deprecated.
  Fix: Replace `import direct.directbase.DirectStart` with `from direct.showbase.ShowBase import ShowBase` and instantiate `ShowBase` explicitly. Replace `from pandac.PandaModules import *` with specific imports from `panda3d.core` and other relevant `panda3d.*` modules.
• gotcha Performance can suffer significantly from common pitfalls such as excessive meshes, too many state changes, frequent text updates, and performing complex Python calculations in the main loop.
  Fix: Optimize 3D models (coalesce meshes), minimize state changes, update text sparingly, and offload heavy Python computations to C++ plugins or optimized Panda3D functions. Utilize Panda3D's PStats tool for profiling to identify bottlenecks.
• gotcha Cg shaders, including the shader generator and `CommonFilters`, do not work on ARM-based machines (e.g., Apple Silicon) due to the unavailability of the NVIDIA Cg Toolkit for arm64 architecture. Cg will be deprecated in future versions.
  Fix: Migrate to GLSL shaders for better compatibility and future-proofing on ARM platforms.
• gotcha When loading models or specifying file paths in Panda3D functions, use Unix-style forward slashes (`/`) even on Windows, and avoid drive letter prefixes like `C:`. Panda3D's internal filename conventions require this for portability.
  Fix: Convert Windows-style paths (e.g., `C:\models\my_model.egg`) to Panda3D's Unix-style paths (e.g., `/c/models/my_model.egg`) or use `Filename.fromOsSpecific()` for conversion.

Install

• pip install panda3d Install Panda3D

Imports

• ShowBase
  wrong:

  import direct.directbase.DirectStart

  correct:

  from direct.showbase.ShowBase import ShowBase

  `DirectStart` was deprecated in Panda3D 1.9.0 and replaced by explicit `ShowBase` instantiation. The `DirectStart` import implicitly created a `ShowBase` instance, which is now discouraged for cleaner code.
• core classes (e.g., WindowProperties)
  wrong:

  from pandac.PandaModules import *

  correct:

  from panda3d.core import WindowProperties

  Using `pandac.PandaModules` is discouraged since Panda3D 1.10.0. Specific modules like `panda3d.core`, `panda3d.egg`, etc., should be imported directly for better clarity and compatibility.

Quickstart

This minimal example initializes Panda3D, creates a window with specified dimensions, and disables the default mouse camera control. It prints a message and then enters the main game loop (`app.run()`), which keeps the window open until closed by the user.

from direct.showbase.ShowBase import ShowBase
from panda3d.core import WindowProperties

class MyApp(ShowBase):
    def __init__(self):
        ShowBase.__init__(self)

        # Set window properties
        props = WindowProperties()
        props.setSize(1024, 768)
        self.win.requestProperties(props)

        # Disable default mouse camera control
        self.disableMouse()

        print("Panda3D window opened. Close the window to exit.")

app = MyApp()
app.run()