aioli-max-scripts

Custom tools the /ai.oli collective builds for itself and runs inside 3ds Max, on the productions where we use it. Kept in one place so they stay usable, updatable and shareable.

Four tools so far. Each lives in its own folder with its own README.

Tool	What it does
clonelayers	Clones a selection and rebuilds the whole layer / sub-layer tree of the sources, with a prefix, a suffix or an auto-incremented number.
ratiomask	Viewport matte that previews any crop ratio (16:9, 9:16, 4:5…) without ever touching the render settings. Render 1:1, crop later.
sunpos	Places a sun at the real sun's position for a location, date and time, taking the scene's north rotation into account. NOAA maths, no time zone guessing.
phys2vray (in test)	Replaces the Physical Materials on the selection (Blender FBX imports, typically) with VRayMtl, every texture map plugged back into the right slot as a VRayBitmap, with one UVW randomizer per material. And the other way round: VRayMtl → Physical for an FBX / glTF export that Blender opens with its textures, or a .vrscene that keeps the V-Ray materials for V-Ray for Blender.

clonelayers, ratiomask and phys2vray are pure MaxScript, single file, no dependency. sunpos is a Python panel and ships as a folder — it runs on what 3ds Max already has (pymxs, PySide, the Python standard library), so it needs no install either.

---

Install

git clone https://github.com/aiolicollective/aioli-max-scripts.git

Anywhere you like — a tools folder, a synced drive, wherever. Nothing gets copied into 3ds Max, and nothing is written outside Max's own preferences.

Then, once per tool: drag its .ms into a 3ds Max window (or Scripting > Run Script…). The panel opens, and a macro is registered under the aiolicollective category.

Tool	File to drag in
clonelayers	clonelayers/aioli-clonelayers.ms
ratiomask	ratiomask/aioli-ratiomask.ms
sunpos	sunpos/aioli-sunpos.ms
phys2vray	phys2vray/aioli-phys2vray.ms

None of them needs anything installed in order to be used in 3ds Max. sunpos ships an optional setup.bat, but that is for running the calculation outside Max — on the command line, or to feed another 3D application. It also unlocks the auto time zone mode inside the panel; everything else there, daylight saving included, works straight from the drag & drop. See sunpos/README.md.

To update later: git pull in the clone. That is all — the buttons keep pointing at the same files and pick the new version up on the next click.

---

Toolbar buttons

Customize > Customize User Interface… > Toolbars tab > Category aiolicollective > drag the action onto a toolbar. The same actions are available in the Menus, Quads and Keyboard tabs.

Category	Action	Macro
aiolicollective	clonelayers	aioli_clonelayers
aiolicollective	ratiomask	aioli_ratiomask
aiolicollective	sunpos	aioli_sunpos
aiolicollective	phys2vray	aioli_phys2vray

All of them behave the same way, on purpose:

• The button survives a restart of 3ds Max. Max writes the macro into its own usermacros folder and re-reads it on startup.
• The button follows git pull. Each macro is a thin launcher holding the path to its file in the clone, baked in when you drag the .ms in. It never carries a copy of the code, so a pull is enough.
• Move the clone and the button breaks — the baked path no longer resolves. You get an explicit message saying so; drag the .ms in once more and it is fixed.

Uninstalling a button means deleting the matching .mcr in %LOCALAPPDATA%\Autodesk\3dsMax\<version> - 64bit\ENU\usermacros\.

---

Compatibility

Written for 3ds Max 2026, tested there.

clonelayers only uses stable, non-deprecated API (layermanager, maxOps.cloneNodes, native rollout UI) and should run on 2016 and up. ratiomask needs a Nitrous viewport. sunpos uses the pymxs and PySide6 that come with 3ds Max 2026, falling back to PySide2 on older versions — nothing to install, and Autodesk's Python is never modified.

None of these tools touch render settings. clonelayers, ratiomask and sunpos are renderer-agnostic — sunpos moves whichever sun you point it at, V-Ray Sun, Corona Sun, native target light or free directional. phys2vray is the V-Ray one by nature: it needs V-Ray 5+ loaded, and runs on 3ds Max 2017+ (Physical Material).

---

Status

The first three are installed on the collective's machines: dragged in, buttons in place, working. clonelayers and sunpos are at v1.0, ratiomask at v1.3 — see its changelog.

phys2vray is at v1.7.2, in test: written without a 3ds Max at hand, now being tried on real Blender imports and corrected as we go. Its NOTES.md lists what is still unverified.

sunpos has 47 automated tests covering the maths and the CLI, but its pymxs layer has not been exercised end to end in Max yet — see sunpos/NOTES.md for the exact list of what is still to be checked.

Issues and pull requests welcome.

---

Contributing

Each tool folder is self-contained; adding one more means adding a folder and a row in the tables above.

Conventions we hold to:

• The repo is in English, docs and code alike. Public repo, shared tools.
• One macro category, aiolicollective, for every tool. Action named after the tool, macro named aioli_<tool>, file named aioli-<tool>.ms — so a tool is recognisable wherever you meet it.
• The macro is a launcher, never a copy of the code. Bake the path in with getSourceFileName() at registration time, the way they all do. That is what keeps git pull meaningful.
• Nothing gets installed to use a tool. Optional extras may ask for a setup step, but the drag & drop path must always work on what 3ds Max already ships.
• No write to render settings, no write to the source scene beyond what the tool is explicitly for. Everything wrapped in a single undo.
• Design decisions and traps already hit go in the tool's NOTES.md — that file is what stops the next person (or the next AI) from undoing a fix on purpose.

---

Written by the /ai.oli collective, with AI assistance. We say what is generated and by whom.

MIT licence — see LICENSE.