TGE Script Documentation
by Ron Yacketta · in General Discussion · 04/04/2002 (6:34 am) · 86 replies
Hello Everyone,
I have already spoke with Jeff Tunnel via email and he gave me the thumbs up "Go Go Go" signal.
So, work has begun to combine current resources and forum threads regarding TGE scripting into a single HTML formatted resource. Once this has been accomplished I will be trolling through the document (and engine code) to dig up as much info on each scripting command I can (weather it be from code, a GG employee or some other source).
If you have a scripting resource, tip, trick or tid bit of information please forward it to me so I can include it in this document. Full credit will be given to those who contribute to the project.
Regards,
Ron
I have already spoke with Jeff Tunnel via email and he gave me the thumbs up "Go Go Go" signal.
So, work has begun to combine current resources and forum threads regarding TGE scripting into a single HTML formatted resource. Once this has been accomplished I will be trolling through the document (and engine code) to dig up as much info on each scripting command I can (weather it be from code, a GG employee or some other source).
If you have a scripting resource, tip, trick or tid bit of information please forward it to me so I can include it in this document. Full credit will be given to those who contribute to the project.
Regards,
Ron
#2
Correct, that is my intention for the document. To generate an all purpose scripting resource. One that would encompas every facit of the scripting language, yes this will be a tough task! But it NEEDS to be done!
Also, if you would please email me your resources. It would make it a lot easier to deal with.
04/04/2002 (6:47 am)
Stefan,Correct, that is my intention for the document. To generate an all purpose scripting resource. One that would encompas every facit of the scripting language, yes this will be a tough task! But it NEEDS to be done!
Also, if you would please email me your resources. It would make it a lot easier to deal with.
#3
[after edit]
Yes, I did find it. Created the HTML files. I'll post a link in the Torque only section.
04/04/2002 (6:48 am)
A friend of mine wrote a perl script that would generate HTML pages of the script routines, variables, etc. He wrote it when he was playing Tribes 2, I'm sure it'd work for these scripts. Actually, I think he has it in a CVS tree I have access to. I'll update this message if I find it.[after edit]
Yes, I did find it. Created the HTML files. I'll post a link in the Torque only section.
#4
http//pages.prodigy.net/fungame/torque/consoledoc.zip
or here www.iamxp.com/nohbdy/programs.html
Is scans all engine files and generates a HTML documentation of all the scripting stuff it finds - it's not *really* useful, mainly because the code itself isn't always well documented as you know (so there are not very much comments it could potentially grab), and the output could be better sorted, but it's a start and a nice little tool...
But a "handmade" doc with detailed and well documented examples is definitely the way to go! :-)
04/04/2002 (7:02 am)
As you may know, there is also ConsoleDoc, which does the same, I think... you can download it here:http//pages.prodigy.net/fungame/torque/consoledoc.zip
or here www.iamxp.com/nohbdy/programs.html
Is scans all engine files and generates a HTML documentation of all the scripting stuff it finds - it's not *really* useful, mainly because the code itself isn't always well documented as you know (so there are not very much comments it could potentially grab), and the output could be better sorted, but it's a start and a nice little tool...
But a "handmade" doc with detailed and well documented examples is definitely the way to go! :-)
#5
04/04/2002 (11:42 am)
Ronald, are you also looking for complete tutorials, e.g. "How to make a preview gui", "How to make some dirty little bots hunt you after midnight", ...? Or only little snipits showing a specific function, e.t.c.?
#6
rjp.dyndns.org/torquescripts/t2docgen.zip
Props to him for making this a while back for Tribes 2. He can be reached at sporadic@linux.wku.edu.
04/04/2002 (12:04 pm)
Ok, I asked my friend and he said it was cool to release the perl script. You can download it at:rjp.dyndns.org/torquescripts/t2docgen.zip
Props to him for making this a while back for Tribes 2. He can be reached at sporadic@linux.wku.edu.
#7
Here is what I envision for the initial 2 phases.
Phase 1 :
* Combine current resources and forum posts into a single document
* incorporate user supplied content into the document
* Provide information regarding each entity within the document
* Clean up the document
* Fire it off to GG staff for review
Phase 2 :
* Add in ConsoleDoc output
* Provide more detailed information for each entity
* clean up the document
* Fire it back to GG staff for review
I feel that we need to provide an initial document that speaks upon the core functionality of the TGE Scripting Language. Once this has been accomplished we can then visit additional features such as working examples and tutorials.
Regards,
Ron
04/04/2002 (12:08 pm)
Stefan,Here is what I envision for the initial 2 phases.
Phase 1 :
* Combine current resources and forum posts into a single document
* incorporate user supplied content into the document
* Provide information regarding each entity within the document
* Clean up the document
* Fire it off to GG staff for review
Phase 2 :
* Add in ConsoleDoc output
* Provide more detailed information for each entity
* clean up the document
* Fire it back to GG staff for review
I feel that we need to provide an initial document that speaks upon the core functionality of the TGE Scripting Language. Once this has been accomplished we can then visit additional features such as working examples and tutorials.
Regards,
Ron
#8
Could you please provide me a real name for the contributor of t2docgen?
Regards,
Ron
04/04/2002 (12:10 pm)
Ryan,Could you please provide me a real name for the contributor of t2docgen?
Regards,
Ron
#9
I am still having problems accessing information within the url you posted. Could you possible email me zip file or provide it as a resource here?
Regards,
Ron
04/04/2002 (12:11 pm)
Ryan,I am still having problems accessing information within the url you posted. Could you possible email me zip file or provide it as a resource here?
Regards,
Ron
#10
04/04/2002 (12:50 pm)
You should be able to get to it ... try putting http:// in front of the link if it is not there in your 'address bar'.
#12
Can we make a master list, and make a checklist of sorts to ensure that duplicate efforts aren't required.
I'd just be able to pick a few things off the list and write it up, then we could paste the whole thing together and viola! Complete documentation!
04/04/2002 (2:24 pm)
I'd like to help contribute to this documentation, but I don't know what is done or needs to be done.Can we make a master list, and make a checklist of sorts to ensure that duplicate efforts aren't required.
I'd just be able to pick a few things off the list and write it up, then we could paste the whole thing together and viola! Complete documentation!
#13
How would this be for a high level task list?
Classes
Datablocks
Packages
Console Commands and Functions
Each section would include:
Current Entities, description of the entity, data members and syntax.
Yes, this is a very high over view. It would not be so combursome if we could get someone to head each section.
-Ron
04/04/2002 (2:56 pm)
Matt,How would this be for a high level task list?
Classes
Datablocks
Packages
Console Commands and Functions
Each section would include:
Current Entities, description of the entity, data members and syntax.
Yes, this is a very high over view. It would not be so combursome if we could get someone to head each section.
-Ron
#14
Work has begun! I am currently working over Joel's posted resources. I have stumbled apon one oddity (toe me) and that is the use of $Pref. I know $ makes it a global variable, but what is the symbolic nature of Pref? I even see it scattered throught the source code.
Is this some blindly picked variable? is it actualy meaningless? could it have been called $UselessVariable?
Regards,
Ron
04/04/2002 (8:31 pm)
Folks,Work has begun! I am currently working over Joel's posted resources. I have stumbled apon one oddity (toe me) and that is the use of $Pref. I know $ makes it a global variable, but what is the symbolic nature of Pref? I even see it scattered throught the source code.
Is this some blindly picked variable? is it actualy meaningless? could it have been called $UselessVariable?
Regards,
Ron
#15
04/04/2002 (8:39 pm)
$That's pretty funny, Ron :)
#16
The only thing that sets apart Pref variables as a group from other global variables is that the scripting in the TGE SDK treats them as preferences settings, and exports all variables that start with "$Pref::" to fps/client/prefs.cs, and all variables that start with "$Pref::Server::" to fps/server/prefs.cs and common/server/prefs.cs. (Kind of an awkward arrangement.) These files are then exec-ed at various points in execution to "load the prefs".
04/04/2002 (8:45 pm)
There's no intrinsically special meaning to any of the variable name patterns, including the use of Pref or of colons in the name... identifiers is identifiers.The only thing that sets apart Pref variables as a group from other global variables is that the scripting in the TGE SDK treats them as preferences settings, and exports all variables that start with "$Pref::" to fps/client/prefs.cs, and all variables that start with "$Pref::Server::" to fps/server/prefs.cs and common/server/prefs.cs. (Kind of an awkward arrangement.) These files are then exec-ed at various points in execution to "load the prefs".
#17
I have received some decent information from David Michael.
Have a request out to Joel Baxter, David R. Green and Matt Webster for assistance.
Matt has stepped up to the plate to help out documenting datablocks, I am going to work on Console Commands.
If you would like to help out, pick a area/topic to document and let me know. The more help we get the quicker this document can become a reality.
-Ron
04/05/2002 (2:00 pm)
Status update,I have received some decent information from David Michael.
Have a request out to Joel Baxter, David R. Green and Matt Webster for assistance.
Matt has stepped up to the plate to help out documenting datablocks, I am going to work on Console Commands.
If you would like to help out, pick a area/topic to document and let me know. The more help we get the quicker this document can become a reality.
-Ron
#18
i'm a webdeveloper and would like to contribute to this documentation project. if you think you need a mysql-database contact me, i was setting up a commentable "functions"-database with html-dump when i read this. could be "easily" expanded for datablocks, objects ... my version is in a very very very early stage, but if you want take a look at thesoulnomads.de/tork/tofu
if you are interested contact me @ smoover@web.de.
04/06/2002 (1:14 am)
hi there,i'm a webdeveloper and would like to contribute to this documentation project. if you think you need a mysql-database contact me, i was setting up a commentable "functions"-database with html-dump when i read this. could be "easily" expanded for datablocks, objects ... my version is in a very very very early stage, but if you want take a look at thesoulnomads.de/tork/tofu
if you are interested contact me @ smoover@web.de.
#19
Would documentation in the following format be useful to the community?
I (we) will try to provide as many working examples from the scripts as possible.
There are numerous ConsoleFunctions that are currently not used within the scripts,
I will attempt to create working examples for these functions.
-Ron
04/06/2002 (6:39 pm)
Need community input:Would documentation in the following format be useful to the community?
OpenALInitDriver()
Initializes the sound driver
Returns a "BOOL"
OpenALShutdownDriver()
Disables the sound driver
Returns a "void"
OpenALRegisterExtensions()
This appears to be a stub function call into the OpenAL interface
Returns a "void"
alGetString(enum)
Used to return the name for the enum passed
Returns a "const char*"
echo(" Vendor: " @ alGetString("AL_VENDOR"));
alxCreateSource(profile,{x,y,z}|description,filename,{x,y,z})
Creates and validates the Audio source (sound file) and readies it to be played
alxSourcef(handle,ALenum,value)
Used to set the value (a float) of ALenum for the specified handle
Returns a "void"
alxSourcef($ClientChatHandle[%sender], "AL_PITCH", %pitch);
alxSource3f(handle,ALenum,\"xyz\"|x,y,z)
Sets up a loop playback
Returns a "void"
alxSourcei(handle, ALenum, value)
Used to set the value (a int) of ALenum for the specified handle
Returns a "void"
alxGetSourcef(handle,Alenum)
Used to get the value (float) of ALenum for the specified Audio Handle
Reruns a "float"
alxGetSource3f(handle, ALenum)
Used to get the value (3 float's) of ALenum for the specified Audio Handle\
Returns a "float" in the form of "x y z"
alxGetSourcei(handle, ALenum)
Used to get the value (int) of ALenum for the specified Audio Handle
Reruns a "int"
alxPlay(handle) | alxPlay(profile) | alxPlay(profile, x,y,z)
Used to begin audio playback on specified (Handle | profile | profile "x y z")
Returns a "int"
alxStop(handle)
Used to stop the audio playback on specified Handle
Returns a "void"
AlxStopAll()
Used to stop ALL Audio playback on all registered sound channels
Returns a "void"
alxIsPlaying(handle)
Used to determine if a Handle is currently performing audio playback
Returns a "BOOL"
alxListener(ALenum,value)
Used to set the ALenum extension supporting linear gain to value (float)
Returns a "void"
alListener3f(ALenum,\"xyz\"|x,y,z)
Used to set the ALenum extension supporting linear gain to value (passed 3 floats "x y z")
Returns a "void"
alxGetListenerf(ALenum)
Returns the linear gain value of ALenum as a single float
AlxGetListener3f(ALenum)
Returns the linear gain value of ALenum as three floats (x y z)
alxGetListeneri(ALenum)
Returns the linear gain value of ALenum as a int
alxGetChannelVolume(channel_id)
Returns the current volume of specified channel as a int
alxSetChannelVolume(channel_id)
Used to set the volume of the specified channel.
Returns a "BOOL"
DumpConsoleClasses()
Used to dump All registered console classes to the console in native C++ syntax
Returns a "void"
ExpandFilename(filename)
Used to determine the actual path of the specified filename
Returns a "const char*"
strcmp(one,two)
Used to compare two strings.
Returns 0 if they are equal, nonzero if they are different.
stricmp(one,two)
Compares, with case insensitivity, the string pointed to by "one" to the string pointed to by "two".
Returns
< 0
"one" is less than "two".
0
"one" is equal to "two".
> 0
"one" is greater than "two"
strlen(str)
Returns the length of "str" as a int
strstr(string,substr)
locate first occurrence of a "substr" within a "string"
returns a "char *"
strpos(stringhay,stringneedle[,intoffset])
Returns the numeric position of the first occurrence of "stringneedle" in the "stringhay"
ltrim(str)
Strip white space from the beginning of a "str"
rtrim(str)
Strip white space from the end of a "str"
trim(str)
Strip leading and trailing white space of a "str"
sripChars(string,chars)
Used to remove "chars" from "string" returning the result
srlwr(string)
Replaces each character of a "string" with its lowercase equivalent.
srupr(string)
Replaces each character of a "string" with its uppercase equivalent.
strchr(string,char)
ruturns the first occurrence of "char" in "string"
strreplace(string,from,to)
Searches the entire "string" for the occurrences of "fromt" and replaces with "to".
getSubStr(string,start,numChars)
Returns the sub string of "string", starting at "start", and continuing to either the end of the string, or "numChars" characters, whichever comes first.
getWord(text,index)
Returns the word at specified at index within "text", returns a "const char *"
getWords(text,index [,entindex])
Returns the word(s) specified at index [,entindex] within "text", returns a "const char *"
setWord(text,index,replace)"
Replaces word at index with "replace" within "text", returns a 'const char *"
removeWord(text,index)
Remove word at index from "text", returns a "const char *"
getWordCount(text)
Return the number of words within "text", returns a "const char *"
getField(text,index)
Return the "const char*" at index within "text"
getFields(text,index [,entindex])
Returns the field(s) specified at index [,entindex] within "text", returns a "const char *"
setField(text,index,replace)"
Replace field at "index" with "replace", returns a "const char *"
removeField(text,index)
Remove field at "index" from "text", returns a "const char*"
getFieldCount(text)
Returns the number of fields within "text", returns a "int"
getRecord(text,index)
Return the record at "index" within "text", returns a "const char *"
getRecords(text,index[,endIndex])
Return the record(s) at "index [,endIndex]" within "text", returns a "const char *"
setRecord(text,index,replace)
Replace record at "index" with "replace" within "text", returns a "const char *"
removeRecord(text,index)
Remove record at "index" within "text", returns a "const char *"
getRecordCount(text)
Return the number of records within "text", returns a "int"
firstWord(text)
Returns the first word within "text", returns a "const char *"
restWords(text)
Returns the remaining words in "text", returns a "const char *"
detag(textTagString)
Returns a string with its "tag" removed.I (we) will try to provide as many working examples from the scripts as possible.
There are numerous ConsoleFunctions that are currently not used within the scripts,
I will attempt to create working examples for these functions.
-Ron
#20
This would make it easier to understand what it takes (the variable type at least) and exactly what it returns.
The problem with scripting is that variable types are not defined in the script like they are in C++. Unless we describe the variable type in C++ then we won't know what to send it.
04/06/2002 (8:19 pm)
That's a good start, but I think providing the function prototypes and an explanation of what it does would be a bit easier to understand.char * firstWord(char * phrase) The firstWord function accepts a string, and returns the first token/word of it.
This would make it easier to understand what it takes (the variable type at least) and exactly what it returns.
The problem with scripting is that variable types are not defined in the script like they are in C++. Unless we describe the variable type in C++ then we won't know what to send it.
Associate Stefan Beffy Moises
I will collect everything I can find and send it / post it here.
One more thing... we should not only collect all the scripting commands and variables, the same goes for "standard" datablocks, all available GUI elements and parameters(!!), e.t.c.