Overview
The VoxelPlayerController is a comprehensive Unity character controller system that provides modular, decoupled gameplay systems for player movement, combat, environment interaction, and AI.
It solves the problem of tightly-coupled, monolithic controllers by enforcing a strict separation of responsibilities. This design enables individual systems to be enabled, disabled, or replaced without breaking the overall gameplay experience.
Intended for: Indie developers, technical enthusiasts, and professional studios seeking a production-ready, maintainable, and extensible character controller foundation.
Core Systems
PlayerController
The central movement system managing locomotion, physics-based collision response, procedural animation, and state management (Idle, Walk, Run, Crouch, Jump, Dash). Delegates specific responsibilities to dedicated systems.
PlayerCamera
Manages first-person and third-person views, mouse/controller look input, collision avoidance, and water transitions. Operates in LateUpdate for smooth player-following behavior.
AdvancedNPC
A state-driven enemy AI system (Idle, Patrol, Chase, Attack, Return, Dead) using NavMesh navigation, melee combat, health management, and procedural animation. Implements full damage reception and event systems.
WaterSwimming
Handles water detection, swimming mechanics, buoyancy physics, and aquatic animations. Seamlessly transitions between land and water movement, disabling the PlayerController when active.
PlayerEnvironmentSensor
A pure detection system for terrain, obstacles, and surface analysis. Provides ground detection, slope angle calculation, obstacle checks, and auto-step viability data to the PlayerController.
PlayerDamage
Manages the player's melee combat system, including weapon inventory, attack execution with sphere-cast hit detection, damage application to NPCs, and equip/unequip animations using Bézier curves.
HealthSystem
Central health management with damage application, death sequences, respawn logic, fall damage calculation, and health regeneration. Integrates with audio, visual effects, and controls PlayerController state.
PlayerInputManager
Unified input abstraction supporting both Legacy and New Input Systems simultaneously. Provides consistent getters for all control types and manages keyboard/mouse vs. gamepad scheme transitions.
Automatic Sprint System
Allows the character to run automatically when movement input exceeds a configurable threshold, without requiring an additional key press. Manual sprint retains priority. Reduces player fatigue while maintaining full control.
PlayerAudioController
Centralized audio management with five dedicated AudioSources (Land, Water, Melee, Damage, Health). Provides clean API methods for all other systems to trigger domain-specific sounds without managing playback directly.
System Showcase
Performance & Stability
Runtime Efficiency
Environment detection uses cooldowns (default 0.1s for obstacle checks) and optimization radii. Distant water bodies are ignored. Audio uses pre-allocated AudioSources to prevent runtime allocation.
Frame Stability
Strict execution order separation: Input in Update, movement/physics in FixedUpdate, camera in LateUpdate. Coroutines are managed with cancellation support to prevent state corruption during rapid input.
Architecture
Production-safe decoupled design. Each system manages its own internal state with clear public interfaces. No global state manager reduces complexity and side effects. Event-driven communication minimizes per-frame overhead.
Automatic Sprint System
Monitors input magnitude and automatically transitions between Walk and Run states based on a configurable threshold. Manual sprint input retains priority. Optimized to avoid activation during crouch, dash, or airborne states.
Workflow & Usability
The system follows a plug-and-play philosophy. Core prefabs are provided with all components pre-wired.
Configuration is primarily Inspector-driven, with sensible defaults for all parameters. No code modification is required for standard use cases.
Setup is minimal: import the asset, add the player prefab to your scene, configure your environment layers, and press play. The architecture supports a "create a level and play" workflow suitable for rapid prototyping and production.
Configuration is primarily Inspector-driven, with sensible defaults for all parameters including the new Automatic Sprint System. No code modification is required for standard use cases.
Documentation
A comprehensive 40+ page PDF technical documentation is included with the asset.
It provides detailed explanations of:
- System architecture and interaction maps
- Complete script overviews for each component (PlayerController, PlayerDamage, AdvancedNPC, etc.)
- Responsibility boundaries and dependencies
- Public API usage and method signatures
- Internal state machines and lifecycle execution order
- Edge cases handled and key design decisions
The documentation is written for intermediate to advanced Unity developers, focusing on clarity and technical depth over basic tutorials.
Technical Details
Implement a Production-Ready Controller
Reduce development time and increase maintainability with a modular, decoupled architecture designed for professional use.