moguri / pman

A Python package to help bootstrap and manage Panda3D applications

Panda3D Manager

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

Features

• 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

Installation

Use pip to install the panda3d-pman package:

pip install panda3d-pman

Usage

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

cd my_awesome_project
pman create .

pman can also create the directory for you:

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

Configuration

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).

Plugins

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:

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

Built-in Plugins

Below are plugins that ship with pman and their options.

native2bam

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.

Options

None

blend2bam

Supported file formats: blend

Converts Blender files to BAM files via blend2bam.

Options

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:

pip install -e .[test]

Then run the test suite with pytest:

pytest

Building Wheels

Install build:

pip install --upgrade build

and run:

python -m build

License

MIT

pman's Issues

Pman errors when asset_dir does not exist

pman assumes blend2bam is on PATH

This isn't a safe assumption to make.

Document renderers

• why have renderers (allows sharing render logic between editors and applications)
• how to specify a renderer for a project (config)
• describe what the none and basic renderers do
• describe making a renderer

Fix converting assets in sub-directories

From @rdb in IRC:

In pman, assets in nested subdirectories aren't converted unless the target directory is created.

Allow per-file export overrides for blend2bam

It would be nice to change blend2bam options (e.g., pipeline) on a per-file basis.

Set default-model-extension to .bam

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

Unable to run `python -m pman`

It would be useful to be able to run python -m pman when I'm using an installation of Python where I haven't added anything to my $PATH. This would require adding a __main__.py to the package, similar to Moguri/blend2bam#19.

Add PRC file(s) to project quick start

Add a README to the base template

It should include information on running the project (pman run). Doing this in MarkDown is probably fine.

Basic renderer uses a bad linear to sRGB approximation

Some options to fix this:

• Use the equation from ARB_framebuffer_sRGB
• Use panda3d.core.decode_srgb_float() to build a lookup table
• Switch back to using an sRGB framebuffer (add framebuffer-srgb #t to settings.prc)

Describe quick start project

Layout
PyTest
PyLint

Add better error when panda3d cannot be found

Use setuptools entry_points for conversion hooks

deploy-ng support

Modify setup.py
Add dist command
Add no installer option
Add platform select option
Error gracefully if deploy-ng is not supported

Exclude py files from distributions

Document configuration options

Make blender stuff an optional creation extra

This includes:

• blend1,blend2 in ignore list
• panda3d-blend2bam as an install requires (becomes extra requires)
• blend2bam in converters list

Add Texture Optimization

We can create Panda3D txo files for textures using Texture.write('name.txo'). We should add an option to convert textures to txo and to compress textures. Panda3D's texture class will automatically pick an appropriate compression format based on number of channels when using Texture.set_compression(Texture.CM_on). However, we will need to handle switching to CM_rgtc if we detect the texture is used for normal maps.

Add logging to default setup.py

Something like this should be added to pman/templates/setup.py:

'log_filename': '$USER_APPDATA/{}/output.log'.format(APP_NAME),
'log_append': False,

Application arguments for `pman run`

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

Replace blend to BAM conversion logic with blend2bam

Project link

Document builtin creation extras

running pman without arguments gives exception

It would probably be better if usage information were printed instead.

Traceback (most recent call last):
  File "/usr/bin/pman", line 10, in <module>
    sys.exit(main())
  File "/usr/lib/python3.7/site-packages/pman/cli.py", line 106, in main
    args = parser.parse_args()
  File "/usr/lib/python3.7/argparse.py", line 1749, in parse_args
    args, argv = self.parse_known_args(args, namespace)
  File "/usr/lib/python3.7/argparse.py", line 1781, in parse_known_args
    namespace, args = self._parse_known_args(args, namespace)
  File "/usr/lib/python3.7/argparse.py", line 2016, in _parse_known_args
    ', '.join(required_actions))
TypeError: sequence item 0: expected str instance, NoneType found

Invalid X-axis rotation & actor animation issues

All instanced objects and lights have 90 degrees of rotation added to the X-axis.
Bones and their animation are faulty too. Perhaps related?

blends.zip

Deleting an asset should also remove the built file

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.

Allow setting blend2bam --texture option

Missing documentation on how to create a git repo

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.

Setup travis to deploy to GH release and PyPI

Can't override auto_build in .pman.user

Can't override auto_build in .pman.user

pman mangles config file

Every time I run pman run, it appears to mangle my .pman file, changing this:

[build]
converters = ["native2bam", "blend2bam"]

to this:

[build]
converters = [ "native2bam", "blend2bam",]

This happens on Windows. This is a low priority issue for me.