PDA

View Full Version : Documentation Request


Skyld
05-01-2006, 10:10 PM
Request Scripting Documentation

We recognise that the current documentation on the new scripting engine is not excellent, therefore this thread will serve the purpose of collecting ideas and requests for documentation. Feel free to post any sort of sensible suggestion about the sort of scripting documentation that should be written for the new engine.

Spam posts will be deleted.

Anyone can use this thread to find some documentation that needs to be written, and write some themselves to help the community.

The index of the current documentation for GScript is at http://wiki.graal.net/Creation/Dev/GScript.

Tyhm
05-04-2006, 10:43 AM
Do we have examples of the emitter yet? I've been awfully curious about that - if there was an example of "Let's take this picture of a dead fung si yuan, flip him so he's lying to the left instead of to the right, and while we're at it, let's make him redder and translucent", I could do a lot of damage with that...I mean, not damage...fun sunshines and icecream?

napo_p2p
05-04-2006, 10:48 AM
Do we have examples of the emitter yet? I've been awfully curious about that - if there was an example of "Let's take this picture of a dead fung si yuan, flip him so he's lying to the left instead of to the right, and while we're at it, let's make him redder and translucent", I could do a lot of damage with that...I mean, not damage...fun sunshines and icecream?

The wiki has nice documentation: http://wiki.graal.net/index.php/Particle_Engine

Also, here are some good examples (Stefan made): http://forums.graalonline.com/forums/attachment.php?attachmentid=33288

Raeiphon
05-04-2006, 12:11 PM
Possibly some common function and string manipulation documentation would be nice, I had no idea loadline(); existed before I asked.

ApothiX
05-04-2006, 03:23 PM
Possibly some common function and string manipulation documentation would be nice, I had no idea loadline(); existed before I asked.
Run graal4 with the command line option "-listscriptfunctions" and open the file it generates.

Tyhm
05-05-2006, 06:50 AM
Cool, thanks. I'm far more dangerous with a sample than with a theory.

Skyld
05-06-2006, 02:10 PM
Possibly some common function and string manipulation documentation would be nice, I had no idea loadline(); existed before I asked.
http://wiki.graal.net/index.php/Creation/Dev/Output_Methods

This might be what you're looking for, or similar to. I wrote this some time ago.

xAndrewx
05-06-2006, 04:07 PM
I was going to write something about the const function, but I don't know where to put it.

Skyld
05-06-2006, 04:55 PM
I was going to write something about the const function, but I don't know where to put it.
Create a new page, for example, http://wiki.graal.net/Creation/Dev/GScript/Constants

Then link it up to http://wiki.graal.net/Creation/Dev/GScript

Andy0687
05-07-2006, 12:08 AM
Ive been writing some documentation since a little before I saw this post, Ill have some of it up later on. Mostly script and usage examples. I hope it will help someone convert over.

Prozac
05-09-2006, 12:55 AM
you know how you cando findplayer("account").name or something
how about all the player.variables
and all the findplayer.what you can look for
and the findweapon.everythings

basically a break down tree view of what the main classes are
and what properties they can talk to.

also, for playerworld basics, to work on gmaps correctly, we really need free gs2 scripts of weapons/classes for the bow, arrows, and the bomb.
i mean, those a pretty fundamental weapons.
besides, graal used to come with a start level that had those weapons, the superbow, the mace and boomerang in them all for free when you downloaded it.

bring stuff like that back please.

Tyhm
05-09-2006, 01:41 AM
Seriously. Given how very little works with the default movement, baddies, bombs, bows, hit detection, etc., a really nice basic script for all that would help immensely. I mean, lookit Classic - all they had to do was convert from Clientside to Serverside and it killed the server twice.

ApothiX
05-09-2006, 03:12 PM
you know how you cando findplayer("account").name or something
how about all the player.variables
and all the findplayer.what you can look for
and the findweapon.everythings
I think you people don't even bother to look at what the wiki already has.

http://wiki.graal.net/index.php/Creation/Dev/Script/Client/TServerPlayer
http://wiki.graal.net/index.php/Creation/Dev/Script/Client/TPlayer
http://wiki.graal.net/index.php/Creation/Dev/Script/Client/TServerNPC
http://wiki.graal.net/index.php/Creation/Dev/Script/Client/TServerWeapon

jake13jake
05-09-2006, 08:05 PM
I really ought to be writing better documentation on Classic's systems.
Think that documentation stating the implementation of default variables would be good. Ex. player.paused and differences between how it behaves serverside and clientside.

Prozac
05-10-2006, 09:24 PM
Thank you for the links. Interesting that the weapons have only one .attribute that can be checked.

I request a doumentation format that is less like the wikipedia format, and more like ace's scripting guide - which i found here

http://web.archive.org/web/*/http://www.users.qwest.net/~ace2896/commands.html
(the december version worked ok but some of the images are missing)

but keep the search feature-
still, the outline and left frame nav, right frame content, was the most user friendly way to look up information that i have encountered for gscript.

In fact, much of what is in ace's scripting guide covers a lot of concept that would just need the gs2 version, and it could be come a more user friendly documentation than the list o' commands, with little to no expliation of how to actually implement the given commands in any kind of context, that much of the wiki is.

ace's explinations and how he displayed the information + gs2 + a search option = a helpful guide.

Also, why is the letter T before stuff like Graalvar? and Why make a page called tgraalvar when graalvar is not a variable that you will need to use when making any kind of weapon, system, display or anything in-game? just seems like unnecesary overcomplicaiton. that's my 2 cents.

Skrobo2
05-11-2006, 04:15 AM
People are probably going to get mad at me or something :p, but I'd like a commands.rtf for GS2. That would be much better than going to the wiki all the time. :]

Angel_Light
05-11-2006, 02:31 PM
I have a idea to add to the new engine.

function onPlayerkills() {
if (params[0]=="AccountName") {
blah();
player.chat = "You killed" SPC player.killed;
}
else if (params[1]=="NPC or Player var") {
blah();
}
}

for the default system hitpoint sys and it would see if the playerkilled someone or a NPC. it should also hold who got killed for awhile ;)

ApothiX
05-11-2006, 03:22 PM
People are probably going to get mad at me or something :p, but I'd like a commands.rtf for GS2. That would be much better than going to the wiki all the time. :]
Run graal4 with the command line option "-listscriptfunctions" and open the file it generates.
Sad, I've already said that in this thread.


I have a idea to add to the new engine.

function onPlayerkills() {
if (params[0]=="AccountName") {
blah();
player.chat = "You killed" SPC player.killed;
}
else if (params[1]=="NPC or Player var") {
blah();
}
}

for the default system hitpoint sys and it would see if the playerkilled someone or a NPC. it should also hold who got killed for awhile ;)
This is a documentation request thread, not a suggestion thread.


Thank you for the links. Interesting that the weapons have only one .attribute that can be checked.

I request a doumentation format that is less like the wikipedia format, and more like ace's scripting guide - which i found here

http://web.archive.org/web/*/http://www.users.qwest.net/~ace2896/commands.html
(the december version worked ok but some of the images are missing)

but keep the search feature-
still, the outline and left frame nav, right frame content, was the most user friendly way to look up information that i have encountered for gscript.

In fact, much of what is in ace's scripting guide covers a lot of concept that would just need the gs2 version, and it could be come a more user friendly documentation than the list o' commands, with little to no expliation of how to actually implement the given commands in any kind of context, that much of the wiki is.

ace's explinations and how he displayed the information + gs2 + a search option = a helpful guide.

Also, why is the letter T before stuff like Graalvar? and Why make a page called tgraalvar when graalvar is not a variable that you will need to use when making any kind of weapon, system, display or anything in-game? just seems like unnecesary overcomplicaiton. that's my 2 cents.
TServerWeapon only has one attribute because it is derived from TServerNPC, hence the reason I linked you to that too. 'T' is a common prefix for denoting objects, it is good practice to use it so that the programmer/scripter can easily know what the datatype/variable represents without having to search for the declaration in the source code.

Prozac
05-11-2006, 06:45 PM
TServerWeapon only has one attribute because it is derived from TServerNPC, hence the reason I linked you to that too. 'T' is a common prefix for denoting objects, it is good practice to use it so that the programmer/scripter can easily know what the datatype/variable represents without having to search for the declaration in the source code.

Good point, but in that case, the wiki would help the person developing the Graal application(s) - which in this case is only one person, Stefan. (and whoever else in france that he has hired, who knows).

Shouldn't the public wiki made for the players be focuses on what the players will actually encounter?

For example, in stead of the top of the page being

Creation/Dev/Script/Client/TServerPlayer

perhaps it could be more like

Creation/Development/NPCs/Client/player.attributes that you can access and modify

a bit more wordy and less 1337 code looking - but that's what people new to programming need. This is a game engine that is ideal for new players. No one is going to pay you money to make npc's, at least not a professional software company. It should be written for the programming novice and beginner level, not for the one who has years of coding under their belt.

jake13jake
05-12-2006, 12:57 AM
It should be written for the programming novice and beginner level, not for the one who has years of coding under their belt.
That's what a tutorial is for :P. I would say that the wiki is good for people with a year experience, and really good for people with more experience. Write one. Write a tutorial. It is a wiki after all. That way we could hire people for scripting that are using gscript2 for their first computer language (although sometimes often second for the HTML people). Unfortunately, there's still the fact that hiring trainee scripters is a huge security risk if you don't have a dev server *cough*.

Rick
05-12-2006, 08:23 AM
Good point, but in that case, the wiki would help the person developing the Graal application(s) - which in this case is only one person, Stefan. (and whoever else in france that he has hired, who knows).

Shouldn't the public wiki made for the players be focuses on what the players will actually encounter?

For example, in stead of the top of the page being

Creation/Dev/Script/Client/TServerPlayer

perhaps it could be more like

Creation/Development/NPCs/Client/player.attributes that you can access and modify

a bit more wordy and less 1337 code looking - but that's what people new to programming need. This is a game engine that is ideal for new players. No one is going to pay you money to make npc's, at least not a professional software company. It should be written for the programming novice and beginner level, not for the one who has years of coding under their belt.They are named after the class name. Why not just go to Client#Classes / Object Types (http://wiki.graal.net/index.php/Creation/Dev/Script/Client#Classes_.2F_Object_Types) ?

ApothiX
05-12-2006, 03:13 PM
Good point, but in that case, the wiki would help the person developing the Graal application(s) - which in this case is only one person, Stefan. (and whoever else in france that he has hired, who knows).

Shouldn't the public wiki made for the players be focuses on what the players will actually encounter?

For example, in stead of the top of the page being

Creation/Dev/Script/Client/TServerPlayer

perhaps it could be more like

Creation/Development/NPCs/Client/player.attributes that you can access and modify

a bit more wordy and less 1337 code looking - but that's what people new to programming need. This is a game engine that is ideal for new players. No one is going to pay you money to make npc's, at least not a professional software company. It should be written for the programming novice and beginner level, not for the one who has years of coding under their belt.
I believe I said the programmer and the scripter. No, they should not change the wiki to what you stated, and for one reason. The objects are available in scripts.

For example, if you wanted to make a new TStaticVar, you would do:

temp.mykewlvar = new TStaticVar();
temp.mykewlvar.test = "Zomg this variable now has members, and can be passed as a parameter to a function while keeping it's members.";

upsilon
07-07-2006, 06:45 PM
The graal bible has command documentation, but i havent beenable to find any event documentation.

ApothiX
07-08-2006, 02:29 PM
The graal bible has command documentation, but i havent beenable to find any event documentation.
Not looking in the right place. It has lists of events for the types of variables that call the events. If you cannot find the event where it should be, keep going up the hierarchy until you find it. (By up, I mean to the parent)

upsilon
07-10-2006, 04:28 PM
It has lists of events for the types of variables that call the events.

so they are classified by the caller? thats a bit weird. I have no idea what (for instance), calls the onCreated() event. Makes it very hard to just look around for events.

The only event descriptions ive found so far are in the gui stuff, and those are listed for the classes these things are called on. Could you point out an example maybe? Im not entirely sure i even understood you correctly.

Tyhm
07-10-2006, 11:10 PM
He's got a point, you know.
if(created) ideally meant When the level is first entered - by anyone, anywhere - run this event. And for quite a few versions it meant The first time any given player enters the level, so it got replaced with if(playerenters&&isleader&&this.open<1){ this.open=1;...
So the conditions in Plain English would be nice. Is "created" called when the level is uploaded? When the level is refreshed? When the NPCServer restarts? Does it wait for a player to enter the level and in so doing provide a processor on which to run scripts, or does the server run the script even if nobody ever finds the level?

upsilon
07-10-2006, 11:21 PM
well i can pretty much guess the answers to all of that. Id assume that the memory allocator is what actually calls onCreated when memory is allocated for the object, but many of them are not so obvious, and i dont see any documentation for the memory allocator ;) .

It looks like theres some documentation on GUI events, so the rest of it getting filled in is probably just a matter of time. I just haven't gotten to the point where i need to know about GUI object events yet. So i hadnt looked there.

Admins
07-11-2006, 12:46 PM
Well the onCreated event occurs when the object is created :D The loading behaviour of levels is another thing.
Should make some documentation on events though, especially for the new scripting engine where the event-functions are handled differently than the old-script 'if (eventname)' thing.

Tyhm
07-12-2006, 01:35 AM
Created by/for the client, or by/for the server? You don't have to answer right away, but this is the sort of question that'd make life easier if it was in the documentation, see. :-)

ApothiX
07-12-2006, 03:02 AM
Created by/for the client, or by/for the server? You don't have to answer right away, but this is the sort of question that'd make life easier if it was in the documentation, see. :-)
Both. It depends if it's clientside or serverside.

Tyhm
07-12-2006, 08:39 AM
A good clarification for the documentation too.
onCreated - serverside - [this is an example, please don't expect me to be right] called when the NPC is created by the NPCServer, typically when the level is first uploaded or when the NPCServer is restarted. In the case of Non Database NPCs (See Database NPCs, [and that would be a link]), this is also called when the level is updated.
- clientside - called when the NPC is first encountered by the player and thus 'created' locally. Also called when the level is updated. [maybe, depends on if people still use "update level" to restart the NPCs fresh, and if it works clientside, and if it works serverside, all three questions at once.]
onPlayerEnters - serverside - called whenever any player enters the level by any means - walking, warping, connecting, reconnecting, anything. Also checked when the NPCServer restarts or the level is updated, but only if there is a player still in the level (to the NPC, the player just "entered" - "enter" and "poof into existance" are synonimous)
onPlayerEnters - clientside - called whenever the player enters the level. For checking if another player entered their level, you'd need [link to functioncall here].
onHit - serverside - called whenever any damage is dealt to this NPC by any source...

I'm sure I'm beating a dead horse by this point, just speaking to hear myself talk - ye who write the documentation, you get what I'm sayin' right?

Rick
07-12-2006, 08:45 AM
ye who write the documentation, you get what I'm sayin' right?You're one of them. If you arn't, you should be. Get to work wenchy! ^^

ApothiX
07-12-2006, 11:00 AM
onCreated() is pretty straight forward, though.. If you go into the level, the NPC is created clientside, when you change the script, it is created serverside.

Raeiphon
07-12-2006, 11:09 AM
I dont think there's any documentation on the mudlib functions, only syntax.. Wouldn't mind some documentation on that

Python523
07-12-2006, 03:21 PM
I dont think there's any documentation on the mudlib functions, only syntax.. Wouldn't mind some documentation on that
Why would you care? It's not like you can play around with them.

Warcaptain
07-12-2006, 09:50 PM
Rwar we should be able to play around with them!

upsilon
07-13-2006, 06:35 AM
since they seem crutial to getting any non-trivial chunk of work done in gscript, someone who understands them pretty thoroughly should start a page on the wiki exclusively for triggerserver triggerclient and triggeraction, and object.trigger. distinctions between them, non pseudo code examples without confusing or non-descript variable names for the parameter.. descriptions of each parameter, stuff like that.

I racked my brain the other day trying to figure out how to use them all, and they seem to have overlapping functionality, but totally differ in their usage. Ive manage to get a triggerserver working so far. I could help out on that part of the page ^^

Reguardless of that though, i think they deserve special attention.

JkWhoSaysNi
08-28-2006, 10:37 PM
I think it would be nice if we had examples of each function. Kinda like php's documentation. All of the functions are listed but, useless mostly. changeimgpart(float,float,float,float,float); isn't useful without knowing what the params are supposed to be.

It'd be good if I could just type changeimgpart into the search box on wiki.graal.us and get an explanation of what it does and a couple of examples of how to use it.

I usually end up finding a function name in the wiki and then typing it into the forums search to get an example of usage.

Skrobo2
08-28-2006, 11:28 PM
I still think someone should type up a GS2 equivalent of commands.rtf. And cover everything that can be done with Gscript, not just some of it. I find myself adding new things that I learn to my commands.rtf quite a bit. The wiki is nice, but I'd rather have a file to open, instead of having to go online.

And before someone quotes Okie again.

Run graal4 with the command line option "-listscriptfunctions" and open the file it generates.

I know I've said this before, and I know what he said. I did as he said and the list I got was not that helpfull. We need something that gives a short explanation like in commands.rtf.

Like this:


// simple npc manipulation:
setimg("filename"); changes the npc’s image
setimgpart("filename",x,y,width,height); changes the npc’s image and only displays the rectangle (x,y,width,height) of it
hide(); hides the npc
show(); shows an hidden npc
dontblock(); lets the npc don’t block the player anymore
drawoverplayer(); draws the npc over the player
drawunderplayer(); draws the npc under the player
drawaslight(); draws the npc above day/night
blockagain(); turns off the four previous flags
canbecarried(); the npc can now be lifted and carried by the player
cannotbecarried(); turns off the previous flag
canbepushed(); the npc can now be pushed by the player
cannotbepushed(); turns off the previous flag
canbepulled(); the npc can now be pulled by the player
cannotbepulled(); turns off the previous flag
cannotwarp(); disables link warping (dnpc) (server-side)
canwarp(); enables link warping (dnpc) (server-side)
canwarp2(); enables link warping for overworld links (dnpc) (server-side)
noplayeronwall(); players aren’t counted as a wall in onwall() or onwall2()
timershow(); lets the npc’s timeout be shown
showcharacter(); displays a player character instead of the npc image
throwcarry(); throws the carried object
*followplayer; Removed in GS2
hidelocal(); hides the npc (only for the current player)
showlocal(); shows an hidden npc (only for the current player)
dontblocklocal(); lets the npc don’t block the player anymore (only for the current player)
blockagainlocal(); turns off the three block flags (only for the current player)
destroy(); deletes the npc
shootball(); shoots a ball directly to the player

_Z3phyr_
08-31-2006, 03:46 AM
My mental version of commands.rtf is this:

- Same as GS1, but with () marks... and start off every code block by declaring a function.



---

But yeah though Skrobo, you keep doing what you're doing man with that commands.rtf and I, along with everyone else who is trying to teach themselves GS2 but has no one to teach them, will love you long time.

Skrobo2
08-31-2006, 05:20 AM
Problem is, I don't know GS2 well, myself. It'd be nice if Skyld or someone could do this. Most of it is just syntaxing, but things have been removed and there are new additions to the scripting language such as GUI windows and particles.

Tyhm
11-11-2006, 11:17 PM
- shoot real,real,real,real,real,real,string,string
Not only is this posted numerous times, only once does it list it as
shoot x,y,z,angle,zangle,power,ani,aniparams;
which STILL omits the most useful bit of information from the original documentation:
angle is in radians, and what number you set Power to to make it a classic-style goes-until-it-hits-a-wall projectile.

jake13jake
11-13-2006, 09:32 PM
Function prototypes are not documentation by any means.

Tyhm
11-13-2006, 11:33 PM
http://wiki.graal.net/index.php/Creation/Dev/Old_GScript

Well, I mean, we got stuff like

move dx,dy,time,options; moves the npc, options: cachtype(0,1,2) +
blockcheck(4) + eventwhendone(8) +
applydir(16)
...so I can figure out dx, dy is going to be something like -8, 0 for Move 8 tiles left, and time's probably going to be in seconds, so if you say 1 it'll move those 8 tiles in one second...
So what's cachtype 0,1,and 2? I imagine it's standard-issue binary, 0 means no cachtype, 1 means cachtype 1, 2 means cachtype 2, 3 means both 1 and 2...but what do they DO in vague terms?
Blockcheck 4, I imagine it detects blocking tiles - does it detect water? Chairs? Beds? Lava? Shallows?
Eventwhendone, I remember this being terrifically useful - but what event did it call? With what parameters/arguments?
Applydir? Will that turn the NPC automatically?
I'll grant, I could do some of this legwork myself, but EventWhenDone, that's infinite possible event-calls to detect for...

-5 minutes later-
It's a good thing I keep everything.

From NewFeatures2001.txt:
There are also nice options to makes things very simple:
- cachingmode:
- 0: previous movements will be finished immediatelly
- 1: movements will be cached, the previous movements
will only be finished when the cache is too large
(distance to go >5);
this caching can be used on server-side npcs to
make the movement look like non-laggy even when
there are little delays sometimes
- 2: the movement will just be appended to the movement
list; you can add up to 100 movements
- blockcheck: add 4 to the options when you want the
npc to stop when there is a wall blocking the npc
- informmewhendone: if you add 8 to the options then the
script will be called with a 'movementfinished' flag
when the the npc has stopped walking; catch this event
with
if (movementfinished) {...}
if you want to do something when the npc has stopped
(e.g. walking in a different direction)
- applydirection: add 16 to the options if you want the
game to automatically set the direction of the npc
depending on the movement direction (can be good
when using movement caching)


I wonder if I have access to add the old NewFeatures to the Wiki myself...
Nope, sure don't. Oh well.

Riot
11-14-2006, 12:38 AM
I wonder if I have access to add the old NewFeatures to the Wiki myself...
Nope, sure don't. Oh well.

You do, login to the Bible with your Graal account information and you can add a new page or edit an already existing one.

Tyhm
11-14-2006, 12:50 AM
Tried. The scripting section is locked down, no edit or add links. I can upload graphics for all the good that'd do me. Unless they hide the New Page links somewhere sneaky...

Admins
11-14-2006, 02:25 PM
Tyhm, login to the wiki first, I don't think that any page is protected right now except the main page.
Best would be to add the old "newfeatures.txt" to http://wiki.graal.net/index.php/Creation/Dev/Client_Releases I guess.

Tyhm
11-14-2006, 10:33 PM
Okay, duh, now I see it, way off to the left...
Well that's cool, if I make the links then the pages create themselves...
Alright, should be up soon then.

zokemon
08-05-2007, 12:29 PM
:: revives the sticky ::

I would be glad to do some major updating to the wiki (most notably the scripting part) if I got some sort of recognition for it. I know it may be selfish to ask for that but I don't think there is one person on here that doesn't want recognition for their hard work.

EDIT:
I'm sure many of you know I'm plenty capable for the job.