fix: should now also prevent areas from spawning events; also removes a superfluous variable

addons/escoria-core/game/core-scripts/esc/commands/set_active_if_exists.gd

@@ -1,6 +1,11 @@
 # `set_active_if_exists object active`
 #
-# Changes the "active" state of the object in the current room.
+# *** FOR INTERNAL USE ONLY ***
+#
+# Changes the "active" state of the object in the current room if it currently
+# exists in the object manager. If it doesn't, then, unlike set_active, we don't
+# fail and we just carry on.
+#
 # Inactive objects are invisible in the room.
 #
 # **Parameters**
@@ -22,19 +27,6 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate whether the given arguments match the command descriptor
-func validate(arguments: Array):
-	if not escoria.object_manager.has(arguments[0]):
-		escoria.logger.report_errors(
-			"set_active: invalid object",
-			[
-				"Object with global id %s not found" % arguments[0]
-			]
-		)
-		return false
-	return .validate(arguments)
-
-
 # Run the command
 func run(command_params: Array) -> int:
 	if escoria.object_manager.has(command_params[0]):

addons/escoria-core/game/core-scripts/esc/commands/set_global.gd

@@ -1,4 +1,4 @@
-# `set_global name value [ignore_reserved=false]`
+# `set_global name value [force=false]`
 #
 # Changes the value of a global.
 #

addons/escoria-core/game/core-scripts/esc/esc_object_manager.gd

@@ -15,14 +15,25 @@ const RESERVED_OBJECTS = [
 	CAMERA
 ]
 
-# The array of registered objects (organized by room, incl. one "room" for 
+
-# reserved objects).
+# The array of registered objects (organized by room, so each entry is a structure
+# representing a room and its registered objects). This also includes one 
+# "room" for reserved objects; that is, we use one entry of the array to
+# hold all reserved objects. This entry can be identified by the "is_reserved"
+# property being set to true.
+#
+# "Reserved objects" are those which are named in the RESERVED_OBJECTS const 
+# array and include objects that are used internally by Escoria in every room, 
+# e.g. a music player, a sound player, a speech player, the main camera.
+#
+# In almost all cases, the reserved objects' entry doesn't need updating once
+# created.
 #
 # Example structure:
 #
 #	[
 #		{
-#			is_reserved: true,
+#			is_reserved: true,	# Indicates this is the "reserved objects" entry
 #			room: "",
 #			room_instance_id: "",
 #			objects:
@@ -31,7 +42,7 @@ const RESERVED_OBJECTS = [
 #				},
 #		},
 #		{
-#			is_reserved: false,
+#			is_reserved: false,	# Indicates this an entry for a room's objectss
 #			room_global_id: "<room_global_id>",
 #			room_instance_id: "<room_object_instance_id>",
 #			objects:
@@ -41,9 +52,6 @@ const RESERVED_OBJECTS = [
 #				}
 #		}
 #	]
-#
-# Note that the "is_reserved" entry cannot be altered or otherwise changed and
-# that it belongs to no specific room.
 var room_objects: Array = []
 
 # We also store the current room's ids for retrieving the right objects.
@@ -81,7 +89,8 @@ func set_current_room(room: ESCRoom) -> void:
 		escoria.logger.report_errors(
 			"ESCObjectManager:set_current_room()",
 			[
-				"Unable to set current room: No valid room specified."
+				"Unable to set current room: No valid room specified.",
+				"Please pass in a valid ESCRoom as an argument to the method."
 			]
 		)
 
@@ -106,7 +115,7 @@ func register_object(object: ESCObject, room: ESCRoom = null, force: bool = fals
 		escoria.logger.report_warnings(
 			"ESCObjectManager:register_object()",
 			[
-				"Registering object with empty global_id.",
+				"Registering ESCObject %s with empty global_id." % object.name,
 				"Using node's full path as global_id: %s"
 							% object.node.global_id
 			]
@@ -130,10 +139,13 @@ func register_object(object: ESCObject, room: ESCRoom = null, force: bool = fals
 		room_key.room_instance_id = current_room_key.room_instance_id
 		
 		if not room_key.is_valid():
+			# This condition should very likely never happen.
 			escoria.logger.report_errors(
 				"ESCObjectManager:register_object()",
 				[
-					"No room was specified to register object with, and no current room is properly set."
+					"No room was specified to register object with, and no current room is properly set.",
+					"Please either pass in a valid ESCRoom to this method, or " + \
+						"call set_current_room() with a valid ESCRoom first."
 				]
 			)
 	else:
@@ -256,8 +268,7 @@ func get_object(global_id: String, room: ESCRoom = null) -> ESCObject:
 			escoria.logger.report_warnings(
 				"ESCObjectManager:get_object()",
 				[
-					"Invalid reserved object retrieved.",
+					"Reserved object with global id %s not found in object manager!" 
-					"Reserved object with global id %s not found" 
 						% global_id
 				]
 			)
@@ -279,7 +290,7 @@ func get_object(global_id: String, room: ESCRoom = null) -> ESCObject:
 		escoria.logger.report_warnings(
 			"ESCObjectManager:get_object()",
 			[
-				"Specified room empty/not found.",
+				"Specified room is empty/not found.",
 				"Object with global id %s in room instance (%s, %s) not found" 
 				% [global_id, room_key.room_global_id, room_key.room_instance_id]
 			]
@@ -294,7 +305,6 @@ func get_object(global_id: String, room: ESCRoom = null) -> ESCObject:
 		escoria.logger.report_warnings(
 			"ESCObjectManager:get_object()",
 			[
-				"Invalid object retrieved.",
 				"Object with global id %s in room instance (%s, %s) not found" 
 				% [global_id, room_key.room_global_id, room_key.room_instance_id]
 			]
@@ -390,6 +400,8 @@ func save_game(p_savegame: ESCSaveGame) -> void:
 			objects[obj_global_id].get_save_data()
 
 
+# Returns the current room's starting location. If more than one exists, the
+# first one encountered is returned.
 func get_start_location() -> ESCLocation:
 	if _room_exists(current_room_key):
 		for object in _get_room_objects_objects(current_room_key).values():

addons/escoria-core/game/core-scripts/esc/esc_room_manager.gd

@@ -55,8 +55,6 @@ func change_scene(room_path: String, enable_automatic_transitions: bool) -> void
 	# events in there so we avoid running these multiple times)
 	escoria.event_manager.clear_event_queue()
 
-	var exited_previous_room = false
-
 	# If auto transition is enabled, try to determine whether we just exited a
 	# room previously, so that we must play the auto transition out or not.
 	# This must happen if ESC_LAST_SCENE is set, or if we're running an
@@ -77,8 +75,6 @@ func change_scene(room_path: String, enable_automatic_transitions: bool) -> void
 			)
 		):
 
-		exited_previous_room = true
-
 		var transition_id = escoria.main.scene_transition.transition(
 			"",
 			ESCTransitionPlayer.TRANSITION_MODE.OUT
@@ -146,8 +142,6 @@ func change_scene(room_path: String, enable_automatic_transitions: bool) -> void
 		else:
 			room_scene.enabled_automatic_transitions = enable_automatic_transitions
 
-		room_scene.exited_previous_room = exited_previous_room
-
 		# If the game scene is already in the tree but not a child of the room
 		# we remove it
 		if escoria.game_scene.is_inside_tree() \
@@ -274,8 +268,7 @@ func _perform_script_events(room: ESCRoom) -> void:
 	var yielded: bool = false
 	
 	if room.enabled_automatic_transitions \
-			and not room.is_run_directly \
+			and not room.is_run_directly:
-			and not room.exited_previous_room:
 		var script_transition_out = escoria.esc_compiler.compile([
 			"%s%s" % [ESCEvent.PREFIX, escoria.event_manager.EVENT_TRANSITION_OUT],
 			"%s %s out" %

addons/escoria-core/game/core-scripts/esc/types/esc_room_objects_key.gd

@@ -4,9 +4,15 @@ extends Reference
 class_name ESCRoomObjectsKey
 
 
+# Contains the global_id of the room being represented by this key.
 var room_global_id: String = ""
+
+# Contains the instance ID of the room being represented by this key.
 var room_instance_id: int = -1
 
 
-func is_valid():
+# Checks whether this key is valid and represents an actual room.
+#
+# **Returns** true iff the key has a valid global_id and room instance ID.
+func is_valid() -> bool:
 	return not room_global_id.empty() and room_instance_id > -1

addons/escoria-core/game/core-scripts/esc_item.gd

@@ -57,6 +57,8 @@ signal mouse_right_clicked_item(global_id)
 signal arrived(walk_context)
 
 
+# Group for ESCItem's that can be collided with in a scene. Used for quick
+# retrieval of such nodes to easily change their attributes at the same time.
 const GROUP_ITEM_CAN_COLLIDE = "item_can_collide"
 
 

addons/escoria-core/game/core-scripts/esc_room.gd

@@ -46,9 +46,6 @@ var enabled_automatic_transitions = true
 # Whether this room was run directly with Play Scene (F6)
 var is_run_directly = false
 
-# Whether this room was accessed from an exit in a previous room
-var exited_previous_room = false
-
 
 # Start the random number generator when the camera limits should be displayed
 func _enter_tree():

addons/escoria-core/game/main.gd

@@ -74,6 +74,10 @@ func set_scene(p_scene: Node) -> void:
 
 # Only called by the room manager in the case where it hasn't executed a 
 # coroutine prior to calling set_scene_finish().
+#
+# ### Parameters
+#
+# - p_scene: The scene currently being initialized by set_scene.
 func finish_current_scene_init(p_scene: Node) -> void:
 	move_child(p_scene, 0)
 
@@ -223,6 +227,14 @@ func check_game_scene_methods():
 	assert(current_scene.game.has_method("_on_event_done"))
 
 
+# Determines whether two scenes represent the same room.
+#
+# ### Parameters
+#
+# - scene_1: Scene to be compared.
+# - scene_2: Other scene to be compared.
+#
+# **Returns** true iff the two scenes represent the same room.
 func _is_same_scene(scene_1: Node, scene_2: Node) -> bool:
 	if scene_1 is ESCRoom and scene_2 is ESCRoom:
 		return scene_1.global_id == scene_2.global_id
@@ -238,4 +250,7 @@ func _disable_collisions() -> void:
 	for item in items_to_disable:
 		if is_instance_valid(item.collision):
 			item.collision.disabled = true
+		if item is Area2D:
+			item.monitoring = false
+			item.monitorable = false
 	

game/rooms/room12/esc/room12.esc

@@ -20,4 +20,4 @@
 
 
 :ready
-transition curtain in
+transition instant in

project.godot

@@ -465,6 +465,11 @@ _global_script_classes=[ {
 "path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_active.gd"
 }, {
 "base": "ESCBaseCommand",
+"class": "SetActiveIfExistsCommand",
+"language": "GDScript",
+"path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_active_if_exists.gd"
+}, {
+"base": "ESCBaseCommand",
 "class": "SetAngleCommand",
 "language": "GDScript",
 "path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_angle.gd"
@@ -671,6 +676,7 @@ _global_script_class_icons={
 "SayCommand": "",
 "SchedEventCommand": "",
 "SetActiveCommand": "",
+"SetActiveIfExistsCommand": "",
 "SetAngleCommand": "",
 "SetAnimationsCommand": "",
 "SetGlobalCommand": "",