-
Notifications
You must be signed in to change notification settings - Fork 129
Development
A basic understanding of Github, Git and blender python API is required.
-
Make sure you have the following:
-
Text Editor / IDE of your choice for python.
e.g Sublime Text, Visual Studio code, Pycharm etc.
-
Github account.
-
Navigate to this project's repository.
-
Fork the project.
-
Navigate to the newly created fork in your Github account.
-
Clone the project into your local machine.
The source code for building tool is laid out in an obvious manner.
assets/
docs/
tests/
btools/
__init__.py
.building/
.window/
__init__.py
window.py
window_ops.py
window_props.py
window_types.py
...
__init__.py
generic.py
...
.road/
road/
__init__.py
.utils/
util_common.py
util_geometry.py
util_material.py
util_mesh.py
...
The main addon folder is named btools
.
At the root of the btools
folder __init__.py
can be found which serves as the addon initialization. You can expect to find:
- The addon
bl_info
used by Blender's Python API for addon meta data. - UI definition for the addon's main panels.
-
register
andunregister
functions.
Also in the btools
folder is a utils
folder. This contains a collection of useful, reusable modules and functions. Great effort has been taken to keep related functionality in common files.
Finally, the guts of the addon are in the folders building
and road
. These folders contain collections of modules alongside some python files. The files include:
__init__.py
-
generic.py
- contains all properties that are used by more than one module.
The modules include:
window
door
roof
floorplan
floors
balcony
stairs
road
with more to be added.
Each of these modules contains at least 5 python files:
__init__.py
-
mod.py
- contains a class tobuild
geometry andvalidate
the blender context. -
mod_ops.py
- contains operators required by the module -
mod_props.py
- contains properties required by the module. -
mod_types.py
- contains helper functions used by the module operator.
where mod
is the name of the module.
The root of the project also contains a tests
folder.
The tests
folder contains per-module test files e.g tests for the floors
module will be found in the test module called test_floors.py
.
Also in the tests
folder is a __main__.py
file that should be run from within blender python in order to run the tests. A command to run the test can look as follows:
blender --window-geometry 0 0 1 1 --no-window-focus -P tests/__main__.py
This command will run the tests in an unfocussed blender window. Tests must be run from within blender to provide the proper context and extra modules such as bpy
.
To start contributing to the development of Building Tool
you need to have the appropriate environment setup. Developing blender addons can be somewhat tricky especially when using an external editor. I will provide a short overview of my setup for developing Building Tool
.
- You will need to get ScriptWatcher.
A very handy blender addon I stumbled across that watches your project files in blender and runs your addon when you make changes.
-
Once ScriptWatcher is installed in blender, locate the ScriptWacher panel which should be in the
Properties
editor under theScene
tab. -
Point ScriptWacher to the
__init__.py
file at the root of your localBuilding Tool
development sources. ClickWatch Script
to runBuilding Tool
in the current blender workspace.
To avoid having to repeat these steps every time, you can save the current blender workspace as a file, say building_tool_dev.blend
. Then in the SciptWatcher settings, enable the Watch on startup
checkbox. Now every time you open the .blend file, everything will already be setup.
At this point, making changes to the building tools source code should not be a scary endeavour. You should be able to fix issues, add new features and refactor appropriately.
It is advisable of course to take the time to understand the portions of code you would like to change. Be sure to maintain a style consistent with the rest of the source code. I personally use black
to handle python style, but occasionally prefer the freedom of deciding on my own.
Unfortunately, there are no tests available to prevent blunders during development. This means that it's up to the developer to ensure that changes do what is intended.
In general, the following hints apply:-
-
Run
Blender
from a terminal. This allows you to watch all output from the addon including errors when testing functionality. -
Make small changes and test often.
-
If adding/removing new classes, ensure you register/unregister them. Errors relating to this issue are usually vague and not helpful.
-
When adding new properties, caution should be taken when defining
update
functions. Blenders documentation warns users aboutInfinite Recursion
, but errors relating to this issue can be vague and seem unrelated to recursion. -
If you feel that a piece of code is used often or that it could be useful in other areas of the addon, consider adding it in the
utils
module. -
As part of a consistent style, I have made great effort to keep the length of functions reasonable. Less than
40 lines
is preferred.
Once you are happy with the changes you have made, push them to your fork and create a pull request.