3ds Max Python How Tos

The mxthread module allows Python worker threads to queue work to be executed by the 3ds Max main thread. This is essential because most pymxs operations and certain UI/print functions can only be safely called from the main thread.

mxthread handles the complexity of passing functions to the main thread, waiting for execution to complete, retrieving return values, and propagating exceptions back to the caller thread.

Key Features

• Return Values: Functions executed on the main thread can return values directly to the caller thread.
• Exception Propagation: If the code on the main thread raises an exception, it is caught and re-raised in the worker thread.
• Thread Safety: Uses Qt mechanisms (Signals, Slots, and QWaitCondition) to bridge the threads.

from mxthread import on_main_thread, run_on_main_thread

@on_main_thread
def my_task(val):
    return val * 2

# Called from a worker thread
result = my_task(10)
print(result)  # Outputs 20

mxs2py is an experimental transpiler that parses MAXScript programs into a syntax tree and generates equivalent Python code. It is designed to help Python developers understand and use MAXScript samples by providing automatic translation.

Limitations and Warnings

• Experimental Status: The project is in an experimental state.
• Parsing Errors: Error reporting for invalid MAXScript syntax is poor; ensure your input code is valid MAXScript.
• Unsupported Constructs: Some MAXScript constructs (e.g., plugin, tool, custom attributes) are parsed but may have nonexistent or limited Python support. When a construct cannot be translated, a warning is emitted within the generated Python code.
• Code Quality: Generated Python code may be functionally correct but syntactically "awkward."
• Dependencies: The generated code relies on mxsshim.py, which is an early and incomplete emulation layer for MAXScript constructs in Python.

from mxs2py import topy

(output, _) = topy("rotate $ (angleaxis 90 [1,0,0])")
print(output)

The zdepthchannel tool demonstrates how to access Z-buffer depth information from the 3ds Max scanline renderer to create 3D geometry.

Workflow:

1. Cleanup: Deletes existing objects named with the prefix VoxelBox to clear previous runs.
2. Rendering: Renders the active viewport at a low resolution (e.g., 32x32) while requesting an additional Z-depth channel. The Virtual Frame Buffer (VFB) is disabled during this process.
3. Mask Extraction: Converts the Z-depth channel into a grayscale mask bitmap.
4. Geometry Generation: Iterates through every pixel of the rendered bitmap and its corresponding Z-depth mask. For each pixel, it creates a rt.box where:
   • The height is derived from the Z-depth value.
   • The wirecolor is set to the pixel's RGB color.
   • The position is mapped from bitmap coordinates to 3ds Max world space (mirroring the Y-axis to align the bitmap's top-left origin with the 3ds Max coordinate system).
5. Progress Tracking: Uses rt.progressStart, rt.progressupdate, and rt.progressEnd to provide visual feedback in the status bar.

The pystartup mechanism uses pkg_resources (part of setuptools) to discover and execute startup functions from installed packages.

Workflow:

1. The MAXScript pystartup.ms executes a Python block via python.execute.
2. The Python code imports pkg_resources.
3. It iterates through pkg_resources.working_set to inspect all installed distributions.
4. For each distribution, it searches for an entry point named 'startup' within the '3dsMax' group using pkg_resources.get_entry_info(dist, '3dsMax', 'startup').
5. If found, the entry point is loaded via .load() and the resulting function is called.

Requirements:

• pip and setuptools must be installed in the 3ds Max Python environment to provide pkg_resources.

# Conceptual logic used by pystartup
import pkg_resources

for dist in pkg_resources.working_set: 
    entrypt = pkg_resources.get_entry_info(dist, '3dsMax', 'startup')
    if entrypt is not None:
        fcn = entrypt.load()
        fcn()

To create a custom PySide dialog that is properly attached to the 3ds Max main window, subclass QDialog and set its parent using rt.windows.getMAXHWND(). This ensures the dialog behaves correctly within the 3ds Max UI environment.

Key steps:

1. Find the 3ds Max window handle using rt.windows.getMAXHWND().
2. Pass this handle to the QDialog constructor as the parent.
3. Use layouts (like QVBoxLayout) to organize widgets such as QLabel, QLineEdit, and QPushButton.

class PyMaxDialog(QDialog):
    """
    Custom dialog attached to the 3ds Max main window
    """
    def __init__(self, click, parent=QWidget.find(rt.windows.getMAXHWND())):
        super(PyMaxDialog, self).__init__(parent)
        self.setWindowTitle('Rename')

        main_layout = QVBoxLayout()
        label = QLabel("Enter new base name")
        main_layout.addWidget(label)

        edit = QLineEdit()
        main_layout.addWidget(edit)

        btn = QPushButton("Rename selected objects")
        # Connect the button click to the provided callback function
        btn.clicked.connect(lambda : click(edit.text()))
        main_layout.addWidget(btn)

        self.setLayout(main_layout)
        self.resize(250, 100)

To ensure your custom menu items are correctly injected into the 3ds Max 2025 menu system whenever the UI regenerates, you should use pymxs.runtime.callbacks.

1. Define a menu configuration function (e.g., menu_func) that retrieves the menu manager via rt.callbacks.notificationparam() and calls your registration logic.
2. Use rt.callbacks.addscript with a unique ID to hook this function into the cuiRegisterMenus event. This ensures that whenever the menu system needs to rebuild, your items are re-added.

from pymxs import runtime as rt
from menuhook import register_howtos_menu_2025

def menu_func():
    menumgr = rt.callbacks.notificationparam()
    register_howtos_menu_2025(menumgr)

cuiregid = rt.name("cuiRegisterMenus")
howtoid = rt.name("pyScriptHowtoMenu")

# Remove existing callback to prevent duplicates, then add
rt.callbacks.removescripts(id=cuiregid)
rt.callbacks.addscript(cuiregid, menu_func, id=howtoid)