Timers (Scripting) - Revision history

Kayli at 23:11, 28 December 2015

2015-12-28T23:11:21Z

Annieruru: fix the link so it will show the correct line forever even if some dev update it, thx to angelmelody

2015-12-10T19:37:35Z

fix the link so it will show the correct line forever even if some dev update it, thx to angelmelody

Annieruru: read 'npc_timerevent_export' in src/map/npc.c, the 't' is INT, so it can be as big as int goes

2015-12-05T23:34:16Z

read 'npc_timerevent_export' in src/map/npc.c, the 't' is INT, so it can be as big as int goes

Annieruru: I dislike the method that set the value into the future, better stick to this one. Previous method will bug if that number turn into a configurable variable, and that variable is decrease

2015-12-05T23:27:00Z

I dislike the method that set the value into the future, better stick to this one. Previous method will bug if that number turn into a configurable variable, and that variable is decrease

Annieruru: oops ... the @boom variable has to set only when addtimer together ... otherwise if the player dead/warp during the close button, the variable been set without addtimer triggered

2015-12-05T22:43:53Z

oops ... the @boom variable has to set only when addtimer together ... otherwise if the player dead/warp during the close button, the variable been set without addtimer triggered

Annieruru at 21:11, 5 December 2015

2015-12-05T21:11:23Z

Annieruru: nothing much to say about this part

2015-12-05T21:07:45Z

nothing much to say about this part

Annieruru: how do the OnCharIfInit come out in the 1st place ? o.o

2015-12-05T20:46:41Z

how do the OnCharIfInit come out in the 1st place ? o.o

Annieruru: fix some typo

2015-12-05T20:39:07Z

fix some typo

Annieruru: getnpctimer(0) can't use with attachnpctimer yet ... as of now, better tell this properly first

2015-12-05T17:32:42Z

getnpctimer(0) can't use with attachnpctimer yet ... as of now, better tell this properly first

@@ Line 168: / Line 168: @@
       [[end]];
+  }
-''someone please help explain properly about this script''
+In the code above, we have manipulated the behavior of the NPC to have two separate live states. The first state is before anyone has clicked the NPC, after which the player variable(@ prefix) boom is set to a value of 1 immediately following the [[close2]] command by sending "[[set]] @boom, 1". Then upon clicking the NPC during the timer sessions the NPC will have a regular [[close]] command after displaying the message to the player due to the if( @boom == 1 ) check; instead of creating more timers. Once the second timer finishes we also see the player variable boom set back to 0 with "[[set]] @boom,0;", it's off state.
-{{Incomplete|type=section}}
 <br><br>
 Now, on to the bomb npc.

@@ Line 408: / Line 408: @@
   getnpctimer 2,"My Other NPC"; // Same as above, but for the NPC named "My Other NPC".
-'''Note:''' Currently there is no way to retrieve the value of getnpctimer(0) with attachnpctimer;. It's still mark as a [https://github.com/HerculesWS/Hercules/blob/master/src/map/npc.c#L771 TODO] in the source code ;-)
+'''Note:''' Currently there is no way to retrieve the value of getnpctimer(0) with attachnpctimer;. It's still mark as a [https://github.com/HerculesWS/Hercules/blob/e711753b9d584845e385ada29780b9ed216c4f55/src/map/npc.c#L771 TODO] in the source code ;-)
 == SetNPCTimer ==

@@ Line 352: / Line 352: @@
 Now, on each tick (tick means every increment of this variable), the timer will check if inside the NPC it is running from or attached to, if there is a label that matches his current value. The labels have a special format, and look like this:
   OnTimerXXXXX:
-Where XXXXX is a number that can be as small as 0, or as big as 7200000 (3 hours). If the value of the timer matches one of those labels, then the NPC will start running at that specific label. So, let's say you have a label OnTimer1000: (1 second), and you have started a NPC timer, then one second later, the script will jump to that label, and start executing the code underneath it.<br>
+Where XXXXX is a number that can be as small as 0, or as big as 2,147,483,647 (roughly 24 days). If the value of the timer matches one of those labels, then the NPC will start running at that specific label. So, let's say you have a label OnTimer1000: (1 second), and you have started a NPC timer, then one second later, the script will jump to that label, and start executing the code underneath it.<br>
 Often, when using NPC Timers, you want to stop them at some point, or reset them, to make the NPC start over again. For this purpose, the [[Developers|developers]] have written several commands that are now at our disposal, which allow us to manipulate this NPC based timer.<br>
 A last thing you need to know, before we go into detail on the specific commands, is that by default a NPC Timer will run in the same NPC as where the command is found, and that there is no player attached. The last part means, that you will be unable by default to manipulate the player, variable wise or command wise.<br>

@@ Line 189: / Line 189: @@
 = Use Number 3: Deny Usage =
 Let's start with another example:
-  prontera,23,20,2<TAB>script<TAB>Daily Healer<TAB>1_M_JOBGUIDER,{
+  prontera,23,20,2	script	Daily Healer	1_M_JOBGUIDER,{
-      mes "[Healer]";
+      [[mes]] "[Healer]";
-      mes "Hello there.";
+      [[mes]] "Hello there.";
-      mes "I am a special healer, who will fully restore your HP and SP.";
+      [[mes]] "I am a special healer, who will fully restore your HP and SP.";
-      mes "However, my powers are limited, and I need to rest for a full day after healing you, before I can help you again.";
+      [[mes]] "However, my powers are limited, and I need to rest for a full day after healing you, before I can help you again.";
-     next;
-     mes "[Healer]";
-     mes "Do you want me to heal you?";
       [[next]];
-      [[if]]([[select]]("Yes","No") == 2) {
+     [[mes]] "[Healer]";
-           mes "[Healer]";
+     [[mes]] "Do you want me to heal you?";
-           mes "Ok, good bye then.";
+     [[next]];
-           close;
+      [[if]] ([[select]]("Yes","No") == 2) {
+      }
-      if(TimeHealed > gettimetick(2)) {
+      [[if]] (TimeHealed + 86400 > [[gettimetick]](2)) { // 86400 is one day in seconds.
-           mes "[Healer]";
+           [[mes]] "[Healer]";
-           mes "I am sorry, but I am not a robot.";
+           [[mes]] "I am sorry, but I am not a robot.";
-           mes "I am still exhausted from the last time I healed you.";
+           [[mes]] "I am still exhausted from the last time I healed you.";
-           close;
+           [[close]];
+      }
-      mes "[Healer]";
+      [[mes]] "[Healer]";
-      mes "Ok, here goes!";
+      [[mes]] "Ok, here goes!";
-      close2;
+      [[close2]];
       [[percentheal]] 100,100;
-      set TimeHealed, gettimetick(2) + 86400; // 86400 is one day in seconds.
+      [[set]] TimeHealed, [[gettimetick]](2);
-      dispbottom "Healer : Please give me at least a day to recover.";
+      [[dispbottom]] "Healer : Please give me at least a day to recover.";
-      end;
+      [[end]];
+  }
 Q: I see no timers?<br>
-A: That is correct. This NPC uses what I would like to call a Static Timer. We will review it in detail below.<br><br>
+A: That is correct. This NPC uses what I would like to call a Static Timer. We will review it in detail below.
 <br><br>
 Ok, at a first glance, this is a normal healer NPC that fully heals your HP and SP. The interesting part though is at the bottom. Let's start with the bottom most part:
-      close2;
+      [[close2]];
-      precentheal 100,100;
+      [[percentheal]] 100,100;
-      set TimeHealed, [[gettimetick]](2) + 86400; // 86400 is one day in seconds.
+      [[set]] TimeHealed, [[gettimetick]](2);
-      dispbottom "Healer : Please give me at least a day to recover.";
+      [[dispbottom]] "Healer : Please give me at least a day to recover.";
-      end;
+      [[end]];
-The NPC does the healing here, but after the healing, it sets a weird value to TimeHealed. First, it gets a value from gettimetick(2). This command returns the amount of seconds elapsed since 1/1/1970, based on your server current time. To this number, it adds 86400, which is the amount of seconds that goes in a day (24 * 60 * 60). Those two combined give us the next time the player is allowed to use the NPC again. Now, we go back a tiny bit, to this line:
+The NPC does the healing here, but after the healing, it sets a weird value to TimeHealed. First, it gets a value from gettimetick(2). This command returns the amount of seconds elapsed since 1/1/1970, based on your server current time.
-     if(TimeHealed > gettimetick(2)) {
-When the player wants to use the NPC again, the NPC first checks if the player is still allowed to be healed. How? Well, remember, in TimeHealed, we stored the next time the player is allowed to use the NPC again, in seconds. With gettimetick(2) we get the current time in seconds that has elapsed since 1/1/1970. If the player is allowed to use the NPC again, his stored value should be in the past, so it should be less than what gettimetick(2) will return to us. If it is the other way around, the player is not allowed to use the NPC yet, and it will jump inside the if-statement.
-−
 Please note, that using a Static Timer comes with some disadvantages. First, it uses a player variable.
-Second, the more dynamic you make it, the more resources it will cost. Although it should be less CPU intensive than a normal timer, making it dynamic means, that you do the math in the following if statement:
+Second, the more dynamic you make it, the more resources it will cost. Although it should be less CPU intensive than a normal timer, making it dynamic means.
-     if(TimeHealed > gettimetick(2)) {
+<br><br>
-Instead of where you set the new time.
+By turning that numbers into a Global variable,
-     set TimeHealed, gettimetick(2) + 86400; // 86400 is one day in seconds.
+      [[if]] ((TimeHealed + $HealInterval)> [[gettimetick]](2)) {
 $HealInterval will be a variable that you can set as a GM through another NPC, to determine the time between two heal possibilities in seconds.
-Basically, these two lines will become this:
       if((TimeHealed + $HealInterval)> gettimetick(2)) {
-and
-     set TimeHealed, gettimetick(2);
-Where $HealInterval will be a variable that you can set as a GM through another NPC, to determine the time between two heal possibilities in seconds.
 = Difference between Timers =

@@ Line 150: / Line 150: @@
       [[mes]] "Please help me find it before it explodes.";
       [[if]] ( @boom == 1 ) [[close]];
       [[close2]];
       [[addtimer]] 15000, "Bomb Squad::OnWarn";
       [[addtimer]] 30000, "Bomb Squad::OnBoom";

@@ Line 491: / Line 491: @@
 * You always need a player attached to the script to use this.
 * The timer is erased on log out. (Can be an advantage as well.)
-* Cannot be read out in any way.
+* Cannot be read out without abusing a variable.
-* Cannot be used on start up or time triggered labels.
+* Cannot be used when server start up or npc only triggered labels, otherwise the server will throw ''Player not Attached!'' error
 [[Category:Scripting]] [[Category:Script_Command]]

@@ Line 272: / Line 272: @@
 Label Timers aren't timers actually. They are labels that are triggered depending on the current time of the server. There are several different kinds of them, but they all almost work in the same way. You simply put them in your script as a label, and they look like this:
 * OnClockXXXX:
-* OnDayXXXX: - Not tested by author, but should work.
+* OnDayXXXX:
 * OnHourXX:
 * OnMinuteXX:
 Where XX is a two digit number and XXXX is a four digit number. SSSXXXX is three letters followed by four digits.
+<br>
 How they work? Relatively easy. OnClock is already explained in the first part of this article, but here is the recap in case you forgot. To make it work, you replace XXXX by an actual time in the 24 hour format. The time you put there, is when the label is triggered. So, for example:
   OnClock0700: // This label is triggered at 7 AM servertime.
   OnClock1414: // This label is triggered at 2:14 PM servertime.
+<br>
 Just like normal labels, you can use the same OnClock label in different NPCs, but, it cannot occur twice in the same NPC. You can have different OnClocks in the same NPC though.
+<br>
 OnDayXXXX works a bit like OnClock. The XXXX here stands for a specific day in a specific month. The first XX is the month, the second XX is the day of that month. When it is that day, it will be triggered. Assumed is, that this happens only once at the start of that day, or the first time that your server is up during that day. Here are a couple of examples:
   OnDay0101: // This label is triggered on the first day of January.
@@ Line 289: / Line 288: @@
   OnDay1231: // This one is triggered on the last day of December.
   OnDay0229: // This label is only triggered when it is February 29th, so once every four years.
+<br>
 OnHourXX and OnMinuteXX are similar in use. With OnHour, the XX stands for a specific hour during the day when it is triggered. The XX within OnMinute stands for a specific minute per hour. Some examples to make it clear:
   OnHour01: // Triggers at 1 AM every day.
@@ Line 295: / Line 294: @@
   OnMinute00: // Triggers at each new hour, so 1:00, 2:00, 3:00, 4:00 etc.
   OnMinute17: // Triggers each hour at 17 minutes past. So, 8:17, 9:17, 10:17 etc.
+<br>
 Last, and probably the least known is OnSSSXXXX. The best way to describe this one is an OnWeekday label. (OnWeekday does not exist.)
 In this label, SSS is replaced by one of the following: Sun, Mon, Tue, Wed, Thu, Fri, Sat.
@@ Line 302: / Line 301: @@
   OnSat1200: // Triggers at noon on each Saturday.
   OnTue0707: // Triggers at 7 past 7 AM on Tuesday.
+<br>
 Note:
-Although there is no OnSecondXX or OnMillisecondXXXX label, you can simulate this. Be aware though, this causes a heavy load on your server. To do this, you will have to use a NPC or player timer. Here is a short example simulating OnSecond30 using a NPC timer:
+Although there is no OnSecondXX or OnMillisecondXXXX label, you can simulate this. Be aware though, this causes a heavy load on your server. To do this, you will have to use a NPC. Here is a short example simulating OnSecond30 using a NPC timer:
-  -<tab>script<tab>Annoying Announcer<tab>FAKE_NPC,{
+  -	script	Annoying Announcer	FAKE_NPC,{
-  OnInit:
+  [[OnInit]]:
-      initnpctimer;
+      [[initnpctimer]];
-      end;
+      [[end]];
-  OnTimer1000:
+  [[OnTimer]]1000:
-      if(gettime(1) != 30) end;
+      if ([[gettime]](GETTIME_SECOND) != 30) [[end]];
-      announce "I'm very annoying.",bc_all;
+      [[announce]] "I'm very annoying.", bc_all;
-      setnpctimer, 0;
+      [[initnpctimer]];
-      end;
+      [[end]];
+  }
 And one that triggers every 40 milliseconds:
-  -<tab>script<tab>Flooder<tab>-1,{
+  -	script	Flooder	FAKE_NPC,{
-  OnInit:
+  [[OnInit]]:
-      initnpctimer;
+      [[initnpctimer]];
-      end;
+      [[end]];
-  OnTimer40:
+  [[OnTimer]]40:
-      announce "Flood!";
+      [[announce]] "Flood!", bc_all;
-      setnpctimer, 0;
+      [[initnpctimer]];
-      end;
+      [[end]];
+  }

@@ Line 331: / Line 331: @@
 These timers are actually nowhere related to timers. To be exact, they are event triggered labels, but let's go over them anyway, because they are useful. The timers I'm referring to are the following:
 * [[OnInit]]:               - Is triggered on server start up.
-* [[OnCharIfInit]]:         - Is triggered when the mapserver connects to the charserver.
+* [[OnInterIfInit]]:        - Is triggered when the mapserver connects to the charserver.
-* [[OnInterIfInit]]:        - Roughly same as previous.
 * [[OnInterIfInitOnce]]:    - Is only triggered on the first time the map server connects to the char server. If it loses connection after that, and gets a connection again, these labels are no longer triggered (unless the map server is really restarted).
 * [[OnAgitInit]]:           - Is triggered when WoE is initiated.

@@ Line 178: / Line 178: @@
       [[deltimer]] "Bomb Squad::OnBoom";
       [[set]] @boom, 0;
-      [[end]];
+      [[close]];
+  }
 deltimer command will remove the timer that has previously attached to the player. So if the player previously talk to the Bomb Squad, will able to disarm the bomb. This will prevent the addtimer from invoking the OnWarn: and OnBoom: label.
 <br><br>
 Q: What happens if the player click on the Bomb after 15 seconds, will the server throw error for OnWarn: label already executed ?<br>
-A: Nope, the server doesn't seem to care about that. This means you can put as many addtimer command, and deltimer all of them without worry. Neat, isn't it?
+A: Nope, the server doesn't seem to care about that. This means you can put as many addtimer command, and deltimer all of them without additional checks. Neat, isn't it?
 <br><br>
 '''Note''' : addtimer can only attached to the up to 31 instances on that player. This means, if you have more than a number of scripts using addtimer command on that player, on 32th queue will throw an error on the server to notify some of your script has over abuse this command. To lift off this limit, simply increase the MAX_EVENTTIMER in src\map\map.h, and recompile your server.