Welcome to StepToSky 3DsMax-XplnObj’s documentation!

Plug-in version: 2.6.0
Doc revision: 1

Tip

You can leave your wishes and bug-reports on the following sites:

Warning

Supporting some old 3Ds Max versions may be dropped soon. At this time we don’t exactly know what versions will be dropped but we are aimed to support last 3 3Ds Max versions.
It is difficult to develop and test the plug-in for all 3Ds max versions and different OS like windows 7, windows 10. So it may not be tested for some 3Ds Max versions and may have problems with them.

Danger

The plug-in isn’t UNICODE friendly. Don’t use paths and strings with none ASCII characters!
The X-Plane’s .obj also doesn’t support none ASCII characters for example: datarefs, commands, tool-tips etc …

Contents:

License BSD (3-Clause) for the Plug-in

Copyright (C) 2018, StepToSky

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1.Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2.Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation and / or other materials provided with the distribution.
3.Neither the name of StepToSky nor the names of its contributors
may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contacts: www.steptosky.com

Notes

  • English is not our native language so we apologize for all mistakes in this text and we are open for the mistakes reports.
  • The plug-in’s binaries can be found here: 3DsMax-XplnObj
  • The plug-in supports 9-2019 (x64) versions of 3Ds Max.
  • The plug-in is free for using in commercial and noncommercial purposes.
  • A lot of the plug-in’s options work according to the specification of the X-Plane obj format, so you ought to learn that specification.
  • The plug-in has auto-checking for updates functional don’t block access to the url: https://api.github.com/repos/steptosky/3DsMax-XplnObj/releases/latest
  • The plug-in can slow down opening large non x-plane scenes.

Start

UI

You have to open the window with objects options for the X-Plane.

_images/x-plane-obj-options.jpg

This window can be docked to the left and the right sides or can be float. The X-Obj and X-Lod you can find in the helpers category.

_images/objects.jpg

Scene Conception

There is the object X-Obj in the 3Ds Max which is associated with one X-Plane obj file. One 3Ds Max scene may contain any number of that objects.

Note

If the scene contains more than one that object and more than one are marked for exporting the exporter will work as a batch exporter, and name of each X-Plane .obj file will be the same as X-Obj name.

The objects which needs to be exported must be linked to one X-Obj. If you want to use X-Lod you need to link X-Lod to X-Obj then link your objects to that X-Lod.
_images/link.jpg
The plug-in processes each object and then its children, so with the objects tree you can manage the order as well.
For example: Assume that you want 2 manipulators to be always processed after the display. In the .obj file it should look like this:
TRIS X X ## display
TRIS X X ## manipulator 1
TRIS X X ## manipulator 2

So you have to make manipulator 1 and manipulator 2 as children of the display. Ordering is useful when you want to optimize your .obj.

Animation

You can use part of the native 3Ds max mechanism for the animation translation and rotation. For the hide/show animations the plug-in provides its own instruments. | The plug-in supports Position XYZ and Euler XYZ controllers with the linear tangents on keys. | You can specify the correct animation keys’ tangents globally or for the local keys only.

_images/tangents.jpg

Warning

For animation rotate you must use only one axis for one object. 3Ds Max uses Euler XYZ rotation controller with the default order XYZ, so only rotation around X can be animated safely.

It is possible to have other axis animated (not at the same time) but you will need to set the orientation with a parent. The system coordinates of your object must be aligned to the parent’s system coordinates then you may rotate parent as you wish and animate any axis of your object. It is not the exporter problem in some use cases you will have the animation problem in 3Ds max too because of Euler XYZ.
If you want to have the animation rotation for more than one axis you have to do it with the additional parent objects where each the parent object has animation on certain axis. The parent objects can be any objects including helpers.
You also can use bones for animation they always have X axis along their body.

DataRefs and Commands

The plug-in provides a dialog for working with the X-Plane’s DataRefs and Commands. It can be opened with buttons DRF: and CMD:.

X-Plane’s

For using X-Plane’s DataRefs and Commands you have to specify the X-Plane’s folder with the plug-in’s menu X-Plane -> Settings The files DataRefs.txt and Commands.txt from X-Plane’s folder will be loaded into plug-in.

Warning

Some 3Ds Max’s version can’t save last specified X-Plane’s folder properly if it contains non ASCII characters.

Project’s

Warning

It is still experimental feature! You can use it on your risk.

Note

The plug-in’s DataRef.txt reader ignores the first line. This is because the reader for X-Plane’s DateRefs and Project’s DataRef is the same and this format assumes that the first line is just an information line.

The X-Plane -> Settings contains some settings for this feature.
  • UseID: Enables using ID feature. It is described bellow.
  • Sorting: Enables sorting. Data from the DataRef.txt and Commands.txt will be sorted by data’s name while loading.

Warning

If UseID and Sorting are enabled then while auto-assigning ID the sorted data will be save.

For using project’s DataRefs and Commands you have to put files DataRefs.txt and Commands.txt in the same place where your 3Ds Max’s scene file is saved. The format of those data files the same as X-Plane’s ones, but it has an extension.
The extended format contains unique ID for each DataRef or Command. The plug-in manages such DataRefs and Commands by their ID only! If ID isn’t assigned then when you select a DataRef or Command for using the plug-in will auto-assign it and use that ID as the data key. If you want to see the real key associated with the ID you have to open dialog for working with DataRefs and Commands.
In other words there is the association unique ID -> data key (DataRef/Command) and the plug-in uses ID in your 3Ds Max’s scene. While exporting the ID will be replaced with the associated with it data (DataRef/Command).
This extension allows you to change DataRefs and Commands outside your 3Ds Max scene in their .txt files.
It helps for interaction between developer and 3D designers. 3D designers can create and use any key-name for DataRef or Command and when developers are ready to provide the correct keys they should only change project’s DataRafs and Commands .txt files. Then those changes will be pulled into 3Ds Max’s scene while it is loading and will be used while exporting.
This feature can be enabled or disabled in settings.

Example of valid data

Pay attention that DataRefs use tab symbol as the separator while Commands use space.

000001: my/data/ref/1
000005: my/data/ref/2
my/data/ref/3

000001: my/command/1
my/command/2
000005: my/command/3

Objects

Contents:

X-Obj

This is the main object which is associated with the one exported obj file. The scene must contain at least one that object.
All the options in this object affects whole obj file i.e. the options are global for the obj file.

Shading

  • Path prefix: The textures can be in any folder relative the obj file, so you can specify that folder as prefix. For example: if you want to put your textures into the folder map/cabin near your obj file you have to specify in this field the following text: map/cabin.
  • Diffuse: The diffuse texture of the object. See TEXTURE in the obj specification. The plug-in doesn’t change the texture it only uses the texture’s name.
  • Lit: The LIT texture of the object. See TEXTURE_LIT in the obj specification. The plug-in doesn’t change the texture it only uses the texture’s name.
  • Normal: The normal texture of the object. See TEXTURE_NORMAL in the obj specification. The plug-in doesn’t change the texture it only uses the texture’s name.
  • Normal Metalness: See NORMAL_METALNESS in the obj specification.
  • Blend Glass: See BLEND_GLASS in the obj specification.
  • Blend: See GLOBAL_no_blend and GLOBAL_shadow_blend and GLOBAL_specular in the obj specification.
  • Specular: See GLOBAL_specular in the obj specification.
  • Tint: See GLOBAL_tint in the obj specification.

Other attributes

Cockpit

Obj Options

These options are for the exporter itself.

  • Enable Meshes: Enables meshes exporting.
  • Enable Lines: Enables lines exporting.
  • Enable Lights: Enables lights exporting.
  • Enable Animation: Enables animation exporting.
  • Optimization: Does some optimization to avoid losing the FPS.

Warning

This functional is not implemented yet.

  • Instancing: Enables checking whether the object is instance friendly. The current algorithm does not check all the use cases but the X-Plane can check more ones. If the debug option is enabled the log file will contain a printout about your object. If the word complex is not present and the word additive is (or your object does not contain multiple LODs) then your object can be instanced. For more information about instancing read the X-Plane obj format specification.
  • Debug: Prints the obj text in friendly form and prints DEBUG attribute in the obj file.
  • Scale: The scene scale. You can use the system units In the 3Ds Max as you wish but the X-Plane uses meters. So you can set the scale which is needed for the transformation your scene size to the X-Plane’s scene size. It doesn’t work automatically yet. For example: if you use centimeters then the scale must be 0.01. Pay attention that the system units in the 3Ds Max aren’t the same as the Display units.

Useful for the debug options:

TRIS 6 6 ## My mesh object name here
LINES 6 6 ## My line object name here
## My light object name here
LIGHT_NAMED
## My dummy object name here
  • Name Meshes: Enables the mesh name printing near the TRIS.
  • Name Lines: Enables the lines name printing near the LINES.
  • Name Lights: Enables the light name printing near the LIGHT_XXX.
  • Name Dummies: Enables the dummies name printing.
  • Tree Hierarchy: Enables text line indent corresponding the tree hierarchy.

Display

  • Scale: The scale of icon it also depends on the system units.

X-Lod

Represents the LOD object.

Parameters

  • Near: distance in meters.
  • Far: distance in meters.

Display

  • Scale: The scale of icon it also depends on the system units.

X-Smoke

Represents the smoke object.

Options

  • White/Black: smoke type.
  • Size: is a size number indicating the relative intensity of the smoke.

Display

  • Scale: The scale of icon it also depends on the system units.

Objects parameters

Contents:

X Base Attributes

This options is only allowed for the mesh oriented geometric objects. (Primitives, editable mesh, editable poly etc..)

X Manipulator

One object may have only one manipulator. For more information about the manipulators see manipulation commands in the obj specification.

X Light Attributes

This options is only allowed for the light objects.

Named Light

See LIGHT_NAMED in the obj specification.
See More about named light.
You can locate the master list of named lights in the file Resources/bitmaps/world/lites/lights.txt. Do not edit this text file!

Param Light

See LIGHT_PARAM in the obj specification.
See More about param light.
You can locate the master list of named lights in the file Resources/bitmaps/world/lites/lights.txt. Do not edit this text file!
Param light supports text variables, the following variables may be used:
  • $rgb Reads RGB color from the light.
  • $direction Reads target direction from the light. If the light is omni direction it will be 0.0 0.0 0.0. As the direction value also depends on the param light type the plug-in detects the type reading end of the light name _sp means light is spill.
  • $width Reads falloff value of the 3Ds Max’s spot light. This will be 1.0 if the light is omni.
The $direction and $width values are transformed to the correct ones for the obj file depending on the param and 3Ds max lights types.
Example:
  • airplane_strobe_sp $rgb 0 1.0 $direction $width.
  • airplane_landing_core $direction:a+10.0 0 1.0.
The $direction Also has addition parameters for the billboard light. As the 3Ds Max’s spot light may have maximum cone angle 180 degrees but billboard light may have up to 360 you can use the following syntax to make cone angle greater:
  • $direction:a+10 where 10 is any value and this value will be added to the light cone angle. Assume your spot light has 90 degrees cone angle then cone for the billboard light will be 90 + 10 = 100.
  • $direction:a-10 the same as above but subtract the value 90 - 10 = 80.
  • $direction:a120 exactly set the cone angle 120

Custom Light

See LIGHT_CUSTOM in the obj specification.
See More about custom light.

Spill Custom Light

See LIGHT_SPILL_CUSTOM in the obj specification.
See More about spill custom ight.
You have to use ‘Target Spot’ light for this light type. The plug-in reads the Falloff/Field parameter and the target direction to calculate necessary values for the X-Plane.

Animations

Rotate/Translate

  • Enable: Enables or disables this animation export.
  • U: (Update) Synchronizes animation keys and associated with them values.
  • Value: Click the line in the list view below and then with this spinner you can set the necessary value.
  • Dfr : DataRef for the animation.
  • Reverse: If checked then the animation keys will be reversed while exporting, it doesn’t affect the animation in the 3Ds max scene.
  • RV: Reverses values of the DataRef.
  • Calc.V: Opens the value calculator. The calculator tries to calculate the values for the correct linear animation, so the values depends on the frame number where the animation keys are. It is useful when you try to animate relation between the objects or simulate Inverse/forward Kinematic, for example: mechanism of the landing gears.
  • Loop: Enables or disables loop animation.

Hide/Show

  • Enable: Enables or disables this animation export.
  • Add Show and Add Hide: Adds corresponding animation to the animation list.
  • Del: Deletes the selected animation from the animation list.
  • v1 and v2: sets the corresponding values to the selected animation.
  • Dfr : DataRef for the animation.

Exporting

For export the objects go File→Export→(Export) and choose X-Plane Obj specify the name and press save.

Note

If there are more than one objects for exporting then the file name will be ignored and the name from X-Obj will be used.

Buttons

  • Donate: Opens the link where you can donate for the developing the plugin.
  • Check for Update: Opens the link where you can see the actual plugin version.
  • About: Opens the window with the information about the plugin.
  • Exporter: Starts exporting.
  • Cancel: Closes the window and aborts the exporting.

Objects for exporting

This area contains list of all X-Obj in the scene and you can enable or disable the exporting for the certain objects.
The selection set is not the global and it is saved with the 3Ds Max’s scene.

Settings

  • Auto-Export: In normal way you have to press the button Export to start the exporting but when you do that action very often and don’t change any settings you can check this checkbox and the export will be auto-started without pressing the Export button. The state of the parameter isn’t the global and it is saved with the 3Ds Max’s scene.

Log console

The plug-in prints the information into the console about some events. (info, warnings, errors etc…) - Save Log: This button saves the current 3Ds Max’s log into the place you have specifies. The log file is necessary when you report about some bugs.

Best Practices

  • Don’t make UVW seams and smoothing groups seams if you don’t actually need it. All geometry will be broken by UVW seams and smoothing groups seams. It means that producing obj file will contain more vertex. So keep in mind this situation while you are modeling.

Backward Compatibility

Note

  • Old plug-in versions don’t support scenes which are made with newer ones.
  • if it is possible new plug-in versions support scenes which are made with the previous versions not older then 1.8.5. If new version breaks backward compatibility you will be informed in this documentation and in the change log.

Version 2.6.0

In this version Datarefs and Commands project format was changed. The new format allows you to use data started with figures.
Symbol ‘’:’’ must immediately follow the ID. Example: 000001: my/dataref/name
You must manually change your DataRefs.txt and Commands.txt project files if they have data ID.
Read more.

Version 2.4.0

In this version bug with LODs’ values was fixed.

Attention

This change may need your attention:

Version 2.2.0

In this version the cockpit and manipulators state machine was changed. Previous behavior worked incorrectly. The plug-in will ask you to update your scene. The update will add the panel manipulator to all objects that have cockpit or cockpit region attribute except the objects that have already another manipulator.
After the update you have to check the affected objects manually because it isn’t possible to do the correct updating programmatically in some cases, so if some objects don’t need the enabled panel manipulator just disable it.

Attention

  • Previous behavior: The panel manipulator was enabled implicitly with the cockpit or cockpit region attribute and was incorrectly disabled in some cases (it is the bug). There was also incorrect interaction between cockpit/cockpit region and manipulators.
  • New behavior: The panel manipulator have to be enabled explicitly if you need it. The bugs were fixed.

Change-log

Note

Don’t forget to see Backward Compatibility

2.6.0 (28.11.2018)

  • Added: Settings - enable/disable project’s DataRefs and Commands ID usage.
  • Added: Settings - enable/disable project’s DataRefs and Commands Sorting.
  • Updated: Datarefs and Commands project format. Symbol ‘’:’’ must immediately follow the ID. See the help for more details.
  • Fixed: Bug when you try to set custom DataRef or Command key while project’s DataRef or Command list is open, the key was set as ERROR_DATA_NOT_FOUND

2.5.0-beta (27.10.2018)

  • Added: Dialog DataRefs/Commands selector. I.e. buttons drf: and cmd: are implemented now.
  • Added: Settings window. Use menu X-Plane->Settings for accessing it.
  • Added: Ability to use tool-tip for ATTR_manip_noop.
  • Added: Ability to use text variables in the param light’s parameters string.
  • Updated: Link to the help. It is on-line now.
  • Updated: Embedded named and param lights’ names lists. Full list you can find here X-Plane-root/Resources/bitmaps/world/lites/lights.txt
  • Fixed: Sorting algorithm for LODs. #9
  • Fixed: Bug for attribute printing: AttrShiny AttrBlend. Default/disabled values were not printed when those attributes were enabled and then disabled.

2.4.0-beta (12.09.2018)

  • Added: Supporting for 3ds max 2018 and 2019.
  • Improved: Some GUI elements/windows/dialogs.
  • Fixed: LODs’ values exporting. It isn’t scaled anymore if you use system units other than ‘meters’.

Note

New Plug-in’s dock window and menu aren’t good adjusted to be used with the new 3Ds Max’s workspaces conception.

2.3.1 (31.08.2018)

  • Updated: Some manipulators UI text to be shorter.
  • Updated: Limits for values of hide/show animation. 10 000 -> 1 000 000.
  • Fixed: LIGHT_SPILL_CUSTOM direction export.
  • Fixed: Signature printing.
  • Fixed: Printing incorrect attribute name for the ATTR_manip_command_switch_up_down and ATTR_manip_command_switch_left_right.

2.3.0 (05.10.2017)

  • Added: Error if any LOD except the first one contains hard polygons.
  • Added: Auto-flip normals for objects with mirrored transformation.
  • Fixed: GUI for the light param.
  • Fixed: Creating two sided mesh.
  • Fixed: Printing custom name of the LIGHT_PARAM.

2.2.1 (26.08.2017)

  • Fixed: Printing error if texture name contains illegal symbols.
  • Fixed: Opening update message for non x-plane scenes.
  • Fixed: Crashing on some objects, for example ‘Biped Object’.
  • Fixed: Vertical scroll bar in the export console.

2.2.0 (10.07.2017)

  • Modified: By default all the manipulators are disabled now! Previous behavior was: the ‘panel’ manipulator was implicitly set when you added any cockpit attribute like ATTR_cockpit.
  • Added: Panel-Click manipulator. This manipulator should be used for the cockpit geometry (ATTR_cockpit) when you want to enable the panel manipulators.
  • Added: Checking if opening scene was created with a newer plug-in version. If so then the scene will not be loaded and a warning will be printed.
  • Added: Smoke object. It can be found near X-Obj and X-Lod.
  • Added: ‘X-Plane’ menu on the 3Ds Max’s top menu bar.
  • Added: Documentation in the separated repository. Use the ‘X-Plane’ menu to get it.
  • Fixed: Log file creation for some 3d max versions.
  • Fixed: Manipulators’ state machine. There were some problems in the state machine one of them could lead to undefined behavior, it was fixed.

2.1.0 (16.05.2017)

  • Added: ‘(U) Update’ buttons for the animation rollups, allows you to re-synchronize animation keys and values.
  • Added: Tool-tips for the some controls of the export window.
  • Added: Ability to enable or disable ‘X-Obj’ export. It helps when you work with more than one ‘X-Obj’ in the scene. You can export only selected ones.
  • Added: Check-box for enabling auto-export. If it is enabled then the export will be auto-started without pressing the ‘Export’ button.
  • Fixed: Link to donate. The button ‘donate’ leads to the correct web page now.
  • Fixed: Loop animation attribute printing.

2.0.2-beta (23.04.2017)

  • Added: Changing the text of the update button if a new version is available.
  • Fixed: Potential unstable code.

2.0.1-beta (22.04.2017)

  • Added: Auto-check for update. If a new version is available after exporting you will see the information in the console.
  • Fixed: Incorrect error printing for the animation keys.
  • Fixed: Cloning X-Plane object data during the objects clone in the 3Ds Max 2017.

2.0.0-beta (19.04.2017)

  • Released: beta version.