(#76) Implement tracks rendering

This is initial implementation of tracks rendering.
It is not 100%-compatible with the original simulator,
but still good enough for PoC.

Current implementation:

* adds TrackRenderingServer, which uses RenderingServer directly
* TrackRenderingServer is written in GDScript instead of PoC due to
  potential issues with memory management, which causes segfaults
* adds initial MaszynaTrack3D node for tracks placement
* adds initial MaszynaSwitch3D for junctions

Limitations:

* tracks are defined as Curve3D with multiple points,
  where the original simulator uses 2-point curves only per track
  segment; this is incompatible with Mover physics server
* junctions are defined as MaszynaSwitch3D, a separate nodes,
  where the original simulator uses for switches two curves per track
  with a common point; this is incompatible with Mover physics server
* common render settings like curve quality or smoothing should be
  implemented as project-wide settings

Co-authored-by: Marcin Nowak <marcin.j.nowak@gmail.com>

Author: JezSonic

AGENTS.md

@@ -0,0 +1,33 @@
+Planning and architectue:
+
+* apply separation of concerns
+
+Code generation:
+
+* Keep code clean and do minimal code changes
+* Follow DRY and KISS principles
+* use english comments (if needed)
+* GDSCRIPT: avoid type interference, use explicit type declaration
+
+General guidelines:
+
+* IMPORTANT: do only what operator want, do not assume anything by yourself!
+* if you are not sure, ask operator for decision
+
+Custom nodes and Godot Editor:
+
+* place editor related code in addons/libmaszyna/editor
+* use libmaszyna.gd just for bootstraping and proxying to editor plugins
+
+Documentation:
+
+* after changes update Godot documentation in `doc_classes`
+
+Build:
+
+* use cmake to build c++ extension (check Makefile and compile-debug target)
+
+Checks:
+
+* compile c++ plugin and check result
+* run Godot in headless mode outside sandbox, look for parse errors

addons/libmaszyna/libmaszyna.gd

@@ -9,6 +9,8 @@ var maszyna_environment_node_script = preload("res://addons/libmaszyna/environme
 var maszyna_environment_node_icon = preload("res://addons/libmaszyna/environment/maszyna_environment_node_icon.png")
 var e3d_model_instance_script = preload("res://addons/libmaszyna/e3d/e3d_model_instance.gd")
 var e3d_model_instance_icon = preload("res://addons/libmaszyna/e3d/e3d_model_instance.png")
+var maszyna_track_3d_script = preload("res://addons/libmaszyna/maszyna_track_3d.gd")
+var maszyna_switch_3d_script = preload("res://addons/libmaszyna/maszyna_switch_3d.gd")
 
 # Editor plugins
 
@@ -48,6 +50,21 @@ func _enter_tree():
     )
 
     ResourceLoader.add_resource_format_loader(e3d_loader)
+
+    add_custom_type(
+        "MaszynaTrack3D",
+        "Path3D",
+        maszyna_track_3d_script,
+        null
+    )
+
+    add_custom_type(
+        "MaszynaSwitch3D",
+        "Node3D",
+        maszyna_switch_3d_script,
+        null
+    )
+
     user_settings_dock = user_settings_dock_scene.instantiate()
     add_control_to_dock(DOCK_SLOT_RIGHT_UL, user_settings_dock)
 
@@ -62,6 +79,8 @@ func _exit_tree():
 
     remove_custom_type("E3DModelInstance")
     remove_custom_type("MaszynaEnvironmentNode")
+    remove_custom_type("MaszynaTrack3D")
+    remove_custom_type("MaszynaSwitch3D")
 
     remove_autoload_singleton("AudioStreamManager")
     remove_autoload_singleton("E3DModelInstanceManager")

addons/libmaszyna/maszyna_switch_3d.gd

@@ -0,0 +1,95 @@
+@tool
+extends Node3D
+class_name MaszynaSwitch3D
+
+enum SwitchState { STRAIGHT, DIVERGING }
+
+@export var state: SwitchState = SwitchState.STRAIGHT:
+    set(x):
+        state = x
+        _update_switch()
+
+@export_group("Tracks")
+@export var straight_track: MaszynaTrack3D:
+    set(x):
+        straight_track = x
+        update_configuration_warnings()
+        _update_switch()
+
+@export var diverging_track: MaszynaTrack3D:
+    set(x):
+        diverging_track = x
+        update_configuration_warnings()
+        _update_switch()
+
+@export var common_track: MaszynaTrack3D:
+    set(x):
+        common_track = x
+        update_configuration_warnings()
+        _update_switch()
+
+func _ready():
+    _update_switch()
+
+func _get_configuration_warnings():
+    var warnings = []
+    if not straight_track:
+        warnings.append("No straight track node assigned.")
+    if not diverging_track:
+        warnings.append("No diverging track node assigned.")
+    if not common_track:
+        warnings.append("No common track node assigned.")
+    
+    if straight_track and diverging_track and common_track:
+        if not straight_track.curve or not diverging_track.curve or not common_track.curve:
+            warnings.append("One or more tracks are missing curves.")
+        else:
+            var inlet_pos = _get_inlet_position()
+            var s_start = straight_track.to_global(straight_track.curve.get_point_position(0))
+            var s_end = straight_track.to_global(straight_track.curve.get_point_position(straight_track.curve.point_count - 1))
+            
+            if s_start.distance_to(inlet_pos) > 0.5 and s_end.distance_to(inlet_pos) > 0.5:
+                warnings.append("Straight track does not seem to connect to the switch inlet.")
+    
+    return warnings
+
+func _get_inlet_position() -> Vector3:
+    if common_track and common_track.curve:
+        # inlet is at the end of common track (usually)
+        return common_track.to_global(common_track.curve.get_point_position(common_track.curve.point_count - 1))
+    if straight_track and straight_track.curve:
+        # or at the start of straight track
+        return straight_track.to_global(straight_track.curve.get_point_position(0))
+    return global_position
+
+func resolve_track(incoming_track: Node3D) -> MaszynaTrack3D:
+    if incoming_track == common_track:
+        return straight_track if state == SwitchState.STRAIGHT else diverging_track
+    elif incoming_track == straight_track or incoming_track == diverging_track:
+        return common_track
+    return null
+
+func _update_switch():
+    if not is_inside_tree(): return
+    update_configuration_warnings()
+    
+    if common_track: _auto_link_track(common_track)
+    if straight_track: _auto_link_track(straight_track)
+    if diverging_track: _auto_link_track(diverging_track)
+
+func _auto_link_track(track: MaszynaTrack3D):
+    if not track or not track.curve: return
+    var inlet_pos = _get_inlet_position()
+    var p_start = track.to_global(track.curve.get_point_position(0))
+    var p_end = track.to_global(track.curve.get_point_position(track.curve.point_count - 1))
+    
+    # Only link the end that is actually AT the switch junction
+    if p_start.distance_to(inlet_pos) < 0.5:
+        if track.previous_track.is_empty():
+            track.previous_track = track.get_path_to(self)
+    elif p_end.distance_to(inlet_pos) < 0.5:
+        if track.next_track.is_empty():
+            track.next_track = track.get_path_to(self)
+
+func toggle():
+    state = SwitchState.DIVERGING if state == SwitchState.STRAIGHT else SwitchState.STRAIGHT

addons/libmaszyna/maszyna_switch_3d.gd.uid

@@ -0,0 +1 @@
+uid://bami2gx4l6pyl