Refactored new AI components (#31421)

code/_hooks/events.dm

@@ -1,11 +1,9 @@
-#define EVENT_HANDLER_OBJREF_INDEX 1
-#define EVENT_HANDLER_PROCNAME_INDEX 2
+// WARNING
+// Event handlers (i.e.: procs that are registered with `proc/register_event` MUST NOT sleep()).
 
 // Declare children of this type path to use as identifiers for the events.
 /event
 
-// TODO: Document here the arguments that need to be passed to the procs invoked by each event
-
 // Called by human/proc/apply_radiation()
 // Arguments:
 // mob/carbon/living/human/user: The human.
@@ -238,6 +236,25 @@
 // mob/source: the mob performing the emote
 /event/emote
 
+// Called by mob/living/Hear
+// Arguments:
+// datum/speech/speech: the speech datum being heard
+/event/hear
+
+// Called by area/Entered
+// Arguments:
+// atom/movable/enterer: the movable entering the area
+/event/area_entered
+
+// Called by area/Exited
+// Arguments:
+// atom/movable/exiter: the movable exiting the area
+/event/area_exited
+
+// Note: the following are used by datum/component/ai subtypes to give instructions to each other.
+// AI components are expected to INVOKE_EVENT these to send commands to other components
+// on the same datum without having to hold references to them.
+// They may need to be reworked, and they are currently undocumented.
 /event/comp_ai_friend_attacked
 
 /event/comp_ai_cmd_get_best_target
@@ -260,11 +277,8 @@
 /event/comp_ai_cmd_set_state
 /event/comp_ai_cmd_get_state
 
-/event/comp_ai_cmd_hear
 /event/comp_ai_cmd_say
 /event/comp_ai_cmd_specific_say
-/event/comp_ai_cmd_area_enter
-/event/comp_ai_cmd_area_exit
 
 /datum
 	/// Associative list of type path -> list(),
@@ -283,6 +297,9 @@
   */
 #define INVOKE_EVENT(target, event_type, arguments...) (target.registered_events?[event_type] && target.invoke_event(event_type, list(##arguments)))
 
+#define EVENT_HANDLER_OBJREF_INDEX 1
+#define EVENT_HANDLER_PROCNAME_INDEX 2
+
 /datum/proc/invoke_event(event/event_type, list/arguments)
 	SHOULD_NOT_OVERRIDE(TRUE)
 	var/list/event_handlers = registered_events[event_type]