A Python package to help bootstrap and manage Panda3D applications

Moguri, updated 🕥 2022-11-25 05:46:42

Build Status Panda3D Versions

Panda3D Manager

pman is a Python package to help bootstrap and manage Panda3D applications.


  • Project quick-start
  • Automatic asset conversion
  • Automatically adds export directory to the model path
  • Convenient CLI for running and testing applications
  • Plugin system for expanding functionality


Use pip to install the panda3d-pman package:

bash pip install panda3d-pman


Quick start a project with pman create. If you already have a directory for your project:

bash cd my_awesome_project pman create .

pman can also create the directory for you:

bash pman create my_awesome_project

In addition to the create command, pman has the following commands:

  • update - re-run project creation logic on the project directory
  • help - display usage information
  • build - convert all files in the assets directory and place them in the export directory
  • run - run the application by calling python with the main file
  • test - run tests (shortcut for python setup.py test)
  • dist - create distributable forms of Panda3D applications (requires Panda3D 1.10+)
  • clean - remove built files


pman will look for any of the following files in the project root: * pyproject.toml * .pman * .pman.user

This configuration uses TOML for markup. The .pman or pyproject.toml configuration file is project-wide and should be checked in under version control.

Another, per-user configuration file also exists at the project root as .pman.user. This configuration file stores user settings and should not be checked into version control.

Settings in .pman.user take precedence over settings in .pman and both take precedence over pyproject.toml. If a setting is not defined in a config file, a default value will be used.

When storing settings in pyproject.toml, section names should be pre-pended with tool.pman.. For example, general options would be under tool.pman.general.

General Options

Section name: general

|option|default|description| |---|---|---| |name|"Game"|The project name. For now this is only used for naming the built application in the default setup.py.| |plugins|["DefaultPlugins"]|A list of plugins to load and use. "DefaultPlugins" is expanded to the current default plugins, which makes it easier to enable additional plugins.|

Build Options

Section name: build

|option|default|description| |---|---|---| |asset_dir|"assets/"|The directory to look for assets to convert.| |export_dir|".built_assets/"|The directory to store built assets.| |ignore_patterns|[]|A case-insensitive list of patterns. Files matching any of these patterns will not be ignored during the build step. Pattern matching is done using the fnmatch module

Run Options

Section name: run

|option|default|description| |---|---|---| |main_file|"main.py"|The entry-point to the application.| |extra_args|""|A string of extra arugments that are append to the invocation of main_file.| |auto_build|true|If true, automatically run builds as part of running the application (via pman.shim.init). This is disabled in deployed applications.|

Distribution Options

Section name: dist

|option|default|description| |---|---|---| |build_installers|true|Whether or not to build installers for built applications (i.e., run bdist_apps).|


To extend functionality, pman offers a plugin system. These plugins are found by pman using entry points.

Default Plugins

By default, pman loads the following plugins:

  • native2bam
  • blend2bam

When specifying plugins, a special DefaultPlugins string is available that expands to pman's current default plugins. For example, to use MyAwesomePlugin in addition to pman's default plugins use:

toml [General] plugins = ['DefaultPlugins', 'MyAwesomePlugin']

Built-in Plugins

Below are plugins that ship with pman and their options.


Support file formats: egg, egg.pz, obj (and mtl), fbx, dae, ply

Loads the file into Panda and saves the result out to BAM. This relies on Panda's builtin file loading capabilities.




Supported file formats: blend

Converts Blender files to BAM files via blend2bam.


Section name: blend2bam

|option|default|description| |---|---|---| |material_mode|"pbr"|Specify whether to use the default Panda materials ("legacy") or Panda's new PBR material attributes ("pbr"). This is only used by the "gltf" pipeline; the "egg" always uses "legacy".| |physics_engine|"builtin"|The physics engine that collision solids should be built for. To export for Panda's builtin collision system, use "builtin." For Bullet, use "bullet." This is only used by the "gltf" pipeline; the "egg" pipeline always uses "builtin."| |pipeline|"gltf"|The backend that blend2bam uses to convert blend files. Go here for more information.|

Running Tests

First install the project in editable mode along with test extras:

bash pip install -e .[test]

Then run the test suite with pytest:

bash pytest

Building Wheels

Install build:

bash pip install --upgrade build

and run:

bash python -m build




Allow for local, per-project plugins

opened on 2022-09-20 15:25:23 by zimLeTux

Edit: I am currently reworking this as I have realized this relies on a dist-info present in the working directory, which is not the wanted behaviour at all !

This small change allow to have custom converters in a given project. It is more like a proof of concept and should probably be reworked/cleaned up. Project plugins should be located in a "plugins" directory.

Current limitations: * the plugin class name must be the same name as the file, but starting with a capital letter ; * plugins can only be located in the plugins subdirectory, and nested subdirs are not yet possible ;

Some use-cases: * Have a tool to create NPC (both mesh and in-game properties, or even scripts) and export them automatically ; * Mesh generation based on parametric files ; * Conversion of table-based data (for instance an ODS table listing all the items or monsters) to a more game-friendly format (XML, json, SQLite...) * ...

Deleting an asset should also remove the built file

opened on 2020-09-22 20:53:40 by rdb

When deleting (or moving, renaming) an asset, the built file remains in the built assets directory. This takes up extra space, but also hides errors when I forget to change the path in a loadModel call in my code.

Missing documentation on how to create a git repo

opened on 2020-09-20 13:23:23 by rdb

A quick grep through the source code shows that creating a gitignore automatically is possible, but I can't find anywhere in the documentation explaining how to do this. I think this should be a very common need.

Allow setting blend2bam --texture option

opened on 2020-02-24 17:49:38 by Moguri None

Application arguments for `pman run`

opened on 2019-04-26 04:35:40 by Schwarzbaer

pman run should allow for arguments to be passed to the application, e.g.: pman run -- app_arg invokes main.py app_arg

Set default-model-extension to .bam

opened on 2019-04-01 17:30:18 by Moguri

Also need to default to appending '.bam' instead of replacing the extension


v0.14 2022-04-23 02:12:04


  • Fix config error with pman create


  • Fix "Running main file" f-string


  • Fix error where blend2bam could be called with no source assets

v0.13 2020-10-16 03:11:16

This release includes quite a few potentially breaking changes


  • Add main.py to allow using python -m pman
  • Stop re-writing .pman config file after every call to `pman
  • Remove renderers
  • Remove special venv logic
  • Add editorconfig file
  • Switch from format() to f-strings
  • Add control over verbose prints


  • Enabled by default
  • Default to PBR materials
  • Support setting the --animations flag
  • Allow matching against basenames for overrides (instead of just full paths)
  • Do not expect to locate blend2bam on the PATH

v0.12.1 2020-09-05 19:26:54

  • Fix error when parsing blend2bam version with patch part

v0.12 2020-09-01 01:24:29

  • Fail on building if blend2bam fails
  • Allow matching against file paths for ignore patterns
  • Add quotes to file paths when calling blend2bam to avoid splitting on Windows

v0.11 2020-04-19 03:21:09


  • Use dicts instead of OrderedDicts for config now that order is preserved since Python 3.6
  • Add "blender" key to defaults to prevent errors if .pman.user does not exist


  • Require Python >= 3.6
  • List Python 3.8 as supported
  • blend2bam is no longer option to make installation more straight-forward

v0.10 2020-03-17 02:07:25


  • Move material_mode and physics_engine from general to a new blend2bam section


  • Fix running create_blender() if the project config layer does not have build options


  • Add support for new --pipeline option


  • Make sure the render stub is created if the assets directory does not exist


  • Fix error code when running pman test

New Project Template

  • Add "base" as an additional builtin for PyLint
  • Lock down PyLint version in setup.py
  • Do not explicitly exclude *.py or __py_cache__/** in setup.py (this is handled by build_apps already)
Mitchell Stokes
GitHub Repository

panda3d panda3d-game-engine game-development gamedev gamedev-tool