Hercules Wiki - User contributions [en]

Readparam

2013-06-28T10:05:51Z

Neqste: Created page with "==Syntax== *'''readparam'''(<parameter number>); ==Description== This function will return the basic stats of an invoking character, referred to by the parameter number. Ins..."

==Syntax==
*'''readparam'''(<parameter number>);

==Description==
This function will return the basic stats of an invoking character,
referred to by the parameter number. Instead of a number, you can use a
parameter name if it is defined in '[https://github.com/HerculesWS/Hercules/blob/master/db/const.txt db/const.txt]'.

Example parameters:

StatusPoint, BaseLevel, SkillPoint, Class, Upper, Zeny, Sex, Weight,
MaxWeight, JobLevel, BaseExp, JobExp, NextBaseExp, NextJobExp, Hp, MaxHp,
Sp, MaxSp, BaseJob, Karma, Manner, bVit, bDex, bAgi, bStr, bInt, bLuk

All of these also behave as variables, but don't expect to be able to just
'set' them - some will not work for various internal reasons.

==Example==
===Example 1:===

// Returns how many status points you haven't spent yet.
mes "Unused status points: "+readparam(9);

Using this particular information as a function call is not required.
Typing this will return the same result:

mes "Unused status points: "+StatusPoint;

===Example 2:===

You can also use this command to get stat values.

if (readparam(bVit) > 77)
mes "Only people with over 77 Vit are reading this!";

==See Also==
* '[https://github.com/HerculesWS/Hercules/blob/master/db/const.txt db/const.txt]'

[[Category:Script Command]]

Freeloop

2013-06-28T09:58:33Z

Neqste: Created page with "==Syntax== *'''freeloop'''(<toggle>); ==Description== Toggling this to enabled (1) allows the script instance to bypass the infinite loop protection, allowing your script to..."

==Syntax==
*'''freeloop'''(<toggle>);

==Description==
Toggling this to enabled (1) allows the script instance to bypass the
infinite loop protection, allowing your script to loop as much as it may
need. Disabling (0) will warn you if an infinite loop is detected.

==Example==
freeloop(1); // enable script to loop freely

//Be aware with what you do here.
for ( set .@i,0; .@i<.@bigloop; set .@i, .@i+1 ) {
dothis;
// will sleep the script for 1ms when detect an infinity loop to
// let Hercules do what it need to do (socket, timer, process,
// etc.)
}

freeloop(0); // disable

for ( set .@i,0; .@i<.@bigloop; set .@i, .@i+1 ) {
dothis;
// throw an infinity loop error
}

==See Also==
* [[while]]
* [[for]]

[[Category:Script Command]]

Getcastledata

2013-06-28T08:11:38Z

Neqste: Created page with "==Syntax== *'''getcastledata'''("<map name>",<type of data>); *'''setcastledata''' "<map name>",<type of data>,<value>; ==Description== This function returns the castle owne..."

==Syntax==
*'''getcastledata'''("<map name>",<type of data>);
*'''setcastledata''' "<map name>",<type of data>,<value>;

==Description==
This function returns the castle ownership information for the castle
referred to by its map name. Castle information is stored in
`guild_castle` SQL table.

Types of data correspond to `guild_castle` table columns:
1 - `guild_id` - Guild ID.
2 - `economy` - Castle Economy score.
3 - `defense` - Castle Defense score.
4 - `triggerE` - Number of times the economy was invested in today.
5 - `triggerD` - Number of times the defense was invested in today.
6 - `nextTime` - unused
7 - `payTime` - unused
8 - `createTime` - unused
9 - `visibleC` - Is 1 if a Kafra was hired for this castle, 0 otherwise.
10 - `visibleG0` - Is 1 if the 1st guardian is present (Soldier Guardian)
11 - `visibleG1` - Is 1 if the 2nd guardian is present (Soldier Guardian)
12 - `visibleG2` - Is 1 if the 3rd guardian is present (Soldier Guardian)
13 - `visibleG3` - Is 1 if the 4th guardian is present (Archer Guardian)
14 - `visibleG4` - Is 1 if the 5th guardian is present (Archer Guardian)
15 - `visibleG5` - Is 1 if the 6th guardian is present (Knight Guardian)
16 - `visibleG6` - Is 1 if the 7th guardian is present (Knight Guardian)
17 - `visibleG7` - Is 1 if the 8th guardian is present (Knight Guardian)

All types of data have their meaning determined by War of Emperium
scripts, with exception of:
- `guild_id` that is always the ID of the guild that owns the castle,
- `defense` that is used in Guardians & Emperium HP calculations,
- `visibleG` that is always considered to hold guardian presence bits.

The '''setcastledata''' command will behave identically, but instead of
returning values for the specified types of accessible data, it will alter
them and cause them to be sent to the char-server for storage.

Changing Guild ID or Castle Defense will trigger additional actions, like
recalculating guardians' HP.

[[Category:Script Command]]

Getguildmasterid

2013-06-28T08:08:56Z

Neqste: Created page with "==Syntax== *'''getguildmasterid'''(<guild id>); ==Description== This function will return the character ID number of the guild master of the guild specified by the ID. 0 if ..."

==Syntax==
*'''getguildmasterid'''(<guild id>);

==Description==
This function will return the character ID number of the guild master of
the guild specified by the ID. 0 if the character is not a guild master of
any guild.

==Examples==
prontera,155,180,5 script guildmasterID 89,{
if (getcharid(2)!=0) {
mes getguildmasterid(getcharid(2))+" it's your guildmaster id";
close;
}
}

==See Also==
* [[getguildmaster]]

[[Category:Script Command]]

Getguildmaster

2013-06-28T08:04:42Z

Neqste: Created page with "==Syntax== *'''getguildmaster'''(<guild id>); ==Description== This function return the name of the master of the guild which has the specified ID number. If there is no such..."

==Syntax==
*'''getguildmaster'''(<guild id>);

==Description==
This function return the name of the master of the guild which has the
specified ID number. If there is no such guild, "null" will be returned.

// Would return the guild master of guild 10007, whatever that might be.
mes getguildmaster(10007)+" runs "+getguildname(10007);

Can be used to check if the character is the guild master of the specified
guild.

==Example==
Maybe you want to make a room only guild masters can enter:

set @GID,getcharid(2);
if(@GID==0) goto L_NoGuild;
if(strcharinfo(0)==getguildmaster(@GID)) goto L_GuildMaster;
mes "Sorry you don't own the guild you are in";
close;
L_NoGuild:
mes "Sorry you are not in a guild";
close;
L_GuildMaster:
mes "Welcome guild master of "+GetGuildName(@GID);
close;

==See Also==
* [[getguildmasterid]]

[[Category:Script Command]]

Viewpoint

2013-06-24T10:35:50Z

Neqste: Created page with "==Syntax== *'''viewpoint''' <action>,<x>,<y>,<point number>,<color>; ==Description== This command will mark places on the mini map in the client connected to the invoking ch..."

==Syntax==
*'''viewpoint''' <action>,<x>,<y>,<point number>,<color>;

==Description==
This command will mark places on the mini map in the client connected to
the invoking character. It uses the normal X and Y coordinates from the
main map. The colors of the marks are defined using a hexadecimal number,
same as the ones used to color text in 'mes' output, but are written as
hexadecimal numbers in C. (They look like 0x<six numbers>.)

Action is what you want to do with a point, 1 will set it, while 2 will
clear it. 0 will also set it, but automatically removes the point after 15
seconds.
Point number is the number of the point - you can have several. If more
than one point is drawn at the same coordinates, they will cycle, which
can be used to create flashing marks.

==Examples==
This command will show a mark at coordinates X 30 Y 40, is mark
number 1, and will be red.
viewpoint 1,30,40,1,0xFF0000;

This will create three points:

viewpoint 1,30,40,1,0xFF0000;
viewpoint 1,35,45,2,0xFF0000;
viewpoint 1,40,50,3,0xFF0000;

And this is how you remove them:

viewpoint 2,30,40,1,0xFF0000;
viewpoint 2,35,45,2,0xFF0000;
viewpoint 2,40,50,3,0xFF0000;

[[Category:Script Command]]

Setitemscript

2013-06-24T10:31:54Z

Neqste: Created page with "==Syntax== *'''setitemscript'''(<item id>,<"{ new item script }">{,<type>}); ==Description== Set a new script bonus to the Item. Very useful for game events. You can remove a..."

==Syntax==
*'''setitemscript'''(<item id>,<"{ new item script }">{,<type>});

==Description==
Set a new script bonus to the Item. Very useful for game events.
You can remove an item's itemscript by leaving the itemscript argument
empty. Returns 1 on success, or 0 on fail (item_id not found or new item
script is invalid).

Type can optionally be used indicates which script to set (default is 0):
0 - Script
1 - OnEquip_Script
2 - OnUnequip_Script

==Examples==
[[setitemscript]] 2637,"{ if(isequipped(2236)==0)end; if(getskilllv(26)){skill 40,1;}else{skill 26,1+isequipped(2636);} }"; // new bonus
[[setitemscript]] 2637,""; // now without bonus.

==See Also==
* [[setiteminfo]]

[[Category:Script Command]]

Setiteminfo

2013-06-24T10:28:48Z

Neqste: Created page with "==Syntax== *'''setiteminfo'''(<item id>,<type>,<value>); ==Description== This function will set some value of an item. Returns the new value on success, or -1 on fail (item_i..."

==Syntax==
*'''setiteminfo'''(<item id>,<type>,<value>);

==Description==
This function will set some value of an item.
Returns the new value on success, or -1 on fail (item_id not found or
invalid type).

'''Valid types are:'''
0 - Buy Price;
1 - Sell Price;
2 - Item Type;
3 - maxchance (Max drop chance of this item e.g. 1 = 0.01% , etc..
if = 0, then monsters don't drop it at all (rare or a quest item)
if = 10000, then this item is sold in NPC shops only
4 - sex;
5 - equip;
6 - weight;
7 - atk;
8 - def;
9 - range;
10 - slot;
11 - look;
12 - elv;
13 - wlv;
14 - view id

==Examples==
[[setiteminfo]] 7049,6,9990; // Stone now weighs 999.0
[[setiteminfo]] 512,0,3000; // Apple Buy Price is 3000

==See Also==
* [[setitemscript]]

[[Category:Script Command]]

Escape sql

2013-06-24T10:23:47Z

Neqste: Created page with "==Syntax== *'''escape_sql'''(<value>); ==Description== Converts the value to a string and escapes special characters so that it's safe to use in query_sql(). Returns the esc..."

==Syntax==
*'''escape_sql'''(<value>);

==Description==
Converts the value to a string and escapes special characters so that it's
safe to use in query_sql(). Returns the escaped form of the given value.

==Examples==
[[set]] .@str$, "John's Laptop";
[[set]] .@esc_str$, [[escape_sql]](.@name$); // Escaped string: John\'s Laptop

==See Also==
* [[query_sql]]

[[Category:Script Command]]

Query sql

2013-06-24T10:21:54Z

Neqste: Created page with "==Syntax== *'''query_sql'''("your MySQL query"{, <array variable>{, <array variable>{, ...}}}); *'''query_logsql'''("your MySQL query"{, <array variable>{, <array variable>{, ..."

==Syntax==
*'''query_sql'''("your MySQL query"{, <array variable>{, <array variable>{, ...}}});
*'''query_logsql'''("your MySQL query"{, <array variable>{, <array variable>{, ...}}});

==Description==
Executes an SQL query. A 'select' query can fill array variables with up
to 128 rows of values, and will return the number of rows (the array size).

Note that 'query_sql' runs on the main database while 'query_logsql' runs
on the log database.

==Examples==
[[set]] @nb, [[query_sql]]("select name,fame from `char` ORDER BY fame DESC LIMIT 5", @name$, @fame);
[[mes]] "Hall Of Fame: TOP5";
[[mes]] "1."+@name$[0]+"("+@fame[0]+")"; // Will return a person with the biggest fame value.
[[mes]] "2."+@name$[1]+"("+@fame[1]+")";
[[mes]] "3."+@name$[2]+"("+@fame[2]+")";
[[mes]] "4."+@name$[3]+"("+@fame[3]+")";
[[mes]] "5."+@name$[4]+"("+@fame[4]+")";

==See Also==
* http://dev.mysql.com/doc/refman/5.6/en/
* [[escape_sql]];

[[Category:Script Command]]

Getusers

2013-06-24T09:08:20Z

Neqste: /* Syntax */

=Syntax=
*[[getusers]](<type>)

=Description=
This function will return a number of users on a map or the whole server. What
it returns is specified by Type.

Type can be one of the following values, which control what will be returned:

0 - Count of all characters on the map of the invoking character.
1 - Count of all characters in the entire server.
8 - Count of all characters on the map of the NPC the script is
running in.
=Example=

[[mes]] getusers(1)+" players on the server";
[[close]];

=See Also=
*[[getmapusers]];
*[[getareausers]];

Getusers

2013-06-24T09:08:08Z

Neqste: /* See Also */

=Syntax=
:[[getusers]](<type>)
=Description=
This function will return a number of users on a map or the whole server. What
it returns is specified by Type.

Type can be one of the following values, which control what will be returned:

0 - Count of all characters on the map of the invoking character.
1 - Count of all characters in the entire server.
8 - Count of all characters on the map of the NPC the script is
running in.
=Example=

[[mes]] getusers(1)+" players on the server";
[[close]];

=See Also=
*[[getmapusers]];
*[[getareausers]];

Getguildname

2013-06-24T09:07:20Z

Neqste: Created page with "==Syntax== *getguildname(<guild id>) ==Description== This function returns a guild's name given an ID number. If there is no such guild, "null" will be returned; This is us..."

==Syntax==
*getguildname(<guild id>)

==Description==
This function returns a guild's name given an ID number. If there is no such
guild, "null" will be returned;

This is used all over the WoE controlling scripts. You could also use it for a
guild-based event.

==Example==
// Would print what ever guild 10007 is, in my case this would return "AlcoROhics"
mes "The guild "+GetGuildName(10007)+" are all nice people.";

// This will do the same as above:
set @var,10007;
mes "We have some friends in "+GetGuildName(@var)+", you know.";

==See Also==
*[[getguildmaster]]
[[Category:Script Command]]

Getareausers

2013-06-24T09:04:17Z

Neqste:

== Syntax ==
* getareausers("<map name>",<x1>,<y1>,<x2>,<y2>)

== Description ==
This function will return the count of connected characters which are located
within the specified area - an x1/y1-x2/y2 square on the specified map.

This is useful for maps that are split into many buildings, such as all the
"*_in" maps, due to all the shops and houses.

==See Also==
*[[getmapusers;]]
*[[getareausers;]]
[[Category:Script Command]]

Getusers

2013-06-24T09:01:29Z

Neqste: Created page with "=Syntax= :getusers(<type>) =Description= This function will return a number of users on a map or the whole server. What it returns is specified by Type. Type can be one ..."

Getmapusers

2013-06-24T08:55:58Z

Neqste: Created page with "=Syntax= getmapusers ("<map name>") =Description= Returns the amount of persons from the given guild that are on the given map. =Example= <pre> //Will set the @persons va..."

=Syntax=
[[getmapusers]] ("<map name>")
=Description=
Returns the amount of persons from the given guild that are on the given map.
=Example=
<pre>
//Will set the @persons variable to the amount of persons from the guild
//which ID's = 10 and are at prontera.
set @persons,getMapGuildUsers("prontera",10);
</pre>

Category:Installation

2013-06-23T19:16:32Z

Neqste:

This category is used as a place for all pages covering installation of Hercules or its dependancies to be found. If you want to include a page here, and it covers installation of rAthena in any way, shape or form, or one of it's major dependancies, such as SQL or possibly SVN, tag it with the following:

<pre>[[Category:Installation]]</pre>

Please do not create duplicate articles. Thank you.

Setarray

2013-06-23T19:09:10Z

Neqste:

[[Category:Script_Command]]
==Syntax==
* [[setarray]] <array name>[<first value>],<value>{,<value>...<value>};
==Description==
This command will allow you to quickly fill up an array in one go. Check the
Kafra scripts in the distribution to see this used a lot.

First value is the index of the first element of the array to alter.
==Examples==
<pre>
[[setarray]] .@array[0],200,200,200;
[[setarray]] .@array[1],300,150;
// will produce:
// .@array[0]=200
// .@array[1]=300
// .@array[2]=150
</pre>

==String Array==
[[setarray]] @array$[0],"word1","word2","word3","word4";
// will produce:
// @array$[0] = word1
// @array$[1] = word2
// @array$[2] = word3
// @array$[3] = word4

// Example
[[setarray]] .@maps$[0],"guild_vs1","guild_vs2";
[[if]](class < 10) {[[warp]] .@maps$[1],0,0; }
[[if]](class > 10) {[[warp]] .@maps$[2],0,0; }

Switch

2013-06-23T19:02:58Z

Neqste:

== Syntax ==
* [[switch]](<expression>);
== Description ==
The switch statement is similar to a series of [[if]] statements on the same expression. In many occasions, you may want to compare the same variable (or expression) with many different values, and execute a different piece of code depending on which value it equals to. This is exactly what the [[switch]] statement is for.

It is important to understand how the [[switch]] statement is executed in order to avoid mistakes. The [[switch]] statement executes line by line (actually, statement by statement). In the beginning, no code is executed. Only when a [[case]] statement is found with a value that matches the value of the switch expression the [[case]] statement(s) will to executed. The parser continues to execute the statements until the end of the [[switch]] block, or the first time it sees a [[break]] statement. If you don't write a [[break]] statement at the end of a [[case]]'s statement list, the parser will go on executing the statements of the following [[case]] (fall-through).

== Example ==
// Returns the number of refines on your top headgear
[[set]](.@refCount, [[getequiprefinerycnt]](EQI_HEAD_TOP));
// Output a message
[[switch]](.@refCount) {
// 0 means no refine yet
[[case]] 0:
[[mes]]("No refine on your top headgear yet?");
[[mes]]("You need to go to the refiner!");
[[break]];

// +1
[[case]] 1:
[[mes]]("Your top headgear is +1!");
[[break]];
// +2
[[case]] 2:
[[mes]]("Your top headgear is +2!");
[[break]];

// +3
[[case]] 3:
[[mes]]("Your top headgear is +3!");
[[break]];

// +4
[[case]] 4:
[[mes]]("Your top headgear is +4!");
// NOTE: no break here means the code from "case 5" will be executed afterwards!

// +5
[[case]] 5:
[[mes]]("Your top headgear is +5!");
[[break]];

// [...]

// This case will be triggered if no other case was triggered yet
[[default]]:
[[mes]]("Your top headgear has upgrades above +5!");
[[break]];
}

== Next Example ==
[[switch]]([[rand]](1,3)) {
[[case]] 1:
[[mes]] "Randomly Selected Number is 1";
[[break]];
[[case]] 2:
[[mes]] "Randomly Selected Number is 2";
[[break]];
[[case]] 3:
[[mes]] "Randomly Selected Number is 3";
[[break]];
}

== Next Example ==
[[switch]]([[select]]("Menu 1:Menu 2:Menu 3")) {
case 1:
[[mes]] "Menu 1 message";
[[close]];
[[break]];
case 2:
[[mes]] "Menu 2 message";
[[close]];
[[break]];
case 3:
[[mes]] "Menu 3 message";
[[close]];
[[break]];
}

[[Category:Script Command]]

Getcharid

2013-06-23T18:58:41Z

Neqste: /* Examples */

[[Category:Script_Command]]
==Syntax==
* [[getcharid]](<type>{,"<character name>"});
==Description==
This function will return a unique ID number of the invoking character, or, if a
character name is specified, of that character.

For most purposes other than printing it, a number is better to have than a name
(people do horrifying things to their character names).

If the character is not in a party or not in a guild, the function will return 0
if guild or party number is requested. If a name is specified and the character
is not found, 0 is returned.

If [[getcharid]](0) returns a zero, the script got called not by a character and
doesn't have an attached [[RID]]. Note that this will cause the map server to
print "player not attached!" error messages, so it is preferred to use
'[[playerattached]]' to check for the character attached to the script.

==Type Values==
{| class="wikitable" border="1"
!Value
!Description
|-
|0||Character ID number.
|-
|1||Party ID number.
|-
|2||Guild ID number.
|-
|3||Account ID number.
|-
|4||Battleground ID number.
|}

==Examples==
[[if]]( '''getcharid'''(2) == 0 ) [[mes]] "Only members of a guild are allowed here!";

// This code will get charid from not attached player, if he is online (useful in dialogues)
input .@charname$;
if (getcharid(.@charname$,0)>0) { do something } // if player online