diff --git a/api.lua b/api.lua
index 6e50900..36fa6a1 100644
--- a/api.lua
+++ b/api.lua
@@ -2449,6 +2449,13 @@ local mob_activate = function(self, staticdata, def, dtime)
 	update_tag(self)
 	set_animation(self, "stand")
 
+	-- run on_spawn function if found
+	if self.on_spawn and not self.on_spawn_run then
+		if self.on_spawn(self) then
+			self.on_spawn_run = true --  if true, set flag to run once only
+		end
+	end
+
 	if use_cmi then
 		self._cmi_components = cmi.activate_components(self.serialized_cmi_components)
 		cmi.notify_activate(self.object, dtime)
@@ -2687,6 +2694,8 @@ minetest.register_entity(name, {
 	facing_fence = false,
 	_cmi_is_mob = true,
 
+	on_spawn = def.on_spawn,
+
 	on_blast = def.on_blast or do_tnt,
 
 	on_step = mob_step,
diff --git a/api.txt b/api.txt
index 90a5966..5fbcbfe 100644
--- a/api.txt
+++ b/api.txt
@@ -1,5 +1,5 @@
 
-MOB API (13th July 2017)
+MOB API (1st September 2017)
 
 The mob api is a function that can be called on by other mods to add new animals or monsters into minetest.
 
@@ -94,6 +94,7 @@ This functions registers a new mob as a Minetest entity.
         'shoot_interval' the minimum shoot interval
         'shoot_offset' +/- value to position arrow/fireball when fired
         'reach' how far a reach this mob has, default is 3
+        'on_spawn' is a custom function that runs on mob spawn with 'self' as variable, return true at end of function to run onyl once.
         'sounds' this is a table with sounds of the mob
             'random' random sounds during gameplay
             'war_cry' sound when starting to attack player