You can download the distributions of this plugin, Primitive tsxPython (ptsxpy), for trueSpace (tS) series here. Please take a brief look at Requirement, License, and Disclaimer first.

Warning: Almost all methods (functions) have been roughly tested but the project is on "Beta test" stage. Please run at your own risk.

Quick Start

Quick Start

Last modified: 2023-04-20

1.  Install

(1) Make sure that following runtime library has already been installed in your conputer.

Microsoft Visual C++ 2017 Redistributable (x86)

Note that it must be "x86" (i.e. for 32 bit) even if your OS is 64 bit. You can download and install it from Microsoft's site. If a file, ucrtbase.dll, has already been installed in the directory Windows\SysWOW64\ or Windows\System32\ of your computer, the installation of the runtime may not be unnecessary. You can also check that by right-clicking Windows "Start" - "Programs and Features" (or "Control Panel" - "Programs and Features").

(2) Unzip the downloaded zip files to any folder you like. You will get the following files. Don't unzip python37.zip extracted from a *.zip.zip file.

Contents of zipped Python files
For Python3 scriptsFor Python2 scriptsNote
python37.dll python27.dll Copy of Python Official
python37.zip   Copy of Python Official. No unzip needed

 

Contents of zipped ptsx Main parts files
For Python3 scriptsFor Python2 scriptsNote
ptsx3cnsl.dll ptsx2cnsl.dll Console
ptsx3py.tsx ptsx2py.tsx Main
ptsxpydef1.py Pre-defined classes, constants, etc.

 

Contents of zipped ptsxpy tS specific parts files
For Python3 scriptsFor Python2 scriptsNote
ptsx3pysb66.dll ptsx2pysb66.dll

for trueSpace 6.6
(Model side of trueSpace 7.6*) only

ptsx3pysb60.dll ptsx2pysb60.dll for trueSpace 6.0 only
ptsx3pysb51.dll ptsx2pysb51.dll for trueSpace 5.1 only
ptsx3pysb43.dll ptsx2pysb43.dll for trueSpace 4.3 only

 

If you want to check the version of each ptsxpy DLL file, right click the file, select "Property", and select "Details" tab. You can also know the version of *.tsx after temporarily renaming to *.dll.

If you want to check the Python DLL files are genuine, please read "About the Python DLL" section in the License tab.

(3) Using File Explorer (Windows Explorer), locate to the directory where tS was installed. (If you forgot it, right click your trueSpace icon and select "Open file location")

(4) Find "tsx" (or "Tsx") folder and locate in it.

For example, you may be in: c:\xxxxxxx\trueSpace761\tS\tsx\

(5) Make a folder in the "tsx" folder, rename it to "ptsx3py" (or "ptsx2py") or any name you like, and move the downloaded and unzipped files to the folder. You need not unzip the python.37.zip.

Warning: Please bear in mind that tS may crash or the current tS scene, objects, parameters, or other states may be broken by running the plugin and scripts.  It's recommended to save the important scene and objects before load or run the plugin.

 

2. Uninstall and partial update 

If you would like to uninstall the ptsxpy, just delete the "ptsx3py" (or "ptsx2py") folder that you made at the installation precess. This plugin does not write any Windows registory on its installation.

If you would like to update to newly released version, just replace the files. Before you run your script, you should unload the old ptsxpy3 (or ptsxpy2) icon using Shift drag to trashcan icon, and then load the .tsx file to trueSpace.

3. Load ptsxpy to trueSpace

(1) Start your trueSpace.

(2) Find "Install new trueSpace extension" button ("plug" icon) and click it. A file selection dialog appears.

If you use tS4.3, a place holder with eight buttons appeares when you click the plugin button. Click unused one of eight.

 

 

(3) Locate to the "ptsx3py" (or "ptsx2py") folder, double-click "ptsx3py.tsx" (or "ptsx2py.tsx") or select it and hit Enter key.

(4) The "ptsxpy3" (or "ptsxpy2") icon appears next to the "plug" icon. The Screen shot below is of tS7.6 (Model side)

, or for tS4.3

If you would like to unload the plugin, Shift drag the icon to the trashcan. You can clone the icon by dropping any othre place.

You may load both ptsxpy3 and ptsxpy2 on a tS at the same time and can run script with each Python. However please note that the console window and the tS resources are common for both. You must avoid conflict of them.

4.  Run a Python script file

(1) Prepare your script file. For example, create a text file, open it using a text editor, copy following code, save and rename it like "test1.py".

In Python language, the indentation level (i.e. blank preceding to each line) is significant. Please check the documents distributed by python.org: "PEP 8 -- Style Guide for Python Code" )

#------------------------------
# Create and move some cubes.
#------------------------------
import ptsxpy as p
import ptsxgp
import math

x = 0.

for i in range( 5 ):
    print( "i=", i )
    cb1 = p.CreateCube( 2 , 1., 1., 1. )
    p.SceneAddObject( cb1, e_tsxFALSE )
    loc = Vec3f( x, 0., 0. )
    print( "loc=", loc.prt() )
    p.GNodeSetLocation( cb1, loc.p )
    x += 2.

p.SceneDraw()

 In the example above, p.CreateCube() calls the correcponding C++ side tSxAPI function tsxCreateCube(). You can get information from tSxAPIxx.doc in SDK for each trueSpace version. The module "ptsxgp" and "math" are imported but not used in this example. They are necessary only if you use methods of these module. The "math" is a satandard module of Python and the "ptsxgp" has general purpose functions for user script and "ptsxpydef1.py".  The "ptsxpydef1.py" is always imported automatically to user script (please read also the section below).

(2) Click the "ptsxpy" button.

(3) A file selection dialog and a console window (with black background) appear. tS may hide the console window. you can bring it forward later using holding-Alt key and a few times of Tab key.

 

 

 

Note: Turn off the preview mode of the file selection dialog before you open a file. If you open in the preview mode, a tS screen view would get freezed.

(4) Locate to the directory where a script you would like to run exists. Double-click your script file (or select and Enter key)  to start it.

(5) A message "...ended" comes to the console window when the scripts ended.

Note: It's highly recommended that you manage the combination of the Python major version  (2 or 3) and ptsxpy major.minor version (x.y in x.y.z), because the specifications and the implementations of ptsxpy may change in the future. In addition, if you attach the script to a post to the Uesr Forum, etc., you should clearly describe on which tS version the script can run.

KNOWN FATAL BUG: Don't close the (black-and-white) console window using "x" button, Alt F4 key, or Ctrl C key, etc. If you close it with such actions, trueSpace will crash. The console window will close safely when you terminated trueSpace or when you right-clicked the ptsxpy icon and click "OK" button in a message-box.

Don't close the console by other than right-clicking the ptsxpy icon

 

5. Syntax of functions, predefined classes and constants

In the above sample code, the script is calling some tsxAPI functions like: p.XXXXX( ---- ). The "p" here is an alias of a module "ptsxpy" defined at the beginning of the script. The "XXXXX" here is the part of the name of each tsxAPI function, tsxXXXXX(). If you have the SDK (Software Development Kit) distributed by Caligari corporation for your trueSpace version, you can know the syntax and behavior of them from tsxAPIxx.doc and .h files. The SDK may be found via the net.

The plugin automatically imports a plain text, "ptsxpydef1.py", while it initializes Python. It defines some classes (e.g. Vec3f) and constants (e.g. sizeof_CtsxVector3f). Please don't modify the file. You can add your original classes and constants in each script file or in your file. In the sample script, an instance of Vec3f class is assigned to  the variable "loc". The "loc.p" means the pointer to the three float values. The function GNodeSetLocation() receives it as the 2nd parameter, and sets the location of the cube object given to the 1st parameter. The "e_tsxFALSE" is defined in the "ptsxpydef1.py". You need not to write like "ptsxpydef1.e_tsxFALSE" and can omit the module name because the module is imported like "from ptsxpydef1 import *" by the plugin. The "ptsxgp" is a module of general purpose auxiliary functions.There are some ptsxpygp functions used in "ptsxpydef1.py".


Please read also HELP pages and visit FORUM where you can get sample scripts, read tutorials, report bugs, request features, discuss with members, or ask questions. Registration required before submitting your first post.