NO GUARANTEE. MAY NOT WORK ON YOUR SYSTEM OR ANY OTHER SYSTEM, FOR THAT MATTER. ALL USAGE OF THE CONTENTS OF THIS PACKAGE IS SOLELY YOUR RESPONSIBILITY. NEITHER THE ATX PLUGIN SYSTEM NOR ITS AUTHOR ARE RELATED IN ANY WAY TO THE COMPILERS/UTILITIES MENTIONED HEREIN, AND THEIR PROPERTIES BELONG TO THEIR RESPECTIVE OWNERS. ANY LEGAL ISSUES THAT MAY ARISE WITH THE USE OF THIS SYSTEM ARE YOURS TO DEAL WITH.

- About
- Updates
- Installation
- Plugin System Programmer's Reference
- Known Bugs
- Credits

This module is a limited built-in component of ATYPEX.dll of the ATX Trespasser modification package. It defines a series of import and callback functions at the DLL level, which permits separate DLLs created using programming languages and compilers other than (as well as) assembly to add to ATX's functionality, all easily swappable on the user end. It also defines various structures, data types, and other info necessary to manipulate some of the game's objects.

The plugin system files consist of a C/C++ include header file for all needed definitions, atxplugin.h, an example atypex.lib file for linking with Microsoft Visual Studio C/C++ 2003+, and a programmer's reference (found further within this document). There is also a "atxtresclassdefs.h" include file (included in atxplugin.h) who's sole purpose is to declare the more known Trespasser classes and their inheritance relationships using simple structures. It has very limited use in practice, but is required. A third large include file, "atxtscriptindexes.h", declares every known T-Script name ID for use with the new plugin ActionTypes.

Although the current system has only been tested with C/C++ compilers, particularily MSVS 2003, all functions imported and exported by ATYPEX.dll use unmangled names as well as the 'stdcall' calling convention, potentially allowing other languages to communicate with ATX just as simply. In general, any Win32-capable language should be compatible; all that is usually needed is a proper definition of imports/exports (i.e., generating library (*.lib) files using definition (*.def) files for C/C++) and a translation of the header definitions. All functions exported by ATYPEX.dll can also be imported into modules using the Win32 GetProcAddress function (though DLL callbacks must still be exported using some method such as *.def files).

All items noted hereby can be found in the ATX 2.00+ source package, under the folder "ATX_PLUGIN".

* Plugin System versions/releases correspond and are equivalent to ATX package versions/releases.

V2.00:
- first plugin system integration into atypex.dll

Plugin installation is very simple. Simply place the plugin's DLL into your main base Trespasser folder, i.e., in the same folder as ATYPEX.dll and the Trespasser executable are found. Then, navigate to the "MAPS\PLG\" sub-folder, and create a new empty sub-folder under "PLG\" with the same name as the plugin's DLL, without extension.

For example, suppose you have a plugin named "myplugin.dll". The DLL will have the path, "[trespasser folder]\myplugin.dll", and the plugin's sub-folder will have the path, "[trespasser folder]\MAPS\PLG\myplugin\".

Even if the plugin's sub-folder is empty, it is necessary for it to exist; this is how ATX detects the presence/identity of the plugin, which it could otherwise not do simply by scanning the base Tres folder, since DLLs other than plugin DLLs exist there as well. The plugin's sub-folder itself is reserved for use by the plugin, which receives a reference to it at game load time. It is recommended that all plugins save any and all required data to their respective plugin folders; this will allow multiple plugins to coexist peacefully on the same systems.

It is recommended that you distribute plugins in a package that will automatically create the plugin's sub-folder upon installation, for example by including a "MAPS\PLG\[plugin name]\" sub-folder in your ZIP file containing your DLL, even if empty, which will create the folder when the user extracts it (preserving pathnames) to his base Trespasser folder. It is also recommended that you have a unique, clear name for your plugin which corresponds to its DLL name at all times. This will minimize confusion.

- Requirements - Where To Start (IMPORTANT!)
- Plugin Callback Functions (Plugin DLL Exports)
- Plugin Library Functions (ATYPEX.dll Exports)

This ATX plugin system reference enumerates and describes the functions and constants declared in the "atxplugin.h" main header file for C/C++. For C/C++ -based plugins, it is assumed in this document that atxplugin.h is present alongside your project and that you have included it at the beginning of your main source file (i.e., " #include "atxplugin.h" " for C/C++).

An ATX plugin must be a Win32 Portable Executable (PE) in the form of a Dynamic Link Library (DLL). It should always have a DLLEntryPoint/DllMain function for compatibility and proper automated initialization/uninitialization by the compiler.

However, your plugin should NEVER have any important code in its DllEntryPoint/DllMain; all it should do is take note of its module handle. ATX provides two callback functions, ATXCPostDLLLoad and ATXCPreDLLUnload, which are called following DLL load and prior to DLL unload, respectively. These should ALWAYS be used for (un)initialization instead. These correspond loosely to the DLL_PROCESS_ATTACH and DLL_PROCESS_DETACH cases of DllMain.

How you will tell your compiler to create such a valid DLL will depend on the compiler. For Microsoft Visual C++ 2003+, you simply need to create a new "Visual C++ Project", select "Win32 Project", and in the "Application Settings", select "DLL". You may want to disable pre-compiled headers if they annoy you.

Once you have the project created, go to its project folder, and copy "atxplugin.h", "atxtresclassdefs.h", and "atypex.lib" to it. You should also create an empty text file in this folder named after your plugin's name and with a *.def extension, to be able to export symbols later (i.e., "myplugin.def"). See Plugin Callback Functions (Plugin DLL Exports) for info on exporting functions in MSVC++.

In your main source file, you then simply have to include "atxplugin.h", using, say, "#include "atxplugin.h"". However, you must also tell the linker to link using "atypex.lib", which includes imports for the functions defined in the header file. See Plugin Library Functions (ATYPEX.dll Exports) for info on setting up library imports in MSVC++.

The rest is trivial; simply provide definitions for atxplugin.h atxcallback functions that you want to implement in your main source file. Use the provided atximport functions as much as possible to accomplish your plugin's task. Once you've decided on your exports, all that's left to do compiler-wise is to tell MSVC++ to export the functions using undecorated names, which you must do using the *.def file mentioned earlier. Again, see Plugin Callback Functions (Plugin DLL Exports) for info on exporting functions in MSVC++.

You can check whether you properly exported these once you've compiled runnable code. Simply install the plugin in your Trespasser folder as previously described and run ATX. Once that is done, open "ATX_LOGFILE.txt" and look for the plugin system info. It will list all plugins that were detected and which callbacks were detected for each.

If you are using MSVC++, make sure that you ALWAYS compile your plugin using Release mode, and NOT Debug mode. Remember: your DLL will run in the context of an already-compiled game, with a lot of emulation. Simple, safe, straightforward code with explicit error checking is a necessity, and should always be chosen over fast, theoretically practical, or debug-heavy code with implied error handling. You will not have access to MSVC++'s debugger at all; only low-level disassemblers such as Ollydbg and WDasm can provide such real-time help, and via assembly code only.

In short, try to keep memory management and (un)initialization as simple as possible. Always check for null pointers. DO NOT RELY ON LOCAL VARIABLES, RECURSIVE FUNCTIONS, AND FUNCTIONS WITH MANY/LARGE PARAMETERS!!! Using functions that allocate too much space on the stack (i.e., more than a few hundred bytes, say 100-200) can sometimes cause stack overflows and crashes in the context of the game. Entire ATX features had to be rewritten because of this. As an exception to general programming, it is highly recommended for ATX plugins to rely on global (static) variables as opposed to automatic ones. Also of great importance: if you must allocate memory that is to be passed in any way to the game, such as an ActionType instance, you MUST go through the plugin library's explicit memory management functions for allocation (ATXGameMemNew, ATXNewATAllocInstance, etc.). Likewise, if you must free any memory gotten from the game, you must use the corresponding explicit memory management plugin library functions. Failure to do this may lead to mixups with memory spaces allocated using different mediums.

-> Go to Callback Listing

The plugin DLL callback functions are the functions that your plugin DLL can export so that ATX (via ATYPEX.dll) will call your code at their appropriate predefined times (DLL load, level load begin/end, frame drawing, etc.). Some are optional, while others may be mandatory. When ATX loads your plugin (at game start), it searches your DLL for all exported functions of known ATX callback names, and later calls them when appropriate. If certain function names are not found (i.e., not exported or wrongly exported), ATX simply does not call them for your plugin.

These functions are declared as stdcall external functions in atxplugin.h, using the label "atxcallback". All names begin with "ATXC" (but do not rely on this to distinguish from library functions). To make use of them, simply define them in your plugin's source using the same provided signatures.

You must also find a way to tell your compiler to export these functions in your DLL, without name decoration of any kind (i.e., a callback named SuperFunction must be exported as symbol "SuperFunction", and NOT as "_SuperFunction@1" or such nonsense). In Microsoft Visual Studio, this can be done by linking a *.DEF file, which list all function names to export, with your project.

To do this, create an empty text file with extension *.def, i.e., "myplugin.def", in your main project folder. Open the file and enter the following:

LIBRARY myplugin
EXPORTS
 MyFirstExport
 MySecondExport
 MyThirdExport	     

... and so on, where the entries under "EXPORTS" are the names of the atxcallback functions you wish your plugin to export for ATX. Once you've done this, all you need is to add the *.def file to your linker command line (Project -> [project name] Properties -> Linker -> Command Line -> Additional Options: /DEF:"myplugin.def").

This method, unfortunately, does not work for all compilers (some generate decorated names automatically and/or thoroughly enjoy wasting your time). You may have to consult your compiler's documentation to figure out how to export DLL functions without name decoration. If you are unable to find a way to do so, you may have to switch to a more able compiler, as these callbacks should be of utmost importance to most plugins.

ATXCPostDLLLoad
ATXCPreDLLUnload
ATXCPreScreenRender
ATXCPostScreenRender
ATXCPreLevelLoad
ATXCPostLevelLoad
ATXCOnActBite
ATXCOnLevelSave
ATXCOnPlgUserCommand
ATXCNewATInit

C/C++ Signature: void atxcallback ATXCPostDLLLoad(const char *pluginDLLPath,const char *pluginFolderPath);

Parameters:
pluginDLLPath - full path and filename of this plugin's DLL file (always in base Trespasser folder)
pluginFolderPath - full path of this plugin's subfolder (always a sub folder of "[trespasser folder]\MAPS\PLG\")

Return value(s): none

Description: This is the main initialization callback for all plugins. It is called as soon as the Trespasser executable is first executed by the user, which instantly launches ATX and begins initialization. Very few functions are available for use during this time, because the game is NOT loaded; your plugin should simply initialize all of its static values here and take note of its plugin folder for saving data (as well as its own DLL path from which it can get the base Trespasser folder, if needed). Only the required ATX modules are initialized before this call.

It is HIGHLY RECOMMENDED that you rely on this callback to initialize any data and NOT on the DLLEntryPoint of your DLL.

C/C++ Signature: void atxcallback ATXCPreDLLUnload();

Parameters: none

Return value(s): none

Description: This is a complement to ATXCPostDLLLoad. It is called whenever the game is exited, that is, after the game has fully unloaded from memory and is about to call ExitProcess(). Please limit your plugin's activities to simple, independant un-initialization of your DLL's static variables during this callback.

C/C++ Signature: void atxcallback ATXCPreScreenRender();

Parameters: none

Return value(s): none

Description: This callback happens right in the core of Trespasser's world game system mayhem. It is at some point before the next back-buffered frame of the current game state is drawn, around the time when the game's *.asa animations are cycled. This is where you would include anything having to do with the manipulation of instances in the game world, i.e., teleportation, velocity changes, camera movements, physics stuff, etc. You *could* also check user input here, asynchronously. You do NOT have access to any rendering functions during this callback.

C/C++ Signature: void atxcallback ATXCPostScreenRender();

Parameters: none

Return value(s): none

Description: This callback takes place about at the same time that the game's "LOC" cheat handler displays the player's location using a TextOut() call. This is where you would include anything that accesses the screen for drawing. The functions ATXGetBackBufferSurfaceDC and ATXReleaseBackBufferSurfaceDC are designed explicitly to this effect. All of ATX's screen outputs, i.e., text messages and the 2D maps, as well as video recording, take place during this time. You *could* also check user input here, asynchronously.

C/C++ Signature: void atxcallback ATXCPreLevelLoad(bool isNewGRFLoad);

Parameters:
isNewGRFLoad - this value is TRUE if the level that will be loaded is being loaded/reloaded using its GRF file (not a quick reload)

Return value(s): none

Description: This callback happens prior to a level load. It is generally useful for initialization purposes, but supports no operations on game instances in general, because they're considered not to have been loaded yet. However, if the level is not being reloaded using its GRF file (and only the SCN file), its instances, for the most part, are not re-loaded and are still considered valid, which you may have to take into consideration. You also may NOT do any screen writing.

C/C++ Signature: void atxcallback ATXCPostLevelLoad(bool isNewGRFLoad);

Parameters:
isNewGRFLoad - this value is TRUE if the level that has been loaded was done so using its GRF file (not a quick reload)

Return value(s): none

Description: This callback is called as soon as a level is about to begin. At this time, all T-Script-based CStartTriggers have already been run, and most ATX functions initialized. All game instances are also ready to be manipulated, so you can do any such manipulation at level start using this callback, if necessary. You may not, however, do any direct screen writing.

C/C++ Signature: void atxcallback ATXCOnActBite(CActivityBite *biteInst, CInstance *biteTarget, CInfluence *sourceInfluence);

Parameters:
biteInst - the CActivityBite instance of the CAnimal instance that is performing the biting act
biteTarget - the instance that is currently the target of the animal's biting (may be NULL)
sourceInfluence - the CInfluence instance which 'pushed' the animal to performing the act of biting (currently has no use)

Return value(s): none

Description: This callback occurs every time an animal exhibits [i]and maintains[/i] the "ActBite" behaviour. You are generally free to manipulate game instances during this callback. You may use the ATXGetCurrentBitingAnimal, which is explicit to this callback, to get the CAnimal instance which is currently performing the bite.

C/C++ Signature: void atxcallback ATXCOnLevelSave(const char *saveFilePathName);

Parameters:
saveFilePathName - this is the full path and name of the savegame which is being written to by Trespasser

Return value(s): none

Description: This callback takes place every time a game is saved, whether it be initiated by the user, ActionType 19, or ATX. You could use this to trigger your own savegame data, although you should ensure that whatever data is saved remains separate from the existing Trespasser and ATX files (i.e., in your plugin's "MAPS\PLG\" folder, for instance).

C/C++ Signature: void atxcallback ATXCOnPlgUserCommand(const char *args);

Parameters:
args - pointer to a string of commands (may be NULL if no arguments entered by user)

Return value(s): none

Description: This callback happens every time the user enters the "PLG" cheat at the in-game console with arguments. What the args pointer designates at this time is whatever string arguments the user might have entered at the console following the "PLG" cheat. Thus, you can parse this string for any keywords your plugin might interpret as commands or cheats.

Be aware that there can be more than one argument and various space characters, so it must in fact be parsed and not simply compared to a single keyword or such. I suggest using the 'sscanf' function. The args parameter will never be null.

The general idea behind this callback is that you can implement your own cheats, as ATX does, simply by checking these arguments as you would from other console. The only real difference is that the user must type "PLG" before the command(s).

Please keep in mind that the Trespasser console supports a maximum of 32 characters (from the beginning of the "PLG" command to the last parameter), so please refrain from using very large command names or too many parameters.

Note: Please use unique command names whenever possible, as all commands are always sent to all plugins, whether they have already been processed by one or not.

C/C++ Signature: void* atxcallback ATXCNewATInit(uint atNum, void *lpScriptIDTable, CObjectValue *lpSourceObject, CValueTable *lpValueTable);

Parameters:
atNum - the integer number of the ActionType being processed/queried
lpScriptIDTable - pointer to the base of the script entry name ID table
lpSourceObject - pointer to a CObjectValue instance for the T-Script group entry containing this ActionType's values
lpValueTable - pointer to the CValueTable instance being used to process the GRF file (trivial)

Return value(s): pointer to a new ActionType instance, or NULL if plugin does not process this AT number or if failure occurs

Description: This callback is called every time a new ActionType number that is over 499 is detected while loading a level's GRF T-Scripts file. It is meant to allow plugins to define and implement their own ActionTypes based on Trespasser Script values and predefined AT numbers.

If your plugin implements this function, it must return a value. It must return NULL to indicate that it has not processed the passed ActionType number, i.e., that it does not implement the ActionType. The only other acceptable return value is a pointer to an instance returned to your plugin using the function ATXNewATAllocInstance. This is in fact a pointer to the memory instance your plugin will have initialized that corresponds with the ActionType number and script passed.

What this memory instance will hold is entirely at the plugin maker's discretion. It can be anything from simple speed or location values read from the GRF script to complex calculation results and instance IDs. Internally, ATX adds a header to this memory, but this is completely transparent to all plugins and should not be tampered with (the pointer to the memory instance never includes this header; the latter is found lower in memory).

As soon as ATX receives a valid return value from this function by a plugin, it returns it to the game. Thus, only one plugin can successfully implement an ActionType for a given T-Script ActionType number. Any number above or equal to 500 constitutes a valid plugin ActionType number. You should always CLEARLY state in your plugin's documentation which numbers it reserves/requires and try to use original values as much as possible.

-> Go to Function Listing

The plugin system library consists of all the functions exported by ATYPEX.dll and usable by plugin DLLs. Typically, you will use these functions inside your plugin's exported callbacks. In fact, many of these you will only be able to call from within specific callbacks, because their functions or return values may only be valid at certain times during execution (i.e., you wouldn't get a handle to draw to the in-game screen during level load or teleport a dino at DLL load, naturally). The callbacks from which each function can be called are noted in their descriptions, further below.

These functions are declared as stdcall imports in atxplugin.h, using the label "atximport". All names begin with "ATX" (but do not rely on this to distinguish from callback functions). To make use of them, you simply have to call them as you would any other Win32 function, passing the appropriate parameters. Some require Win32 definitions from Windows.h. Make sure you use "#include " or whatever is appropriate for your compiler/language to include Win32 definitions.

The only catch is the method by which you will import these functions; in Microsoft Visual Studio 2003+, all you need to do is to add the provided "atypex.lib" library file to the linker's command line (Project -> [project name] Properties -> Linker -> Command Line -> Additional Options: atypex.lib), assuming it is already found in your plugin's project folder. It will be a similar for other linkers.

However, the provided atypex.lib file is not universal; it is intended mainly for MSVS, so it will not work with all other compilers, for example Borland C. In this case, all you need is to read the compiler's documentation on how to generate library files from a given set of known functions. Some compilers have separate utilities that can do this using *.DEF definition files or DLL (atypex.dll) files. As already mentioned, the atximport functions all use undecorated names, i.e., not symbolized with underscores or "@" symbols, so you have to make sure your compiler imports them with their raw names (i.e., ATXTestExport would be "ATXTestExport", and NOT "_ATXTestExport@0' or such), or your plugin will not be able to use them/may not pass load-time.

If you can find no way to get your compiler to generate a library for imports, you can always rely on the Win32 GetProcAddress function to import the function addresses in real-time from ATYPEX.dll. This pretty much always works; see the internet for various examples on how to use GetProcAddress. Once you get a pointer to a function using GetProcAddress, all you need to do is ensure that you cast it to a pointer of the appropriate atximport function declaration as found in atxplugin.h (if you cast it to the wrong function pointer, it may crash horribly). Once again, it must be stressed that the names you will pass to GetProcAddress as function symbols will correspond exactly to the names of the functions in atxplugin.h you wish to import (i.e., ATXTestExport -> "ATXTestExport"), without name decoration of any kind.

New Plugin ActionTypes
ATXNewATAllocInstance
ATXNewATFreeInstance
ATXNewATGetGroupValue
ATXNewATGetScriptValue

Physics
ATXGetGameSpeed
ATXGetGravity
ATXGetInstanceLocation
ATXGetInstancePhysicsVelocity
ATXSetInstanceLocation
ATXSetGameSpeed
ATXSetInstancePhysicsUnfreezeOnly
ATXSetInstancePhysicsVelocity

AI System
ATXGetCAISystemInstance

Camera/Player
ATXCCameraTeleport
ATXChangePlayerAIType
ATXGetCCameraInstance
ATXGetHeldWeaponInstance
ATXGetPlayerAIType
ATXIsPlayerHoldingGun
ATXResetCCameraPlayerSources

Rendering/Particles
ATXConvert3DPixelTo2DRender
ATXGetBackBufferSurfaceDC
ATXGetCParticlesFromID32
ATXGetCParticlesID32FromString
ATXGetDDrawObjectInGame
ATXGetDDrawSurfaceCurrent
ATXGetDDScreenDimensions
ATXGetDDSurfaceStructSize
ATXReleaseBackBufferSurfaceDC
ATXSeedParticleEffect

Input
ATXDisableInGameKeys
ATXDisableInGameMvtKeys
ATXEnableInGameKeys

Memory
ATXGameMemDelete
ATXGameMemNew

Animate Instances (player, animal, etc.)
ATXGetAllCAnimalInstances
ATXGetAnimateHealth
ATXGetCAnimalInstanceCount
ATXGetCPlayerPrivInstance
ATXGetCurrentBitingAnimal
ATXSetAnimateHealth
ATXSetAnimateMaxHealth

General Instances
ATXGetInstanceFromID32
ATXGetInstanceFromString
ATXGetInstanceFromStringCBD
ATXGetInstanceID32
ATXGetInstanceID32FromString
ATXIsValidInstance

SCN/Savegames
ATXFindNextSaveGameFileName
ATXGetLevelSavedSceneName

Miscellaneous
ATXGetEXEType
ATXGetGameDifficulty
ATXGetINIFloatEntry
ATXGetTimeSinceLastLevelLoad
ATXTestExport
ATXWriteLogFile

C/C++ Signature: void atximport ATXCCameraTeleport(const SObjLocOrient *newLoc);

Parameters:
newLoc - pointer to new location and orientation (quaternion) for camera

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: This function teleports the main camera instance to the specified location. By default, this will effectively teleport the player to that location, and not just the CCamera instance.

Related function(s): ATXGetCCameraInstance, ATXResetCCameraPlayerSources

C/C++ Signature: void atximport ATXChangePlayerAIType(uint newAIType); ;

Parameters:
newAIType - new AIType value. Can be AITYPE_PLAYER, AITYPE_INVISIBLE, or AITYPE_TOGGLE.

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: This changes the player AIType value on-the-fly by either setting it directly (AITYPE_PLAYER or AITYPE_INVISIBLE) or toggling it from its current value (AITYPE_TOGGLE).

Related function(s): ATXGetPlayerAIType

C/C++ Signature: bool atximport ATXConvert3DPixelTo2DRender(SPixel2Dz *lpResult, const SObjLoc *pixel3DLoc);

Parameters:
lpResult - pointer to structure to receive screen coordinates of 2D pixel
pixel3DLoc - pointer to 3D world coordinates of pixel to draw

Return value(s): return TRUE if the given pixel is within screen coordinates and lpResult holds valid coordinates. returns FALSE if 3D location does not fall within camera/screen.

Available in callbacks: ATXCPostScreenRender

Description: Converts the specified world coordinates to screen coordinates if possible, as if rendering a single pixel.

Related function(s):

C/C++ Signature: void atximport ATXDisableInGameKeys();

Parameters: none

Return value(s): none

Available in callbacks: all

Description: Disables all key-based user input.

Related function(s): ATXDisableInGameMvtKeys, ATXDisableInGameKeys

C/C++ Signature: void atximport ATXDisableInGameMvtKeys();

Parameters: none

Return value(s): none

Available in callbacks: all

Description: Disables all key-based user player movement controls (forward, backward, etc.).

Related function(s): ATXEnableInGameKeys, ATXDisableInGameKeys

C/C++ Signature: void atximport ATXEnableInGameKeys();

Parameters: none

Return value(s): none

Available in callbacks: all

Description: Sets user key input state to fully functional state (default - no keys disabled).

Related function(s): ATXDisableInGameMvtKeys, ATXDisableInGameKeys

C/C++ Signature: void atximport ATXFindNextSaveGameFileName(char *lpResult);

Parameters:
lpResult - holds next savegame file name (array must be 13 bytes, including null-terminator)

Return value(s): none

Available in callbacks: all

Description: Gets the name of the next save game file Trespasser saves data to (TRESPASS.xxx). It is sufficient that the array be 13 bytes in length, including null-terminator, because the savegame names do not vary in length.

Related function(s): ATXGetLevelSavedSceneName

C/C++ Signature: void atximport ATXGameMemDelete(void *memToFree);

Parameters:
memToFree - pointer to ATX-wrapped game memory to free (allocated using ATXGameMemNew)

Return value(s): none

Available in callbacks: all

Description: This frees memory allocated by ATXGameMemNew.

Related function(s): ATXGameMemNew

C/C++ Signature: void* atximport ATXGameMemNew(uint numberOfBytes);

Parameters:
numberOfBytes - number of bytes to allocate

Return value(s): pointer to newly-allocated memory

Available in callbacks: all

Description: This function allocates a block of memory of given size using Trespasser's standard heap-allocation technique. It is NECESSARY that you use this function, and NOT the standard C "new" or any other operator/allocation function, whenever you need to allocate heap memory that may be freed by the game or by ATX.

Related function(s): ATXGameMemDelete

C/C++ Signature: bool atximport ATXGetAllCAnimalInstances(CAnimal **lpAnimalsTable);

Parameters:
lpAnimalsTable - pointer to a table that will be filled with an array of CAnimal instance pointers. Must be large enough to accomodate all CAnimal instances (get number/required size using ATXGetCAnimalInstanceCount).

Return value(s): returns TRUE if at least one instance pointer was copied to the supplied buffer.

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This copies to the passed array the pointers for all CAnimal instances of the current level. The supplied array MUST be large enough to hold all of them.

Related function(s): ATXGetCAnimalInstanceCount

C/C++ Signature: const SAnimateHP* atximport ATXGetAnimateHealth(CAnimate *lpInst);

Parameters:
lpInst - pointer to the instance from which to retrieve current health

Return value(s): pointer to the instance's health values

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This gives you access to a player or animal's health values. Instance must be an animate and not a general instance.

Related function(s): ATXSetAnimateHealth, ATXSetAnimateMaxHealth

C/C++ Signature: HDC atximport ATXGetBackBufferSurfaceDC();

Parameters: none

Return value(s): Win32-compatible Device Context for screen drawing

Available in callbacks: ATXCPostScreenRender

Description: This gets a handle to the current back-buffer that you can use to draw to the screen (before the next DirectDraw frame flip) using the standard Win32 GUI functions (TextOut, DrawText, etc.).

Related function(s): ATXReleaseBackBufferSurfaceDC, ATXGetDDrawObjectInGame

C/C++ Signature: CAISystem* atximport ATXGetCAISystemInstance()

Parameters: none

Return value(s): pointer to global CAISystem instance

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: Gets the game's main CAISystem instance if the current level is loaded.

Related function(s): ATXGetCAnimalInstanceCount

C/C++ Signature: uint atximport ATXGetCAnimalInstanceCount();

Parameters: none

Return value(s): number of CAnimal instances

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: Gets number of CAnimal instances in current loaded level.

Related function(s): ATXGetAllCAnimalInstances, ATXGetCAISystemInstance

C/C++ Signature: CCamera* atximport ATXGetCCameraInstance();

Parameters: none

Return value(s): pointer to camera instance

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: Returns a pointer to the main CCamera player instance. This instance is, by default, associated with the player instance; if teleported under these conditions, the CPlayerPriv instance will be teleported with it.

Related function(s): ATXCCameraTeleport, ATXResetCCameraPlayerSources

C/C++ Signature: CParticles* atximport ATXGetCParticlesFromID32(ID32 particlesID);

Parameters:
particlesID - Unique ID of CParticles instance to fetch

Return value(s): pointer to CParticles instance corresponding to passed ID, or NULL if does not exist.

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This gets the CParticles instance associated with the given ID. The ID should have been gotten using the ATXGetCParticlesID32FromString function. Only use this function for CParticles instance; use ATXGetInstanceFromID32 for other types of instances.

Related function(s): ATXGetCParticlesID32FromString, ATXGetInstanceFromID32

C/C++ Signature: ID32 atximport ATXGetCParticlesID32FromString(const char *lpTypeName);

Parameters:
lpTypeName - pointer to name of CParticles instance of which to get an ID (i.e., "Bleed", "Blood", "Terrain", etc.)

Return value(s): unique ID for the requested CParticles instance, possibly NULL if invalid string

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPreLevelLoad, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This computes a unique CRC32-based ID for the given name of a CParticles instance type. It is the same as the ATXGetInstanceID32FromString function, but using non-case-sensitive encoding. You should always use this function for CParticles instances, and ATXGetInstanceID32FromString for other types of instances.

Related function(s): ATXGetCParticlesFromID32, ATXGetInstanceID32FromString

C/C++ Signature: CPlayerPriv* atximport ATXGetCPlayerPrivInstance();

Parameters: none

Return value(s): pointer to player instance

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: Returns a pointer to the main CPlayerPriv player instance. This instance controls the player's physical properties (sub-objects), reacts to input, etc., but is, however, separate from the camera (CCamera).

Related function(s): ATXChangePlayerAIType, ATXGetPlayerAIType, ATXIsPlayerHoldingGun, ATXResetCCameraPlayerSources

C/C++ Signature: CAnimal* atximport ATXGetCurrentBitingAnimal();

Parameters: none

Return value(s): pointer to CAnimal instance

Available in callbacks: ATXCOnActBite

Description: This retrieves from ATX the animal instance that is performing the current ongoing ActBite activity.

Related function(s):

C/C++ Signature: DDObj* atximport ATXGetDDrawObjectInGame();

Parameters: none

Return value(s): pointer to the DirectDraw surface object for the back-buffer

Available in callbacks: ATXCPostScreenRender

Description: Similar to ATXGetBackBufferSurfaceDC, but returns a pointer to the DirectDraw surface currently associated with the back-buffer that you can use to perform standard DirectDraw operations (i.e., blitting).

Related function(s): ATXGetDDrawSurfaceCurrent, ATXGetDDScreenDimensions, ATXGetDDSurfaceStructSize, ATXGetBackBufferSurfaceDC

C/C++ Signature: uint atximport ATXGetDDSurfaceStructSize();

Parameters: none

Return value(s): size of DirectDraw surface

Available in callbacks: ATXCPostScreenRender

Description: This returns the size of the DirectDraw surface objects currently being used by the game. The size can vary depending on whether the user is running in Software or Direct3D rendering, at least apparently so.

Related function(s): ATXGetDDrawSurfaceCurrent, ATXGetDDScreenDimensions, ATXGetDDSurfaceStructSize, ATXGetDDrawObjectInGame

C/C++ Signature: DDSurface* atximport ATXGetDDrawSurfaceCurrent();

Parameters: none

Return value(s): pointer to current DirectDraw back-buffer surface or NULL if not available

Available in callbacks: ATXCPostScreenRender

Description: Gets the current DirectDraw surface. Only valid during this callback.

Related function(s): ATXGetDDScreenDimensions, ATXGetDDSurfaceStructSize, ATXGetDDrawObjectInGame

C/C++ Signature: const SDimensions2* atximport ATXGetDDScreenDimensions();

Parameters: none

Return value(s): pointer to screen dimensions or NULL if surface not available

Available in callbacks: ATXCPostScreenRender

Description: Gets a pointer to screen dimensions. Pointer is only valid during same callback.

Related function(s): ATXGetDDrawSurfaceCurrent, ATXGetDDSurfaceStructSize, ATXGetDDrawObjectInGame

C/C++ Signature: TRESEXETYPE atximport ATXGetEXEType();

Parameters: none

Return value(s): unique ID for Trespasser executable type

Available in callbacks: all

Description: Returns the type of the Trespasser executable that ATX is currently hooked into. It can be compared against the four types defined in atxplugin.h and supported by ATX.

Related function(s):

C/C++ Signature: uint atximport ATXGetGameDifficulty();

Parameters: none

Return value(s): an integer giving the current game difficulty

Available in callbacks: all

Description: This gets an integer in the range 0 to 4 which gives the current game difficulty as set using the ATX Game Difficulty slider. 2 is "normal". "normal" is returned also if the game difficulty value scanned from ATXconfig.ini is invalid. The game difficulty can be changed by the user while the game is loaded only at the menu.

Related function(s):

C/C++ Signature: const float* atximport ATXGetGameSpeed();

Parameters: none

Return value(s): a pointer to the global game speed value (read-only).

Available in callbacks: all

Description: This returns a read-only pointer to the current game speed value. Use the ATXSetGameSpeed function to modify it. The pointer is kept as read-only because many ATX features rely on this value and for compatibility may need to be notified (though ATXSetGameSpeed) about when it is modified.

Related function(s): ATXSetGameSpeed

C/C++ Signature: const float* atximport ATXGetGravity();

Parameters: none

Return value(s): a pointer to the global game gravity value.

Available in callbacks: all

Description: This returns a read-only pointer to the current gravity value (default = 10.0). It is read-only because modification of this variable often leads to unpredictable results.

Related function(s):

C/C++ Signature: CGun* atximport ATXGetHeldWeaponInstance(uint weaponLocation);

Parameters:
weaponLocation - Which holster to get weapon instance from. Can be GETWEAPON_PRIMARY, GETWEAPON_SECONDARY, GETWEAPON_SECONDARYWAIST, or GETWEAPON_SECONDARYBACK.

Return value(s): a pointer to a CGun instance or NULL if no instance at specified location.

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This gets the CGun instance the player currently has active at one of the three predefined holster-able locations (in-hand, waist, back). GETWEAPON_SECONDARY can be used to check both waist and back at same time, while GETWEAPON_PRIMARY only checks in-hand. If there is no gun holstered at specified location, the function returns NULL.

Related function(s): ATXIsPlayerHoldingGun

C/C++ Signature: float atximport ATXGetINIFloatEntry(const char *sectionName, const char *keyName, const char *defaultVal, const char *iniPath);

Parameters:
sectionName - name of section in INI file
keyName - name of key in INI file
defaultVal - default value for float in the form of a string, returned if key not found/invalid
iniPath - full path and filename of INI. Make sure you specify an absolute path.

Return value(s): float value associated with key in INI file (in st0, on FPU stack)

Available in callbacks: all

Description: This function is analogous to the Win32 function, GetPrivateProfileInt, but instead of fetching an integer associated with the given key in the specified INI file and section, will convert the value to a float. Also note that the default value must be given in the form of a string and not a float.

Related function(s): Win32 API functions GetPrivateProfileInt and GetPrivateProfileString

C/C++ Signature: CInstance* atximport ATXGetInstanceFromID32(ID32 instanceID);

Parameters:
instanceID - unique CRC32 ID of the instance to get

Return value(s): pointer to the instance associated with the given ID or NULL if not existing

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This uses the game functions to get the memory instance associated with the given ID.

Related function(s): ATXGetInstanceID32, ATXGetInstanceID32FromString, ATXGetInstanceFromString, ATXGetInstanceFromStringCBD

C/C++ Signature: CInstance* atximport ATXGetInstanceFromString(const char *instanceName);

Parameters:
instanceName - string representing the full, case-sensitive name of the instance

Return value(s): pointer to the instance or NULL if not found

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This function returns a pointer to the instance in-memory who's string name has been passed as parameter. If it does not exist in the game world or if its name is not properly represented, this returns NULL.

Related function(s): ATXGetInstanceFromStringCBD, ATXGetInstanceID32, ATXGetInstanceID32FromString, ATXGetInstanceFromID32

C/C++ Signature: CInstance* atximport ATXGetInstanceFromStringCBD(const char *instanceName);

Parameters:
instanceName - string representing the full, case-sensitive name of the instance

Return value(s): pointer to the instance or NULL if not found

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This is the same as ATXGetInstanceFromString, but also checks for name of CBackDrop instances (which the game does not normally do). Use only if a CBackDrop instance is valid or needed in your code.

Related function(s): ATXGetInstanceFromString, ATXGetInstanceID32, ATXGetInstanceID32FromString, ATXGetInstanceFromID32

C/C++ Signature: ID32 atximport ATXGetInstanceID32(CInstance *lpInstance);

Parameters:
lpInstance - pointer to this instance from which to retrieve ID

Return value(s): instance's CRC32 ID value

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This returns the ID of the designated memory instance.

Related function(s): ATXGetInstanceID32FromString, ATXGetInstanceFromID32, ATXGetInstanceFromString, ATXGetInstanceFromStringCBD

C/C++ Signature: ID32 atximport ATXGetInstanceID32FromString(const char *lpInstName);

Parameters:
lpInstName - string name of the instance from which to generate a unique ID

Return value(s): instance's CRC32 ID value, corresponding to given string. If string is badly formatted, can return NULL.

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPreLevelLoad, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This returns the ID of the instance designated by name. This ID is unique, but may not necessarily correspond to a memory instance if the name is mispelled or if the instance represented by the name does not exist.

Related function(s): ATXGetInstanceID32, ATXGetInstanceFromID32, ATXGetInstanceFromString, ATXGetInstanceFromStringCBD

C/C++ Signature: const SObjState* atximport ATXGetInstanceLocation(CInstance *lpInst);

Parameters:
lpInst - CInstance from which to get location, orientation, and scale

Return value(s): pointer to the instance's state

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This returns a pointer to the given instance's position, orientation, and scale values. This is only valid for instances which exist in the game world.

Related function(s): ATXSetInstanceLocation

C/C++ Signature: bool atximport ATXGetInstancePhysicsVelocity(SRotVel *lpVelocity, const CInstance *lpInstance);

Parameters:
lpVelocity - pointer to structure in which to store specified instance's current velocity
lpInstance - pointer to instance from which to get current velocity

Return value(s): Returns TRUE if object is currently moving, or FALSE if object is still (frozen).

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: An easy way to get a vector representing an instance's current absolute velocity. Works for most types of instances, including animates in general.

Related function(s): ATXSetInstancePhysicsVelocity, ATXSetInstancePhysicsUnfreezeOnly

C/C++ Signature: const char* atximport ATXGetLevelSavedSceneName();

Parameters: none

Return value(s): pointer to a string giving the current level's source SCN file.

Available in callbacks: ATXCPreDLLUnload, ATXCPreScreenRender, ATXCPostScreenRender, ATXCPreLevelLoad, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This returns the name of the SCN file last used to load the current file. It can be the original SCN file (*.scn) or a savegame file (TRESPASS.*). It can not *always* be used to differentiate between savegame loads and non-savegame loads, because level restarts initiated for a level that was last loaded using a savegame will keep the same source SCN name, which is the savegame file (TRESPASS.*) at this point.

Related function(s): ATXFindNextSaveGameFileName

C/C++ Signature: uint atximport ATXGetPlayerAIType();

Parameters: none

Return value(s): player's current AIType value

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This returns the player's current AIType value. It is 5 by default and should either be 0 or 5 throughout gameplay (AITYPE_INVISIBLE or AITYPE_PLAYER, respectively).

Related function(s): ATXChangePlayerAIType

C/C++ Signature: uint atximport ATXGetTimeSinceLastLevelLoad();

Parameters: none

Return value(s): tick count, in milliseconds

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This returns the tick count since the last successful level load. You should only use this for relative calculations, because it does not necessarily represent the time from which the level was first attempted by the player (i.e., it is reset by subsequent savegame loads). THIS VALUE IS NOT AFFECTED BY GLOBAL GAME SPEED.

Related function(s):

C/C++ Signature: CGun* atximport ATXIsPlayerHoldingGun();

Parameters:

Return value(s): pointer to CGun instance or NULL if player does not have any in-hand.

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand

Description: This returns the CGun instance the player currently has in-hand, or NULL if the player is holding nothing or if he/she is holding an instance of type other than CGun. This does not check in any way the waist and back for holstered guns.

Related function(s): ATXGetHeldWeaponInstance

C/C++ Signature: bool atximport ATXIsValidInstance(void *lpMem, uint memSize);

Parameters:
lpMem - pointer to memory to check for valid instance
memSize - maximum expected size of designated memory space

Return value(s): returns TRUE if the instance is considered a valid polymorphic Trespasser instance, and FALSE otherwise

Available in callbacks: all

Description: This checks whether the given memory is probably a valid Trespasser instance or not. A valid instance is considered to be an instance with a valid VTable.

Related function(s):

C/C++ Signature: void* atximport ATXNewATAllocInstance(uint memSize, newatdestp *lpDestructor, newatmainp *lpMainProc, newatreinp *lpReInitProc);

Parameters:
memSize - size of logical memory instance to allocated, in bytes (i.e., gotten using "sizeof(MyInstanceStructure)" )
lpDestructor - pointer to a function to use as destructor for this ActionType instance (may be NULL)
lpMainProc - pointer to a function to use as main real-time trigger for this ActionType instance (MUST BE VALID)
lpReInitProc - pointer to a function to use as re-initialization for this ActionType instance (may be NULL)

Return value(s): pointer to new logical memory for instance or NULL if error/invalid parameters

Available in callbacks: ATXCNewATInit

Description: This function allocates a plugin-based new ActionType instance of given size. This is the ONLY way you are allowed to generate a new ActionType instance. The function will return a pointer which you will have to cast to the type of your new AT instance, and which you will have to either a) return to ATX as new instance or b) free using ATXNewATFreeInstance before the end of the ATXCNewATInit callback. Use carefully.

You will also have to pass the addresses of three callback functions (which you do not have to export) which ATX will internally associate with the returned instance. They may all be NULL (no function) except for lpMainProc, which designates the function that will be called during gameplay, when the new AT is triggered. The lpDestructor function is basically a destructor which you will need to implement if your new AT instance holds pointers to separately-allocated memory. If you have such memory, however, it may be advantageous to attempt to include it directly in your main ActionType instance in order to simplify destruction and possibly avoid future issues. The lpReInitProc is available, but should generally be avoided (pass NULL).

All specified function types are listed in atxplugin.h as "atxcallback" functions. Each of them takes one parameter, "lpThis", which is a pointer to your new AT's instance (equivalent to the "this" pointer in C++ or Java). Simply cast this pointer to one of your new AT structure's type.

ALWAYS use a simple C-style structure to describe the new AT instance you are allocating memory for using this function. Do not define complex classes with methods and virtual members for this purpose.

Related function(s): ATXNewATFreeInstance

C/C++ Signature: void atximport ATXNewATFreeInstance(void *lpThis);

Parameters:
lpThis - pointer to logical memory of new ActionType instance to free

Return value(s): none

Available in callbacks: ATXCNewATInit

Description: Required if you may need to free a new AT instance allocated using ATXNewATAllocInstance during the ATXCNewATInit callback. Do NOT use it during any under circumstance.

Related function(s): ATXNewATAllocInstance

C/C++ Signature: bool atximport ATXNewATGetGroupValue(CObjectValue **lpFarReturnGroupObject, uint valueNameIndex, CObjectValue *lpSourceObject, uint *lpEntryCount);

Parameters:
lpFarReturnGroupObject - pointer to variable that will hold a pointer to the CObjectValue instance of the specified group value name ID
valueNameIndex - index (ID) of the requested script name (used as group label in T-Script). Must be one of the TSCRIPT_INDEXVALUE_xxx constants.
lpSourceObject - pointer to the CObjectValue instance of the of group holding the above script name
lpEntryCount - pointer to an integer that will be incremented if the requested group script name is found and valid

Return value(s): Returns TRUE if requests group entry exists and lpFarReturnGroupObject holds a valid object pointer. Returns FALSE otherwise.

Available in callbacks: ATXCNewATInit

Description: Gets a CObjectValue far pointer which corresponds to a "group xxxx = { ... }" T-Script entry in a level's GRF file. You can use this to browse through T-Script directory-style group structures and pass the new CObjectValue instance pointer to ATXNewATGetScriptValue to retrieve values within these sub-groups.

Related function(s): ATXNewATGetScriptValue

C/C++ Signature: void* atximport ATXNewATGetScriptValue(uint valueNameIndex, CObjectValue *lpSourceObject, uint entryNum, uint valueType);

Parameters:
valueNameIndex - index (ID) of the requested script name. Must be one of the TSCRIPT_INDEXVALUE_xxx constants.
lpSourceObject - pointer to the CObjectValue instance of the group holding the above script name
entryNum - the index of the requested script name, i.e., the number of script names that have been scanned for in this group so far (trivial)
valueType - the type of value being fetched. Can be TSCRIPT_VALUETYPE_BOOL, TSCRIPT_VALUETYPE_INT, TSCRIPT_VALUETYPE_FLOAT, or TSCRIPT_VALUETYPE_STRING.

Return value(s): A pointer to the value assigned to this instance of the script name in the GRF file; NULL if not found. You must cast this pointer according to the value type you passed using the valueType parameter.

Available in callbacks: ATXCNewATInit

Description: This fetches the value associated with a certain T-Script entry during level load. You will have to cast the returned pointer manually, corresponding to the value type you specified using the valueType parameter.

Related function(s): ATXNewATGetGroupValue

C/C++ Signature: void atximport ATXReleaseBackBufferSurfaceDC(HDC bufHandle);

Parameters:
bufHandle - device context of back-buffer to release (retrieve using ATXGetBackBufferSurfaceDC)

Return value(s): none

Available in callbacks: ATXCPostScreenRender

Description: This releases the device context to the back-buffer gotten using a call to ATXGetBackBufferSurfaceDC. Every call to ATXGetBackBufferSurfaceDC should eventually be followed by a call to ATXReleaseBackBufferSurfaceDC before the end of a plugin callback function or before another call to ATXGetBackBufferSurfaceDC. It is highly recommended to release the back-buffer handle as soon as it is not longer used/required.

Related function(s): ATXGetBackBufferSurfaceDC

C/C++ Signature: void atximport ATXResetCCameraPlayerSources();

Parameters: none

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: This re-associates the main CCamera instance with the player instance, effectively allowing the player to control the camera again (default game state). The CCamera instance can be separated from the player instance at times, i.e., during ATX's FOLLOWDINO cheat.

Related function(s): ATXGetCCameraInstance, ATXCCameraTeleport

C/C++ Signature: void atximport ATXSeedParticleEffect(CParticles *lpEffect, SObjLoc *lpLocation, SVector3 *lpDirection, float param7D, float pThreshold);

Parameters:
lpEffect - pointer to CParticles instance for effect qualities
lpLocation - pointer to struct giving location of effect (point of origin)
lpDirection - pointer to vector giving direction of effect
param7D - misc. float value. Usually 1.000000, but can be diminished to affect effect density
pThreshold - threshold to use for this seed. Should be within the specified CParticles instance's Threshold limits

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCOnActBite

Description: This creates a new particle effect at a given location, with a certain orientation and power. The effect is never guaranteed to be shown due to engine limitations, so if this effect is depended upon, you should make sure the user has the right ATX particle settings prior to running the plugin (some can be used to break these limits).

Related function(s):

C/C++ Signature: void atximport ATXSetAnimateHealth(CAnimate *lpInstance, float newHealth);

Parameters:
lpInstance - pointer to animate instance
newHealth - new health value

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: Sets an absolute value for the specified animate's HP (HitPoints).

Related function(s): ATXSetAnimateMaxHealth, ATXGetAnimateHealth

C/C++ Signature: void atximport ATXSetAnimateMaxHealth(CAnimate *lpInstance, float newMaxHealth);

Parameters:
lpInstance - pointer to animate instance
newMaxHealth - new max health value

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: Sets an absolute value for the specified animate's max hit points (MaxHitPoints).

Related function(s): ATXSetAnimateHealth, ATXGetAnimateHealth

C/C++ Signature: void atximport ATXSetGameSpeed(float newGameSpeed);

Parameters:
newGameSpeed - new value to set as game speed.

Return value(s): none

Available in callbacks: all

Description: This modifies the current global game speed value. All modifications need to be done through this wrap as to notify ATX features of any and all external changes.

Related function(s): ATXGetGameSpeed

C/C++ Signature: void atximport ATXSetInstanceLocation(CInstance *lpInstance, SObjLocOrient *lpLoc);

Parameters:
lpInstance - pointer to instance
lpLoc - new global location AND orientation for instance (and all its sub-objects)

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: Teleports an instance to specified location (*can* be used for animation purposes).

Related function(s): ATXGetInstanceLocation, ATXCCameraTeleport

C/C++ Signature: void atximport ATXSetInstancePhysicsUnfreezeOnly(CInstance *lpInstance);

Parameters:
lpInstance - pointer to instance to unfreeze

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: This sets the specified instance to an unfrozen state.

Related function(s): ATXGetInstancePhysicsVelocity, ATXSetInstancePhysicsVelocity

C/C++ Signature: void atximport ATXSetInstancePhysicsVelocity(CInstance *lpInstance, const SRotVel *lpVelocity);

Parameters:
lpInstance - pointer to instance on which to apply absolute velocity
lpVelocity - pointer to velocity to apply to instance

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnPlgUserCommand

Description: This assigns the passed velocity values to the specified instance through the physics system. The velocity values are absolute and include the undefined 'rotational velocity'. To effectively set velocity, you must first retrieve the instance's velocity using ATXGetInstancePhysicsVelocity and then modify only the standard velocity values, making sure to pass the same 'rotational velocity' values back to ATXSetInstancePhysicsVelocity. NOTE: THIS FUNCTION WILL ONLY WORK ON STANDARD SIMPLE CINSTANCES AND BOXES (NOT ANIMATES).

Related function(s): ATXGetInstancePhysicsVelocity, ATXSetInstancePhysicsUnfreezeOnly

C/C++ Signature: void atximport ATXTestExport(const char *testMessage);

Parameters:
testMessage - text message

Return value(s): none

Available in callbacks: ATXCPreScreenRender, ATXCPostScreenRender, ATXCPostLevelLoad, ATXCOnActBite, ATXCOnLevelSave, ATXCOnPlgUserCommand,

Description: Displays a simple message for a short period of time. The message must be a static variable and must be valid for the duration of the display (usually 4-6 seconds, but can be longer depending on user intervention).

Related function(s):

C/C++ Signature: void atximport ATXWriteLogFile(const char *text, uint textSize);

Parameters:
text - pointer to text to write to ATX_LOGFILE.txt
textSize - total size of text to write to ATX_LOGFILE.txt

Return value(s): none

Available in callbacks: all

Description: This prints out a raw message to the ATX_LOGFILE.txt file by appending. You must take care to include the appropriate carriage returns and formatting.

Related function(s):

- If the user changes video driver or important system settings while a level is loaded, this can cause a mid-level reload that may cause certain callback functions to be unexpectedly called. It is of general concensus that users should never change such settings in-game (only from main game menu), in order to avoid such issues.

Regards to Oleh Yuschuk, who's excellent OllyDbg debugger's plugin support was used as base example for the ATX plugin system.

EOF