feat: InterpolationServer (#602)

Switch tick interpolation to use server pattern while keeping all
original contracts.

Added unit and perf tests.

Fixes #538 
Fixes #473 
Supersedes #539

---------

Co-authored-by: Tamás Gálffy <ezittgtx@gmail.com>

Author: albertok

addons/netfox.extras/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.extras"
 description="Game-specific utilities for Netfox"
 author="Tamas Galffy and contributors"
-version="1.45.0"
+version="1.46.0"
 script="netfox-extras.gd"

addons/netfox.internals/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.internals"
 description="Shared internals for netfox addons"
 author="Tamas Galffy and contributors"
-version="1.45.0"
+version="1.46.0"
 script="plugin.gd"

addons/netfox.noray/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.noray"
 description="Bulletproof your connectivity with noray integration for netfox"
 author="Tamas Galffy and contributors"
-version="1.45.0"
+version="1.46.0"
 script="netfox-noray.gd"

addons/netfox/interpolators.gd

@@ -1,6 +1,22 @@
 extends Object
 class_name Interpolators
 
+## Tracks interpolation functions for various data types
+##
+## The interpolation system can be used to interpolate arbitrary values,
+## regardless of their types. This is done by keeping a list of interpolators,
+## with each handling a specific data type. These can be registered using
+## [method register].
+## [br][br]
+## Later on, these values can either be interpolated using [method interpolate],
+## or getting the interpolation function using [method find_for] and calling it.
+## [br][br]
+## By default, this class supports most built-in data types, aside from objects,
+## arrays, and dictionaries. Custom interpolators can be registered, and will
+## take precedence over built-in ones.
+##
+## @tutorial(Interpolators): https://foxssake.github.io/netfox/latest/netfox/guides/interpolators/
+
 class Interpolator:
 	var is_applicable: Callable
 	var apply: Callable
@@ -11,37 +27,56 @@ class Interpolator:
 		result.apply = apply
 		return result
 
+## Fallback interpolator.
+## [br][br]
+## Returns the starting value in the first half of the tick, and the target
+## value in the other half.
 static var DEFAULT_INTERPOLATOR := Interpolator.make(
 	func (v): return true,
-	func (a, b, f): return a if f < 0.5 else b
+	default_apply
 )
 
+## List of known interpolators.
+## [br][br]
+## This list is used to look up interpolators in [method find_for] and [method
+## find_interpolator_for]. The list is ordered - the earlier an interpolator
+## is in the list, the higher its precedence.
+## [br][br]
+## Do not modify - use [method register] instead.
 static var interpolators: Array[Interpolator]
+
+## Default interpolation function
 static var default_apply: Callable = func(a, b, f): a if f < 0.5 else b
 
 ## Register an interpolator.
-##
+## [br][br]
 ## New interpolators are pushed to the front of the list, making them have
 ## precedence over existing ones. This can be useful in case you want to override
 ## the built-in interpolators.
 static func register(is_applicable: Callable, apply: Callable) -> void:
 	interpolators.push_front(Interpolator.make(is_applicable, apply))
 
 ## Find the appropriate interpolator for the given value.
-##
-## If none was found, the default interpolator is returned.
-static func find_for(value) -> Callable:
+## [br][br]
+## If none was found, returns the default interpolator.
+static func find_for(value: Variant) -> Callable:
+	return find_interpolator_for(value).apply
+
+## Find the appropriate interpolator instance for the given value.
+## [br][br]
+## If none was found, returns the default interpolator.
+static func find_interpolator_for(value: Variant) -> Interpolator:
 	for interpolator in interpolators:
 		if interpolator.is_applicable.call(value):
-			return interpolator.apply
+			return interpolator
 
-	return DEFAULT_INTERPOLATOR.apply
+	return DEFAULT_INTERPOLATOR
 
 ## Interpolate between two values.
-##
-## Note, that it is usually faster to just cache the Callable returned by find_for
-## and call that, instead of calling interpolate repeatedly. The latter will have
-## to lookup the appropriate interpolator on every call.
+## [br][br]
+## Note that this method looks up the appropriate interpolator using [method
+## find_for] on every call. It is faster to call [method find_for] once, and
+## call the resulting [Callable] repeatedly.
 static func interpolate(a, b, f: float):
 	return find_for(a).call(a, b, f)
 

addons/netfox/netfox.gd

@@ -216,6 +216,10 @@ const AUTOLOADS: Array[Dictionary] = [
 	{
 		"name": "RollbackLivenessServer",
 		"path": ROOT + "/servers/rollback-liveness-server.gd"
+	},
+	{
+		"name": "InterpolationServer",
+		"path": ROOT + "/servers/interpolation-server.gd"
 	}
 ]
 

addons/netfox/network-time.gd

@@ -562,6 +562,8 @@ func _loop() -> void:
 	_last_process_time = _clock.get_time()
 	while _next_tick_time < _last_process_time and ticks_in_loop < max_ticks_per_frame:
 		if ticks_in_loop == 0:
+			InterpolationServer._clear_teleports()
+			InterpolationServer._apply_target_state()
 			before_tick_loop.emit()
 
 		before_tick.emit(ticktime, tick)
@@ -579,14 +581,18 @@ func _loop() -> void:
 	if ticks_in_loop > 0:
 		after_tick_loop.emit()
 		NetworkHistoryServer._restore_synchronizer_state(tick)
+		InterpolationServer._record_next_state()
 
 	NetworkIdentityServer.flush_queue()
 
 func _process(delta: float) -> void:
 	_process_delta = delta
 
-	if _is_active() and not sync_to_physics:
-		_loop()
+	if _is_active():
+		if not sync_to_physics:
+			_loop()
+
+		InterpolationServer.interpolate(tick_factor)
 
 func _physics_process(delta: float) -> void:
 	if _is_active() and sync_to_physics:

addons/netfox/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox"
 description="Shared internals for netfox addons"
 author="Tamas Galffy and contributors"
-version="1.45.0"
+version="1.46.0"
 script="netfox.gd"

addons/netfox/servers/data/property-pool.gd

@@ -27,6 +27,9 @@ func add(subject: Object, property: NodePath) -> void:
 func has(subject: Object, property: NodePath) -> bool:
 	return (_properties_by_subject.get(subject, []) as Array).has(property)
 
+func has_subject(subject: Object) -> bool:
+	return _properties_by_subject.has(subject)
+
 func erase(subject: Object, property: NodePath) -> void:
 	if not _properties_by_subject.has(subject):
 		return

addons/netfox/servers/data/snapshot.gd

@@ -135,6 +135,13 @@ func erase_subject(subject: Object) -> void:
 	_data.erase(subject)
 	_auth_subjects.erase(subject)
 
+# TODO: Wth, document this class
+# NOTE: If there's no data for the subject, it will erase it from target too
+func copy_subject_to(subject: Object, target: _Snapshot) -> void:
+	target.erase_subject(subject)
+	if has_subject(subject):
+		target._data[subject] = (_data[subject] as Dictionary).duplicate()
+
 func get_subjects() -> Array:
 	return _data.keys()
 

addons/netfox/servers/interpolation-server.gd

@@ -0,0 +1,194 @@
+extends Node
+class_name _InterpolationServer
+
+# @public class
+
+## Manages interpolation between network ticks
+##
+## Handles interpolation for multiple TickInterpolator nodes, storing snapshots
+## and applying interpolation based on the network tick factor.
+## [br][br]
+## This server can interpolate properties of any arbitrary type.
+## See [Interpolators] for specifics on how interpolation is implemented.
+## [br][br]
+##
+
+var _properties := _PropertyPool.new()
+var _interpolators: Dictionary = {}    # {subject Node: {property_path String: Interpolator}}
+
+var _state_from := _Snapshot.new(0)
+var _state_to := _Snapshot.new(0)
+
+var _enabled := _Set.new()
+var _recording_enabled := _Set.new()
+var _teleporting := _Set.new()
+
+static var _logger := NetfoxLogger._for_netfox("InterpolationServer")
+
+## Register a [param property] for interpolation on a [param subject] node.
+## [br][br]
+## If the subject didn't have any properties configured yet, it will be enabled
+## for interpolation and recording. Call [method set_enabled] and
+## [method set_recording] to configure the subject after registration. If the
+## property is already registered for this subject, nothing happens.
+func register(subject: Node, property: NodePath, interpolator: Interpolators.Interpolator = null) -> void:
+	if not _properties.has_subject(subject):
+		# Subject wasn't registered before, setup defaults
+		_interpolators[subject] = {}
+		_enabled.add(subject)
+		_recording_enabled.add(subject)
+
+	if _properties.has(subject, property):
+		# Property already registered, do nothing
+		return
+
+	_properties.add(subject, property)
+	if interpolator == null:
+		var value := subject.get_indexed(property)
+		_interpolators[subject][property] = Interpolators.find_interpolator_for(value)
+	else:
+		_interpolators[subject][property] = interpolator
+
+## Deregister all properties for a [param subject].
+func deregister(subject: Node) -> void:
+	_state_from.erase_subject(subject)
+	_state_to.erase_subject(subject)
+
+	_properties.erase_subject(subject)
+	_interpolators.erase(subject)
+
+	_enabled.erase(subject)
+	_recording_enabled.erase(subject)
+	_teleporting.erase(subject)
+
+## Return true if the [param subject] is registered.
+func has_subject(subject: Node) -> bool:
+	return _properties.has_subject(subject)
+
+## Enable or disable interpolation for a [param subject].
+## [br][br]
+## See [method is_enabled].
+func set_enabled(subject: Node, enabled: bool) -> void:
+	if enabled:
+		_enabled.add(subject)
+	else:
+		_enabled.erase(subject)
+
+## Return true if the [param subject] is enabled for interpolation.
+## [br][br]
+## If the subject is enabled, it will be interpolated between ticks.
+## [br][br]
+## See [method set_enabled].
+func is_enabled(subject: Node) -> bool:
+	return _enabled.has(subject)
+
+## Enable or disable automatic state recording for a [param subject].
+## [br][br]
+## See [method is_recording].
+func set_recording(subject: Node, enabled: bool) -> void:
+	if enabled:
+		_recording_enabled.add(subject)
+	else:
+		_recording_enabled.erase(subject)
+
+## Return true if the [param subject] is enabled for recording.
+## [br][br]
+## This means that the subject's interpolation states will be updated
+## automatically. Use [method push_state] to update manually.
+## [br][br]
+## See [method set_recording].
+func is_recording(subject: Node) -> bool:
+	return _recording_enabled.has(subject)
+
+## Return true if interpolation can be done for a [param subject].
+## [br][br]
+## May return false for multiple reasons - subject is unknown, not enabled for
+## interpolation, or is currently teleporting.
+func can_interpolate(subject: Node) -> bool:
+	if not has_subject(subject):
+		# Unknown subject, can't interpolate
+		return false
+	if not is_enabled(subject):
+		# Interpolation is disabled for subject
+		return false
+	if is_teleporting(subject):
+		# Subject is teleporting, just snap to target state
+		return false
+
+	return true
+
+## Record current state for interpolation.
+## [br][br]
+## Called automatically, unless disabled with [method set_recording].
+func push_state(subject: Node) -> void:
+	if not has_subject(subject):
+		_logger.warning("Trying to push state for unregistered subject %s", [subject])
+		return
+
+	# Copy to[subject] => from[subject]
+	_state_to.copy_subject_to(subject, _state_from)
+
+	# Capture current as to[subject]
+	_state_to.erase_subject(subject)
+	for property in _properties.get_properties_of(subject):
+		var value := subject.get_indexed(property)
+		if value == null:
+			# NOTE: This shouldn't happen?
+			_logger.warning("Captured null value for interpolation on %s:%s; either a bug or wrong usage", [subject, property])
+		else:
+			_state_to.set_property(subject, property, value)
+
+## Skip interpolation for this tick.
+func teleport(subject: Node) -> void:
+	if is_teleporting(subject):
+		return
+	if not has_subject(subject):
+		_logger.warning("Trying to teleport unregistered subject %s", [subject])
+		return
+
+	_teleporting.add(subject)
+
+## Return true if the [param subject] is currently teleporting.
+## [br][br]
+## See [method teleport].
+func is_teleporting(subject: Node) -> bool:
+	return _teleporting.has(subject)
+
+## Interpolate properties for a [param subject].
+## [br][br]
+## Called automatically by default.
+func interpolate_subject(subject: Node, factor: float) -> void:
+	if not can_interpolate(subject):
+		return
+
+	var interps := _interpolators.get(subject, {}) as Dictionary
+	if interps.is_empty():
+		_logger.debug("No interpolators found for %s", [subject])
+
+	for property in _properties.get_properties_of(subject):
+		if not _state_from.has_property(subject, property) or not _state_to.has_property(subject, property):
+			continue
+
+		var a = _state_from.get_property(subject, property)
+		var b = _state_to.get_property(subject, property)
+		var interpolator := interps.get(property, Interpolators.DEFAULT_INTERPOLATOR) as Interpolators.Interpolator
+
+		var value := interpolator.apply.call(a, b, factor)
+		subject.set_indexed(property, value)
+
+## Interpolate all registered subjects.
+## [br][br]
+## Called automatically by default.
+func interpolate(factor: float) -> void:
+	for subject in _properties.get_subjects():
+		interpolate_subject(subject, factor)
+
+func _clear_teleports() -> void:
+	_teleporting.clear()
+
+func _apply_target_state() -> void:
+	_state_to.apply()
+
+func _record_next_state() -> void:
+	for subject in _recording_enabled.values():
+		push_state(subject)