From 9defec8448c44468462bd224571b5afca7258e65 Mon Sep 17 00:00:00 2001 From: Marto Date: Wed, 29 Apr 2026 16:04:32 +0200 Subject: [PATCH] Comments to describe each functionality in-depth --- src/infrastructure/node_manager.zig | 11 +++++++++++ src/infrastructure/road_manager.zig | 11 +++++++++++ src/simulator.zig | 17 +++++++++++++++++ 3 files changed, 39 insertions(+) diff --git a/src/infrastructure/node_manager.zig b/src/infrastructure/node_manager.zig index f8a244e..f57231e 100644 --- a/src/infrastructure/node_manager.zig +++ b/src/infrastructure/node_manager.zig @@ -7,10 +7,14 @@ const Node = @import("node.zig").Node; const Road = @import("road.zig").Road; pub const NodeManager = struct { + /// Tracks which ID the next added node will get next_id: usize, + /// Tracks all the node (pointers) nodes: std.ArrayList(*Node), + /// Tracks the temporary node, being part of the newly built road temp_node: ?*Node, + /// Constructor (for convenience) pub fn init() NodeManager { return .{ .next_id = 0, @@ -19,6 +23,7 @@ pub const NodeManager = struct { }; } + /// Deinitialises every node (pointer) within the list and then deinits the list containing the nodes itself pub fn deinit(self: *NodeManager, allocator: std.mem.Allocator) !void { for (self.nodes.items) |node| { try node.deinit(allocator); @@ -26,6 +31,7 @@ pub const NodeManager = struct { self.nodes.deinit(allocator); } + /// Regular draw function pub fn draw(self: *const NodeManager, pos: Vector2) void { for (self.nodes.items) |node| { node.draw(null); @@ -43,6 +49,8 @@ pub const NodeManager = struct { } } + /// Checks if there is a node pointer within the snap radius of pos coordinate; + /// otherwise creates a new node and returns its pointer pub fn getSelectedNode(self: *NodeManager, allocator: std.mem.Allocator, pos: Vector2) !*Node { for (self.nodes.items) |node| { if (node.posWithinRadius(pos)) return node; @@ -57,6 +65,7 @@ pub const NodeManager = struct { return self.nodes.items[self.nodes.items.len - 1]; } + /// Gets next id, resets only on clear() fn getNextID(self: *NodeManager) usize { const id = self.next_id; self.next_id += 1; @@ -64,6 +73,7 @@ pub const NodeManager = struct { return id; } + /// Clears all existing nodes connected, not deinitialisation pub fn clear(self: *NodeManager, allocator: std.mem.Allocator) !void { self.temp_node = null; for (self.nodes.items) |node| { @@ -73,6 +83,7 @@ pub const NodeManager = struct { self.next_id = 0; } + /// Deletes node, returns error if node still has road references pub fn deleteNode(self: *NodeManager, allocator: std.mem.Allocator, node_to_delete: *Node) !void { if (node_to_delete.roads.items.len != 0) return e.Entity.HasReferences; diff --git a/src/infrastructure/road_manager.zig b/src/infrastructure/road_manager.zig index 5f5f05f..26ab41b 100644 --- a/src/infrastructure/road_manager.zig +++ b/src/infrastructure/road_manager.zig @@ -17,6 +17,7 @@ pub const RoadManager = struct { }; } + /// Deinitialises every road (pointer) and then the list itself pub fn deinit(self: *RoadManager, allocator: std.mem.Allocator) void { for (self.roads.items) |road| { road.deinit(allocator); @@ -24,6 +25,7 @@ pub const RoadManager = struct { self.roads.deinit(allocator); } + /// Draws all the roads in the list, sends the information ahead whether the road drawn should be highlighted pub fn draw(self: *const RoadManager, delete_mode: bool) void { for (self.roads.items) |road| { const is_highlighted = delete_mode and self.highlighted_road != null and self.highlighted_road.? == road; @@ -31,6 +33,8 @@ pub const RoadManager = struct { } } + /// Function which creates the road object, its pointer, adds it to the list + /// and then also references that same road to the bounding nodes pub fn addRoad(self: *RoadManager, allocator: std.mem.Allocator, start: *Node, end: *Node) !void { const road: Road = .init(self.getNextID(), start, end); const road_ptr = try allocator.create(Road); @@ -42,6 +46,7 @@ pub const RoadManager = struct { try end.referenceRoad(allocator, ref); } + /// Returns the id, and increases it by one; used for generating ID's for new entities fn getNextID(self: *RoadManager) usize { const id = self.next_id; self.next_id += 1; @@ -49,6 +54,7 @@ pub const RoadManager = struct { return id; } + /// Deinits all the roads, clears them but not deiniting the list itself; also resets the next ID var pub fn clear(self: *RoadManager, allocator: std.mem.Allocator) void { for (self.roads.items) |road| { road.deinit(allocator); @@ -57,6 +63,11 @@ pub const RoadManager = struct { self.next_id = 0; } + /// Removes the references of the road, from the nodes that bound that road + /// + /// Then it deinitialises the road and removes it from the list + /// + /// Will return an error if the road itself is not present in the list pub fn deleteRoad(self: *RoadManager, allocator: std.mem.Allocator, road_to_delete: *Road) !void { // unreference the road from its bounding functions road_to_delete.unreferenceNodes() catch |err| { diff --git a/src/simulator.zig b/src/simulator.zig index f050c5c..2289958 100644 --- a/src/simulator.zig +++ b/src/simulator.zig @@ -6,13 +6,20 @@ const NodeManager = @import("infrastructure/node_manager.zig").NodeManager; const RoadManager = @import("infrastructure/road_manager.zig").RoadManager; pub const Simulator = struct { + /// allocator for convenience allocator: std.mem.Allocator, + /// 'class' tracking all the nodes (and appropriate functions) node_man: NodeManager, + /// 'class' tracking all the roads (and appropriate functions) road_man: RoadManager, // vars + /// Tracks whether next road will start building from the node the last road was built at auto_continue: bool, + /// Tracks whether the system will delete the road cursor is pointed at + /// (in such case, the road-to-be-deleted will also be highlighted) delete_mode: bool, + /// Constructor for convenience pub fn init(new_allocator: std.mem.Allocator) Simulator { return .{ .allocator = new_allocator, @@ -23,11 +30,13 @@ pub const Simulator = struct { }; } + /// Deinitialisation of node and road objects pub fn deinit(self: *Simulator) !void { self.road_man.deinit(self.allocator); try self.node_man.deinit(self.allocator); } + /// Main draw function exposed to RayLib's loop pub fn draw(self: *const Simulator, pos: rl.Vector2) void { rl.clearBackground(c.BACKGROUND_COLOR); @@ -35,15 +44,18 @@ pub const Simulator = struct { self.node_man.draw(pos); } + /// Update tick pub fn update(self: *Simulator, pos: rl.Vector2) void { self.road_man.update_highlighted_road(pos); } + /// Exposed input handling function exposed to raylib pub fn handleInput(self: *Simulator, pos: rl.Vector2) void { self.handleKeyboardInput(); self.handleMouseInput(pos); } + /// Sub input handling function for keyboard input only fn handleKeyboardInput(self: *Simulator) void { self.auto_continue = rl.isKeyDown(.left_control); self.delete_mode = rl.isKeyDown(.left_shift); @@ -53,10 +65,12 @@ pub const Simulator = struct { }; } + /// Sub input handling function for mouse input only fn handleMouseInput(self: *Simulator, pos: rl.Vector2) void { if (rl.isMouseButtonReleased(.left)) self.leftClickEvent(pos); } + /// Function that handles functionality that executes upon left click fn leftClickEvent(self: *Simulator, pos: rl.Vector2) void { if (self.delete_mode) { self.delete_road() catch |err| { @@ -67,6 +81,7 @@ pub const Simulator = struct { self.new_road(pos); } + /// User initiated road building functionality fn new_road(self: *Simulator, pos: rl.Vector2) void { const cur_node = self.node_man.getSelectedNode(self.allocator, pos) catch |err| { std.debug.panic("Failed to append the newly created node at pos ({d}, {d}) to node list: {}\n", .{ @@ -87,6 +102,7 @@ pub const Simulator = struct { self.node_man.temp_node = cur_node; } + /// User initiated road destroying functionality fn delete_road(self: *Simulator) !void { if (self.road_man.highlighted_road == null) return; const h_road = self.road_man.highlighted_road.?; @@ -106,6 +122,7 @@ pub const Simulator = struct { try self.node_man.deleteNode(self.allocator, end_node); } + /// Clearing node and road lists without deinitialising them (only the children) fn clear(self: *Simulator) !void { self.road_man.clear(self.allocator); try self.node_man.clear(self.allocator);