path: root/doc/whisper_sys.txt

//===== rAthena Documentation ================================
//= NPC Whisper System
//===== By: ==================================================
//= lordalfa
//===== Current Version: =====================================
//= 20120826
//===== Description: =========================================
//= A description of rAthena's NPC whispering system.
//============================================================

This piece of code to allows characters to execute events in NPCs by whispering 
them up to ten parameters. The NPC must have an "OnWhisperGlobal" label, or an 
"event not found" error will result.

	NPC:<NPC Name>		<String>{#String 2{#...{#String 10}}}
	
The whispered strings are separated by the "#" character, and are each stored
into separate temporary character string variables:

	@whispervar0$, @whispervar1$, ... @whispervar9$

---------------------------------------------------------------------------------

Below is an example of how this feature might be used.
You whisper an NPC "NPCCommander" in-game with the following instructions:

	NPC:NPCCommander	Report#Killstealing#Lordalfa

The parameters are passed on to the "OnWhisperGlobal" label of the NPC, and can
be processed accordingly:

-	script	NPCCommander	-1,{
OnWhisperGlobal:
	// Inform player "Lordalfa" that he has been reported for killstealing.
	if (@whispervar0$ == "Report")
		message @whispervar2$,"You have been reported for "+@whispervar1$+".";
	end;
}

The Whisper System is also useful for hidden event handler NPCs (NPCs that don't
have a sprite on a map for you to click). E.g:

OnWhisperGlobal:
if (getgmlevel()<80) goto L_NotGM;
if (@whispervar0$ == "event1") goto L_Event1;
if (@whispervar0$ == "event2") goto L_Event2;
if (@whispervar0$ == "event3") goto L_Event3;

// If the string sent to this NPC doesn't contain any of the above:
else goto L_NoVar;
end;

L_NotGM:
	dispbottom	"NPC : You do not have sufficient access to whisper in my ear.";
	end;

L_NoVar:
	dispbottom "NPC : Sorry, i do not recognise that command.";
	end;

L_Event1:
	if (@whispervar1$ == "start"){
		// Execute scripts to start Event1
	}
	if (@whispervar1$ == "stop"){
		//Execute scripts to forcefully stop Event1
	}