Skip to content

plugin-overview.md

Latest commit

 

History

History
135 lines (100 loc) · 6.46 KB

plugin-overview.md

File metadata and controls

135 lines (100 loc) · 6.46 KB
Raw

Plugin overview

Reference description of what 3DsMax-XplnObj is, how data moves through it, and which Max classes it registers.

Identity

Item Value
Purpose Export (and attempt to import) X-Plane OBJ8 from Autodesk 3ds Max
Original author StepToSky (~2017); modernization under Coalition-of-Freeware-Developers
License BSD 3-Clause (license.txt)
Primary ship target 3ds Max 2024 (SDK major 26), x64
Feature era in tree XP10/11-era OBJ8 (e.g. NORMAL_METALNESS, BLEND_GLASS, draping, manips). XP12-specific directives are not claimed as supported — see obj8-xp12-gap-matrix.md
UI stack Win32 dialogs + ParamBlock2 rollups (no Qt)
Binary form Single combined utility plugin: .dlu

Import is registered but unfinished. Upstream and in-repo warnings state it does not work correctly. See plugin-operations.md.

Architecture pipeline

3ds Max scene
  │  X-Obj / X-Lod / X-Smoke helpers + mesh/light/anim node data
  ▼
src/converters/*          (Converterer, ConverterMain, ConverterMesh, …)
  ▼
xobj::*  (XplnObj library)   ObjMain / ObjLodGroup / Transform / ObjMesh / …
  ▼
ObjMain export APIs (XplnObj)   →  OBJ8 .obj on disk

Export uses the installed XplnObj write path (exportObj / export context — see DlgExport and current library headers). Import uses the matching import entry and remains unfinished at the Max conversion layer.

Layer Location Role
Max plugin entry src/3dmax/DllEntry.cpp LibNumberClasses / LibClassDesc / LibInitialize
Class descriptors src/classes-desc/ Six ClassDesc2 registrations
Helpers src/objects/main/, lod/, smoke/ Scene objects artists create
GUP / session src/gup/ObjCommon.* Menu, tool frame, settings, update check
UI src/ui/ Export/import dialogs, dock rollups, manip/light/anim panels
Models / IO src/models/ Per-node attribute, manip, anim, light persistence
Converters src/converters/ Max ↔ XplnObj bridge (Converterer)
OBJ library third_party/XplnObj or XPLNOBJ_PATH Read/write OBJ8, attribute/manipulators object model

Coordinate conversion uses a fixed Max→OpenGL matrix applied on export (ConverterUtils::TOOGL_MTX in DlgExport).

Registered ClassDesc types

DllEntry.cpp exports 6 classes via LibClassDesc:

Index Factory Class name (UI) Superclass Implementation Descriptor
0 ClassesDescriptions::commonClass() X-Common GUP_CLASS_ID ObjCommon CommonClassDesc
1 ClassesDescriptions::mainObj() X-Obj HELPER_CLASS_ID MainObject MainObjDesc
2 ClassesDescriptions::lodObj() X-Lod HELPER_CLASS_ID LodObject LodObjDesc
3 ClassesDescriptions::smokeObj() X-Smoke HELPER_CLASS_ID SmokeObject SmokeObjDesc
4 ClassesDescriptions::exporter() X-Obj-Export SCENE_EXPORT_CLASS_ID ObjExporter ExporterDesc
5 ClassesDescriptions::importer() X-Obj-Import SCENE_IMPORT_CLASS_ID ObjImporter ImporterDesc

Collector: src/classes-desc/ClassesDescriptions.{h,cpp}.

Helpers (Create panel, category X-Plane)

Class Internal name Role
X-Obj xObjectMain Root export unit: global textures/shading, cockpit regions, layer groups, export options ParamBlocks
X-Lod xObjectLod LOD group under an X-Obj; near/far distances
X-Smoke xObjectSmoke Legacy smoke_white / smoke_black emitter helper (deprecated in OBJ8 since 2020)

Exporter / importer

Class File dialog short desc Extension
ObjExporter X-Plane obj .obj
ObjImporter X-Plane obj .obj

Export entry: ObjExporter::DoExport → ui::DlgExport::show (src/3dmax/ObjExporter.cpp, src/ui/DlgExport.cpp).

Import entry: ObjImporter::DoImport → ui::DlgImport::show (src/3dmax/ObjImporter.cpp, src/ui/DlgImport.cpp).

GUP (X-Common)

ObjCommon (src/gup/ObjCommon.*) starts on Max load:

  • Main menu presenter (MainMenuPresenter + MainMenuActions action table)
  • Tool frame / dock UI (ui::ToolFrame)
  • Settings (Config / Settings)
  • Optional remote update check (UpdateChecker)
  • Scene open notification for scene-updater paths

.dlu artifact

CMake target naming (cmake/Sts3dmaxTarget.cmake):

Property Pattern (Max 2024 example)
CMake project / target 3DsMax-2024
Output base name 3DsMax2024-XplnObj
Suffix .dlu
Postfix -x64
Typical file 3DsMax2024-XplnObj-x64.dlu

Install: install(TARGETS … RUNTIME DESTINATION "$<CONFIG>") under CMAKE_INSTALL_PREFIX (e.g. …/output/Release/).

Runtime install into Max: copy the .dlu into the 3ds Max Plugins folder — see ../Install-Instructions.md.

Scene data model (conceptual)

X-Obj (MainObject)                    ← one exportable OBJ root
 ├── ParamBlocks: Attr / Exp / Display
 ├── child X-Lod …                     ← optional LOD groups
 │     └── meshes, lights, dummies, hierarchy, anim
 └── (or children directly if no LOD) ← export treats root as single LOD
X-Smoke                               ← can appear in hierarchy as smoke object

Per-mesh / per-node X-Plane attributes, manipulators, and animation keyframes are stored on Max nodes via models under src/models/ and edited through dock rollups (MainDock, ObjAttr, ManipAttr, LightAttr, anim views).

Dependencies

Dependency Role
3ds Max SDK Headers + link libs (core, maxutil, mesh, …)
XplnObj OBJ8 object model and file IO (xpln/obj/ObjMain.h)
WinHTTP / Win32 Update check, UI
nlohmann json (vendored) Update checker JSON (src/3rdParties/json)

XplnObj resolution: environment XPLNOBJ_PATH, third_party/XplnObj, or CMake AUTO_FETCH_XPLNOBJ — see build-max-2024.md.

What this plugin does not do

  • Does not write airport (apt.dat), DSF, forest, facade, polygon, line, terrain, or network files — see xplane-file-formats.md
  • Does not implement the X-Plane Plugin SDK (aircraft runtime plugins)
  • Does not claim full X-Plane 12 OBJ directive coverage