script cleanup/scripting standards proposal

Content and general development discussion, including maps, quests, and server code from the development team.
User avatar
o11c
Knight
Knight
Posts: 2262
Joined: 20 Feb 2011, 22:09
Location: ^ ^

script cleanup/scripting standards proposal

Post by o11c » 04 Aug 2011, 08:59

I would like to see some feedback, particularly regarding anything that I have missed.

Much of this is useful immediately, but some bits are designed to make porting to my (eventual) new scripting engine more painless
  • indentation with 4 spaces
  • no trailing whitespace
  • in every file, document every variable as one of:
    • account variable (prefix #)
      (note that there are also ## variable but they don't work in the stable version of the server;)
    • permanent player variable (no prefix)
    • temporary player variable (prefix @) - used after the script close;s or end;s.
    • dynamic player variable (prefix @) - passed into or out of callsub or callfunc
    • lexical (local) player variable (prefix @) - used only within the function
      (scripthelp.txt documents that ".@" means this but I don't know if that works)
    • local constant (prefix @) - not dependent on the player, used only within the function.
      e.g. lots of @QUEST_FOO_{SHIFT,MASK}
    • global permanent variable (prefix $) (I'm not sure if we have any of these right now)
    • npc permanent variable (prefix $) same as above but only used by one NPC
    • global temporary variable (prefix $@)
    • npc temporary variable (prefix $@) same as above but only used by one NPC, scripthelp.txt mentions prefix "." but I don't know if that works
    • special variable (in db/const.txt with a 1 following)
    • global constant (in const.txt)
    If we use a consistent method of documenting these, we can then generate a list of all variables by type.
  • Check for troublesome arrays
    A troublesome array is defined as an array that is not
    • initialized all at once
    • initialized by appending elements to the end, for use in a menu
  • Set dynamic and local @variables to 0 before close;
  • Remove unnecessary next;
  • Remove redundant code such as end; after close;
  • remove break; instead use end; (requires changing the java converter)
  • Replace monsters.txt with _mobs.txt except in special cases.
  • A standard for whitespace and comments.
    • I have begun to use "^// " lines to be commented out code (because that is what my editor uses automatically to disable code), maybe "^///" lines for documentation? leaving "^//[^ /]" for "other". Documentation should maybe have doxygen-like tags?
    • I dislike boxed comments.
    • newline before every label
    • no newline after label
    • newline between if (condition) and conditional_command; ?
    • limit line length? (break long strings using + concatentation)
  • One NPC per file, except for "flavor" NPCs that only say a single line
  • capitalization of temporary variable names and labels?
  • An unused line after the closing '}'? I found this useful while stepping through the debugger ... maybe it could be something dual-use, such as a comment saying "end of npc Foo"?
  • use checkweight("item", amount) instead of comparing against 100 items in inventory (edit because I didn't notice the bbcode error earlier - this may fall in the "higher-level concerns" category)
Once discussion is ended and there is a wiki page, you should:
  • Follow this list for all new script files
  • Create these changes (in a separate patch) when making changes to an existing script
  • Gradually apply these changes across the whole set of script files.
---

Personally, I dislike code like:

Code: Select all

set @reward, 500;
set Zeny, Zeny+@reward
and

Code: Select all

set @reward_amount, 3;
getitem "reward", @reward_amount
because it makes it hard to grep,
but in the (additional) case of delitem I can see why it would be wanted since it must be checked-for first ...
Last edited by o11c on 04 Aug 2011, 22:50, edited 1 time in total.
Former programmer for the TMWA server.
alastrim
Novice
Novice
Posts: 137
Joined: 02 Jun 2009, 13:19
Location: Brasil

Re: script cleanup/scripting standards proposal

Post by alastrim » 04 Aug 2011, 12:54

These are some very good suggestions in my opinion:
indentation with 4 spaces
no trailing whitespace
Set dynamic and local @variables to 0 before close;
Remove unnecessary next;
Remove redundant code such as end; after close;
remove break; instead use end; (requires changing the java converter)
Replace monsters.txt with _mobs.txt except in special cases.
You mean documenting them in the beginning of the file as comments?
in every file, document every variable as one of:
account variable (prefix #)
(note that there are also ## variable but they don't work in the stable version of the server;)
permanent player variable (no prefix)
temporary player variable (prefix @) - used after the script close;s or end;s.
dynamic player variable (prefix @) - passed into or out of callsub or callfunc
lexical (local) player variable (prefix @) - used only within the function
(scripthelp.txt documents that ".@" means this but I don't know if that works)
local constant (prefix @) - not dependent on the player, used only within the function.
e.g. lots of @QUEST_FOO_{SHIFT,MASK}
global permanent variable (prefix $) (I'm not sure if we have any of these right now)
npc permanent variable (prefix $) same as above but only used by one NPC
global temporary variable (prefix $@)
npc temporary variable (prefix $@) same as above but only used by one NPC, scripthelp.txt mentions prefix "." but I don't know if that works
special variable (in db/const.txt with a 1 following)
global constant (in const.txt)
User avatar
Jenalya
TMW Adviser
TMW Adviser
Posts: 718
Joined: 22 Sep 2010, 20:28

Re: script cleanup/scripting standards proposal

Post by Jenalya » 04 Aug 2011, 13:07

Generally I like the idea to have some coding style conventions very much. But we should take care not to create a deterrent environment for new contributors with creating requirements only few people can meet.
o11c wrote:indentation with 4 spaces
Having in mind the first line of an NPC needs a tab, how to use this in a comfortable way? Are you going to change that? That'd be great!
o11c wrote:in every file, document every variable as one of:
Can you give an example of how that documention should look like? Also, I assume some script writers don't even know which of those variables they are using.
o11c wrote:Check for troublesome arrays
A troublesome array is defined as an array that is not
  • initialized all at once
  • initialized by appending elements to the end, for use in a menu
What should be done with those?
o11c wrote:remove break; instead use end; (requires changing the java converter)
What would be the effect of that?
o11c wrote:newline between if (condition) and conditional_command; ?
Generally yes, but I think at the beginning of NPCs to determine to jump to which label depending on some variable, it's clearer without a newline.
o11c wrote:capitalization of temporary variable names and labels?
Do you mean with capitalization This or THIS?
When I started scripting, I learned by reading existing scripts and adopted to name lables with something like "L_Labelname", what about making that a convention as well?
o11c wrote: Personally, I dislike code like:

Code: Select all

set @reward, 500;
set Zeny, Zeny+@reward
and

Code: Select all

set @reward_amount, 3;
getitem "reward", @reward_amount
because it makes it hard to grep,
but in the (additional) case of delitem I can see why it would be wanted since it must be checked-for first ...
I experienced having hard coded numbers all over the code is bad...
Though using constants for values used only once in the script might be exaggerated, but I suggest to have constants at least for values that are used several times, e.g. the amount of an item needed to fullfill a quest.

What about guidelines regarding saving playervariables with using bitmasking or setting used playervariables to zero and set a flag for it after a quest is finished?
User avatar
Wombat
TMW Adviser
TMW Adviser
Posts: 1532
Joined: 08 Aug 2008, 17:31

Re: script cleanup/scripting standards proposal

Post by Wombat » 04 Aug 2011, 18:41

Your proposal is interesting. I like tabs and how things have been with scripting. Why can't we use the standards we've used for years? I don't like changing how scripting is done. Also, a great many of your points aren't contrasted against others. If it is a change proposal, it helps to know what is changing. They also assume the reader understands what you are saying. Many script writers for the game don't understand programming.
Current character is "Abolish".
User avatar
argul
Novice
Novice
Posts: 237
Joined: 08 Aug 2010, 19:43

Re: script cleanup/scripting standards proposal

Post by argul » 04 Aug 2011, 21:23

o11c wrote:
  • indentation with 4 spaces
  • no trailing whitespace
Additional a serious header! (gpl, authors, years!)
o11c wrote:
  • in every file, document every variable as one of:
    • account variable (prefix #)
      (note that there are also ## variable but they don't work in the stable version of the server;)
    • permanent player variable (no prefix)
    • temporary player variable (prefix @) - used after the script close;s or end;s.
    • dynamic player variable (prefix @) - passed into or out of callsub or callfunc
    • lexical (local) player variable (prefix @) - used only within the function
      (scripthelp.txt documents that ".@" means this but I don't know if that works)
    • local constant (prefix @) - not dependent on the player, used only within the function.
      e.g. lots of @QUEST_FOO_{SHIFT,MASK}
    • global permanent variable (prefix $) (I'm not sure if we have any of these right now)
    • npc permanent variable (prefix $) same as above but only used by one NPC
    • global temporary variable (prefix $@)
    • npc temporary variable (prefix $@) same as above but only used by one NPC, scripthelp.txt mentions prefix "." but I don't know if that works
    • special variable (in db/const.txt with a 1 following)
    • global constant (in const.txt)
    If we use a consistent method of documenting these, we can then generate a list of all variables by type.
Yes definitively a good idea! I'd personally only document the longterm variables like permanent player/account variables.
That is already partly done. (All the more critical npc, like skill giving npc or hurnscald story npc)

o11c wrote:
  • Check for troublesome arrays
    A troublesome array is defined as an array that is not
    • initialized all at once
    • initialized by appending elements to the end, for use in a menu
Could you point out an example for how to do arrays?

o11c wrote:
  • Set dynamic and local @variables to 0 before close;
(Would be good coding style indeed, but would need refactoring lots of already-there code.)
Can't the game engine handle this and prevent memleaks or staying variables?
o11c wrote:
  • Remove unnecessary next;
What is unneccessary? comments?

All in all it sounds like a roadmap. :)

What about indentation style?
---
User avatar
o11c
Knight
Knight
Posts: 2262
Joined: 20 Feb 2011, 22:09
Location: ^ ^

Re: script cleanup/scripting standards proposal

Post by o11c » 04 Aug 2011, 22:46

Jenalya wrote:
o11c wrote:indentation with 4 spaces
Having in mind the first line of an NPC needs a tab, how to use this in a comfortable way? Are you going to change that? That'd be great!
Unfortunately I cannot change that: in particular, because the name of an NPC may contain a space.
Jenalya wrote:
o11c wrote:Check for troublesome arrays
A troublesome array is defined as an array that is not
  • initialized all at once
  • initialized by appending elements to the end, for use in a menu
What should be done with those?
Nothing needs to be done, merely document them. I want this information at hand when I design the new scripting language to minimize conversion pains.
I wouldn't be surprised if there were no troublesome arrays at all. If there are only a couple it might be worth refactoring the code to remove them, but that might be a high-level decision which is beyond the scope of this proposal.
Jenalya wrote:
o11c wrote:remove break; instead use end; (requires changing the java converter)
What would be the effect of that?
No effect, they are identical internally. But I'm trying make all functions have the same name internally and externally, which is not really possible the the function has multiple external names.
The only other example is that "save" is an alias for "savepoint", but this is believed to be unused.
Jenalya wrote:
o11c wrote:newline between if (condition) and conditional_command; ?
Generally yes, but I think at the beginning of NPCs to determine to jump to which label depending on some variable, it's clearer without a newline.
That sounds like a good single exception: "newline between if (condition) and conditional_command, except when conditional_command is a goto at the beginning of a major script block (usually only at the beginning of a script), in which case if there are multiple if statements on adjacent lines, the gotos shall be aligned"
Jenalya wrote:
o11c wrote:capitalization of temporary variable names and labels?
Do you mean with capitalization This or THIS?
When I started scripting, I learned by reading existing scripts and adopted to name labels with something like "L_Labelname", what about making that a convention as well?
Yeah.
My tendency is to use lower_case_with_underscores for most variables, UpperCamelCase for special variables, lowerCamelCase for the not-quite-special variables like bAgi, CAPS_WITH_UNDERSCORES for global constants, CAPS_followed_by_lowercase (or CAPS_FollowedByCamelCase?) for local constants.
Labels should always start with L_, except those that act as a subfunction, which should start with S_. There must not be a fallthrough or goto to a subfunction label.
Current practice for labels is L_CamelCase: for labels and I don't think that is worth changing, although I personally would prefer L_lower_case:, especially for things like L_close:
Labels shall be outdented. Which, since the main script body only has one level of indentation, means it starts in column 0.
The one ambiguous case with lower_case_with_underscores is if there is a number as part of the variable name: my_option1 or my_option_2. When there are already underscores in the name 2 looks less unbalanced but without existing underscores I instinctively choose 1. Note that db/const.txt has e.g. NIBBLE_0_MASK and the scripts have quite a bit of both (sometimes on the same line: in npc/010-2/loratay.txt:46: @agostine_msg0$, L_agostine_0)
Also, what should labels within a subfunction label use? I was thinking LS_ or SL_; loratay currently uses L_SUB_ ... or perhaps this should be refactored out into a standalone function?
Jenalya wrote:
o11c wrote:Personally, I dislike code like:
(snip)
I experienced having hard coded numbers all over the code is bad...
Though using constants for values used only once in the script might be exaggerated, but I suggest to have constants at least for values that are used several times, e.g. the amount of an item needed to fullfill a quest.
Yeah, I know magic numbers are a Bad Thing, and I never thought my concerns were enough for an argument. At least you can stop and think "is this variable meaningful?"
But note also that this ties into the "set variables to 0 at end of script" - it might be better to put them in db/const.txt as MY_NPC__SOME_CONSTANT or MY_QUEST_SomeConstant
What about guidelines regarding saving playervariables with using bitmasking or setting used playervariables to zero and set a flag for it after a quest is finished?
I consider this a high level concern which is beyond the scope of my proposal. But, such high-level concerns (including bitmasking in general) could be added as a separate section in the "scripting standards" document.
Wombat wrote:I like tabs and how things have been with scripting. Why can't we use the standards we've used for years? I don't like changing how scripting is done.
Because we don't have a standard. Most, if not all of these items are inconsistent between files.
Also I found this ironic:
irc wrote:10:23:45 < Wombat> it doesn't have proper tabs since I did it on another computer
Tabs are intrinsically problematic and if I could remove the required ones, I would.
Wombat wrote:Also, a great many of your points aren't contrasted against others. If it is a change proposal, it helps to know what is changing.
There is not much of a "change" proposal here as much as "stop having 4 different indentation and variable naming style", some "add" and "remove" stuff, and my vaguely-planned ideas about commenting and documentation. Can you you be more specific?
Wombat wrote:They also assume the reader understands what you are saying.
This topic, to specify the standard, is intended for developers who know what they are doing, as they are the ones maintaining the code.
Wombat wrote:Many script writers for the game don't understand programming.
Jenalya wrote:Generally I like the idea to have some coding style conventions very much. But we should take care not to create a deterrent environment for new contributors with creating requirements only few people can meet.
Jenalya wrote:When I started scripting, I learned by reading existing scripts ...
For new/inexperienced script writers, I think this would improve the situation by
  1. Making all existing scripts consistent with each other (and with themselves!)
  2. Having an official "scripting standards" document (and/or "how to script")
argul wrote:
o11c wrote:
  • Set dynamic and local @variables to 0 before close;
(Would be good coding style indeed, but would need refactoring lots of already-there code.)
Can't the game engine handle this and prevent memleaks or staying variables?
@variables persist until the player logs out (or the server restarts).
Only a few quests actually use this feature (which would not be changed, as they would be documented as "temporary", not "dynamic" or "lexical"), most are only used within the function ("local"/"lexical") or to/from subfunctions ("dynamic") and waste (not leak) memory if they are not cleared.
(Keep in mind that there are also memory leaks in tmwA, such as about 1300 bytes every time a spell is cast (which is TMW code, not from eA :roll: ), if I understand it correctly; also some larger one-time leaks during initialization. Decreasing wastage means it will be longer until the leaks get bad enough to crash the server)
argul wrote:
o11c wrote:
  • Remove unnecessary next;
What is unnecessary?
I know there was a hunt for these earlier and my memory was from playing before that, but I can think of a couple of categories:
  1. next; before close;
  2. next; not after a mes; line (such as after a menu; see npc/xmax/2010/santa.txt and npc/032-1/miriam.txt; there might be more if there is a larger menu but these are the only ones within 2 lines, when grepping for a larger gap there are too many false positives)
  3. next; between lines that are not logically separated (I guess this one is a higher-level concern)
Former programmer for the TMWA server.
User avatar
o11c
Knight
Knight
Posts: 2262
Joined: 20 Feb 2011, 22:09
Location: ^ ^

Re: script cleanup/scripting standards proposal

Post by o11c » 05 Aug 2011, 00:25

I'm not really good about coming up with a strict format for documentation and commenting. But here's a shot.

all code blocks are intended to be run together, perhaps with blank lines; they are split only so I can comment about the commenting

Code: Select all

///myscript.txt: An NPC that frobs your itens
Begin with the filename and a one-line description. I'm not sure whether to break the lines or not, and I'm not sure if it should include @file, even if the following is accepted

Code: Select all

///Copyright 2011 The Mana World developers

///History:
///July 2011:
/// initial version by argul, most dialog
/// o11c tweaked the menu logic
///August 2011:
/// o11c reimplemented with new frobbing builtins, greatly simplifying the code
Copyright should include all the years that file changed (easily done with git log)
and be generically to "TMW Devs".

There should be some sort of history, oldest first. But, I'm not sure if this would be too much work, especially pulling old changes out of the git history. And I'm not entirely happy with it.
At the least, we can skim git history for missing authors.

I considered embedding doxygen format or something but decided against it; these comments should only be for people reading the (text) file.

Code: Select all

//!global constant MY_FROB_TIMEOUT - the minimum delay between frobbings
//!global permanent $my_frob_count - total number of frobbings
//!global temporary $@my_frob_timer - time at which another frob can happen
//!global temporary $@last_frob_user - id of the last player to have something frobbed
//!account permanent #OPTIONS bits 3 and 4 - whether the player knows about frobbing, and whether the player has been frobbed
//!dynamic array @items - passed to S_do_frob and really_do_frob - items which may be frobbed
These would be match by the regex "^//!"
I thought about requiring ": " after the type, but I figured it would be too easy to make mistakes
I thought about specifying a stricter format, but am concerned it would be error-prone or look unnatural. Instead, I'm thinking the only grep (with filename option) will be the only thing - although it should follow the general form
Actually, it might be a good idea to put the variable name before anything else.
Within each file of course the trailing bits should be aligned.
Or, it might look more natural to put the type on a separate line, but that would make ripping these bits out harder.
Perhaps: don't depend on the suffix$: strings must be explicitly documented (All variables are assumed to be integers)

I'm thinking also though that each dynamic or permanent variable specify where it comes from or goes to, e.g.
nibble 3 of FOO: set to 4 by someothernpc, then set to 5 and 6 by thisnpc...

The main purpose of documenting every variable is to make the conversion to my eventual new scripting language easier, so it may not be worth doing much at all.

I'm beginning to think that local variables only need not be documented, except in the L_close block(s) which every script shall have (even if there is nothing to reset, but not for NPCs with no menu;)

Code: Select all

///    This file is part of The Mana World.
///
///    The Mana World is free software: you can redistribute it and/or modify
///    it under the terms of the GNU General Public License as published by
///    the Free Software Foundation, either version 3 of the License, or
///    (at your option) any later version.
///
///    The Mana World is distributed in the hope that it will be useful,
///    but WITHOUT ANY WARRANTY; without even the implied warranty of
///    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
///    GNU General Public License for more details.
///
///    You should have received a copy of the GNU General Public License
///    along with The Mana World.  If not, see <http://www.gnu.org/licenses/>.
I know it is recommended, but do we really want this in every script file? It doesn't fit well with the above.
Also, we should consider changing to the AGPL. It is explicitly allowed to "link" separate files that are individually under GPLv3 and AGPLv3 (but, despite being nearly identical, not relicense, unless all copyright holders agree).
Since we don't know who the copyright holders are for all of tmwA, there's not much we can do about that (although I have created some new files and so could license them as AGPL - still, I don't know that it's worth it, as I'm not sure the server itself can satisfy the requirement to prominently offer the users its source).
But, it is quite feasible for an NPC or the motd.txt or news.txt to display something regarding the server-data. And since the scripts are dependent ("linked") on the builtins of the server, this guarantees freedom. The advantage of an NPC is that it could be an option "I want legal information" or "I want to see the scripts running on the server", or even just an NPC named "legal information", but this would not guarantee all players would see it. Of course, if the position of all players (including offline players, obviously) was reset ...
Former programmer for the TMWA server.
User avatar
Wombat
TMW Adviser
TMW Adviser
Posts: 1532
Joined: 08 Aug 2008, 17:31

Re: script cleanup/scripting standards proposal

Post by Wombat » 05 Aug 2011, 08:28

We have scripting standards, have for quite some time. Are they clearly defined? No. It would be nice to clearly define our standards. You presented this as a proposal, then say you aren't really proposing anything. Other than the tabs, which we will keep...what is changing in your proposal vs. a desire to offer a more consistent guideline for scripting standards?

Eathena Scripting Standards for TMW
Current character is "Abolish".
User avatar
Nard
Knight
Knight
Posts: 1113
Joined: 27 Jun 2010, 13:45
Location: France, near Paris

Re: script cleanup/scripting standards proposal

Post by Nard » 13 Nov 2012, 17:28

I'm not really good about coming up with a strict format for documentation and commenting.
It is the best and only way to ensure that the project can survive after you! :mrgreen:

I know this thread is quite old but, the wiki page was not updated since :(.
[url:http://wiki.themanaworld.org/index.php/ ... _Standards]eAthena Scripting Standards for TMW[/url]
And if Jenalya started today, she would still say:
When I started scripting, I learned by reading existing scripts ...
It seems to me that most o11c's proposals are agreed with some points still unclear :
  1. o11c's proposals are agreed and I transfer them on wiki page.
  2. Is o11c's proposition about constant and variables retained as a standard ? I mean :
    My tendency is to use lower_case_with_underscores for most variables, UpperCamelCase for special variables, lowerCamelCase for the not-quite-special variables like bAgi, CAPS_WITH_UNDERSCORES for global constants, CAPS_followed_by_lowercase (or CAPS_FollowedByCamelCase?) for local constants.
    Labels should always start with L_, except those that act as a subfunction, which should start with S_. There must not be a fallthrough or goto to a subfunction label.
    Current practice for labels is L_CamelCase: for labels and I don't think that is worth changing, although I personally would prefer L_lower_case:, especially for things like L_close:
    Labels shall be outdented. Which, since the main script body only has one level of indentation, means it starts in column 0.
    The one ambiguous case with lower_case_with_underscores is if there is a number as part of the variable name: my_option1 or my_option_2. When there are already underscores in the name 2 looks less unbalanced but without existing underscores I instinctively choose 1. Note that db/const.txt has e.g. NIBBLE_0_MASK and the scripts have quite a bit of both (sometimes on the same line: in npc/010-2/loratay.txt:46: @agostine_msg0$, L_agostine_0)
    Also, what should labels within a subfunction label use? I was thinking LS_ or SL_; loratay currently uses L_SUB_ ... or perhaps this should be refactored out into a standalone function?
    Code like:

    Code: Select all

    set @reward, 500;
    set @reward_amount, 3;
    [...]
    set Zeny, Zeny+@reward
    getitem "reward", @reward_amount
    is not only allowed but is the rule
  3. Comments and file description headers: I am not sure of what was decided. (especially I don't understand why the doxygen format is not a good one and if it is for the server code documentation?)
  4. I will post here when job is done go get your agreement and change the banners. (additionally I will rename the page "TMW-athena Scripting Standards"
I wait for Jenalya and o11c green traffic light. :)

[url:http://wiki.themanaworld.org/index.php/ ... _Standards]eAthena Scripting Standards for TMW[/url]
User avatar
o11c
Knight
Knight
Posts: 2262
Joined: 20 Feb 2011, 22:09
Location: ^ ^

Re: script cleanup/scripting standards proposal

Post by o11c » 13 Nov 2012, 20:28

It's better if the information is wikified sooner; it can be edited later.

For things like variable names, it should probably be commented as "in new code".

If there's any point of debate remaining, mention that on the wiki page with a pointer to the discussion and/or mark it as a "suggestion".
Nard wrote:(additionally I will rename the page "TMW-athena Scripting Standards"
Actually, that was a deliberate decision on my part, to avoid confusion with the next-generation scripting language.
Former programmer for the TMWA server.
User avatar
Jenalya
TMW Adviser
TMW Adviser
Posts: 718
Joined: 22 Sep 2010, 20:28

Re: script cleanup/scripting standards proposal

Post by Jenalya » 13 Nov 2012, 22:10

About how to name variables, labels and such, in the recent scripts I made I tended to use lower_case_with_underscores for usual variables, and L_CamelCase for scripts. I was just thinking about this for a while to find out why, and I think for the labels the underscore has the purpose to seperate the prefix which says what it is from the actual name. That's just my personal preference though.

I agree with o11c that it'd be good if the wikipage is updated as soon as possible - maybe you could add everything that's already clear, also still unclear things marked as suggestion or such, and then I look through the page and modify where I can clarify and post here for points which need further discussion?
User avatar
Nard
Knight
Knight
Posts: 1113
Joined: 27 Jun 2010, 13:45
Location: France, near Paris

Re: script cleanup/scripting standards proposal

Post by Nard » 14 Nov 2012, 08:48

o11c wrote:It's better if the information is wikified sooner;
Jenalya wrote:I agree with o11c that it'd be good if the wikipage is updated as soon as possible - maybe you could add everything that's already clear, also still unclear things marked as suggestion or such, and then I look through the page and modify where I can clarify and post here for points which need further discussion?
Set to Priority one

Variables, labels and functions: I'll try to make a simple consensual suggestion to be fixed later if necessary.


Additionnally:
  1. I created EAthena Scripting Basics after Fredzilla's "eAthena Script Command, A reference manual for the eAthena scripting language" at http://buwinow5.tripod.com/. (Please check to see if information is correct and up to date)
    But it appears to be to big for basics. Thus I need to split it and maybe make a 3 step approach: Basic script tutorial ( with examples), Reference "manual" and a "memo card" (?)
  2. Question: What is the standard for storing functions ? i.e. when I see : callfunc "NoobDevGetLost"; where can I find the function code ? Is there a list of actually available functions, their actions, their location?
  3. In order to avoid tricky issues such as the one which happened in Blue Sage, we have to keep a solid track from former information. At the moment I have no idea but a "scripting tips and tricks" page to gather it, along with updating the function reference page(s)
  4. Sample Code: In order to make script learning easier, it could be very useful to have wisely chosen scripts in various categories (Item, NPC, Map, fucntions...) in the wiki, stored, for example, in an Item, NPC, Map, function sub-page and heavily commented (they have to follow the standards; server and client data and may have to be updated according to them :/). Maybe Andra and Tulimshar's Desert storm would be such examples ?
"The language of everyday life is clogged with sentiment, and the science of human nature has not advanced so far that we can describe individual sentiment in a clear way." Lancelot Hogben, Mathematics for the Million.
“There are two motives for reading a book; one, that you enjoy it; the other, that you can boast about it.” Bertrand Russell, Conquest of Happiness.
"If you optimize everything, you will always be unhappy." Donald Knuth.
User avatar
Jenalya
TMW Adviser
TMW Adviser
Posts: 718
Joined: 22 Sep 2010, 20:28

Re: script cleanup/scripting standards proposal

Post by Jenalya » 14 Nov 2012, 09:38

Nard wrote:Question: What is the standard for storing functions ? i.e. when I see : callfunc "NoobDevGetLost"; where can I find the function code ? Is there a list of actually available functions, their actions, their location?
All the general functions are located in this folder: https://github.com/themanaworld/tmwa-se ... /functions. There might be some special purpose functions used only in some scripts (e.g. I for the upcoming Christmas event I'm using a function that is supposed to be only used by the event scripts) which are located in the context of those scripts.
Nard wrote:In order to avoid tricky issues such as the one which happened in Blue Sage, we have to keep a solid track from former information. At the moment I have no idea but a "scripting tips and tricks" page to gather it, along with updating the function reference page(s)
I think updating the reference page with the scripting commands is the most useful way for this.
User avatar
o11c
Knight
Knight
Posts: 2262
Joined: 20 Feb 2011, 22:09
Location: ^ ^

Re: script cleanup/scripting standards proposal

Post by o11c » 14 Nov 2012, 22:58

Yeah, it could be beneficial to add (or link) examples under the commands on this page:
http://wiki.themanaworld.org/index.php/ ... _Reference
(Don't edit the existing ones - they're signatures, not examples)

Though, a few larger examples would likely not "fit" in a single command. Wherever you introduce the larger syntax (how a warp or mob looks like; the meaning of all the pipe-and-comma separated values have and which ones are optional) might be a good place to do that. (like the current one on the "Standards" page is)


There are definitely some major inaccuracies in the Basics page.

I would start with a brief mention of how the NPC scripts are loaded from the conf, then mention the top-level constructs besides scripts (with appropriate warnings that they should usually be generated by the converter rather than by hand), then finally scripts.
Former programmer for the TMWA server.
User avatar
Nard
Knight
Knight
Posts: 1113
Joined: 27 Jun 2010, 13:45
Location: France, near Paris

Re: script cleanup/scripting standards proposal

Post by Nard » 14 Nov 2012, 23:12

Wiki page EAthena Scripting Standards has been heavily updated. Though still unfinished, it may begin to look to be usable
"The language of everyday life is clogged with sentiment, and the science of human nature has not advanced so far that we can describe individual sentiment in a clear way." Lancelot Hogben, Mathematics for the Million.
“There are two motives for reading a book; one, that you enjoy it; the other, that you can boast about it.” Bertrand Russell, Conquest of Happiness.
"If you optimize everything, you will always be unhappy." Donald Knuth.
Post Reply