From The Mana World
(tmwAthena Scripting Standards)
 
Line 1: Line 1:
This page defines the scripting and formatting standards to be used for scripts submitted to The Mana World project.
This page defines the scripting and formatting standards to be used for scripts submitted to The Mana World project.


== Formatting ==
== Formatting ==
*Code is to be indented using 4 spaces per indent.
*One NPC per file, except in cases of 'flavor' NPC's who only have one or two lines.
*When indenting is required, code is to be indented using 4 spaces per indent.
*Code in the same block should have the same indentation.
*Code in the same block should have the same indentation.
*Labels have no indentation.
*Menu options are on their own lines and are given an additional indentation.
*Menu options are on their own lines and are indented further.
*Multiple sentences should carry a single space between the period at the end of the first sentence and the first letter of the next sentence.
*Multiple sentences should carry a single space between the period at the end of the first sentence and the first letter of the next sentence.
*Any dialog by an NPC should be put in double quotes (").
*Any dialog by an NPC should be put in double quotes (").
*There should be no trailing whitespaces.
*There should be no trailing whitespaces.
*Separation of script header elements is to be done with a pipe (|).
*Documentation within a script should be commented out using // as a prefix.
*Documentation within a script should be commented out using // as a prefix.
*When checking for, creating, or deleting an item, the item name should be used instead of the item id.


== Code and Variables ==
== Code and Variables ==
* Code blocks should be separated from the others in a distinct way; the best way of doing it is to insert a blank line between code blocks.  
*Permanent player/account variables should be documented at the beginning of the file.
*Dynamic and local @variables should be set to 0 before calling close;
*Separation of script header elements is to be done with a pipe |.
*When checking for, creating, or deleting an item, the item name should be used instead of the item id.
*There should be a newline before every label.
*There should not be a newline after the label.
*When writing conditional statements, a newline should be used between ''if (condition)'' and ''conditional_command;''.
**Exception to this rule is when the conditional_command is a goto at the beginning of a major script block.


* Individual blocks should be together (i.e. without blank lines within them).
* The opening brackets should be at the end of the parent line, not in a new line; the closing ones should be in a line of their own.


== Example ==
== Example ==
An example is given by a quest to get a key for a chest:
An example which shows correct NPC definition, indentation, label definition, and commenting:


{| border=0
{| border=0
Line 38: Line 38:


L_Sure:
L_Sure:
     if (countitem("treasurekey") < 3) goto L_WrongKey;
     if (countitem("treasurekey") < 3)
        goto L_WrongKey;
     delitem "treasurekey", 3;
     delitem "treasurekey", 3;
     getitem "shortsword", 1;
     getitem "shortsword", 1;
Line 51: Line 52:
|}
|}


The above script starts with describing the NPC (the chest, NPC sprite 111) and its location. Then follows what happens on activation. A message is shown, then an option dialog is displayed. Then, when the player has less than 3 keys, he is told not to have the right key. If he does, the player looses three keys and receives a short sword.
For more complex examples of the current system, check out the current scripts in use by the server. Beware though, this could affect your enjoyment of the game as it does spoil some of the mystery. Here's a link to the GitHub repository so you can view them in your browser:
 
For more examples of the current system, check out the current scripts in use by the server. Beware though, this could affect your enjoyment of the game as it does spoil some of the mystery. Here's a link to git so you can view them in your browser:


https://github.com/themanaworld/tmwa-server-data/tree/master/world/map/npc
https://github.com/themanaworld/tmwa-server-data/tree/master/world/map/npc
==Using as little variables as you need==
So there are some quests, which require lots of variables.
Think of monster oil quest, Oric and Warum quest etc.
This can often be done by bitmasking:
One variable has 32 bits. So a variable can store 2^32 different numbers: 4294967296
But sometimes you only need numbers from 0 to 15, but more of these variables.
but numbers in range 0 to 15 can be stored in 4 bits ( 2^4 = 16 different numbers)
Here is an example how to use bitmasking:
[[Media:Tester.txt]]
== Defining Map Objects ==
{|border="0" cellspacing="0" cellpadding="2" style="float: right;"
!colspan="2"| Key
|-
| <TAB>
| a tab
|-
| text
| text that must be the same
|-
| ''text''
| text to be changed
|}
These sections describe how to define map objects.
=== Warp Definitions ===
Warps are what move players between maps. They can also be used to move players around a single map, if needed. Warps are defined like this:
''map1'',''startX'',''startY''<TAB>warp<TAB>''name''<TAB>''width'',''height'',''map2'',''endX'',''endY''
Key:
;map1
:the starting map
;startX
:the x-coordinate of the starting warp tile
;startY
:the y-coordinate of the starting warp tile
;name
:the name of the warp, unused but must be defined
;width
:the width of the warp
;height
:the height of the warp
;map2
:the ending map
;endX
:the x-coordinate of the tile the player will end up on
;endY
:the y-coordinate of the tile the player will end up on
Width and height are described in detail here: [[EAthena Scripting Standards/Warp Details|Warp Details]].
=== Monster Definitions ===
Monsters are defined like this:
''map'',''x'',''y'',''width'',''height''<TAB>monster<TAB>''name''<TAB>''mobID'',''count'',''spawn1'',''spawn2'',''event''
;map
:the map the monsters should appear on
;x
:the x-coordinate of the spawn tile
;y
:the y-coordinate of the spawn tile
;width
:the tile width of the spawn area
;height
:the tile height of the spawn area
;name
:the name of the mob, unused but must be defined
;mobID
:the mob identifier of the desired monster (in the monster db)
;count
:the number to spawn
;spawn1
:the minimum delay between successive spawns (per individual)
;spawn2
:the minimum delay between death and respawn (per individual)
;event
:the script event to fire upon death
A detailed description of position and area can be found here: [[EAthena Scripting Standards/Mob Details|Mob Details]].
=== NPC Definitions ===
== Script Functions ==
See [[EAthena Scripting Reference]]

Revision as of 21:21, 9 June 2012

This page defines the scripting and formatting standards to be used for scripts submitted to The Mana World project.

Formatting

  • One NPC per file, except in cases of 'flavor' NPC's who only have one or two lines.
  • When indenting is required, code is to be indented using 4 spaces per indent.
  • Code in the same block should have the same indentation.
  • Menu options are on their own lines and are given an additional indentation.
  • Multiple sentences should carry a single space between the period at the end of the first sentence and the first letter of the next sentence.
  • Any dialog by an NPC should be put in double quotes (").
  • There should be no trailing whitespaces.
  • Documentation within a script should be commented out using // as a prefix.

Code and Variables

  • Permanent player/account variables should be documented at the beginning of the file.
  • Dynamic and local @variables should be set to 0 before calling close;
  • Separation of script header elements is to be done with a pipe |.
  • When checking for, creating, or deleting an item, the item name should be used instead of the item id.
  • There should be a newline before every label.
  • There should not be a newline after the label.
  • When writing conditional statements, a newline should be used between if (condition) and conditional_command;.
    • Exception to this rule is when the conditional_command is a goto at the beginning of a major script block.


Example

An example which shows correct NPC definition, indentation, label definition, and commenting: 

// A treasure chest. You need three keys to open it.

001-1.gat,93,37,0|script|Treasure|111,{
    mes "Would you try to open it?";
    next;
    menu
        "Yup", L_Sure,
        "Nope", close;

L_Sure:
    if (countitem("treasurekey") < 3)
        goto L_WrongKey;
    delitem "treasurekey", 3;
    getitem "shortsword", 1;
    mes "You opened it and found a short sword!";
    close;

L_WrongKey:
    mes "It seems that this is not the right key...";
    close;
}

For more complex examples of the current system, check out the current scripts in use by the server. Beware though, this could affect your enjoyment of the game as it does spoil some of the mystery. Here's a link to the GitHub repository so you can view them in your browser:

https://github.com/themanaworld/tmwa-server-data/tree/master/world/map/npc

Retrieved from "https://wiki.themanaworld.org/index.php?title=Archive:TmwAthena_Scripting_Standards&oldid=23853"