Skip to content

Extending Core Safely

Edition: Core

Use small, focused changes and validate the entire workflow after every change. Texelator is stateful: a UI choice can affect scene nodes, material connections, Revert behavior, and existing-setup loading.

Example: add a control shape

Control shapes are declared in logic/step2_logic.py through CONTROL_SHAPES, and the curve construction is handled by create_control_curve(). A new shape needs both a menu entry and a matching curve-creation branch. Then verify that it appears in Part Control Settings: and that Create Control builds it for regular and mirrored parts.

Example: add a control color

Control display colors are mapped in CONTROL_COLORS in logic/step2_logic.py. Add the menu-facing color name and its Maya override color index together, then verify the generated curve display.

Checklist for any feature

  1. Identify the workflow stage that owns the feature.
  2. Use the existing UI label style and English terminology.
  3. Preserve the selected mesh, guide, control, and final-build state flow.
  4. Confirm that the correct Revert action removes the new generated nodes.
  5. Confirm the setup can still be found by Edit Existing Setup when relevant.
  6. Test both Projection? and UV placement if Step 3 behavior changes.
  7. Test mirror behavior if a guide, control, or texture setting changes.
  8. Test Maya 2022 Python 3 mode and Maya 2026 when changing compatibility code.
  9. Update the user documentation and changelog.

Persistence and cleanup rules

If a feature creates Maya nodes, track enough information for both Step Revert and a failed Build Final rollback to delete only the nodes it owns. Do not delete arbitrary material networks. Core captures the prior material input before Step 3 specifically to avoid destroying an artist's pre-existing setup.

If a feature introduces a choice that should survive reopening Maya, add it to the serialized setup data written to texelatorData, then handle restoring it in the existing-setup load path. A setting that works only until the window closes is acceptable only when it is explicitly temporary.

When changing a generated node name or setup attribute, consider old scenes. Core already contains legacy setup detection, so new changes should prefer backward-compatible reads or an explicit migration path.

Technical validation matrix

Area Minimum manual check
Step 1 One regular part, one mirrored part, each mirror axis needed by the change.
Step 2 Every curve shape/color affected; Precision remains keyable and responsive.
Step 3 Existing material, no material, Projection mode, and UV mode.
Ordering Two main textures; confirm Input 0 remains the top visible managed layer.
Recovery Step 3 Revert, Step 2 Revert, Step 1 Revert, and Edit Existing Setup.
Versions Maya 2022 in Python 3 mode and Maya 2026 for math-node compatibility changes.

Manual validation scene

Use a simple mesh with valid UVs. Create one regular part and one mirrored part, build controls, select image files, test projection and UV modes, build final, and walk backward through Step 3, Step 2, and Step 1 Revert. This covers the main state transitions without requiring a large production scene.

Note

The current repository does not include an automated test suite. Manual Maya verification is therefore especially important for contributions.