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
### 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<T> 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<T> : StateMachine<T> 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