Seele-art-3dmax

A loopback bridge that delivers validated Seele Web 3D asset transfers to Autodesk 3ds Max.

Seele AI 3D · Quick start · Receiver API · Security boundary

Seele Receiver accepts a dcc-transfer.v1 manifest on localhost, downloads its referenced asset from an approved CDN, verifies the declared size and SHA-256 digest, and queues the file for a 3ds Max importer.

Bridge, not a generator or editor. This plugin does not generate, modify, optimize, rig, texture, or render models inside 3ds Max. Asset creation happens outside the plugin; the implemented responsibility is validated delivery and import handoff.

Why Seele Receiver?

• Connect web creation to desktop work. Create or obtain an asset through Seele AI 3D, then use a compatible sending service to hand it to 3ds Max.
• Keep the receiver local. The bundled configuration listens on 127.0.0.1:9880; configuration validation permits loopback hosts only.
• Validate before import. The receiver checks protocol metadata, expiry, URL policy, declared byte size, and SHA-256 integrity before scheduling an importer.
• Protect the 3ds Max main thread. Network and verification work runs outside the scene API; a bounded queue is drained by a Qt timer on the main thread.
• Track asynchronous work. Transfer state, history, idempotent resubmission, best-effort cancellation, and optional allowlisted callbacks are supported.

Requirements

• Windows 64-bit
• Autodesk 3ds Max with an existing user profile
• Administrator permission to install under %PROGRAMDATA%\Autodesk\ApplicationPlugins
• A compatible service that can submit a dcc-transfer.v1 manifest

The package manifest targets Win64 and 3ds Max, but an authoritative per-version compatibility matrix has not yet been established. Start 3ds Max once before installation so its user-profile startup directory exists.

Quick start

Current production version: 0.2.0.

1. Download Seele Receiver production 0.2.0.
2. Close 3ds Max and extract the ZIP.
3. Run Install.cmd and approve the Windows administrator prompt.
4. Restart 3ds Max.
5. Open http://127.0.0.1:9880/healthz. A running receiver returns its version, protocol, and listening address.
6. In a compatible Seele Web workflow, submit a ready asset transfer while 3ds Max is open.

The installer places the ApplicationPlugins bundle at:

%PROGRAMDATA%\Autodesk\ApplicationPlugins\SeeleReceiver.bundle

It also installs SeeleReceiverStartup.ms into existing profiles under:

%LOCALAPPDATA%\Autodesk\3dsMax\<version> - 64bit\<language>\scripts\startup

An upgrade preserves the existing user configuration and moves the previous bundle to a timestamped backup. Uninstall.cmd disables the bundle and removes startup loaders while preserving configuration and cache data.

How an asset reaches 3ds Max

1. A compatible web or server workflow submits a dcc-transfer.v1 JSON manifest to the localhost receiver.
2. The receiver validates the transfer ID, expiry, asset URL, declared size, SHA-256 digest, and configured destination policies.
3. It streams the asset from an allowlisted CDN into a controlled local cache.
4. Only a size- and hash-verified file enters the bounded import queue.
5. A Qt timer drains that queue on the 3ds Max main thread and calls the available 3ds Max importer without prompting.
6. The sender can query the transfer state and full history; configured callback hosts may also receive best-effort status events.

The HTTP API does not accept arbitrary local filesystem paths, scripts, commands, MAXScript, or importer parameters from a manifest.

Supported formats and compatibility

Manifest format	Receiver dispatch	Runtime dependency
OBJ	obj	A working 3ds Max importer for the file
FBX	fbx	A working 3ds Max importer for the file
GLB	glb	A working 3ds Max importer for the file
glTF	gltf	A working 3ds Max importer for the file

The bridge dispatches OBJ, FBX, GLB, and glTF through pymxs.runtime.importFile. This is not a guarantee that every file, material, texture dependency, coordinate system, unit convention, or format feature will import correctly. Actual results depend on the importers available in the installed 3ds Max version.

Automated tests exercise protocol validation, cache policy, transfer state, loopback HTTP handling, CORS/PNA behavior, downloading, integrity verification, idempotency, and a fake importer. Real 3ds Max smoke testing and a formal version matrix remain pending.

Configuration

Configuration is stored at:

%LOCALAPPDATA%\Seele\3dsMaxReceiver\config.json

The production 0.2.0 package bundles:

{
  "host": "127.0.0.1",
  "port": 9880,
  "authToken": null,
  "allowedCdnHosts": [
    "static.seeles.ai",
    "agent-workspace-1368252780.cos.na-ashburn.myqcloud.com",
    "seeleh5.blob.core.windows.net",
    "d3vhd1f81y5p6c.cloudfront.net"
  ],
  "allowedCallbackHosts": [],
  "allowHttp": false
}

authToken: null means Bearer authentication is disabled by default in the bundled production configuration. Run Configure.cmd to customize CDN or callback allowlists and generate or rotate a Receiver Token; configure the same token on the sending service. Connection details are then written to %LOCALAPPDATA%\Seele\3dsMaxReceiver\receiver-connection.txt.

Production and test packages are built from separate configuration files. They currently use identical allowlists but may diverge in future releases.

Security boundary

• Binding is restricted to 127.0.0.1, ::1, or localhost; the bundled default is 127.0.0.1:9880.
• When authToken is configured, every endpoint except GET /healthz requires a matching Bearer Token.
• Asset and callback destinations must match explicit host allowlists.
• Asset downloads require HTTPS by default; redirects are bounded and revalidated.
• Declared size and SHA-256 are verified before import; temporary downloads are atomically placed only after verification.
• Request size, asset size, cache quota, worker count, and queue capacity are bounded.
• URL query parameters are excluded by the provided redaction helper.
• The manifest cannot supply executable scripts, commands, MAXScript, or arbitrary importer arguments.
• Browser access is granted only to the fixed web-origin allowlist implemented by the receiver.

The default empty callback allowlist prevents outbound callbacks. For local development fixtures only, a custom configuration may set allowHttp: true; do not enable it for production asset delivery.

Receiver API

The fixed browser-origin allowlist is:

• https://code4agent-feature-3dsmax-dcc-server.seele.chat
• https://www.seele.chat
• https://test.seeles.ai
• https://www.seeles.ai

Unknown origins receive no CORS or Private Network Access permission.

Method	Path	Purpose
GET	/healthz	Return receiver version, protocol, and listening address
POST	/v1/transfers	Validate a manifest and enqueue an asynchronous transfer
GET	/v1/transfers/{transferId}	Return current state and complete state history
POST	/v1/transfers/{transferId}/cancel	Request best-effort cancellation

A new valid submission returns 202 Accepted. Repeating the same normalized manifest returns the existing transfer without another import. Reusing a transfer ID with different content returns 409 Conflict. Cancellation cannot interrupt an importer after it has entered an uninterruptible 3ds Max operation.

Local development

Python 3.9 or later is required. The test suite has no third-party Python dependency and does not require 3ds Max:

$env:PYTHONPATH = "$PWD\src"
py -m unittest discover -s tests -v

Build the ApplicationPlugins bundle or create environment-specific archives:

.\scripts\build-package.ps1
.\scripts\create-release.ps1 -Environment production
.\scripts\create-release.ps1 -Environment test

The release outputs are:

dist\SeeleReceiver-production-0.2.0.zip
dist\SeeleReceiver-test-0.2.0.zip

For transport debugging without scene modification:

$env:PYTHONPATH = "$PWD\src"
py -m seele_max.cli --allow-host cdn.example.com --token dev-token

Standalone mode receives, downloads, and verifies transfers, but has no 3ds Max importer and therefore cannot edit a scene.

Repository structure

src/seele_max/   Receiver protocol, transport, cache, state, and 3ds Max bridge
packaging/       ApplicationPlugins manifest, startup entries, configs, and installer
scripts/         Package, release, install, and uninstall PowerShell scripts
tests/           Protocol, cache, state, and receiver integration tests

Current limitations

• Server schema, signing or authentication ownership, receiver discovery, callback envelope, retry ownership, and cancellation semantics still require authoritative end-to-end alignment.
• Production URL lifetime, redirect policy, and maximum-file policy remain integration-dependent.
• Supported 3ds Max versions and per-version GLB/glTF importer availability are not yet formally validated.
• Coordinate systems, units, texture dependencies, and importer options are not normalized by this bridge.
• Real Seele Web-to-CDN-to-3ds Max testing, Windows CI with 3ds Max, code signing, and installer signing remain pending.

Support

Report reproducible problems through GitHub Issues. Include the 3ds Max version, receiver version, transfer state, and a redacted log excerpt. Never include Receiver Tokens, credentials, or signed URL query strings.