From fe21b7a3725240d0f44291f6a2830e125e1c010a Mon Sep 17 00:00:00 2001 From: harrison Date: Thu, 23 Oct 2025 17:55:41 +0000 Subject: [PATCH] Update planning/UTILITY_PLANNING.md --- planning/UTILITY_PLANNING.md | 279 +++++++++++++++-------------------- 1 file changed, 123 insertions(+), 156 deletions(-) diff --git a/planning/UTILITY_PLANNING.md b/planning/UTILITY_PLANNING.md index fa7853f..9075889 100644 --- a/planning/UTILITY_PLANNING.md +++ b/planning/UTILITY_PLANNING.md @@ -19,7 +19,6 @@ This document outlines a strategic plan for building a comprehensive C# library - **Refactor When Needed**: Don't be afraid to improve APIs based on usage experience ### 3. Real-World Validation -- **Build Small Games**: Create tiny games to test each library combination - **Iterative Improvement**: Refine APIs based on actual usage - **Performance Monitoring**: Profile libraries in real game scenarios @@ -29,10 +28,12 @@ This document outlines a strategic plan for building a comprehensive C# library These libraries form the bedrock of your game development ecosystem. They have minimal dependencies and provide essential functionality that nearly all other systems will use. -#### 1.1 EinSoftworks.Input -**Priority:** 🔴 Critical - Build First -**Dependencies:** EinSoftworks.Utilities only -**Estimated Timeline:** 1-2 weeks +#### 1.1 - EinSoftworks.Input +| | | | +|--------------|----|-----------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🔴 | Critical | +| Dependencies | ⚫ | EinSoftworks.Utilities only | **Why Build First:** - Nearly every game system needs input handling @@ -78,10 +79,12 @@ public class InputBuffer - Menu navigation system - Basic interaction system (press E to interact) -#### 1.2 EinSoftworks.Events -**Priority:** 🔴 Critical - Build Second -**Dependencies:** EinSoftworks.Utilities only -**Estimated Timeline:** 1 week +#### 1.2 - EinSoftworks.Events +| | | | +|--------------|----|-----------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🔴 | Critical | +| Dependencies | ⚫ | EinSoftworks.Utilities only | **Why Build Second:** - Essential for decoupling systems @@ -132,10 +135,12 @@ public class PooledEvent where T : class, new() - Health system that updates UI without direct references - Scene transition system using events -#### 1.3 EinSoftworks.StateManagement -**Priority:** 🔴 Critical - Build Third -**Dependencies:** EinSoftworks.Utilities, EinSoftworks.Events -**Estimated Timeline:** 1-2 weeks +#### 1.3 - EinSoftworks.StateManagement +| | | | +|--------------|----|---------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🔴 | Critical | +| Dependencies | ⚫ | EinSoftworks.Utilities, EinSoftworks.Events | **Why Build Third:** - State management is fundamental to game logic @@ -194,66 +199,14 @@ public class HierarchicalStateMachine : StateMachine where T : class These libraries provide essential 3D game functionality and build upon the foundation libraries. -#### 2.1 EinSoftworks.Physics -**Priority:** 🟡 High -**Dependencies:** EinSoftworks.Utilities, EinSoftworks.Events -**Estimated Timeline:** 1-2 weeks +#### 2.1 - EinSoftworks.Camera +| | | | +|--------------|----|-----------------------------------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🟡 | High | +| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.Events, EinSoftworks.StateManagement | **Why Build Fourth:** -- Nearly all 3D games need physics utilities -- Independent of complex game systems -- Provides foundation for character controllers and interaction systems -- Can be validated independently - -**Core Features:** -```csharp -// Raycast utilities -public static class PhysicsUtils -{ - public static bool Raycast(Vector3 origin, Vector3 direction, float maxDistance, - uint collisionMask = uint.MaxValue); - public static RaycastHit RaycastWithInfo(Vector3 origin, Vector3 direction, float maxDistance); - public static RaycastHit[] RaycastAll(Vector3 origin, Vector3 direction, float maxDistance); - - // Shape casting - public static bool SphereCast(Vector3 origin, float radius, Vector3 direction, float maxDistance); - public static bool BoxCast(Vector3 origin, Vector3 size, Vector3 direction, float maxDistance); - - // Overlap detection - public static Node3D[] OverlapSphere(Vector3 center, float radius, uint collisionMask); - public static Node3D[] OverlapBox(Vector3 center, Vector3 size, uint collisionMask); -} - -// Physics materials management -public class PhysicsMaterialManager : Node -{ - public void RegisterMaterial(string name, PhysicsMaterial material); - public PhysicsMaterial GetMaterial(string name); - public void ApplyMaterial(RigidBody3D body, string materialName); -} - -// Trigger volume system -public partial class TriggerVolume : Area3D -{ - [Signal] public delegate void BodyEnteredEventHandler(Node3D body); - [Signal] public delegate void BodyExitedEventHandler(Node3D body); - - public bool IsBodyInside(Node3D body); - public Node3D[] GetBodiesInside(); -} -``` - -**Validation Game Ideas:** -- Character that detects ground beneath them -- Interaction system using raycasts -- Trigger volumes that activate when player enters - -#### 2.2 EinSoftworks.Camera -**Priority:** 🟡 High -**Dependencies:** EinSoftworks.Input, EinSoftworks.Events, EinSoftworks.StateManagement -**Estimated Timeline:** 2-3 weeks - -**Why Build Fifth:** - Essential for any 3D game - Benefits from input system for camera controls - Can use state management for different camera modes @@ -315,14 +268,72 @@ public class OrbitCamera : CameraController - Third-person camera that follows a moving object - Orbit camera for examining 3D models +#### 2.2 - EinSoftworks.Physics +| | | | +|--------------|----|---------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🟡 | High | +| Dependencies | ⚫ | EinSoftworks.Utilities, EinSoftworks.Events | + +**Why Build Fifth:** +- Nearly all 3D games need physics utilities +- Independent of complex game systems +- Provides foundation for character controllers and interaction systems +- Can be validated independently + +**Core Features:** +```csharp +// Raycast utilities +public static class PhysicsUtils +{ + public static bool Raycast(Vector3 origin, Vector3 direction, float maxDistance, + uint collisionMask = uint.MaxValue); + public static RaycastHit RaycastWithInfo(Vector3 origin, Vector3 direction, float maxDistance); + public static RaycastHit[] RaycastAll(Vector3 origin, Vector3 direction, float maxDistance); + + // Shape casting + public static bool SphereCast(Vector3 origin, float radius, Vector3 direction, float maxDistance); + public static bool BoxCast(Vector3 origin, Vector3 size, Vector3 direction, float maxDistance); + + // Overlap detection + public static Node3D[] OverlapSphere(Vector3 center, float radius, uint collisionMask); + public static Node3D[] OverlapBox(Vector3 center, Vector3 size, uint collisionMask); +} + +// Physics materials management +public class PhysicsMaterialManager : Node +{ + public void RegisterMaterial(string name, PhysicsMaterial material); + public PhysicsMaterial GetMaterial(string name); + public void ApplyMaterial(RigidBody3D body, string materialName); +} + +// Trigger volume system +public partial class TriggerVolume : Area3D +{ + [Signal] public delegate void BodyEnteredEventHandler(Node3D body); + [Signal] public delegate void BodyExitedEventHandler(Node3D body); + + public bool IsBodyInside(Node3D body); + public Node3D[] GetBodiesInside(); +} +``` + +**Validation Game Ideas:** +- Character that detects ground beneath them +- Interaction system using raycasts +- Trigger volumes that activate when player enters + ### Phase 3: Character and Interaction Systems (Medium Priority) These systems focus on character control and world interaction, building upon the previously established libraries. -#### 3.1 EinSoftworks.Movement -**Priority:** 🟡 Medium-High -**Dependencies:** EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.StateManagement, EinSoftworks.Events -**Estimated Timeline:** 2-4 weeks +#### 3.1 - EinSoftworks.Movement +| | | | +|--------------|----|---------------------------------------------------------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🟡 | High | +| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.StateManagement, EinSoftworks.Events | **Why Build Sixth:** - Core to most 3D games @@ -394,10 +405,12 @@ public class ThirdPersonController : CharacterController3D - Third-person character that rotates to movement direction - Platformer character with precise jumping mechanics -#### 3.2 EinSoftworks.Interaction -**Priority:** 🟡 Medium -**Dependencies:** EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.Events -**Estimated Timeline:** 1-2 weeks +#### 3.2 - EinSoftworks.Interaction +| | | | +|--------------|----|---------------------------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🟡 | Medium | +| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.Events | **Why Build Seventh:** - Common need in 3D games @@ -465,10 +478,12 @@ public class Door : Interactable These systems provide advanced functionality for complete games and can be built once the core systems are stable. -#### 4.1 EinSoftworks.SceneManagement -**Priority:** 🟢 Medium-Low -**Dependencies:** EinSoftworks.StateManagement, EinSoftworks.Events -**Estimated Timeline:** 2-3 weeks +#### 4.1 - EinSoftworks.SceneManagement +| | | | +|--------------|----|---------------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🟢 | Medium-Low | +| Dependencies | ⚫ | EinSoftworks.StateManagement, EinSoftworks.Events | **Core Features:** ```csharp @@ -487,10 +502,12 @@ public class SceneManager : Node } ``` -#### 4.2 EinSoftworks.SaveSystem -**Priority:** 🟢 Medium-Low -**Dependencies:** EinSoftworks.StateManagement, EinSoftworks.SceneManagement -**Estimated Timeline:** 2-3 weeks +#### 4.2 - EinSoftworks.SaveSystem +| | | | +|--------------|----|------------------------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🟢 | Medium-Low | +| Dependencies | ⚫ | EinSoftworks.StateManagement, EinSoftworks.SceneManagement | **Core Features:** ```csharp @@ -513,10 +530,12 @@ public interface ISaveable } ``` -#### 4.3 EinSoftworks.UI -**Priority:** 🟢 Low -**Dependencies:** EinSoftworks.Input, EinSoftworks.StateManagement, EinSoftworks.Events -**Estimated Timeline:** 3-4 weeks +#### 4.3 - EinSoftworks.UI +| | | | +|--------------|----|-----------------------------------------------------------------------| +| Status | 🔴 | Incomplete | +| Priority | 🟢 | Low | +| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.StateManagement, EinSoftworks.Events | **Core Features:** ```csharp @@ -536,7 +555,9 @@ public class UIManager : Control ### Getting Started Checklist -**Week 1-2: EinSoftworks.Input** +Some high level checklist items to maybe follow while building these out. + +**EinSoftworks.Input** - [ ] Set up library repository structure - [ ] Implement basic action queries (IsActionPressed, etc.) - [ ] Add input mapping and saving/loading @@ -545,7 +566,7 @@ public class UIManager : Control - [ ] Document all public APIs - [ ] Test with multiple input devices -**Week 3: EinSoftworks.Events** +**EinSoftworks.Events** - [ ] Implement global event system - [ ] Create type-safe event bus - [ ] Add event pooling for performance @@ -553,7 +574,7 @@ public class UIManager : Control - [ ] Document event naming conventions - [ ] Test event performance under load -**Week 4-5: EinSoftworks.StateManagement** +**EinSoftworks.StateManagement** - [ ] Implement generic state machine - [ ] Add transition system with conditions - [ ] Create hierarchical state support @@ -561,7 +582,7 @@ public class UIManager : Control - [ ] Document state design patterns - [ ] Test state machine performance -**Week 6-7: EinSoftworks.Physics** +**EinSoftworks.Physics** - [ ] Implement raycast utilities - [ ] Add shape casting methods - [ ] Create trigger volume system @@ -569,7 +590,7 @@ public class UIManager : Control - [ ] Document physics best practices - [ ] Test physics performance -**Week 8-10: EinSoftworks.Camera** +**EinSoftworks.Camera** - [ ] Implement base camera controller - [ ] Add specialized camera types (FPS, 3rd person, orbit) - [ ] Create camera effects (shake, zoom) @@ -577,50 +598,21 @@ public class UIManager : Control - [ ] Document camera usage patterns - [ ] Test camera smoothness and responsiveness -### Quality Assurance Process - -#### For Each Library: - -1. **API Design Review** - - Is the API intuitive and consistent? - - Are there any obvious missing features? - - Does it follow C# naming conventions? - -2. **Dependency Check** - - Does it only depend on earlier libraries in the plan? - - Are there any circular dependencies? - - Can dependencies be reduced without losing functionality? - -3. **Performance Testing** - - Profile the library in a realistic game scenario - - Identify and optimize any performance bottlenecks - - Ensure memory allocation is minimal during gameplay - -4. **Integration Testing** - - Build a small game that uses multiple libraries together - - Verify that libraries work well in combination - - Test edge cases and error conditions - -5. **Documentation Review** - - Are all public APIs documented? - - Are there usage examples for complex features? - - Is the library architecture clearly explained? - ### Validation Games Strategy -Create small, focused games to test each library combination: +Perhaps create small, focused games to test each library combination: -#### Foundation Tests (Weeks 1-5) +#### Foundation Tests - **Input Test**: Character that responds to all input types - **Event Test**: Multiple systems communicating via events - **State Test**: Character with idle/walk/run/jump states -#### Integration Tests (Weeks 6-10) +#### Integration Tests - **Physics Test**: Character with ground detection and jumping - **Camera Test**: Switching between camera modes - **Combined Test**: Third-person character with camera following -#### Advanced Tests (Weeks 11+) +#### Advanced Tests - **Movement Test**: Full 3D character controller - **Interaction Test**: World with pickups and doors - **Complete Game**: Small game using all built libraries @@ -657,36 +649,11 @@ public class CharacterController3D : CharacterBody3D { } - Profile and optimize only when needed - Don't sacrifice clarity for minor performance gains -### Success Metrics - -#### Per Library: -- [ ] API is intuitive and well-documented -- [ ] Zero dependencies on later libraries -- [ ] Validation game demonstrates all major features -- [ ] Performance is acceptable for real games -- [ ] Code coverage > 80% through validation games - -#### Overall Ecosystem: -- [ ] Can build a complete 3D game using only these libraries -- [ ] Libraries work well together without conflicts -- [ ] Development time significantly reduced for new projects -- [ ] Other developers can understand and use the libraries - ## Long-Term Maintenance ### Versioning Strategy - Use semantic versioning (major.minor.patch) -- Major version changes for breaking API changes -- Minor version changes for new features -- Patch version changes for bug fixes +- Hardcore versioning adhearance probably isn't necessary... should roughly keep versioning schema going just in case. -### Backward Compatibility -- Maintain backward compatibility within major versions -- Provide migration guides for major version upgrades -- Deprecate features before removing them - -### Community and Documentation +### Documentation - Maintain comprehensive documentation -- Create tutorial projects demonstrating library usage -- Establish contribution guidelines if open-sourcing -- Regular review and updates based on real-world usage