Add Movement library integration with comprehensive test environment: include Movement.csproj reference, create LibraryTest scene with player controller, multiple test areas (bunny hop platforms, surf ramps, vertical tower, speed corridor), advanced lighting setup, input mappings for WASD/gamepad movement controls, and DebugHUD integration
This commit is contained in:
William Stuckey
246
Docs/LIBRARY_INTEGRATION.md
Normal file
246
Docs/LIBRARY_INTEGRATION.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# EinSoftworks Library Integration
|
||||
|
||||
This document describes how all EinSoftworks utility libraries are integrated into the Voider project.
|
||||
|
||||
## Integrated Libraries
|
||||
|
||||
All six EinSoftworks libraries are fully integrated and working together:
|
||||
|
||||
### ✅ EinSoftworks.Movement
|
||||
- **Location**: `Libraries/movement`
|
||||
- **Usage**: `FirstPersonController` for player movement
|
||||
- **Features**: Bunny hopping, air strafing, crouching, sprinting
|
||||
- **Integration**: TestPlayer.cs extends FirstPersonController
|
||||
|
||||
### ✅ EinSoftworks.Input
|
||||
- **Location**: `Libraries/input`
|
||||
- **Usage**: Input management via InputManager singleton
|
||||
- **Features**: Action-based input, device detection, remapping
|
||||
- **Integration**: Automatic via InputManager.Instance
|
||||
|
||||
### ✅ EinSoftworks.Events
|
||||
- **Location**: `Libraries/events`
|
||||
- **Usage**: Event system for decoupled communication
|
||||
- **Features**: MovementEvents, EventBus, state notifications
|
||||
- **Integration**: TestGameManager subscribes to movement events
|
||||
|
||||
### ✅ EinSoftworks.StateManagement
|
||||
- **Location**: `Libraries/state-management`
|
||||
- **Usage**: Movement state machine (idle, walking, airborne, crouching)
|
||||
- **Features**: State transitions, hierarchical states
|
||||
- **Integration**: Built into CharacterController
|
||||
|
||||
### ✅ EinSoftworks.Camera
|
||||
- **Location**: `Libraries/camera`
|
||||
- **Usage**: First-person camera with mouse look
|
||||
- **Features**: Camera effects, smooth transitions
|
||||
- **Integration**: CameraMount node in FirstPersonController
|
||||
|
||||
### ✅ EinSoftworks.Utilities
|
||||
- **Location**: `Libraries/utilities`
|
||||
- **Usage**: Math and physics helper functions
|
||||
- **Features**: Vector operations, physics calculations
|
||||
- **Integration**: Used internally by movement system
|
||||
|
||||
## Test Scene
|
||||
|
||||
**Location**: `Scenes/Testing/LibraryTest.tscn`
|
||||
|
||||
The test scene demonstrates all libraries working together in a fully functional first-person movement system.
|
||||
|
||||
### Components
|
||||
|
||||
1. **TestPlayer** (FirstPersonController)
|
||||
- Full movement with all advanced mechanics
|
||||
- Real-time UI updates
|
||||
- Event publishing
|
||||
|
||||
2. **TestGameManager**
|
||||
- Event subscription management
|
||||
- Game state coordination
|
||||
- Player reset functionality
|
||||
|
||||
3. **TestUI**
|
||||
- Live stats display
|
||||
- FPS counter
|
||||
- Control instructions
|
||||
|
||||
4. **Environment**
|
||||
- Floor, ramps, platforms
|
||||
- Testing geometry for all movement types
|
||||
|
||||
## Project Configuration
|
||||
|
||||
### Voider.csproj
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\..\libraries\utilities\Utilities.csproj" />
|
||||
<ProjectReference Include="..\..\libraries\input\Input.csproj" />
|
||||
<ProjectReference Include="..\..\libraries\events\Events.csproj" />
|
||||
<ProjectReference Include="..\..\libraries\state-management\StateManagement.csproj" />
|
||||
<ProjectReference Include="..\..\libraries\camera\Camera.csproj" />
|
||||
<ProjectReference Include="..\..\libraries\movement\Movement.csproj" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
### project.godot
|
||||
Input actions configured:
|
||||
- `move_forward` (W)
|
||||
- `move_back` (S)
|
||||
- `move_left` (A)
|
||||
- `move_right` (D)
|
||||
- `jump` (Space)
|
||||
- `crouch` (Ctrl)
|
||||
- `sprint` (Shift)
|
||||
- `walk` (Ctrl)
|
||||
|
||||
Autoload configured:
|
||||
- `EventManager` - Global event management
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Creating a Player Controller
|
||||
|
||||
```csharp
|
||||
using EinSoftworks.Movement;
|
||||
|
||||
public partial class MyPlayer : FirstPersonController
|
||||
{
|
||||
public override void _Ready()
|
||||
{
|
||||
base._Ready();
|
||||
|
||||
Config = new MovementConfig
|
||||
{
|
||||
MaxSpeed = 320f,
|
||||
EnableBunnyHopping = true
|
||||
};
|
||||
|
||||
SubscribeToStateChanges(OnStateChanged);
|
||||
}
|
||||
|
||||
private void OnStateChanged(MovementStateChangedEvent evt)
|
||||
{
|
||||
GD.Print($"State: {evt.StateName}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Subscribing to Events
|
||||
|
||||
```csharp
|
||||
using EinSoftworks.Movement;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
MovementEvents.PlayerJumped += OnPlayerJumped;
|
||||
MovementEvents.SpeedChanged += OnSpeedChanged;
|
||||
}
|
||||
|
||||
private void OnPlayerJumped()
|
||||
{
|
||||
PlayJumpSound();
|
||||
}
|
||||
|
||||
public override void _ExitTree()
|
||||
{
|
||||
MovementEvents.ClearAllSubscriptions();
|
||||
}
|
||||
```
|
||||
|
||||
### Using Input Manager
|
||||
|
||||
```csharp
|
||||
using EinSoftworks.Input;
|
||||
|
||||
private InputManager _input;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
_input = InputManager.Instance;
|
||||
}
|
||||
|
||||
public override void _Process(double delta)
|
||||
{
|
||||
if (_input.IsActionJustPressed("jump"))
|
||||
{
|
||||
Jump();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Build Status
|
||||
|
||||
✅ **Build Successful**
|
||||
```
|
||||
Build succeeded.
|
||||
0 Warning(s)
|
||||
0 Error(s)
|
||||
```
|
||||
|
||||
All libraries compile and integrate without errors.
|
||||
|
||||
## Testing
|
||||
|
||||
To test the library integration:
|
||||
|
||||
1. Open the Voider project in Godot
|
||||
2. Run the scene: `Scenes/Testing/LibraryTest.tscn`
|
||||
3. Test movement mechanics:
|
||||
- Walk around with WASD
|
||||
- Jump with Space
|
||||
- Sprint with Shift
|
||||
- Crouch with Ctrl
|
||||
- Try bunny hopping (jump + strafe)
|
||||
- Test air strafing
|
||||
4. Observe UI updates in real-time
|
||||
5. Check console for event notifications
|
||||
|
||||
## Performance
|
||||
|
||||
Target: 60+ FPS
|
||||
All libraries are optimized for real-time game performance.
|
||||
|
||||
## Future Integration
|
||||
|
||||
These libraries can be used throughout the Voider project:
|
||||
|
||||
- **Player Systems**: Use Movement + Input for all player characters
|
||||
- **Camera Systems**: Use Camera library for different camera modes
|
||||
- **UI Systems**: Use Events for UI updates and notifications
|
||||
- **AI Systems**: Use StateManagement for enemy AI
|
||||
- **Game Systems**: Use Events for game state management
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Errors
|
||||
- Ensure all library references are correct in .csproj
|
||||
- Verify all libraries are in `../../libraries/` relative path
|
||||
- Run `dotnet restore` if needed
|
||||
|
||||
### Runtime Errors
|
||||
- Check that EventManager autoload is configured
|
||||
- Verify input actions are defined in project.godot
|
||||
- Ensure all using statements are present in scripts
|
||||
|
||||
### Movement Issues
|
||||
- Verify collision shapes are properly configured
|
||||
- Check that InputManager is available
|
||||
- Ensure CameraNode is set on the controller
|
||||
|
||||
## Documentation
|
||||
|
||||
Each library has comprehensive documentation in its README:
|
||||
- `/libraries/movement/README.md`
|
||||
- `/libraries/input/README.md`
|
||||
- `/libraries/events/README.md`
|
||||
- `/libraries/state-management/README.md`
|
||||
- `/libraries/camera/README.md`
|
||||
- `/libraries/utilities/README.md`
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about library integration, refer to:
|
||||
1. Individual library READMEs
|
||||
2. Test scene implementation (`Scripts/Testing/`)
|
||||
3. Library planning document (`documentation/planning/UTILITY_PLANNING.md`)
|
||||
Reference in New Issue
Block a user