Documentation Request
 

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.

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...chmentid=33288

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.

Cool, thanks. I'm far more dangerous with a sample than with a theory.

http://wiki.graal.net/index.php/Crea...Output_Methods

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

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

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.

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.

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.

I think you people don't even bother to look at what the wiki already has.

http://wiki.graal.net/index.php/Crea.../TServerPlayer
http://wiki.graal.net/index.php/Crea...Client/TPlayer
http://wiki.graal.net/index.php/Crea...ent/TServerNPC
http://wiki.graal.net/index.php/Crea.../TServerWeapon

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.

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://.../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.

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. :]

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 ;)

Sad, I've already said that in this thread.


This is a documentation request thread, not a suggestion thread.


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.

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*.

They are named after the class name. Why not just go to Client#Classes / Object Types ?

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:

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)

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.

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?

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.

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.

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.

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?

You're one of them. If you arn't, you should be. Get to work wenchy! ^^

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.

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.

Rwar we should be able to play around with them!

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.

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.

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.

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:

NPC Code:

---

// 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

---

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.