Repository navigation
Handler Server
The subsystem keeps TACTIC access, repository work, snapshot selection, and application
state outside Maya. A DCC process loads only the transport, command registry,
and its connector. The pre-existing thlib/tactic_server.py and
tactic_api_server.py are Qt local-socket experiments with full application imports;
they were inspected but not modified or reused as the DCC bridge.
flowchart LR
UI["Standalone application UI\nTACTIC API and repository state"]
QC["HandlerServerController\nQML-safe API"]
HS["Handler Server process\nrouter, timeout, lifecycle"]
MC["DCC runtime + native connector\nlifecycle and native actions"]
UI --> QC
QC -->|"framed JSON / localhost"| HS
HS --> MC
MC --> HS
HS --> QC
| Module | Responsibility |
|---|---|
handler_server/protocol.py |
framing, versioning, validation, size limit, message factories |
handler_server/server.py |
localhost listener, handshake, clients, heartbeats, auto-target selection |
handler_server/router.py |
request ownership, result routing, cancel, timeout, disconnect errors |
handler_server/client.py |
reconnecting thin client and command execution boundary |
handler_server/registry.py |
explicit allow-list of callable actions; no eval or exec
|
handler_server/demo_adapter.py |
dependency-free text-document example |
handler_server/demo_maya_adapter.py |
Maya-shaped standalone adapter for UI and routing tests |
handler_server/demo_client.py |
Bundled simulated Maya client, including its existing native window |
handler_server/launcher.py |
separate Handler Server process entry point |
thlib/ui/handler_server_controller.py |
process lifecycle and QML-safe client/result models |
thlib/ui/tactic_rpc.py |
Handler object API transport, session-owned handles, and UI command dispatch |
tactic_handler_dcc/ |
DCC SDK and remote Handler API objects |
tactic_handler_dcc/runtime.py |
shared DCC discovery, standalone autostart, reconnect, hot reload, and local custom-script runner |
tactic_handler_dcc/maya.py |
Maya entry point and Maya-native notification presentation |
tactic_handler_dcc/connectors/maya.py |
Maya capabilities, main-thread dispatch, scene preparation, editor-file execution, and local mf() helpers |
HandlerServerView.qml |
clients, capabilities, command payload, timeout, results |
The demo starts with python -m handler_server.demo_client, or the compiled
application's --handler-demo entry point, from the installation directory.
Its implementation lives under the update archive's existing handler_server
root; runtime startup never depends on excluded source examples. The example
script delegates to this module. Child Python output uses UTF-8 to match the
controller's decoder and retain Unicode diagnostics. The package regression
creates and extracts a real update into a path with Cyrillic/spaces, then checks
registration, selection, commands and shutdown. Browser Stream has no local
subprocess launcher; this native capability is owned by Handler.
- The application UI generates a cryptographically random session token.
- It starts
python -m handler_server.launcherfrom source, or relaunches the compiled application with--handler-serverin a Nuitka build. The entry point dispatches to the same launcher before UI initialization. The token is passed only through the child environment. - The server binds an ephemeral port on
127.0.0.1and atomically publishes a per-user discovery record under local application data. The record is readable only in the user's local session and contains the random handshake token. - The UI connects as
tactic_handler; DCC clients find the newest live record and connect independently without connection parameters. - Each client completes
hello, registers id/application/pid/capabilities, and begins heartbeat exchange. A connected client may re-advertise its own allow-list after a hot reload; the server broadcasts the updated client record without reconnecting it. - The user selects the active DCC client in the main header. UI capabilities and context actions come from that exact client, and commands target its id.
- Each client uses a generated id unless an integration supplies a stable one, so multiple Maya, Blender, and demo processes are registered separately.
- Maya
startup(path)returns immediately. Discovery, standalone application launch, and the connection wait run in a daemon bootstrap thread. Repeated startup reuses the active client and restores the Handler window; Maya's exiting callback stops the current client. - Timeout, connection loss, operator disconnect, or an unexpected server-process exit completes every pending UI request exactly once with a structured error. The Qt lifecycle callback closes the operator socket without joining client threads, so a failed bridge cannot block the GUI while its workers unwind. Clients may reconnect with the same client id.
- Server restart is rediscovered on the next reconnect. Application shutdown removes the discovery record and stops clients, demo process, and server process in order.
The standalone UI starts Handler Server after QML has loaded when
application/autoStartHandlerServer is enabled (the default) in ui_main settings.
Disabling it leaves manual startup available and takes effect on the next launch. A manual
stop uses the authenticated local operator connection; process termination is only a
bounded fallback when graceful shutdown does not complete.
The standalone client remains responsible for TACTIC search, repository selection, download, overwrite policy, and local path verification. The local path plus safe options is sent to the Handler Server only after preparation.
| UI operation | Routed action | Registered capability | Result |
|---|---|---|---|
| Open snapshot | open_scene |
open_scene |
success/cancelled/error/opened path |
| Import snapshot | import_file |
import_file |
same |
| Reference snapshot | reference_file |
reference_file |
same |
| Save current scene |
get_current_scene, then prepare_checkin
|
get_current_scene, prepare_checkin
|
TACTIC-named scene/playblast paths |
| Get current scene | get_current_scene |
get_current_scene |
path/modified/type/workspace/optional selection |
| Run saved DCC script | execute_custom_script |
execute_custom_script |
captured stdout/stderr |
| Run new/edited Script Editor buffer | execute_script_file |
execute_script_file |
captured stdout/stderr |
| Copy active shelf to Maya | create_script_shelf |
create_script_shelf |
saved native Maya shelf |
The main UI preserves its standalone runtime. The selected client's application type acts as the current UI environment, while capability checks expose only supported DCC actions. Existing Check-in/Out downloads still use the normal repository engine; only the final DCC-specific action crosses the bridge.
Connector manifests are discovered without a central DCC list. Standard file actions come from the selected client's registered capabilities, so a new DCC adds its connector and startup module without edits to Handler Server, the application composition root, context menus, or script-trigger actions.
tactic_handler_api.get_api() exposes the Handler object API. Calls execute in standalone
TACTIC-Handler; returned objects remain chainable session-owned handles.
th.ui provides navigation and window commands.
When a connector registers both get_current_scene and prepare_checkin, Save
Scene adds its declared scene extension and optional preview to Commit Queue.
Queue validation resolves the virtual snapshot. Commit then routes the fixed
save command back to that exact client with the final versioned paths.
Standalone TACTIC-Handler subsequently performs the repository transfer and
server-side check-in. Maya uses this contract with an optional playblast; a new
DCC does not require another application-type branch in the queue controller.
- listener is localhost-only and rejects non-loopback configuration;
- token is random per server session and compared with constant-time comparison;
- message size is limited to 1 MiB and command timeout to 300 seconds;
- client id, application type, process id, capabilities, request id, and sender are registered or server-controlled;
- DCC-side execution is limited to callbacks in
CommandRegistry; - standalone RPC permits only the object methods and properties listed in
tactic_handler_api/contract.py, throughhandler.call,handler.release, andhandler.close; - command logs include sender, target, action, and request id, never token/payload;
- Python source and callable expressions are never protocol payloads. The
trusted Script Editor routes an unchanged saved script by validated project
and relative path to
execute_custom_script; a draft uses only a randomized.pypath inside its application-owned temporary directory throughexecute_script_file; - remote peers cannot connect to the loopback listener.
The production entry point is tactic_handler_dcc.maya.startup(handler_path).
It attaches to a live local Handler session or starts launch.pyw as a
separate process and reports progress in Maya. The Handler Server window and the
simulated client are diagnostics only and are not part of this startup path.
For a clean Maya installation, drag installer/drop_install.mel into the Maya
viewport. The installer downloads the configured ZIP, installs it under the Maya
installer directory by default, and recreates the Niki_And_Friends shelf.
Animation, Modelling/Rig, and Full presets reproduce the legacy button sets;
every button loads only the thin connector and dispatches an installed custom
script when required. Standalone configuration is not copied into Maya.
Shelf creation happens before package download, so a failed download can be
recovered by copying the application into the selected TACTIC-handler path.
The documented shelf bootstrap reloads the thin runtime before calling
startup. A live client survives that reload and is reused; a new connection
reloads the thin environment, session, and Maya connector modules so Maya cannot
retain stale capabilities from its Python module cache. A reused connection
immediately re-advertises the refreshed registry to Handler Server.
The main header provides the exact client selector. Opening it refreshes each
client's application version and current scene name and shows those details with
the process id; it does not poll DCC clients while the menu is closed.
See tactic_handler_dcc/README.md for shelf startup, API access, UI calls,
custom scripts, restart, and shutdown.
Server-backed custom scripts are synchronized from config/custom_script into
the local execution tree at startup and whenever the shared server-update poll
reports a script change for the current project. Startup first compares the
script manifest timestamps with local file modification times and downloads
script bodies only when the mirror differs. The requested project is applied
to the standalone environment before the runner imports project modules; Maya
receives only the thin environment proxy and native DCC work.
Custom scripts remain the orchestration layer above these primitives. The DCC
SDK must not absorb project-specific script functions. When an unchanged legacy
script fails because a public API name disappeared, compatibility belongs in the
original thlib or application-command owner (for example,
get_sobjects_new = get_sobjects), not in a new script-specific DCC wrapper.
- transport is dependency-free length-prefixed JSON/TCP, not WebSocket;
- command cancellation is cooperative and cannot interrupt a Maya API call already executing on Maya's main thread;
- DCC commands require an explicitly selected active client;
-
run_before_checkinandrun_after_checkinDCC callbacks still need a bounded callback channel before callback-based custom scripts can migrate unchanged; - Maya execution requires a manual test in Maya;
- no push discovery outside localhost and no persistent request queue.
Future DCC connectors implement the same registration contract, choose a safe
main-thread dispatcher, and register a distinct application_type. A WebSocket can be
added behind the protocol/client interfaces without putting protocol logic in QML.
TACTIC-Handler · Releases · Issues · English · Русский
English
- Home
- Installation
- Feature tour
- User guide
- Assistant
- Dashboards
- Knowledge Base
- Maya / Shelf
- Plugins / Плагины
Русский
- Главная
- Установка
- Обзор возможностей
- Руководство пользователя
- Помощник
- Дашборды
- База знаний
- Maya / Shelf
- Plugins / Плагины
Development / Разработка