TGE Script Documentation

#21 The scripters who may not have a background in coding. So the char * notation may make the documentation harder to understand.

#22 I would have to agree with Harold.

We should construct the document in such a way that even a person with no programming background would be able to understand it.

We need to make a conscious effort to use descriptive words like "text", "string", and "number". It is early, so I have not figured out a decent term to describe "float" (no, not the ice-cream one either ;) ).

A possible function prototype/description could be

firstWord(text)
Returns the first word within "text"
$TheFirstWord = firstWord(%StringOfWords);

Or, we could take a different approach. Give a brief description of "char", "int", "float" and "const char *" within the Preface of the document. Then we could do as Matt suggests.

char * firstWord(char * phrase)
The firstWord function accepts a string, and returns the first token/word of it.

Two schools of thought, which should we entertain?

-Ron

#23 Your talking about documenting the script. So make it script syntax (i.e. %variable). That char * has nothing to do with scripting.

The actual "code" functions should be documented in the source as part of the doxygen stuff. Thats a different project I think.

i think something that shows the function, describes its parameters, tells you its purpose then gives an example usage would be the best solution.

Phil.

#24 Phil,

Its early, so please forgive my ignorance.

Are you speaking like this

firstWord(%text)
Used to Return the first word within "%text"

#25 This is more like what I was hoping for. I just put this together today. So, forgive any errors and lack of details since it is such a rough draft. :-) Ideally, each would have a short description and rather than numbers have "n" and what "n"'s range is.

This is actually from T2, so I'm not sure how much would apply. I haven't programmed for years, and have been getting into T2 scripting quite a bit lately. So, you might consider this how a "non-programmer" might see it. :-)

Two more things: there is an example at the end which has the datablock that calls the projectiledata, and there probably should be some sort of description of what actually makes the call on these. That might be:

datablock ShapeBaseImageData(DiscImage)
{ projectileSpread = 1.0 / 1000.0;
projectile = IDDisc;
projectileType = EnergyProjectile;
};


--------------------------------------------------------------------------
// Projectiles.cs: Note that the actual projectile blocks are stored with
// with weapon that uses them in base/scripts/weapons/*.cs,
// the blocks below are only to illustrate the default values
// for each block type. Also, ProjectileData cannot be used
// as a concrete datablock type.
// Inheritance:
// ProjectileData : GameBaseData
// LinearProjectileData : ProjectileData
// LinearFlareProjectileData : LinearProjectileData
// GrenadeProjectileData : ProjectileData
// SeekerProjectileData : ProjectileData
// SniperProjectileData : ProjectileData


Projectile Data Settings common to all (inherited)

projectileShapeName = "disc.dts";
emitterDelay = -1;
directDamage = 0.0;
hasDamageRadius = true;
indirectDamage = 0.50;
damageRadius = 7.5;
radiusDamageType = $DamageType::Disc;
kickBackStrength = 1750;
sound = discProjectileSound;
explosion = "DiscExplosion";
underwaterExplosion = "UnderwaterDiscExplosion";
splash = DiscSplash;
dryVelocity = 90;
wetVelocity = 50;
velInheritFactor = 0.5;
muzzleVelocity = 15.0;
fizzleTimeMS = 5000;
lifetimeMS = 5000;
explodeOnDeath = true;
reflectOnWaterImpactAngle = 15.0;
explodeOnWaterImpact = true;
deflectionOnWaterImpact = 0.0;
fizzleUnderwaterMS = 5000;
activateDelayMS = 200;
hasLight = true;
lightRadius = 6.0;
lightColor = "0.175 0.175 0.5";
hasLightUnderwaterColor = true;
underWaterLightColor = "0.05 0.075 0.2";
useLensFlare = false; //?
texture[0] = "special/flare3"; //?
size = 4.0; //?
BaseEmitter = FlareEmitter; //?
delayEmitter = MissileFireEmitter;
puffEmitter = MissilePuffEmitter;
bubbleEmitter = MortarBubbleEmitter;
bubbleEmitTime = 1.0;
grenadeElasticity = 0.35;
grenadeFriction = 0.2;
armingDelayMS = 6000;
drag = 0.1;
gravityMod = 0.15;
doDynamicClientHits = false
numFlares = 20;//?
flareColor = "1 0.35 0.35"; //?
flareModTexture = "flaremod";//?
flareBaseTexture = "flarebase"; //?
flareDistance = 200;
flareAngle = 30;
depthTolerance = 10.0; // depth at which it uses underwater explosion. Grenades only?
tracerLength = 20;
tracerAlpha = false;
tracerMinPixels = 3;
tracerColor = "1 1 1 1";
tracerTex[0] = "special/shrikeBolt";
TracerWidth = 0.55;
crossSize = 0.99;
crossViewAng = 0.990;
renderCross = true;
emap = true;
decalData[0] = ChaingunDecal1; //marks on walls. ie: Bulletholes

//these appear only in MissileProjectileData, though may work with other projectile data types
casingShapeName = "weapon_missile_casement.dts";
exhaustEmitter = MissileLauncherExhaustEmitter;
exhaustTimeMs = 300;
exhaustNodeName = "muzzlePoint1";
turningSpeed = 90.0;
proximityRadius = 4;
terrainAvoidanceSpeed = 180;
terrainScanAhead = 25;
terrainHeightFail = 12;
terrainAvoidanceRadius = 100;
useFlechette = true;
flechetteDelayMs = 550;
casingDeb = FlechetteDebris;
minSeekHeat = 0.6;

//only found in SniperProjectileData and TargetProjectileData
rifleHeadMultiplier = 1.3; //? Sniper only?
beamColor = "1 0.1 0.1";
fadeTime = 1.0;
startBeamWidth = 0.145;
endBeamWidth = 0.25;
pulseBeamWidth = 0.5;
beamFlareAngle = 3.0;
minFlareSize = 0.0;
maxFlareSize = 400.0;
pulseSpeed = 6.0;
pulseLength = 0.150;
beacon = true; // TargetProj. Only?


//only found in RepairProjectileData. Possibly share with Sniper/Target?
beamRange = 10;
beamWidth = 0.15;
numSegments = 20;
texRepeat = 0.20;
blurFreq = 10.0;
blurLifetime = 1.0;
cutoffAngle = 25.0;

//only found in ELFProjectileData. Possibly share some with Shocklance?
numControlPoints = 8;
restorativeFactor = 3.75;
dragFactor = 4.5;
endFactor = 2.25;
randForceFactor = 2;
randForceTime = 0.125;
drainEnergy = 1.0;
drainHealth = 0.0015;
mainBeamWidth = 0.1; // width of blue wave beam
mainBeamSpeed = 9.0; // speed that the beam travels forward
mainBeamRepeat = 0.25; // number of times the texture repeats
lightningWidth = 0.1 //also in Shocklance Proj.
lightningDist = 0.15; // distance of lightning from main beam
fireSound = EBLFireSound;
emitter [0]= ELFSparksEmitter; // also in shocklance

//only found in ShocklanceProjectileData (possibly share with ELF?)
zapDuration = 1.0;
impulse = 1800;
boltLength = 14.0;
extension = 14.0; // script variable indicating distance you can shock people from
lightningFreq = 25.0;
lightningDensity = 3.0;
lightningAmp = 0.25;
shockwave = ShocklanceHit;
boltSpeed[0] = 2.0;
texWrap[0] = 1.5;
startWidth[0] = 0.3;
endWidth[0] = 0.6;

//only found in BombProjectileData
minRotSpeed = "60.0 0.0 0.0";
maxRotSpeed = "80.0 0.0 0.0";


Now, just because I have some seperated from the others doesn't necessarily mean they wouldn't work for other projectile types. For my mini-mod of T2, TRON Sea of Simulation I wanted the spinfusor to bounce or ricochet from the walls. So, some of those we may find to be in common with eachother. Note the use of Grenade settings and the disc's original linear projectile settings in their new EnergyProjectileData "home". Here's what I did:

//--------------------------------------------------------------------------
// Projectile -- Tron Disc by Eric Forhan
//--------------------------------------

datablock EnergyProjectileData(IDDisc)
{
projectileShapeName = "disc.dts";
emitterDelay = -1;
directDamage = 0.0;
hasDamageRadius = true;
indirectDamage = 0.50;
damageRadius = 7.5;
radiusDamageType = $DamageType::Disc;
kickBackStrength = 1750;
sound = discProjectileSound;
velInheritFactor = 0.5;
explosion = "DiscExplosion";
splash = DiscSplash;
grenadeElasticity = 0.998;
grenadeFriction = 0.0;
armingDelayMS = 4990; //don't explode on landscape until very end of disc life
activateDelayMS = -1; // same as arming delay?

drag = 0.05;
gravityMod = 0.0; //must have this or projectile will arc
dryVelocity = 90;
wetVelocity = 50;
explodeOnDeath = true;

reflectOnWaterImpactAngle = 15.0;
reflectOnWaterImpactAngle = 0.0;
explodeOnWaterImpact = true;
deflectionOnWaterImpact = 0.0;
fizzleUnderwaterMS = 5000;
lifetimeMS = 5000;
hasLight = true;
lightRadius = 6.0;
lightColor = "0.175 0.175 0.5";
scale = "1.0 1.0 1.0";
};

datablock ShapeBaseImageData(DiscImage)
{ projectileSpread = 1.0 / 1000.0;
projectile = IDDisc;
projectileType = EnergyProjectile;
};

#26 Would this be a more suitable description for the Console Functions?

ltrim(str)
	Used to strip white space from the beginning of "str"
	%LeftTrimed = ltrim(%string);

rtrim(str)
	Used to strip white space from the end of "str"
	%RightTrimed = rtrim(%string);

trim(str)
	Used to strip leading and trailing white space of "str"
	%Trimed = trim(%string);

Regards,
Ron

#27 TGE Scripting Documentation update:

I have just completed documenting 100 of the 323 known "Console Functions/Commands". So far this section of the document is a whopping 9 pages!

I know this might seem like limited progress to some, but digging through the C++ code as well as the scripts/gui files is very time consuming.

Matt,
Could you kindly update the community regarding your " Datablocks " section of the document?

Regards,
Ron

#28 I've only begun writing out a broad list of things relating to datablocks.

1. What is a datablock?
2. What is a script object?
3. What can I do with datablocks?
4. What can I do with script objects?
5. How do I work with datablocks?
6. How do I work with script objects?

No, I haven't really put much effort into it! I'll elaborate it a bit more when I have some free time. Share your ideas here, and I'll be sure to incorporate them.

Oh, and %variable formatting is nice and all... but that's probably the most confusing aspect of the scripting language. Number of variables really don't matter to me at all, especially when I don't know what kind of variable it is. char * = string. Fine, but many other things be required to refer to C++-like syntax? What about floats? Integers? unsigned integers?

What about handles or file paths?

I guess it'd be best to lay out the "rules" so non-coders can understand it, but you're going to have to mix in things you'd normally see in C++. otherwise people won't know what to send it. How does the scripting language accept an x/y/z coordinate? How does it accept a file handle?

If we don't specify the "variable type" then it won't be easy to understand what we have to give it. Sure, we have to give it the transform of the object, but what format is that? What if we wanted to manually assign it? How would we know the format?

I think using the less technical naming of variable types would be nice, but we'd need some sort of "key" in order to have people understand it at a glance. Instead of just "number" or "handle" we'd need to specify what exactly goes in there.

#29 Matt,

I agree 100% with you, it has been a tad bit difficult to NOT use C/C++ terminology. I will work on drafting up an explanation for each variable type as well as a way to make it easier for non programmers to understand the scripting language.

Like you suggested, we should start using terms like "string" and "number" to replace the often used "const char *", "char *" and "integer" notations.

I will also take from Joel Baxter's TGE reference the definition of %, $ and other scripting tokens. Hopefully this will aid in making this document more comprehendible by those with little to no programming background.

Regards,
Ron

#30 I like the string, number terminolgy as well. Other types include objects & datablock references (which can be both strings or numbers), coordinates and transforms. These last two really aren't built in types, but are used by a number of console methods.

I like the basic format:

string ltrim(string)
Description
Example

I see the doco would include the basic overviews you guys are talking about, a table of contents, a function reference, and then I'd probably include documentation for specific object types similar to what I posted ealier for GameBase.

#31 Tim,

Yes, we will definatly have a "book" like reference when we are done. It will include a TOC, preface, reference material and an index. Heck, when it is all said and done, GG could spruce it up; send it off to a proof reader and publish it *snicker*

Today has been a total waste with regards to the document, I will have the something mid afternoon tomarrow.

-Ron

#32 Ron:

Although I'm new to the TGE (just bought the license about a week ago) I would like to offer to help with the documentation you've been discussing. I beleive the documentation would be essential to anyone getting any good use from the engine.

A community effort on this project is probably the best idea I've seen in any of the posts on the forums - and I think I've just about read them all trying to figure out where, and how, to start.

I want to commend you on your efforts here. Please let me know if I can do anything to help.

Dennis (Mo Betta)

#33 Sure,

So far Console Functions/Commands and Datablocks are accounted for, if you wish; dig in and shed some light on the GUI classes or packages.

Refer to the above post by Tim Gift, I would definatly want the classes document like he did.

Regards,
Ron

#34 I've got a few essays to finish up this week, so I'll dive in on the datablock stuff starting Friday.

I'll try to post my progress via a .plan Saturday or Sunday!

#35 No problem, in no hurry I would like this document to be top notch before we release it to the community.
I will be looking for someone with more indepth knowledge regarding layout/format of the document, as well as proofreading etc..

When we turn this document over to GG, I want to knock their socks off! Want it to be very profession, to the quality it could even be published!

-Ron

#36 Damn.

Now I have to delete all the references to Dragonball Z and the phrase "It kicks ass!".

MS Word doesn't happen to have a "Professional Grammar" filter, does it?

#37 ROFL

Well, I just umm fubarbed myself. I have been doing my document on my laptop. Well I noticed I was down to 100MB left (HDD space) so I went cleaning my junk dir.

ACK! my document was in their :( CRAP! *sigh* back to revision 1 which is needless to say, looks like my 8 year old composed it :(

SIGH!

#38 O.K
I need some insight here.
Is this possible?

have several objects
object1 - object7

is it possible to create a for loop and manipulate each of the obecjts?

for ( i = 1 ; i <= 7 ; i++ )
{
  objecti.something(something);
}

#39 Yeah, you can create a loop for multiple objects. Try something like:


for (%i = 1; %i <=7; %i++)
{
%objectName = "object" @ %i;
%objectName.functionOrWhatever(values);
}

or maybe you need to use eval... Try it and see I guess. =)

#40

for ( i = 1 ; i <= 7 ; i++ )
{
  nametoID(object @ %i).something(something);
}