Merge pull request #39606 from aaronfranke/pause

Update documentation for the new ProcessMode

6 files changed, 27 insertions, 18 deletions

diff --git a/doc/classes/AnimationTree.xml b/doc/classes/AnimationTree.xml
index 7e70e0a31b..2517941133 100644
--- a/doc/classes/AnimationTree.xml
+++ b/doc/classes/AnimationTree.xml
@@ -46,6 +46,7 @@
 			The path to the [AnimationPlayer] used for animating.
 		</member>
 		<member name="process_callback" type="int" setter="set_process_callback" getter="get_process_callback" enum="AnimationTree.AnimationProcessCallback" default="1">
+			The process mode of this [AnimationTree]. See [enum AnimationProcessCallback] for available modes.
 		</member>
 		<member name="root_motion_track" type="NodePath" setter="set_root_motion_track" getter="get_root_motion_track" default="NodePath(&quot;&quot;)">
 			The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. To specify a track that controls properties or bones, append its name after the path, separated by [code]":"[/code]. For example, [code]"character/skeleton:ankle"[/code] or [code]"character/mesh:transform/local"[/code].
diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml
index ead5045d4b..7ee6860dfc 100644
--- a/doc/classes/Node.xml
+++ b/doc/classes/Node.xml
@@ -883,6 +883,7 @@
 			The node owner. A node can have any other node as owner (as long as it is a valid parent, grandparent, etc. ascending in the tree). When saving a node (using [PackedScene]), all the nodes it owns will be saved with it. This allows for the creation of complex [SceneTree]s, with instancing and subinstancing.
 		</member>
 		<member name="process_mode" type="int" setter="set_process_mode" getter="get_process_mode" enum="Node.ProcessMode" default="0">
+			Can be used to pause or unpause the node, or make the node paused based on the [SceneTree], or make it inherit the process mode from its parent (default).
 		</member>
 		<member name="process_priority" type="int" setter="set_process_priority" getter="get_process_priority" default="0">
 			The node's priority in the execution order of the enabled processing callbacks (i.e. [constant NOTIFICATION_PROCESS], [constant NOTIFICATION_PHYSICS_PROCESS] and their internal counterparts). Nodes whose process priority value is [i]lower[/i] will have their processing callbacks executed first.
@@ -1031,14 +1032,19 @@
 			Notification received when text server is changed.
 		</constant>
 		<constant name="PROCESS_MODE_INHERIT" value="0" enum="ProcessMode">
+			Inherits process mode from the node's parent. For the root node, it is equivalent to [constant PROCESS_MODE_PAUSABLE]. Default.
 		</constant>
 		<constant name="PROCESS_MODE_PAUSABLE" value="1" enum="ProcessMode">
+			Stops processing when the [SceneTree] is paused (process when unpaused). This is the inverse of [constant PROCESS_MODE_WHEN_PAUSED].
 		</constant>
 		<constant name="PROCESS_MODE_WHEN_PAUSED" value="2" enum="ProcessMode">
+			Only process when the [SceneTree] is paused (don't process when unpaused). This is the inverse of [constant PROCESS_MODE_PAUSABLE].
 		</constant>
 		<constant name="PROCESS_MODE_ALWAYS" value="3" enum="ProcessMode">
+			Always process. Continue processing always, ignoring the [SceneTree]'s paused property. This is the inverse of [constant PROCESS_MODE_DISABLED].
 		</constant>
 		<constant name="PROCESS_MODE_DISABLED" value="4" enum="ProcessMode">
+			Never process. Completely disables processing, ignoring the [SceneTree]'s paused property. This is the inverse of [constant PROCESS_MODE_ALWAYS].
 		</constant>
 		<constant name="DUPLICATE_SIGNALS" value="1" enum="DuplicateFlags">
 			Duplicate the node's signals.
diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml
index 830fe6ef4d..f65d013bfc 100644
--- a/doc/classes/SceneTree.xml
+++ b/doc/classes/SceneTree.xml
@@ -64,10 +64,10 @@
 			</return>
 			<argument index="0" name="time_sec" type="float">
 			</argument>
-			<argument index="1" name="pause_mode_process" type="bool" default="true">
+			<argument index="1" name="process_always" type="bool" default="true">
 			</argument>
 			<description>
-				Returns a [SceneTreeTimer] which will [signal SceneTreeTimer.timeout] after the given time in seconds elapsed in this [SceneTree]. If [code]pause_mode_process[/code] is set to [code]false[/code], pausing the [SceneTree] will also pause the timer.
+				Returns a [SceneTreeTimer] which will [signal SceneTreeTimer.timeout] after the given time in seconds elapsed in this [SceneTree]. If [code]process_always[/code] is set to [code]false[/code], pausing the [SceneTree] will also pause the timer.
 				Commonly used to create a one-shot delay timer as in the following example:
 				[codeblock]
 				func some_function():
@@ -363,6 +363,7 @@
 		</signal>
 		<signal name="tree_process_mode_changed">
 			<description>
+				This signal is only emitted in the editor, it allows the editor to update the visibility of disabled nodes. Emitted whenever any node's [member Node.process_mode] is changed.
 			</description>
 		</signal>
 	</signals>
diff --git a/doc/translations/README.md b/doc/translations/README.md
new file mode 100644
index 0000000000..a941eeaf49
--- /dev/null
+++ b/doc/translations/README.md
@@ -0,0 +1 @@
+These `.po` and `.pot` files come from Weblate. Do not modify them manually.
diff --git a/scene/main/scene_tree.cpp b/scene/main/scene_tree.cpp
index 656ace9f64..6d50738de1 100644
--- a/scene/main/scene_tree.cpp
+++ b/scene/main/scene_tree.cpp
@@ -72,12 +72,12 @@ float SceneTreeTimer::get_time_left() const {
 	return time_left;
 }
 
-void SceneTreeTimer::set_pause_mode_process(bool p_pause_mode_process) {
-	process_pause = p_pause_mode_process;
+void SceneTreeTimer::set_process_always(bool p_process_always) {
+	process_always = p_process_always;
 }
 
-bool SceneTreeTimer::is_pause_mode_process() {
-	return process_pause;
+bool SceneTreeTimer::is_process_always() {
+	return process_always;
 }
 
 void SceneTreeTimer::release_connections() {
@@ -455,7 +455,7 @@ bool SceneTree::process(float p_time) {
 
 	for (List<Ref<SceneTreeTimer>>::Element *E = timers.front(); E;) {
 		List<Ref<SceneTreeTimer>>::Element *N = E->next();
-		if (pause && !E->get()->is_pause_mode_process()) {
+		if (paused && !E->get()->is_process_always()) {
 			if (E == L) {
 				break; //break on last, so if new timers were added during list traversal, ignore them.
 			}
@@ -759,10 +759,10 @@ Ref<ArrayMesh> SceneTree::get_debug_contact_mesh() {
 }
 
 void SceneTree::set_pause(bool p_enabled) {
-	if (p_enabled == pause) {
+	if (p_enabled == paused) {
 		return;
 	}
-	pause = p_enabled;
+	paused = p_enabled;
 	NavigationServer3D::get_singleton()->set_active(!p_enabled);
 	PhysicsServer3D::get_singleton()->set_active(!p_enabled);
 	PhysicsServer2D::get_singleton()->set_active(!p_enabled);
@@ -772,7 +772,7 @@ void SceneTree::set_pause(bool p_enabled) {
 }
 
 bool SceneTree::is_paused() const {
-	return pause;
+	return paused;
 }
 
 void SceneTree::_notify_group_pause(const StringName &p_group, int p_notification) {
@@ -1070,10 +1070,10 @@ void SceneTree::add_current_scene(Node *p_current) {
 	root->add_child(p_current);
 }
 
-Ref<SceneTreeTimer> SceneTree::create_timer(float p_delay_sec, bool p_process_pause) {
+Ref<SceneTreeTimer> SceneTree::create_timer(float p_delay_sec, bool p_process_always) {
 	Ref<SceneTreeTimer> stt;
 	stt.instance();
-	stt->set_pause_mode_process(p_process_pause);
+	stt->set_process_always(p_process_always);
 	stt->set_time_left(p_delay_sec);
 	timers.push_back(stt);
 	return stt;
@@ -1186,7 +1186,7 @@ void SceneTree::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_pause", "enable"), &SceneTree::set_pause);
 	ClassDB::bind_method(D_METHOD("is_paused"), &SceneTree::is_paused);
 
-	ClassDB::bind_method(D_METHOD("create_timer", "time_sec", "pause_mode_process"), &SceneTree::create_timer, DEFVAL(true));
+	ClassDB::bind_method(D_METHOD("create_timer", "time_sec", "process_always"), &SceneTree::create_timer, DEFVAL(true));
 
 	ClassDB::bind_method(D_METHOD("get_node_count"), &SceneTree::get_node_count);
 	ClassDB::bind_method(D_METHOD("get_frame"), &SceneTree::get_frame);
diff --git a/scene/main/scene_tree.h b/scene/main/scene_tree.h
index 35622c2031..f39780831f 100644
--- a/scene/main/scene_tree.h
+++ b/scene/main/scene_tree.h
@@ -52,7 +52,7 @@ class SceneTreeTimer : public Reference {
 	GDCLASS(SceneTreeTimer, Reference);
 
 	float time_left = 0.0;
-	bool process_pause = true;
+	bool process_always = true;
 
 protected:
 	static void _bind_methods();
@@ -61,8 +61,8 @@ public:
 	void set_time_left(float p_time);
 	float get_time_left() const;
 
-	void set_pause_mode_process(bool p_pause_mode_process);
-	bool is_pause_mode_process();
+	void set_process_always(bool p_process_always);
+	bool is_process_always();
 
 	void release_connections();
 
@@ -95,7 +95,7 @@ private:
 	bool debug_collisions_hint = false;
 	bool debug_navigation_hint = false;
 #endif
-	bool pause = false;
+	bool paused = false;
 	int root_lock = 0;
 
 	Map<StringName, Group> group_map;
@@ -316,7 +316,7 @@ public:
 	Error change_scene_to(const Ref<PackedScene> &p_scene);
 	Error reload_current_scene();
 
-	Ref<SceneTreeTimer> create_timer(float p_delay_sec, bool p_process_pause = true);
+	Ref<SceneTreeTimer> create_timer(float p_delay_sec, bool p_process_always = true);
 
 	//used by Main::start, don't use otherwise
 	void add_current_scene(Node *p_current);