harrison/documentation
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update planning/UTILITY_PLANNING.md

Browse Source
This commit is contained in:
harrison
2025-10-23 17:55:41 +00:00
parent def25d7ae8
commit fe21b7a372
1 changed files with 123 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
planning/UTILITY_PLANNING.md
View File

@@ -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 - **Refactor When Needed**: Don't be afraid to improve APIs based on usage experience
### 3. Real-World Validation ### 3. Real-World Validation
- **Build Small Games**: Create tiny games to test each library combination
- **Iterative Improvement**: Refine APIs based on actual usage - **Iterative Improvement**: Refine APIs based on actual usage
- **Performance Monitoring**: Profile libraries in real game scenarios - **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. 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 #### 1.1 - EinSoftworks.Input
**Priority:** 🔴 Critical - Build First | | | |
**Dependencies:** EinSoftworks.Utilities only |--------------|----|-----------------------------|
**Estimated Timeline:** 1-2 weeks | Status | 🔴 | Incomplete |
| Priority | 🔴 | Critical |
| Dependencies | ⚫ | EinSoftworks.Utilities only |
**Why Build First:** **Why Build First:**
- Nearly every game system needs input handling - Nearly every game system needs input handling
@@ -78,10 +79,12 @@ public class InputBuffer
- Menu navigation system - Menu navigation system
- Basic interaction system (press E to interact) - Basic interaction system (press E to interact)
#### 1.2 EinSoftworks.Events #### 1.2 - EinSoftworks.Events
**Priority:** 🔴 Critical - Build Second | | | |
**Dependencies:** EinSoftworks.Utilities only |--------------|----|-----------------------------|
**Estimated Timeline:** 1 week | Status | 🔴 | Incomplete |
| Priority | 🔴 | Critical |
| Dependencies | ⚫ | EinSoftworks.Utilities only |
**Why Build Second:** **Why Build Second:**
- Essential for decoupling systems - Essential for decoupling systems
@@ -132,10 +135,12 @@ public class PooledEvent<T> where T : class, new()
- Health system that updates UI without direct references - Health system that updates UI without direct references
- Scene transition system using events - Scene transition system using events
#### 1.3 EinSoftworks.StateManagement #### 1.3 - EinSoftworks.StateManagement
**Priority:** 🔴 Critical - Build Third | | | |
**Dependencies:** EinSoftworks.Utilities, EinSoftworks.Events |--------------|----|---------------------------------------------|
**Estimated Timeline:** 1-2 weeks | Status | 🔴 | Incomplete |
| Priority | 🔴 | Critical |
| Dependencies | ⚫ | EinSoftworks.Utilities, EinSoftworks.Events |
**Why Build Third:** **Why Build Third:**
- State management is fundamental to game logic - State management is fundamental to game logic
@@ -194,66 +199,14 @@ public class HierarchicalStateMachine<T> : StateMachine<T> where T : class
These libraries provide essential 3D game functionality and build upon the foundation libraries. These libraries provide essential 3D game functionality and build upon the foundation libraries.
#### 2.1 EinSoftworks.Physics #### 2.1 - EinSoftworks.Camera
**Priority:** 🟡 High | | | |
**Dependencies:** EinSoftworks.Utilities, EinSoftworks.Events |--------------|----|-----------------------------------------------------------------------|
**Estimated Timeline:** 1-2 weeks | Status | 🔴 | Incomplete |
| Priority | 🟡 | High |
| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.Events, EinSoftworks.StateManagement |
**Why Build Fourth:** **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 - Essential for any 3D game
- Benefits from input system for camera controls - Benefits from input system for camera controls
- Can use state management for different camera modes - Can use state management for different camera modes
@@ -315,14 +268,72 @@ public class OrbitCamera : CameraController
- Third-person camera that follows a moving object - Third-person camera that follows a moving object
- Orbit camera for examining 3D models - 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) ### Phase 3: Character and Interaction Systems (Medium Priority)
These systems focus on character control and world interaction, building upon the previously established libraries. These systems focus on character control and world interaction, building upon the previously established libraries.
#### 3.1 EinSoftworks.Movement #### 3.1 - EinSoftworks.Movement
**Priority:** 🟡 Medium-High | | | |
**Dependencies:** EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.StateManagement, EinSoftworks.Events |--------------|----|---------------------------------------------------------------------------------------------|
**Estimated Timeline:** 2-4 weeks | Status | 🔴 | Incomplete |
| Priority | 🟡 | High |
| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.StateManagement, EinSoftworks.Events |
**Why Build Sixth:** **Why Build Sixth:**
- Core to most 3D games - Core to most 3D games
@@ -394,10 +405,12 @@ public class ThirdPersonController : CharacterController3D
- Third-person character that rotates to movement direction - Third-person character that rotates to movement direction
- Platformer character with precise jumping mechanics - Platformer character with precise jumping mechanics
#### 3.2 EinSoftworks.Interaction #### 3.2 - EinSoftworks.Interaction
**Priority:** 🟡 Medium | | | |
**Dependencies:** EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.Events |--------------|----|---------------------------------------------------------------|
**Estimated Timeline:** 1-2 weeks | Status | 🔴 | Incomplete |
| Priority | 🟡 | Medium |
| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.Physics, EinSoftworks.Events |
**Why Build Seventh:** **Why Build Seventh:**
- Common need in 3D games - 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. These systems provide advanced functionality for complete games and can be built once the core systems are stable.
#### 4.1 EinSoftworks.SceneManagement #### 4.1 - EinSoftworks.SceneManagement
**Priority:** 🟢 Medium-Low | | | |
**Dependencies:** EinSoftworks.StateManagement, EinSoftworks.Events |--------------|----|---------------------------------------------------|
**Estimated Timeline:** 2-3 weeks | Status | 🔴 | Incomplete |
| Priority | 🟢 | Medium-Low |
| Dependencies | ⚫ | EinSoftworks.StateManagement, EinSoftworks.Events |
**Core Features:** **Core Features:**
```csharp ```csharp
@@ -487,10 +502,12 @@ public class SceneManager : Node
} }
``` ```
#### 4.2 EinSoftworks.SaveSystem #### 4.2 - EinSoftworks.SaveSystem
**Priority:** 🟢 Medium-Low | | | |
**Dependencies:** EinSoftworks.StateManagement, EinSoftworks.SceneManagement |--------------|----|------------------------------------------------------------|
**Estimated Timeline:** 2-3 weeks | Status | 🔴 | Incomplete |
| Priority | 🟢 | Medium-Low |
| Dependencies | ⚫ | EinSoftworks.StateManagement, EinSoftworks.SceneManagement |
**Core Features:** **Core Features:**
```csharp ```csharp
@@ -513,10 +530,12 @@ public interface ISaveable
} }
``` ```
#### 4.3 EinSoftworks.UI #### 4.3 - EinSoftworks.UI
**Priority:** 🟢 Low | | | |
**Dependencies:** EinSoftworks.Input, EinSoftworks.StateManagement, EinSoftworks.Events |--------------|----|-----------------------------------------------------------------------|
**Estimated Timeline:** 3-4 weeks | Status | 🔴 | Incomplete |
| Priority | 🟢 | Low |
| Dependencies | ⚫ | EinSoftworks.Input, EinSoftworks.StateManagement, EinSoftworks.Events |
**Core Features:** **Core Features:**
```csharp ```csharp
@@ -536,7 +555,9 @@ public class UIManager : Control
### Getting Started Checklist ### 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 - [ ] Set up library repository structure
- [ ] Implement basic action queries (IsActionPressed, etc.) - [ ] Implement basic action queries (IsActionPressed, etc.)
- [ ] Add input mapping and saving/loading - [ ] Add input mapping and saving/loading
@@ -545,7 +566,7 @@ public class UIManager : Control
- [ ] Document all public APIs - [ ] Document all public APIs
- [ ] Test with multiple input devices - [ ] Test with multiple input devices
**Week 3: EinSoftworks.Events** **EinSoftworks.Events**
- [ ] Implement global event system - [ ] Implement global event system
- [ ] Create type-safe event bus - [ ] Create type-safe event bus
- [ ] Add event pooling for performance - [ ] Add event pooling for performance
@@ -553,7 +574,7 @@ public class UIManager : Control
- [ ] Document event naming conventions - [ ] Document event naming conventions
- [ ] Test event performance under load - [ ] Test event performance under load
**Week 4-5: EinSoftworks.StateManagement** **EinSoftworks.StateManagement**
- [ ] Implement generic state machine - [ ] Implement generic state machine
- [ ] Add transition system with conditions - [ ] Add transition system with conditions
- [ ] Create hierarchical state support - [ ] Create hierarchical state support
@@ -561,7 +582,7 @@ public class UIManager : Control
- [ ] Document state design patterns - [ ] Document state design patterns
- [ ] Test state machine performance - [ ] Test state machine performance
**Week 6-7: EinSoftworks.Physics** **EinSoftworks.Physics**
- [ ] Implement raycast utilities - [ ] Implement raycast utilities
- [ ] Add shape casting methods - [ ] Add shape casting methods
- [ ] Create trigger volume system - [ ] Create trigger volume system
@@ -569,7 +590,7 @@ public class UIManager : Control
- [ ] Document physics best practices - [ ] Document physics best practices
- [ ] Test physics performance - [ ] Test physics performance
**Week 8-10: EinSoftworks.Camera** **EinSoftworks.Camera**
- [ ] Implement base camera controller - [ ] Implement base camera controller
- [ ] Add specialized camera types (FPS, 3rd person, orbit) - [ ] Add specialized camera types (FPS, 3rd person, orbit)
- [ ] Create camera effects (shake, zoom) - [ ] Create camera effects (shake, zoom)
@@ -577,50 +598,21 @@ public class UIManager : Control
- [ ] Document camera usage patterns - [ ] Document camera usage patterns
- [ ] Test camera smoothness and responsiveness - [ ] 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 ### 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 - **Input Test**: Character that responds to all input types
- **Event Test**: Multiple systems communicating via events - **Event Test**: Multiple systems communicating via events
- **State Test**: Character with idle/walk/run/jump states - **State Test**: Character with idle/walk/run/jump states
#### Integration Tests (Weeks 6-10) #### Integration Tests
- **Physics Test**: Character with ground detection and jumping - **Physics Test**: Character with ground detection and jumping
- **Camera Test**: Switching between camera modes - **Camera Test**: Switching between camera modes
- **Combined Test**: Third-person character with camera following - **Combined Test**: Third-person character with camera following
#### Advanced Tests (Weeks 11+) #### Advanced Tests
- **Movement Test**: Full 3D character controller - **Movement Test**: Full 3D character controller
- **Interaction Test**: World with pickups and doors - **Interaction Test**: World with pickups and doors
- **Complete Game**: Small game using all built libraries - **Complete Game**: Small game using all built libraries
@@ -657,36 +649,11 @@ public class CharacterController3D : CharacterBody3D { }
- Profile and optimize only when needed - Profile and optimize only when needed
- Don't sacrifice clarity for minor performance gains - 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 ## Long-Term Maintenance
### Versioning Strategy ### Versioning Strategy
- Use semantic versioning (major.minor.patch) - Use semantic versioning (major.minor.patch)
- Major version changes for breaking API changes - Hardcore versioning adhearance probably isn't necessary... should roughly keep versioning schema going just in case.
- Minor version changes for new features
- Patch version changes for bug fixes
### Backward Compatibility ### Documentation
- Maintain backward compatibility within major versions
- Provide migration guides for major version upgrades
- Deprecate features before removing them
### Community and Documentation
- Maintain comprehensive 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