added visit counters to readme.md and added custom preconditions for reading them out

api/custom_functions_you_can_override.lua

@@ -254,6 +254,59 @@ yl_speak_up.custom_functions_p_[ "text_contained_these_words" ] = {
 }
 
 
+yl_speak_up.custom_functions_p_[ "counted_visits_to_dialog" ] = {
+	description = "counted dialog visits: "..
+		"How many times has the player visited/seen this dialog during this talk?",
+	param1_text = "Name of dialog (i.e. \"d_1\"):",
+	param1_desc = "Enter the dialog ID of the dialog for which you want to get the amount of "..
+		"visits. If the dialog does not exist, -1 is returned.",
+	code = function(player, n_id, p)
+		local pname = player:get_player_name()
+		if(not(pname)) then
+			return -1
+		end
+		local dialog = yl_speak_up.speak_to[pname].dialog
+		local d_id = p["p_param1"]
+		if(not(yl_speak_up.check_if_dialog_exists(dialog, d_id))) then
+			return -1
+		end
+		local visits = dialog.n_dialogs[d_id].visits
+		if(not(visits)) then
+			return 0
+		end
+		return visits
+	end,
+}
+
+
+yl_speak_up.custom_functions_p_[ "counted_visits_to_option" ] = {
+	description = "counted dialog option/answers visits: "..
+		"How many times has the player visited/seen this dialog *option* during this talk?",
+	param1_text = "Name of dialog (i.e. \"d_1\"):",
+	param1_desc = "Enter the dialog ID of the dialog the option belongs to.",
+	param2_text = "Name of option (i.e. \"o_2\"):",
+	param2_desc = "Enter the option ID of the dialog for which you want to get the amount of "..
+		"visits. If the option does not exist, -1 is returned.",
+	code = function(player, n_id, p)
+		local pname = player:get_player_name()
+		if(not(pname)) then
+			return -1
+		end
+		local dialog = yl_speak_up.speak_to[pname].dialog
+		local d_id = p["p_param1"]
+		local o_id = p["p_param2"]
+		if(not(yl_speak_up.check_if_dialog_has_option(dialog, d_id, o_id))) then
+			return -1
+		end
+		local visits = dialog.n_dialogs[d_id].d_options[o_id].visits
+		if(not(visits)) then
+			return 0
+		end
+		return visits
+	end,
+}
+
+
 -----------------------------------------------------------------------------
 --  Custom actions (of type "evaluate")
 -----------------------------------------------------------------------------

functions.lua

@@ -709,6 +709,13 @@ yl_speak_up.check_if_dialog_has_option = function(dialog, d_id, o_id)
 	  and dialog.n_dialogs[d_id].d_options[o_id])
 end
 
+-- checks if dialog exists
+yl_speak_up.check_if_dialog_exists = function(dialog, d_id)
+	return (dialog and d_id
+	  and dialog.n_dialogs
+	  and dialog.n_dialogs[d_id])
+end
+
 
 -- has the player the right privs?
 -- this is used for the "I am your master" talk based configuration; *NOT* for the staffs!

readme.md

@@ -58,6 +58,7 @@ To get started, best install `yl_speak_up`, `npc_talk`, `mobs_redo` and `mobs_np
    1. [1.20 Logging](#logging)
    1. [1.21 Export/Import](#export)
    1. [1.22 Storing internal notes](#notes)
+   1. [1.23 Counting visits to dialogs and options](#visit-counter)
 
 2. [For moderators: Generic NPCs](#for-moderators)
    1. [2.1 Generic behaviour](#generic_behaviour)
@@ -534,6 +535,29 @@ this NPC - its character, how it behaves and talks, who his friends are etc.
 These internal notes are only shown to players who can edit this NPC.
 
 
+### 1.23 Counting visits to dialogs and options
+<a name="visit-counter"></a>
+
+Whenever a dialog text is displayed to the player and whenever the player
+selects an option which is successful (no aborted actions or `on_failure`
+effects inbetween), a counter called `visits` is increased by one for that
+dialog or option.
+
+This information is *not* persistent! When the player leaves the talk by
+choosing `Farewell!` or pressing ESC all visit information is lost.
+
+The feature can be used to help players see which options they've tried
+and which path they've followed. If an option is set to `*once*` instead
+of the default `often` in the edit options dialog, that option can only
+be selected *once* each time the player talks to this NPC. After that the
+option gets greyed out and displays "[Done]" followed by the normal option
+text.
+
+Visits are not counted in edit mode and not counted for generic dialogs.
+
+There are custom preconditions for checking the number of visits to a dialog
+and/or option.
+
 
 ## 2. For moderators: Generic NPCs
 <a name="for-moderators"></a>