T2D STL Wrappers
by Matthew "Ashteth" Kee · 08/30/2005 (1:39 am) · 3 comments
Download Code File
// -----------------------------------------------------------------------------
// Script wrappers for STL containers in the Torque Game Engine and T2D. (1.0)
// Matthew Kee
// -----------------------------------------------------------------------------
This is a set of wrappers that enables STL containers to be used within TorqueScript. If you are unfamiliar with C++ or the Standard Template Library, you may find that this resource is of no interest to you. If so, that's fine. In case you're still curious though, here's a good resource describing what the Standard Template Library is:
SGI STL Manual
If you visit the above link, pay special attention to the map and list containers as this is what we'll be making accessible from TorqueScript. That said, at present, the two containers wrapped are std::map and std::list. These containers may be used within script to contain sceneobjects, numbers or charactor strings (everything in torque script is in fact a charactor string).
The issue of wether or not to use STL in conjunction with the Torque Game Engine is a heated one. Suffice it to say that I do not wish to get into a debate over this. In practice, I have found my std::map wrapper to be extremely useful in my personal game project and the std::list wrapper to be useful to a lesser extent. In the included example, I will attempt to explain how and why I use the std::map class and why you may be interested in it as well. I don't pretend to be an authoratative voice on this subject. If you like what I do, great, if not, please don't preach -- at least to me ;)
Unfortunately you can't just add the three files in this wrapper and be done with it. The Torque game engine was never designed to be used with STL, so we've got a bit of work to do to get it running.
There are in fact two ways to get STL working with TorqueScript. The first, and simplest method is to disable the Torque Memory Manager. If you don't know what the "Torque Memory Manager" is and you don't do any runtime debugging, you probably don't care if the "Torque Memory Manager" is enabled or not. Personally, I disabled the Torque Memory Manager because I don't use it. To disable the memory manager in theory all you should have to do is add:
#define TORQUE_DISABLE_MEMORY_MANAGER to platform/platform.h to disable the memory manager. In practice, its not quite so simple.
If you wish to disable the Torque Memory Manager, follow the instructions in this resource:
Disable Memory Manager
If you only own T2D (as opposed to TGE and T2D), you may not be able to read the aforementioned link. In this case, I refer you to the file: "Torque_disable_memory_manager_instructions.txt" which is a transcript of that resource and is included in the accompanying zip.
Additionally, if you are using Win32, you may (after backing up your respective files) overwrite the files in your Torque2D directory with the files included in the folder "Disable_Memory_manager_files" included in this zip.
If you actually know what the Memory Manager is and utilize it, you may wish to use the stl_fix.h resource. To install this resource (potentially more difficult), refer to the included file "stl_fix_h_instructions.txt" (also in the zip), or if you have a TGE license:
STL FIX
For convenience, the required file "stl_fix.h" is included in this resource as well.
A final note: It may take some doing to get STL up and running in T2D, but keep at it, you may find that its well worth it ;)
Another hint: if you find that certain standard libraries are "missing", you may need to alter your makefile "Torque2D/SDK/engine/targets.torque.mk" to include more of your compiler's directories. The lines I altered ended up looking more like this:
#---------------------------------------
# Set up include variables here.
INCLUDES_BASE = -I../lib/zlib -I../lib/lungif -I../lib/lpng -I../lib/ljpeg -I../lib/directx8 -I../lib/vorbis/include -I"C:/Dev-Cpp/include/c++" -I"C:/Dev-Cpp/include/c++/mingw32" -I"C:/Dev-Cpp/include/c++/mingw32/bits" -I"C:/Dev-Cpp/include/c++/backward" -I"C:/Dev-Cpp/include"
INCLUDES_LINUX = $(INCLUDES_BASE) -I../lib/openal/LINUX
INCLUDES_OpenBSD = $(INCLUDES_BASE) -I../lib/openal/OpenBSD
INCLUDES_FreeBSD = $(INCLUDES_BASE) -I../lib/openal/FreeBSD
INCLUDES_WIN32 = $(INCLUDES_BASE) -I../lib/openal/win32
The above text to pay attention to are: -I"C:/Dev-Cpp/include/c++" etc. Yours will probably be slightly different, but you get the idea.
Once you've successfully recompiled the engine with STL, add these lines to the file:
"Torque2D/SDK/engine/targets.torque.mk":
After the entry:
SOURCE.T2D=\
...
T2D/t2dGlobals.cc \
T2D/t2dVector.cc
Add this:
SOURCE.STL=\
STL/stlGlobal.cc \
STL/stlList.cc \
STL/stlMap.cc
Compile and run the included example for a demonstration.
Last but not least, if you need any help or have comments / suggestions, feel free to e-mail me. If you just want to bash STL or comment on how gratuitous and unnesessary this resource is, feel free to get bent ;)
// -----------------------------------------------------------------------------
// Script wrappers for STL containers in the Torque Game Engine and T2D. (1.0)
// Matthew Kee
// -----------------------------------------------------------------------------
This is a set of wrappers that enables STL containers to be used within TorqueScript. If you are unfamiliar with C++ or the Standard Template Library, you may find that this resource is of no interest to you. If so, that's fine. In case you're still curious though, here's a good resource describing what the Standard Template Library is:
SGI STL Manual
If you visit the above link, pay special attention to the map and list containers as this is what we'll be making accessible from TorqueScript. That said, at present, the two containers wrapped are std::map
The issue of wether or not to use STL in conjunction with the Torque Game Engine is a heated one. Suffice it to say that I do not wish to get into a debate over this. In practice, I have found my std::map wrapper to be extremely useful in my personal game project and the std::list wrapper to be useful to a lesser extent. In the included example, I will attempt to explain how and why I use the std::map class and why you may be interested in it as well. I don't pretend to be an authoratative voice on this subject. If you like what I do, great, if not, please don't preach -- at least to me ;)
Unfortunately you can't just add the three files in this wrapper and be done with it. The Torque game engine was never designed to be used with STL, so we've got a bit of work to do to get it running.
There are in fact two ways to get STL working with TorqueScript. The first, and simplest method is to disable the Torque Memory Manager. If you don't know what the "Torque Memory Manager" is and you don't do any runtime debugging, you probably don't care if the "Torque Memory Manager" is enabled or not. Personally, I disabled the Torque Memory Manager because I don't use it. To disable the memory manager in theory all you should have to do is add:
#define TORQUE_DISABLE_MEMORY_MANAGER to platform/platform.h to disable the memory manager. In practice, its not quite so simple.
If you wish to disable the Torque Memory Manager, follow the instructions in this resource:
Disable Memory Manager
If you only own T2D (as opposed to TGE and T2D), you may not be able to read the aforementioned link. In this case, I refer you to the file: "Torque_disable_memory_manager_instructions.txt" which is a transcript of that resource and is included in the accompanying zip.
Additionally, if you are using Win32, you may (after backing up your respective files) overwrite the files in your Torque2D directory with the files included in the folder "Disable_Memory_manager_files" included in this zip.
If you actually know what the Memory Manager is and utilize it, you may wish to use the stl_fix.h resource. To install this resource (potentially more difficult), refer to the included file "stl_fix_h_instructions.txt" (also in the zip), or if you have a TGE license:
STL FIX
For convenience, the required file "stl_fix.h" is included in this resource as well.
A final note: It may take some doing to get STL up and running in T2D, but keep at it, you may find that its well worth it ;)
Another hint: if you find that certain standard libraries are "missing", you may need to alter your makefile "Torque2D/SDK/engine/targets.torque.mk" to include more of your compiler's directories. The lines I altered ended up looking more like this:
#---------------------------------------
# Set up include variables here.
INCLUDES_BASE = -I../lib/zlib -I../lib/lungif -I../lib/lpng -I../lib/ljpeg -I../lib/directx8 -I../lib/vorbis/include -I"C:/Dev-Cpp/include/c++" -I"C:/Dev-Cpp/include/c++/mingw32" -I"C:/Dev-Cpp/include/c++/mingw32/bits" -I"C:/Dev-Cpp/include/c++/backward" -I"C:/Dev-Cpp/include"
INCLUDES_LINUX = $(INCLUDES_BASE) -I../lib/openal/LINUX
INCLUDES_OpenBSD = $(INCLUDES_BASE) -I../lib/openal/OpenBSD
INCLUDES_FreeBSD = $(INCLUDES_BASE) -I../lib/openal/FreeBSD
INCLUDES_WIN32 = $(INCLUDES_BASE) -I../lib/openal/win32
The above text to pay attention to are: -I"C:/Dev-Cpp/include/c++" etc. Yours will probably be slightly different, but you get the idea.
Once you've successfully recompiled the engine with STL, add these lines to the file:
"Torque2D/SDK/engine/targets.torque.mk":
After the entry:
SOURCE.T2D=\
...
T2D/t2dGlobals.cc \
T2D/t2dVector.cc
Add this:
SOURCE.STL=\
STL/stlGlobal.cc \
STL/stlList.cc \
STL/stlMap.cc
Compile and run the included example for a demonstration.
Last but not least, if you need any help or have comments / suggestions, feel free to e-mail me. If you just want to bash STL or comment on how gratuitous and unnesessary this resource is, feel free to get bent ;)
#2
11/09/2005 (7:33 pm)
Sorry about that Jason. It seems that Garage Games has been getting good at losing my resources. Anyways, the resource has been updated and now contains an std::vector wrapper in addition to the preexisting std::map and std::list wrappers. I also changed some of the naming conventions for the list and map wrappers to make it more like the stl standard. I don't think there are any major backwards compatibility issues, but if the demo no longer works this is probably why. If something doesn't work, don't hesitate to e-mail me (address in profile) this is typically a faster way to let me know something is wrong as I don't check the resource feedback too often. 
#3
The current (2009) version of this doesn't compile, for a couple of reasons. i have XP, TGB 1.7.4, Visual Studio 2008 and stl_fix already applied. For others trying this, here's what's worked for me:
1. Problem: Doesn't play nice with the version of stl_fix i have. Leads to load of errors in crtdbg. Fix: In each STL wrapper .h file, include stl_fix before the STL files (i.e., #include "../core/stl_fix.h" goes before #include <string>)
2. Problem: ConsoleMethods don't return values. Fix: For each error in the error list, see if the ConsoleMethod thinks it should return a value. Many of them look like "ConsoleMethod(stlMap, addObj, const char *, 4, 4,...". The third parameter is the return type and should be "void"
3. Problem: Methods don't return values. Fix: Two of the methods weren't written (getObject for vector and stlList and stlVector). So, um, write those. For stlVector, i think the code is "return m_raVal[iPos];". i don't know what it is for stlList :) (not sure there's direct access, so you might have to iterate)
4. Problem: Example programs don't work. Fix: The example programs create a dictionary and stuff it full of objects you don't have (fxSprite something). So replace it with a different kind of object
i think that's enough to get this to work. It now compiles for me, although i haven't tested it to verify that it works
07/31/2009 (8:40 am)
Matt, i don't see your address in your profileThe current (2009) version of this doesn't compile, for a couple of reasons. i have XP, TGB 1.7.4, Visual Studio 2008 and stl_fix already applied. For others trying this, here's what's worked for me:
1. Problem: Doesn't play nice with the version of stl_fix i have. Leads to load of errors in crtdbg. Fix: In each STL wrapper .h file, include stl_fix before the STL files (i.e., #include "../core/stl_fix.h" goes before #include <string>)
2. Problem: ConsoleMethods don't return values. Fix: For each error in the error list, see if the ConsoleMethod thinks it should return a value. Many of them look like "ConsoleMethod(stlMap, addObj, const char *, 4, 4,...". The third parameter is the return type and should be "void"
3. Problem: Methods don't return values. Fix: Two of the methods weren't written (getObject for vector and stlList and stlVector). So, um, write those. For stlVector, i think the code is "return m_raVal[iPos];". i don't know what it is for stlList :) (not sure there's direct access, so you might have to iterate)
4. Problem: Example programs don't work. Fix: The example programs create a dictionary and stuff it full of objects you don't have (fxSprite something). So replace it with a different kind of object
i think that's enough to get this to work. It now compiles for me, although i haven't tested it to verify that it works
Torque Owner Jason McIntosh