Dev:2.7/Source/Checklists/ToolsettingsProperty

Adding New Tool Settings Properties/Data

This checklist covers adding a new property or struct (with properties) to Tool Settings (or some data attached to it).

"Tool Settings" is a per-scene place to store settings related to how various tools operate. Unlike User Preferences, these setting are saved with the scene data in each .blend file instead of being a standalone "global preferences" thing. Thus, it is good for being a kind of "global" place to store settings that the user will likely frequently require access to, which need to be adjusted in response to the nature of the current scene/file being worked on, and are not restricted to only being relevant in a particular editor instance. Examples of settings which are stored in Tool Settings include: Sculpt Settings, Particle Edit Settings, Auto Keyframing options (i.e. enabled/not-enabled, etc.), and many others.

Key Precautions and Takeaway Tips

1. The main thing to be careful about is remembering to include the version patching code in all 3 places where these defaults need to be set. It is all too easy to only remember to deal with the most obvious one, only to find later that a critical setting has not been initialised in one of the other cases (and likely leading to a segfault or weird hard-to-trace behaviour).
2. The other thing to be careful about is that since DNA_scene_types.h is included in a LOT of files, it's imperative to double check that you're happy with your code before compiling, as you'll invariably end up having to recompile most of Blender each time you touch that file.
   • Personally, I recommend batching up edits to that file during development, and only splitting out the changes per-feature when committing to Git (by cherry-picking the relevant lines/blocks as needed)
   • Also be warned that every time you modify a RNA file, quite a few of the Blender-side export code for Cycles will also need to be recompiled, as those classes rely on the autogenerated RNA C++ API to do their magic.

Checklist

• makesdna/DNA_scene_types.h - Data structures, types, flag values, etc.
  • 1) Add Property - Find the ToolSettings struct (~60% of the way down the file).
    • Add your property somewhere here, taking into account the SDNA alignment considerations (if appropriate)
    • Otherwise, add to the relevant struct that is linked off here (e.g. ParticleEditSettings)
  • 2) Add any flags defines/enum values - Scroll down ~80-90%, till you start seeing comments like /* toolsettings->snap_flag */

• makesrna/intern/rna_scene.c (or rna_sculpt_paint.c) - RNA defines for the new properties

• Version Patching (x3):
  • blenloader/versioning_270.c - Version Patching for old files.
    • Scroll to the end of the file, and stub the version patch in at the end of blo_do_versions_270
  • blenloader/versioning_defaults.c - Version Patching for old startup/userpref files. (Pretty much the same again, except without the version checks)
  • blenkernel/intern/scene.c - Set defaults for new Scene instances (i.e. those added via the '+' on the Info Header)