Nero Frame 13andClaude Opus 5.5
017bdfc2fd
dev/: test asset files, a fake Libreflow IPC server and an end-to-end Scene Manager test (excluded from the extension build). CLAUDE.md: notes for working on the add-on (conventions, testing, design findings, open points). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
79 lines
4.5 KiB
Markdown
79 lines
4.5 KiB
Markdown
# Melvile Tools: notes for Claude
|
|
|
|
Blender add-on (Blender 5.2) for the Melvile pipeline at Walking The Dog: Sanity Check,
|
|
Rename, Shot Viewer and Scene Manager panels in the 3D View sidebar (WTD tab). `README.md`
|
|
is the user guide: keep it up to date with every user-visible change.
|
|
|
|
## Layout and conventions
|
|
|
|
- `config.py`: every production value (prefixes, formats, patterns, modes). Values are
|
|
read at run time (`config.X`, never copied at import) because a studio JSON file can
|
|
override them (add-on preferences "Config Override", or `WTD_SANITY_CONFIG`).
|
|
New tunable values go here, with a comment, and in the README's Configuration table.
|
|
- `ui/panel.py`: all panels. Operators live with their tool (`rename.py`,
|
|
`shot_viewer.py`, `scene_manager/`, `ui/operators.py` for the Sanity Check).
|
|
- `checks/`: sanity checks, auto-registered (see README > For developers).
|
|
- `__init__.py` deletes cached submodules on reload, so Reload Scripts picks up every file.
|
|
- Versions: `blender_manifest.toml` and `bl_info` in `__init__.py` (keep both in sync).
|
|
- Style: match the surrounding code; short docstrings, few comments, no heavy abstractions.
|
|
|
|
## Working with the user
|
|
|
|
- Commits: when asked, create a branch from `master`, commit there (end with the
|
|
Co-Authored-By line), and give the user the merge / push / branch-delete commands:
|
|
they run them themselves. Only commit straight on `master` when told to.
|
|
- Real Blender API facts beat memory: probe in headless Blender before relying on an API.
|
|
|
|
## Testing
|
|
|
|
Blender binary: macOS `/Applications/Blender.app/Contents/MacOS/Blender`, Windows
|
|
`blender.exe` from the install folder. Import the add-on in tests by putting the folder
|
|
that contains this repo on `sys.path` and importing the repo folder name (see
|
|
`dev/test_scene_manager.py`).
|
|
|
|
- Headless: `blender -b --factory-startup --python-exit-code 1 --python <script> -- <args>`.
|
|
Timers do not run in background mode: pump background jobs by hand
|
|
(`scene_manager.ipc._poll()`).
|
|
- UI: run Blender with a window (`--factory-startup <file.blend> --python <script>`, a
|
|
.blend argument avoids the splash), drive it with `bpy.app.timers`, take screenshots with
|
|
`bpy.ops.screen.screenshot_area`, quit with `bpy.ops.wm.quit_blender()`. A sidebar tab
|
|
(`region.active_panel_category`) can only be set once the region has been drawn.
|
|
- Scene Manager without Libreflow (`dev/`):
|
|
1. `blender -b --factory-startup --python dev/make_test_assets.py -- <workdir>`
|
|
2. `python dev/fake_libreflow.py <workdir>` (keep running; restart for a clean state)
|
|
3. `blender -b --factory-startup --python-exit-code 1 --python dev/test_scene_manager.py -- <workdir>`
|
|
(36 checks, "All checks passed").
|
|
The fake server follows the real `wtdcmds` replies; check them against the real
|
|
Libreflow when one is available.
|
|
|
|
## External pieces
|
|
|
|
- Libreflow `wtdcmds` extension (commands used by the Scene Manager), on the share:
|
|
`WG/_Dev/GIT/ndemaerschalk/_MELVILE/libreflow_dev_utils/dev/src/wtdcmds/`
|
|
(`src/libreflow/extensions/wtdcmds/wtd_cmds.py`, `BLENDER_ADDON_BRIEF.md`).
|
|
Server address/token: `~/.kabaret/ipc/server.json` (config `LIBREFLOW_SERVER_FILE`).
|
|
- Add Camera Rigs extension: `bpy.ops.object.build_camera_rig(mode=...)` builds the
|
|
Shot Viewer cameras. It finds its rigs by the `rig_id` custom property, not by name.
|
|
- `tools_ops.py` "Get Oid" uses the separate kabaret Blender client (`bpy.ops.kabaret.cmds_call`).
|
|
|
|
## Design notes (found by testing)
|
|
|
|
- Shot Viewer: shots are timeline markers bound to cameras, in one scene. Setting
|
|
`scene.frame_current` does not switch the camera (only `frame_set` does): set
|
|
`scene.camera` explicitly.
|
|
- Scene Manager: tags live on `bpy.types.Library` only. Library overrides lose custom
|
|
properties when they resync, so instances are traced back to their library (empty →
|
|
`instance_collection.library`, override → `override_library.reference.library`).
|
|
- `library.reload()` invalidates every Python reference to linked and override data:
|
|
look IDs up again afterwards.
|
|
- Background requests (`scene_manager.ipc.run`) hand results back through a timer;
|
|
in callbacks, find scenes by name (`bpy.context.scene` is not reliable in timers).
|
|
|
|
## Open points
|
|
|
|
- First run of the Scene Manager against a real Libreflow (only tested with the fake
|
|
server): connection, casting, load, update, assetize, Windows paths.
|
|
- Asset type names assumed `chars` / `props` / `sets` (`SCENE_MANAGER_LINK_MODES`,
|
|
`SHOT_VIEWER_ASSET_TYPE_GROUPS`): confirm with Kitsu.
|
|
- Values marked TODO in `config.py` wait for production specs.
|