Developer’s Guide

To Begin

1. Begin by forking the Writing3D repo on Github.

2. Download and install Blender on your system.

   Warning

   Writing3D has only been tested with Blender 2.79. You are welcome to try a later version and let us know the results, but only 2.79 is supported at the moment.

3. Clone your fork of the repo to your computer, and checkout the develop branch.

4. Create a configuration file in your home directory called .w3d.json with the following fields:

   • Blender executable: The (absolute) path to your Blender executable.
   • Blender player executable: The (absolute) path to your Blender player executable.

You should now be able to add and commit changes to your local repo and push those changes to your fork. When you’re ready to share those changes with the rest of the Writing3D community, open a pull request against the develop branch of the Writing3D repo.

Samples

The Writing3D repo includes sample projects written both in archival xml format and as Python scripts. To test that your install is working properly, try running at least some of these samples.

Python Samples

To make it easier to run the Python samples, a script called w3dpy.sh or w3dpy.bat is included in the scripts directory for your platform. Execute this script with the Python sample file as argument. Example (for Linux):

$ cd Writing3D
$ ./scripts/Linux/w3dpy.sh samples/link_sample.py

XML Samples

To run xml samples, we use cwapp.sh or cwapp.bat from the script directory for your platform. These scripts take two arguments: either desktop or desktopfull to run in windowed or fullscreen mode respectively and the name of the xml file to run. Example (for Linux):

$ cd Writing3D
$ ./scripts/Linux/cwapp.sh desktop samples/xml_samples/random_sample.xml

Documentation and Getting Help

pyw3d Documentation

Complete documentation of all classes, methods, functions, etc. of the pyw3d module is available here:

• pyw3d Documentation
  • pyw3d Classes
  • pyw3d Objects
  • pyw3d Groups
  • pyw3d Sounds
  • pyw3d Actions
  • pyw3d Timelines
  • pyw3d Event Triggers
  • Errors
  • Complete Reference

Getting Help

If you have questions on where to find information about something related to Writing3D, please feel free to submit a ticket to the issue tracker with the first word “Documentation”. That way we can make it easier for the next person to find what they need. You should also feel free to contact the maintainer directly via Twitter (@whimsicalilk).

Style Guide

Writing3D code should be PEP 8 compliant. This ensures both maintainability and extensibility (through readability), two of the major goals of this project. It should also contain docstrings for Sphinx-style autodocing. If you are absolutely unable to follow PEP 8 or document your code, you can submit a pull request anyway, but it may be some time before the maintainer can revise your code and integrate it into the main codebase.

Features which introduce new Writing3D functionality should in general inherit from the W3DFeature class and must implement fromXML and toXML methods for creating an archival XML format.