Rename starter game files to demo game and added comments

Author: untoldengine

Sources/StarterGame/BallSystem.swift Sources/DemoGame/BallSystem.swiftSources/StarterGame/BallSystem.swift renamed to Sources/DemoGame/BallSystem.swift

@@ -8,109 +8,137 @@ import simd
 import SwiftUI
 import UntoldEngine
 
+// BallState represents the different states a ball can be in during gameplay.
+// This makes it easier to manage transitions like idle → kick → moving → decelerating.
 enum BallState: Codable {
     case idle
     case kick
     case moving
     case decelerating
 }
 
+// BallComponent is a custom ECS component that stores the ball's state and motion data.
+// Every entity with this component will behave like a ball in the game.
 public class BallComponent: Component, Codable {
-    var motionAccumulator: simd_float3 = .zero
-    var state: BallState = .idle
-    var velocity: simd_float3 = .zero
+    var motionAccumulator: simd_float3 = .zero   // Used to accumulate velocity for smoother force application
+    var state: BallState = .idle                 // Current state of the ball (idle, moving, etc.)
+    var velocity: simd_float3 = .zero            // Current velocity of the ball
     public required init() {}
 }
 
+// ballSystemUpdate runs once per frame and updates all entities that have a BallComponent.
+// This is where we apply physics, update states, and define how the ball behaves.
 public func ballSystemUpdate(deltaTime: Float) {
+    // Get the ID of the BallComponent so we can query entities that use it
     let customId = getComponentId(for: BallComponent.self)
     let entities = queryEntitiesWithComponentIds([customId], in: scene)
 
     for entity in entities {
         guard let ballComponent = scene.get(component: BallComponent.self, for: entity) else { continue }
 
+        // Apply drag to simulate resistance as the ball moves
         setLinearDragCoefficient(entityId: entity, coefficients: simd_float2(0.7, 0.0))
         setAngularDragCoefficient(entityId: entity, coefficients: simd_float2(0.07, 0.0))
 
+        // Update the ball based on its current state
         switch ballComponent.state {
         case .idle:
+            // Do nothing, the ball is at rest
             break
         case .kick:
+            // Transition to moving when the ball is kicked
             ballComponent.state = .moving
             applyVelocity(finalVelocity: ballComponent.velocity * 5.0, deltaTime: deltaTime, ball: entity)
         case .moving:
-
+            // If the velocity drops below a threshold, start decelerating
             if simd_length(getVelocity(entityId: entity)) <= 0.1 {
                 ballComponent.state = .decelerating
             }
         case .decelerating:
+            // Gradually slow down the ball
             decelerate(deltaTime: deltaTime, ball: entity)
-            if simd_length(getVelocity(entityId: entity)) < 0.1 {}
+            if simd_length(getVelocity(entityId: entity)) < 0.1 {
+                // You could transition back to .idle here if desired
+            }
         }
     }
 }
 
+// Apply a force to the ball to simulate a kick or strong push.
+// Uses an accumulator to smooth motion and applies both linear and angular forces.
 func applyVelocity(finalVelocity: simd_float3, deltaTime: Float, ball: EntityID) {
     guard let customComponent = scene.get(component: BallComponent.self, for: ball) else { return }
 
     let mass: Float = getMass(entityId: ball)
     let ballDim = getDimension(entityId: ball)
+
+    // Blend previous motion with new input for smoother physics
     let bias: Float = 0.4
     let vComp: simd_float3 = finalVelocity * (1.0 - bias)
     customComponent.motionAccumulator = customComponent.motionAccumulator * bias + vComp
 
+    // Apply linear force based on mass and deltaTime
     var force: simd_float3 = (customComponent.motionAccumulator * mass) / deltaTime
     applyForce(entityId: ball, force: force)
 
+    // Apply angular force so the ball spins as it moves
     let upAxis = simd_float3(0.0, ballDim.depth / 2.0, 0.0)
-
     force *= 0.25
-
     applyMoment(entityId: ball, force: force, at: upAxis)
 
+    // Reset velocity so physics is only applied through forces
     clearVelocity(entityId: ball)
     clearAngularVelocity(entityId: ball)
 }
 
+// Gradually slow down the ball by applying counter-forces.
+// Works similarly to applyVelocity, but reduces motion instead of adding it.
 func decelerate(deltaTime: Float, ball: EntityID) {
     guard let customComponent = scene.get(component: BallComponent.self, for: ball) else { return }
 
     let ballDim = getDimension(entityId: ball)
     let velocity: simd_float3 = getVelocity(entityId: ball)
+
+    // Blend down velocity for smoother deceleration
     let bias: Float = 0.5
     let vComp: simd_float3 = velocity * (1.0 - bias)
     customComponent.motionAccumulator = customComponent.motionAccumulator * bias + vComp
 
+    // Apply counter-force to slow down
     var force: simd_float3 = (customComponent.motionAccumulator * getMass(entityId: ball)) / deltaTime
     force *= 0.15
     applyForce(entityId: ball, force: force)
 
+    // Apply spin reduction
     let upAxis = simd_float3(0.0, ballDim.depth / 2.0, 0.0)
-
     force *= 0.25
-
     applyMoment(entityId: ball, force: force, at: upAxis)
 
+    // Clear velocity so deceleration is handled through applied forces
     clearVelocity(entityId: ball)
     clearAngularVelocity(entityId: ball)
 }
 
+// BallComponent_Editor integrates the BallComponent with the Editor.
+// This makes the component visible and editable in the UI.
 var BallComponent_Editor: ComponentOption_Editor = .init(
     id: getComponentId(for: BallComponent.self),
     name: "Ball Component",
     type: BallComponent.self,
     view: makeEditorView(fields: [
-        .text(label: "Ball Component",
-              placeholder: "Entity name",
-              get: { entityId in
-                  getEntityName(entityId: entityId) ?? "None"
-              },
-              set: { entityId, targetName in
-                  setEntityName(entityId: entityId, name: targetName)
-              }),
-
+        .text(
+            label: "Ball Component",
+            placeholder: "Entity name",
+            get: { entityId in
+                getEntityName(entityId: entityId) ?? "None"
+            },
+            set: { entityId, targetName in
+                setEntityName(entityId: entityId, name: targetName)
+            }
+        ),
     ]),
     onAdd: { entityId in
+        // When a BallComponent is added in the Editor, register it with the entity
         registerComponent(entityId: entityId, componentType: BallComponent.self)
     }
 )

Sources/StarterGame/CameraFollow.swift Sources/DemoGame/CameraFollow.swiftSources/StarterGame/CameraFollow.swift renamed to Sources/DemoGame/CameraFollow.swift

@@ -10,47 +10,68 @@ import simd
 import SwiftUI
 import UntoldEngine
 
+// CameraFollowComponent defines how a camera should follow a target entity.
+// It stores the name of the target and the offset from that target.
+// This makes it possible to create a third-person or top-down camera easily.
 public class CameraFollowComponent: Component, Codable {
-    var targetName: String = "nil"
-    var offset: simd_float3 = .zero
+    var targetName: String = "nil"      // The name of the entity the camera should follow
+    var offset: simd_float3 = .zero     // The offset position relative to the target
     public required init() {}
 }
 
+// -----------------------------------------------------------------------------
+// Helper functions for accessing and modifying CameraFollowComponent values
+// -----------------------------------------------------------------------------
+
 func getOffsetTarget(entityId: EntityID) -> simd_float3 {
     guard let cameraFollowComponent = scene.get(component: CameraFollowComponent.self, for: entityId) else { return .zero }
-
     return cameraFollowComponent.offset
 }
 
 func setOffsetTarget(entityId: EntityID, offset: simd_float3) {
     guard let cameraFollowComponent = scene.get(component: CameraFollowComponent.self, for: entityId) else { return }
-
     cameraFollowComponent.offset = offset
 }
 
 func getTargetName(entityId: EntityID) -> String? {
     guard let cameraFollowComponent = scene.get(component: CameraFollowComponent.self, for: entityId) else { return nil }
-
     return cameraFollowComponent.targetName
 }
 
 func setTargetName(entityId: EntityID, name: String) {
     guard let cameraFollowComponent = scene.get(component: CameraFollowComponent.self, for: entityId) else { return }
-
     cameraFollowComponent.targetName = name
 }
 
+// -----------------------------------------------------------------------------
+// Camera Follow System
+// Updates all entities with a CameraFollowComponent once per frame.
+// Calls the cameraFollow function to smoothly track the target entity.
+// -----------------------------------------------------------------------------
+
 public func cameraFollowUpdate(deltaTime _: Float) {
     let customId = getComponentId(for: CameraFollowComponent.self)
     let entities = queryEntitiesWithComponentIds([customId], in: scene)
 
     for entity in entities {
         guard let cameraFollowComponent = scene.get(component: CameraFollowComponent.self, for: entity) else { continue }
 
-        cameraFollow(entityId: entity, targetName: cameraFollowComponent.targetName, offset: cameraFollowComponent.offset, smoothSpeed: 0.5, alignWithOrientation: false)
+        cameraFollow(
+            entityId: entity,
+            targetName: cameraFollowComponent.targetName,
+            offset: cameraFollowComponent.offset,
+            smoothSpeed: 0.5,
+            alignWithOrientation: false
+        )
     }
 }
 
+// -----------------------------------------------------------------------------
+// Core camera follow logic
+// Moves the camera smoothly to follow the target and optionally aligns its
+// orientation with the target’s forward direction.
+// -----------------------------------------------------------------------------
+
 func cameraFollow(
     entityId: EntityID,
     targetName: String,
@@ -61,78 +82,78 @@ func cameraFollow(
     lockZAxis: Bool = false,
     alignWithOrientation: Bool = true
 ) {
+    // Ensure the entity has a CameraComponent
     guard let cameraComponent = scene.get(component: CameraComponent.self, for: entityId) else {
         return
     }
 
+    // Find the target entity by name
     guard let targetId: EntityID = findEntity(name: targetName) else {
         return
     }
 
     // Get the target's position and orientation
     var targetPosition: simd_float3 = UntoldEngine.getPosition(entityId: targetId)
     let targetOrientation: simd_float3x3 = UntoldEngine.getOrientation(entityId: targetId) // Rotation matrix
-
     var cameraPosition = cameraComponent.localPosition
 
-    // Apply axis locking to the target position
+    // Apply axis locking (keeps the camera fixed on chosen axes)
     if lockXAxis { targetPosition.x = cameraPosition.x }
     if lockYAxis { targetPosition.y = cameraPosition.y }
     if lockZAxis { targetPosition.z = cameraPosition.z }
 
-    // Calculate the offset relative to the entity's orientation
+    // Adjust offset based on orientation if requested
     var adjustedOffset = offset
     if alignWithOrientation {
-        // Rotate the offset vector using the 3x3 rotation matrix
+        // Rotate the offset by the target's orientation matrix
         adjustedOffset = targetOrientation * offset
     }
 
-    // Calculate the desired position by applying the adjusted offset
+    // Calculate where the camera *wants* to be
     let desiredPosition: simd_float3 = targetPosition + adjustedOffset
 
-    // Smoothly interpolate the camera position towards the desired position
+    // Smoothly interpolate from the current camera position to the desired position
     cameraPosition = lerp(start: cameraPosition, end: desiredPosition, t: smoothSpeed)
 
-    // Move the camera to the new position
+    // Move the camera to its new position
     moveCameraTo(entityId: entityId, cameraPosition.x, cameraPosition.y, cameraPosition.z)
 
-    // Align the camera's view direction using lookAt
+    // Orient the camera towards the target if enabled
     if alignWithOrientation {
-        // Calculate the forward direction of the entity
-        let _: simd_float3 = targetOrientation * simd_float3(0, 0, 1) // Forward direction in local space
+        // Forward direction of the target
+        let _: simd_float3 = targetOrientation * simd_float3(0, 0, 1)
 
-        // Determine the "up" vector (you might need to adjust this based on your engine's coordinate system)
-        let up: simd_float3 = targetOrientation * simd_float3(0, 1, 0) // Transform the local up vector by the orientation
+        // Up vector (adjust depending on coordinate system)
+        let up: simd_float3 = targetOrientation * simd_float3(0, 1, 0)
 
-        // Use lookAt to orient the camera towards the target's forward direction
+        // Look at the target from the camera’s position
         cameraLookAt(entityId: entityId, eye: cameraPosition, target: targetPosition, up: up)
     }
 }
 
+// -----------------------------------------------------------------------------
+// Editor Integration
+// Makes CameraFollowComponent visible in the Editor (Inspector panel).
+// -----------------------------------------------------------------------------
+
 var CameraFollowComponent_Editor: ComponentOption_Editor = .init(
     id: getComponentId(for: CameraFollowComponent.self),
     name: "Camera Follow",
     type: CameraFollowComponent.self,
     view: makeEditorView(fields: [
+        // Editable field for selecting the target entity by name
         .text(label: "Target Name",
               placeholder: "Entity name",
-              get: { entityId in
-                  getTargetName(entityId: entityId) ?? "None"
-              },
-              set: { entityId, targetName in
-                  setTargetName(entityId: entityId, name: targetName)
-              }),
+              get: { entityId in getTargetName(entityId: entityId) ?? "None" },
+              set: { entityId, targetName in setTargetName(entityId: entityId, name: targetName) }),
 
+        // Editable field for the follow offset
         .vector3(label: "Offset",
-                 get: { entityId in
-                     getOffsetTarget(entityId: entityId)
-                 },
-                 set: { entityId, newOffset in
-                     setOffsetTarget(entityId: entityId, offset: newOffset)
-                 }),
-
+                 get: { entityId in getOffsetTarget(entityId: entityId) },
+                 set: { entityId, newOffset in setOffsetTarget(entityId: entityId, offset: newOffset) }),
     ]),
     onAdd: { entityId in
+        // When added in the Editor, register this component with the entity
         registerComponent(entityId: entityId, componentType: CameraFollowComponent.self)
     }
 )