diff --git a/DESIGN_BRIEF.md b/DESIGN_BRIEF.md new file mode 100644 index 0000000..987a260 --- /dev/null +++ b/DESIGN_BRIEF.md @@ -0,0 +1,2074 @@ +# UnrealForts Design Brief + +## Project Overview + +**Project Name:** UnrealForts +**Type:** Original Game Concept +**Target Engine:** Unreal Engine 5 +**Original Inspiration:** Classic Half-Life 2 community mods featuring fort building and combat +**Genre:** Team-Based FPS with Base Building Mechanics + +### Purpose +UnrealForts is an original multiplayer FPS game built in Unreal Engine 5 that combines tactical base construction with team-based combat. Inspired by the legacy of innovative Half-Life 2 community mods that merged building mechanics with competitive gameplay, this project aims to deliver a unique blend of creative engineering and strategic combat while leveraging modern UE5 capabilities. + +--- + +## Core Game Concept + +UnrealForts combines two distinct gameplay phases in a cyclical match structure: + +1. **Build Phase**: Teams collaboratively construct fortifications using physics-based building blocks +2. **Combat Phase**: Teams engage in FPS combat, attempting to capture the enemy's flag while defending their own + +This alternating structure creates a unique gameplay loop that rewards both creative engineering and skilled combat. + +--- + +## Game Mechanics + +### 1. Phase System + +#### Build Phase +- **Duration**: Configurable (typically 2-5 minutes) +- **Objective**: Construct defensive fortifications and strategic structures +- **Rules**: + - All weapons are disabled during this phase + - Teams are typically separated to their respective spawn zones + - Players can only build on their designated half of the map + - Physics manipulation tools are enabled + - Blocks can be spawned, moved, rotated, and frozen in place + +#### Combat Phase +- **Duration**: Configurable (typically 3-7 minutes) +- **Objective**: Capture the enemy flag while defending your own +- **Rules**: + - All weapons and combat abilities are enabled + - Players can freely move across the entire map + - Building tools are disabled (or limited to repairs in some variants) + - Flag must be physically transported using physics manipulation + - Fortifications can be damaged or destroyed + +#### Phase Transitions +- Automated timer-based transitions between phases +- Round cycles: Build → Combat → Build → Combat (repeating) +- Teams may repair and modify fortifications between combat rounds +- Score is tracked across multiple rounds + +### 2. Building System + +#### Block Types +- **Standard Cube Blocks**: Primary building element in various sizes +- **Panel Blocks**: Flat surfaces for walls, floors, and ceilings +- **Metal Blocks**: Durable construction materials +- **Variants**: Different sizes and potentially materials (small, medium, large) + +#### Building Mechanics +- **Physics Manipulation Tool**: Primary building interface (gravity gun equivalent) + - Pick up and move blocks + - Rotate blocks in 3D space + - Precisely position blocks +- **Freeze System**: + - Blocks can be "frozen" to anchor them in place + - Frozen blocks become static and don't respond to physics + - Prevents accidental displacement + - Critical for structural stability +- **Welding/Snapping**: Optional system to connect blocks together +- **Block Limits**: Server-configurable limits to prevent performance issues +- **Building Constraints**: + - Collision detection prevents overlapping blocks + - Physics stability limits on extreme structures + - Potential height/distance limits from spawn + +#### Strategic Building Elements +- **Defensive Walls**: Block enemy movement and projectiles +- **Sniper Towers**: Elevated positions for long-range combat +- **Bridges**: Connect areas or create tactical pathways +- **Bunkers**: Protected firing positions +- **Mazes**: Confuse and delay enemy flag carriers +- **Choke Points**: Force enemies into kill zones +- **Hidden Passages**: Secret routes for flag runners + +### 3. Combat System + +#### Player Classes +Multiple class archetypes with distinct roles: + +1. **Soldier** + - Standard rifle and grenades + - Balanced combat effectiveness + - Medium movement speed + +2. **Scout** + - Lightweight weapons (SMG, pistol) + - Fast movement speed + - Ideal for flag running + +3. **Rocketeer** + - Rocket launcher + - Specializes in destroying fortifications + - Slow movement speed + - High explosive damage to structures + +4. **Sniper** + - Long-range precision rifle + - Effective from defensive positions + - Low health + - Scope for distant targets + +5. **Builder** (Optional) + - Gravity gun/physics tool + - Can repair structures during combat + - Limited combat capability + - Support role + +#### Weapons +Based on class selection, including: +- Assault Rifles +- SMGs +- Rocket Launchers +- Sniper Rifles +- Grenades (frag, sticky) +- Pistols (sidearms) +- Physics Gun (builder class) + +#### Destructible Environment +- Blocks can be damaged by weapons +- Explosive weapons deal area damage to structures +- Blocks can be "unfrozen" by damage, returning to physics simulation +- Strategic destruction creates new paths or collapses defenses + +### 4. Capture the Flag System + +#### Flag Mechanics +- **Flag as Physics Object**: The flag is represented as a physical ball/object +- **Physics-Based Capture**: Players must physically move the flag using: + - The physics manipulation tool (gravity gun) + - Carrying mechanics (player holds the flag) + - Throwing/passing between teammates +- **Flag States**: + - At home base (defended position) + - In transit (being carried by player) + - Dropped (on ground, can be recovered) + - Captured (returned to capturing team's base) + +#### Scoring +- Points awarded for successful flag captures +- Additional points for kills, defensive actions +- Win conditions: Most points at end of round, or first to X captures + +### 5. Teams + +#### Team Structure +- **Two Teams**: + - Team 1: Combine (or equivalent faction) + - Team 2: Rebels (or equivalent faction) +- **Team Size**: Configurable (typically 4v4 to 16v16) +- **Team Communication**: Voice chat and text chat essential +- **Team Roles**: Players naturally specialize in building, attacking, or defending + +#### Teamwork Requirements +- Coordinated fort construction +- Defensive positioning +- Organized attacks +- Flag carrier support +- Communication of enemy positions + +--- + +## Technical Considerations for UE5 + +### Physics System +- **Chaos Physics Engine**: UE5's built-in physics for block dynamics +- **Networked Physics**: Ensure multiplayer synchronization of block positions +- **Physics Optimization**: + - Frozen blocks become static meshes (no physics calculation) + - Dynamic blocks only during build phase or when damaged + - LOD system for distant structures + - Culling of non-visible blocks + +### Building Tool Implementation +- **Physics Handle**: UE5 physics constraint system for object manipulation +- **Placement System**: Snap-to-grid option or free placement +- **Rotation Controls**: Smooth or incremental rotation options +- **Visual Feedback**: Highlight valid/invalid placement positions +- **Undo System**: Allow players to undo recent placements + +### Networking +- **Replication**: + - Block positions and states must be replicated + - Phase changes synchronized across all clients + - Flag position and carrier state +- **Authority**: Server-authoritative for anti-cheat +- **Optimization**: + - Batch block updates during build phase + - Delta compression for block states + - Relevancy filtering for distant players + +### Performance Optimization +- **Block Pooling**: Reuse block actors to reduce spawning overhead +- **Instanced Static Meshes**: When blocks are frozen +- **Level of Detail (LOD)**: Multiple mesh detail levels +- **Occlusion Culling**: Hide blocks behind walls +- **Draw Call Batching**: Minimize rendering overhead + +### User Interface +- **Build Phase HUD**: + - Block selection menu + - Rotation controls indicator + - Freeze/unfreeze status + - Time remaining in phase + - Block count remaining +- **Combat Phase HUD**: + - Health and armor + - Weapon and ammo + - Team scores + - Flag status indicator + - Minimap showing flag locations + - Class indicator +- **Scoreboard**: Kill/death ratios, captures, building contributions + +--- + +## Map Design Principles + +### Layout Requirements +- **Symmetrical Design**: Balanced spawn zones for both teams +- **Build Zones**: Designated areas where building is allowed +- **Neutral Territory**: Central contested area between bases +- **Flag Spawn Locations**: Protected starting positions for flags +- **Height Variation**: Multiple elevation levels for tactical depth +- **Cover Opportunities**: Pre-existing map geometry for tactical positioning + +### Map Elements +- **Spawn Rooms**: Protected team starting areas +- **Building Floors**: Flat surfaces to build from +- **Natural Cover**: Rocks, walls, structures +- **Strategic Points**: Elevated positions, narrow passages +- **Hazards**: Optional environmental dangers (lava, pits, etc.) + +### Example Map Concepts +- **uf_valley**: Open valley with high cliffs on sides +- **uf_rooftop**: Elevated rooftops with gaps between buildings +- **uf_abandon**: Industrial/urban setting with building ruins +- **uf_reservoir**: Water-based map with platforms + +--- + +## Game Modes + +### Primary Mode: Capture the Flag (CTF) +- Classic build-combat cycle +- Two flags, one per team +- Winner is first to capture limit or highest score at time limit + +### Potential Additional Modes +- **Capture Points**: Hold strategic locations instead of flags +- **King of the Hill**: Build around and control a central point +- **Destruction**: Destroy enemy structures or key objectives +- **Pure Combat**: Remove build phase entirely (for quick matches) +- **Extended Build**: Longer build phase for elaborate constructions + +--- + +## Player Progression and Retention + +### Match-Based Systems +- **End of Round Statistics**: Kills, deaths, captures, blocks placed +- **MVP Awards**: Best builder, best attacker, best defender +- **Team Highlights**: Replay of best flag capture or defensive play + +### Long-Term Systems (Optional) +- **Player Levels**: Track overall experience +- **Unlocks**: Cosmetic items, player skins, weapon skins, block textures +- **Achievements**: Special accomplishments (first capture, building feats) +- **Custom Fort Blueprints**: Save and share fort designs + +--- + +## Art Direction + +### Overall Artistic Vision + +UnrealForts embraces a **near-future industrial military aesthetic** that balances tactical realism with visual clarity. The art style prioritizes gameplay readability while delivering immersive, atmospheric environments that feel grounded and believable. Think of it as a fusion of contemporary military shooters with sci-fi industrial design—functional, modular, and purpose-built for combat. + +**Core Pillars:** +1. **Clarity First**: All visual elements must support gameplay readability +2. **Modular Industrial Design**: Everything feels manufactured and utilitarian +3. **Tactical Realism**: Grounded in plausible near-future military technology +4. **Team Distinction**: Clear visual language separates teams without confusion +5. **Dynamic Feedback**: Visual and audio cues provide constant gameplay information + +--- + +### Visual Style Guide + +#### Color Palette + +**Primary Team Colors:** +- **Team Alpha (Red/Orange Team)**: + - Primary: Deep Crimson (#8B1A1A) to Burnt Orange (#CC5500) + - Secondary: Dark Gray (#3A3A3A) with red undertones + - Accent: Bright Warning Orange (#FF6600) for UI highlights + - Emissive: Warm amber glow (#FFB366) for holographic elements + +- **Team Beta (Blue/Cyan Team)**: + - Primary: Naval Blue (#1A3A8B) to Cyan (#0088CC) + - Secondary: Cool Steel Gray (#4A4A52) + - Accent: Electric Blue (#00CCFF) for UI highlights + - Emissive: Cool cyan glow (#66D9FF) for holographic elements + +**Neutral Colors:** +- Base Metal: Brushed steel (#6B7280) with subtle color temperature shifts +- Concrete: Weathered gray (#8B9098) with dirt and wear +- Environment: Desaturated earth tones for maps (browns, greens, grays) + +**Functional Colors:** +- Frozen Block State: Slight blue-white shimmer overlay +- Unfrozen/Active Block: Subtle orange-red heat shimmer +- Damage States: Progressive darkening with orange-red heat damage +- Objective Markers: High-contrast yellow (#FFD700) for flags and objectives + +#### Building Block Design + +**Visual Identity:** +- **Form Language**: Chunky, modular, industrial panels and cubes +- **Surface Details**: + - Rivets, bolts, and weld seams at corners and edges + - Panel lines suggesting manufactured construction + - Subtle embossed labeling (serial numbers, warning symbols) + - Grip texture patterns on surfaces +- **Material Properties**: + - Primary: Brushed or matte metal (steel, titanium alloys) + - Roughness variation for visual interest (0.4-0.7 roughness range) + - Subtle metallic sheen without being mirror-like + - Dirt, scuff, and wear accumulated at edges and high-traffic areas +- **Scale Differentiation**: + - Small blocks: Hand-sized (0.5m cubes) + - Medium blocks: Torso-height (1m cubes) + - Large blocks: Full cover (2m cubes and 2m x 4m panels) + - Consistent visual language across all sizes + +**State Visualization:** +- **Frozen State**: + - Subtle ice-blue edge glow (emissive) + - Small holographic "lock" icon appears on surface + - Slight color desaturation + - Minimal specular highlights (solid and stable) +- **Unfrozen/Dynamic State**: + - Warmer color temperature + - Pulsing orange edge highlight + - More pronounced specular highlights (active physics) + - Subtle floating particle effects around edges +- **Damaged State**: + - Progressive deformation (dents, cracks) + - Exposed inner structure (mesh, wiring) + - Heat/burn marks around damage points + - Sparking particle effects for severe damage +- **Destruction**: + - Fragments break along logical seams + - Inner structural elements revealed (girders, cables) + - Dramatic particle burst with metal shards + - Smoke and heat distortion effects + +#### Character and Player Design + +**Player Models:** +- **Silhouette**: Distinct class silhouettes for instant recognition + - Soldier: Balanced, medium bulk, helmet with visor + - Scout: Lean, lightweight armor, streamlined profile + - Rocketeer: Heavy, broad shoulders, large backpack + - Sniper: Tall, angular, ghillie/camo elements + - Builder: Utility vest, tool harness, work gloves visible +- **Armor Style**: + - Tactical modular armor plates over combat suits + - Near-future military tech (think 2040s special forces) + - Visible pouches, equipment, and utility items + - Helmet designs with HUD visors and comm gear +- **Team Identification**: + - Armor color: Primary team color on shoulders, chest, and helmet + - Emissive highlights: Team-colored lights on helmet and backpack + - Fabric/undersuit: Team color with weathering + - Clear from all angles and distances + +**First-Person View:** +- Visible arms and gloves in team colors +- Weapon held in view with tactile, grounded animation +- Physics tool shows holographic projection and targeting reticle +- HUD elements integrated into "helmet visor" aesthetics + +#### Weapon Design + +**Style Guidelines:** +- **Form**: Near-future military weapons with recognizable real-world influences +- **Materials**: + - Matte black polymer furniture + - Gunmetal gray or dark steel receivers + - Bronze/copper for shell casings and barrel details +- **Details**: + - Rail systems for attachments + - Visible magazines and mechanical parts + - Holographic sights with team-colored reticles + - Weathering and wear on high-use areas (grip, charging handle) +- **Animation**: + - Weighty, realistic recoil + - Smooth reloads with visible mechanical actions + - Tactical handling (magazine checks, bolt releases) + +**Per-Class Weapon Aesthetics:** +- **Assault Rifles**: Bullpup or carbine style, balanced and modern +- **SMGs**: Compact PDW design with folding stocks +- **Rocket Launchers**: Large tube-style with exposed warheads +- **Sniper Rifles**: Long-barreled precision platform with advanced optics +- **Physics Gun**: Futuristic gravity manipulation device + - Glowing energy core (team colored) + - Animated graviton beam effect + - Holographic targeting display + - Mechanical pistons and actuators + +#### Environment and Map Aesthetics + +**Setting Themes:** +- **Industrial Complexes**: Factories, refineries, warehouses +- **Military Installations**: Bases, compounds, training facilities +- **Urban Warfare**: City blocks, rooftops, urban decay +- **Natural Terrain**: Valleys, canyons, forests (with industrial elements) + +**Visual Treatment:** +- **Lighting**: + - Dramatic use of contrast (shadows vs bright areas) + - Volumetric fog for atmosphere + - Colored accent lighting (warning lights, emergency lighting) + - Dynamic time-of-day variations for replayability +- **Architecture**: + - Modular industrial construction + - Brutalist concrete and steel framework + - Functional design (catwalks, pipes, machinery) + - Believable scale and proportions +- **Props and Details**: + - Shipping containers, crates, barrels + - Industrial machinery and equipment + - Warning signage and hazard markings + - Scattered debris suggesting recent activity +- **Weathering and Age**: + - Rust on metal surfaces + - Concrete cracking and staining + - Overgrown vegetation in appropriate areas + - Accumulated dirt in corners and low traffic areas + +**Optimization Considerations:** +- Modular asset library for efficient level construction +- LOD systems with 3-4 detail levels per asset +- Shared material instances for performance +- Texture atlasing where appropriate + +#### User Interface Design + +**HUD Philosophy:** +- Minimalist and non-intrusive during gameplay +- Information appears when contextually relevant +- Diegetic elements (in-world displays) where possible +- Clean typography with excellent readability + +**Build Phase HUD:** +- **Block Selection Menu**: + - Semi-transparent panel in corner + - 3D preview thumbnails of blocks + - Grid layout with category tabs + - Selected block highlighted with team color +- **Block Placement Indicator**: + - Holographic ghost preview of block at placement location + - Green = valid placement, Red = invalid + - Snap points shown as glowing nodes + - Rotation angle indicator (circular arc display) +- **Status Display**: + - Blocks remaining: Counter with icon + - Freeze tool status: Icon showing current mode + - Phase timer: Large, clear countdown + - Team block count comparison bar + +**Combat Phase HUD:** +- **Health and Armor**: + - Segmented bars in corners + - Team color highlights when damaged + - Regeneration feedback with pulse animation +- **Weapon Info**: + - Ammo counter (large, readable numbers) + - Weapon icon with damage state + - Reload indicator (progress arc) +- **Objective Status**: + - Flag locations: 3D markers in world space + - Minimap: Top corner with simplified tactical view + - Team scores: Minimal display at top center + - Kill feed: Right side with icons and team colors +- **Crosshair**: + - Dynamic crosshair adapting to weapon type + - Team-colored center dot + - Hit confirmation feedback (color flash, expansion) + +**Menu Screens:** +- Dark backgrounds with team color accents +- Card-based layouts for options +- Large, readable fonts (military stencil inspired) +- Subtle animated backgrounds (industrial scenes) +- Consistent iconography throughout + +#### Visual Effects (VFX) + +**Particle Systems:** +- **Block Placement**: + - Energy ripple emanating from placement point + - Brief spark shower for metal-on-metal contact + - Dust puff at ground contact + - Sound-synchronized visual beats +- **Block Destruction**: + - Metal fragments with physics + - Ember and spark shower + - Smoke plume (dark gray) + - Screen shake for nearby players +- **Weapon Impacts**: + - Bullet impacts: Spark burst with small debris + - Explosions: Fire ball with expanding smoke ring + - Energy weapons: Dissipating energy burst +- **Physics Gun Effects**: + - Beam from gun to target object + - Energy particle flow along beam + - Pulsing glow on held object + - Distortion effect around manipulation field + +**Post-Processing:** +- Subtle color grading (slightly desaturated with contrast) +- Lens effects (minimal chromatic aberration, dirt on lens) +- Motion blur (per-object for fast movements) +- Depth of field (slight blur for distant objects) +- Bloom (controlled, for emissive elements only) + +### Audio Design + +**Sound Design Philosophy:** +- Realistic weapon and impact sounds grounded in real-world audio +- Clear audio cues for all gameplay-critical events +- Spatial audio for tactical awareness (footsteps, gunfire direction) +- Distinct team-specific audio signatures + +#### Build Phase Audio + +- **Block Manipulation**: + - Pickup: Metallic clank with weight-appropriate resonance + - Movement: Low hum from physics tool, pitch varies with object mass + - Rotation: Servo motor whirr + - Placement: Solid "thunk" with brief reverb + - Freeze: Satisfying "click-lock" with crystalline shimmer + - Unfreeze: Mechanical release "clack" with hiss +- **Ambient Sounds**: + - Background construction noises from both teams + - Tool sounds echoing across the map + - Distant metal clanging and placement + - Phase timer warning beeps (last 30 seconds) +- **UI Sounds**: + - Block selection: Soft beep + - Menu navigation: Click and hover sounds + - Invalid action: Negative buzzer + +#### Combat Phase Audio + +- **Weapon Sounds**: + - Each weapon has unique firing signature + - Realistic mechanical sounds (bolt, magazine, charging handle) + - Shell casings hitting ground (clinking) + - Distant gunfire has muffled, echoing quality +- **Impact and Destruction**: + - Bullet impacts: Sharp crack with metallic ring + - Block damage: Progressive cracking, groaning metal + - Block destruction: Loud crash with echoing debris + - Explosions: Deep bass rumble with high-frequency crack +- **Character Audio**: + - Footsteps vary by surface (metal grating, concrete, dirt) + - Landing from jumps (weight-dependent impact) + - Breathing (heavy when low on stamina) + - Voice lines (callouts, orders, celebrations) +- **Objective Audio**: + - Flag pickup: Energetic acquisition sound + - Flag capture: Triumphant team-specific chime + - Flag drop: Warning tone + - Phase transition: Loud alarm/klaxon + +**Spatial Audio:** +- 3D positional audio for tactical gameplay +- HRTF (Head-Related Transfer Function) for precise directionality +- Occlusion: Sounds muffled when behind walls/blocks +- Reverberation zones for indoor vs outdoor spaces +- Distance attenuation based on environment + +#### Music and Ambience + +- **Build Phase Music**: + - Tempo: 90-100 BPM (measured, thoughtful) + - Instrumentation: Synth pads, electronic percussion, industrial samples + - Mood: Tense anticipation, focused concentration + - Dynamic: Builds intensity as timer counts down + +- **Combat Phase Music**: + - Tempo: 140-160 BPM (energetic, driving) + - Instrumentation: Heavy electronic beats, distorted synths, aggressive bass + - Mood: Intense action, adrenaline + - Dynamic: Intensity spikes during objective captures + +- **Menu Music**: + - Atmospheric, ambient electronic + - Reflective of game's industrial aesthetic + - Non-intrusive, allowing players to focus on options + +**Adaptive Audio:** +- Music intensity scales with match tension +- Sound mix adjusts based on phase (build vs combat) +- Proximity to objectives affects music layers +- Low health triggers audio filters (muffled, heartbeat) + +--- + +### Animation and Motion + +**Character Animation:** +- **Movement**: + - Realistic weight and momentum + - Class-specific run speeds reflected in animation + - Tactical stances (crouching, prone, leaning) + - Transition animations are snappy but grounded +- **Combat**: + - Weapon-specific reload animations + - Recoil affects upper body and camera + - Hit reactions (direction-based flinching) + - Death animations (ragdoll with momentum preservation) +- **Building**: + - Two-handed physics tool grip + - Body leans when manipulating heavy objects + - Head tracks held object + - Placement gesture (release and step back) + +**Block and Object Animation:** +- Smooth interpolation when moved by physics tool +- Natural tumbling when unfrozen +- Destruction animations fragment along logical seams +- Settling micro-movements when placed + +**UI Animation:** +- Menu transitions: Smooth slides and fades (200-300ms) +- HUD updates: Number counting animations +- Objective markers: Pulse and bob in 3D space +- Notification pop-ins: Quick scale and fade + +--- + +### Technical Art Specifications + +**Target Performance:** +- 60+ FPS on mid-range gaming PCs (1080p) +- 4K support with dynamic resolution scaling +- Consistent frame times (no hitching) + +**Material System:** +- Physically Based Rendering (PBR) workflow +- Master materials with instances for variations +- Parameter-driven team colors and wear states +- Parallax occlusion for surface detail on hero assets + +**Lighting:** +- Dynamic lighting for gameplay-critical elements +- Baked lightmaps for static environment +- Light probes for dynamic objects +- Lumen or alternative GI for realistic bounce light + +**Texture Resolution:** +- Hero assets (weapons, characters): 2K-4K textures +- Building blocks: 1K-2K with tiling detail maps +- Environment: Varied based on importance (512-4K) +- UI elements: Vector where possible, high-res raster for icons + +**Polycount Targets:** +- Characters: 25K-40K triangles (LOD0) +- Weapons: 10K-20K triangles +- Building blocks: 500-2K triangles (depends on size) +- Environment props: Highly variable, budgeted per scene + +--- + +### Reference and Inspiration + +**Visual References:** +- *Titanfall 2*: Industrial aesthetic, clean UI, modular design +- *Battlefield series*: Military realism, destruction, team identification +- *Apex Legends*: Character silhouettes, visual clarity, color coding +- *Modern Warfare (2019)*: Weapon detail, audio design, tactical feel +- *Mirror's Edge*: Clean color-coded environments, minimalist HUD + +**Architectural References:** +- Brutalist architecture +- Industrial complexes and factories +- Modern military bases +- Modular construction systems + +**Avoid:** +- Overly stylized cartoon aesthetics +- Muddy, dark visuals that obscure gameplay +- Excessive visual noise and clutter +- Confusing or ambiguous team identification + +--- + +## Accessibility and Learning Curve + +### Tutorial System +- **Interactive Tutorial**: Teach building mechanics step-by-step +- **Practice Mode**: Offline mode to experiment with building +- **Tooltips**: In-game hints for new players + +### Difficulty Scaling +- **Simple Blocks**: Easy to learn basic construction +- **Skill Ceiling**: Advanced building techniques for experienced players +- **Class Variety**: Different playstyles accommodate various skill levels + +--- + +## Community Features + +### Social Systems +- **Server Browser**: Find and join community servers +- **Private Matches**: Host custom games +- **Spectator Mode**: Watch matches in progress +- **Replay System**: Review and share epic moments + +### Customization +- **Server Settings**: + - Adjustable phase timers + - Block limits + - Class restrictions + - Weapon balance tweaks +- **Workshop/Modding Support**: Allow community-created maps and content +- **Custom Maps**: Map editor or import system + +--- + +## Procedural Generation Strategy + +### Overview + +UnrealForts will leverage procedural generation extensively to create a maintainable, testable, and scalable codebase. By generating content programmatically rather than manually creating assets, we gain several key advantages: + +1. **Testability**: Procedural generation enables comprehensive unit testing of game content +2. **Consistency**: Algorithmic generation ensures visual and functional consistency +3. **Iteration Speed**: Parameters can be tweaked without manual asset recreation +4. **Scalability**: Easy to generate variations and expand content library +5. **Simulation**: Game mechanics can be simulated and validated before runtime + +### UE5 Procedural Generation Tools + +**Primary Tools:** +- **Procedural Content Generation (PCG) Framework**: UE5's native PCG system for level generation +- **Blueprints**: Visual scripting for procedural logic and content generation +- **C++ Code**: Performance-critical generation and complex algorithms +- **Python Scripts**: Content pipeline automation and batch generation +- **Geometry Script**: Runtime and editor-time geometry generation +- **Houdini Engine**: Advanced procedural workflows (optional integration) + +--- + +### Procedurally Generated Content + +#### 1. Building Blocks + +**Generation Approach:** +All building blocks will be procedurally generated using parametric definitions. + +**Block Parameters:** +``` +BlockDefinition: + - Type: [Cube, Panel, Beam, Corner] + - Size: [Small, Medium, Large] or custom dimensions (x, y, z) + - Material: [Steel, Titanium, Composite] + - Detail Level: [Low, Medium, High] for LOD generation + - Wear Amount: [0.0 - 1.0] for weathering variation + - Team Color Support: Boolean +``` + +**Generation Process:** +1. **Base Geometry**: Generate core mesh using Geometry Script + - Cubes: 6 faces with edge bevels + - Panels: Optimized single-plane with frame + - Custom shapes: Algorithm-based vertex placement +2. **Surface Details**: Add procedural features + - Rivet placement at edges (spacing algorithm) + - Panel lines (subdivision pattern) + - Grip texture (noise-based displacement) + - Warning labels (decal placement rules) +3. **UV Generation**: Automatic UV unwrapping with consistent texel density +4. **LOD Generation**: Automatic mesh simplification for LOD0-3 +5. **Collision**: Generate simplified collision meshes +6. **Material Assignment**: Apply master material instances with parameters + +**Benefits:** +- Generate hundreds of block variations from single definition +- Easy to adjust proportions and details globally +- Consistent style across all blocks +- Automated LOD and collision generation +- Unit testable: Verify mesh validity, collision accuracy, material assignment + +**Testing Approach:** +```python +# Example unit test for block generation +def test_cube_block_generation(): + block = generate_block(BlockType.CUBE, size=1.0) + assert block.vertex_count == expected_vertex_count + assert block.has_valid_uvs() + assert block.collision_is_convex() + assert block.lod_count == 4 + assert block.material_slots == 1 +``` + +#### 2. Map Layouts + +**Procedural Map Generation:** +While curated maps provide the best competitive balance, procedural generation can create: +- Practice maps for testing building techniques +- Varied layouts for casual play +- Base templates that level designers refine + +**Map Generation Parameters:** +``` +MapDefinition: + - Size: [Small, Medium, Large] (actual dimensions) + - Symmetry: Axis for team balance + - Terrain: [Flat, Valley, Hills, Urban] + - Build Zone Size: Area allocated to each team + - Cover Density: Amount of pre-placed cover + - Height Variation: Vertical complexity + - Prop Density: Environmental detail objects +``` + +**Generation Process:** +1. **Layout Grid**: Generate spatial partition for team zones +2. **Terrain**: Create base geometry using height maps or noise functions +3. **Spawn Points**: Calculate optimal positions using spatial algorithms +4. **Build Floors**: Place flat construction surfaces +5. **Cover Elements**: Distribute props using Poisson disc sampling +6. **Lighting**: Place light sources based on visibility analysis +7. **Optimization**: Generate navmesh, occlusion volumes, and LOD distances + +**UE5 PCG Integration:** +- Use PCG Graph to define generation rules +- Biome-based prop distribution +- Density controls for performance optimization +- Rule-based placement ensures playability + +**Testing Approach:** +```python +def test_map_symmetry(): + map_data = generate_map(MapDefinition(symmetry=Axis.X)) + assert map_data.is_symmetric(axis=Axis.X, tolerance=0.01) + assert map_data.spawn_points[0].distance_to_center() == \ + map_data.spawn_points[1].distance_to_center() +``` + +#### 3. Weapons and Props + +**Procedural Weapon Generation:** +- Base weapon mesh generated from parametric definitions +- Attachment points calculated programmatically +- Animation rigs generated from bone placement rules +- Weapon stats derived from balance formulas + +**Weapon Parameters:** +``` +WeaponDefinition: + - Class: [AssaultRifle, SMG, Sniper, Launcher] + - Barrel Length: Float (affects accuracy, velocity) + - Magazine Size: Int (affects reload time) + - Caliber: Float (affects damage, recoil) + - Fire Rate: Float (rounds per minute) + - Attachment Slots: List of rail positions +``` + +**Generation Benefits:** +- Rapid weapon prototyping +- Consistent visual style +- Automatic balance testing +- Easy to create variants + +**Testing Approach:** +```python +def test_weapon_damage_falloff(): + rifle = generate_weapon(WeaponClass.ASSAULT_RIFLE) + damage_curve = rifle.calculate_damage_curve() + assert damage_curve.at_distance(0) == rifle.base_damage + assert damage_curve.at_distance(100) < rifle.base_damage + assert damage_curve.is_monotonic_decreasing() +``` + +#### 4. Materials and Textures + +**Procedural Materials:** +- Master materials with extensive parameter controls +- Substance Designer integration for texture generation +- Runtime material parameter modifications + +**Material Generation:** +``` +MaterialDefinition: + - Base Color: RGB or texture + - Roughness: Value or map + - Metallic: Value or map + - Normal Strength: Float + - Wear Pattern: Procedural or texture + - Team Color Mask: Grayscale mask for tinting + - Detail Normal: Tiling detail texture +``` + +**Substance Integration:** +- Generate texture sets from procedural graphs +- Parameters expose: wear, dirt, rust, damage +- Batch generation for variations +- Version control friendly (graphs, not large files) + +**Testing:** +```python +def test_material_team_tinting(): + material = generate_team_material(team=TeamAlpha) + assert material.get_parameter('TeamColor') == TEAM_ALPHA_COLOR + assert material.has_valid_texture_channels() +``` + +#### 5. UI Elements + +**Procedural UI Generation:** +- HUD elements sized and positioned programmatically +- Resolution-independent layouts +- Theme-driven color schemes + +**UI Generation:** +- Widget blueprints created from data definitions +- Automatic layout using constraint systems +- Font sizes calculated from resolution and viewing distance +- Icon generation from vector definitions + +**Testing:** +```python +def test_hud_scaling(): + hud = generate_hud(resolution=(1920, 1080)) + assert hud.readability_score() > 0.8 + assert hud.fits_safe_area() + + hud_4k = hud.scale_to(resolution=(3840, 2160)) + assert hud_4k.element_sizes_proportional_to(hud) +``` + +--- + +### Game Mechanics Simulation + +#### Simulation Framework + +Beyond asset generation, we can simulate actual game mechanics to validate design decisions before implementation. + +**Simulation Capabilities:** + +#### 1. Physics Simulation + +**Block Stability Testing:** +- Simulate block stacking and stability +- Test maximum unsupported spans +- Validate collision behavior +- Measure performance impact of complex structures + +```python +class BlockPhysicsSimulation: + def test_tower_stability(self, height: int): + """Simulate a tower of blocks to find collapse height""" + tower = [] + for i in range(height): + block = spawn_block(position=(0, 0, i * BLOCK_SIZE)) + tower.append(block) + if not self.run_physics_step(duration=2.0): + return False # Tower collapsed + return True # Stable + + def test_bridge_span(self, span: float): + """Test maximum unsupported bridge length""" + # Place support blocks at ends + # Add bridge panels between + # Simulate physics with weight + return calculate_max_stable_span() +``` + +**Applications:** +- Determine safe building constraints +- Set block limits before performance degrades +- Validate frozen vs unfrozen states +- Test destruction propagation + +#### 2. Combat Mechanics Simulation + +**Weapon Balance Testing:** +- Simulate engagement scenarios +- Calculate time-to-kill (TTK) for different ranges +- Test damage falloff curves +- Validate hit detection + +```python +class CombatSimulation: + def simulate_engagement(self, attacker_class, defender_class, range_m): + """Simulate 1v1 combat encounter""" + attacker = create_player(attacker_class) + defender = create_player(defender_class) + + # Calculate hits based on accuracy at range + hits_to_kill = defender.health / attacker.weapon.damage_at_range(range_m) + time_to_kill = hits_to_kill / attacker.weapon.fire_rate + + # Account for defender's ability to retreat/return fire + defender_can_escape = defender.move_speed * time_to_kill > SAFE_DISTANCE + + return { + 'ttk': time_to_kill, + 'can_escape': defender_can_escape, + 'balance_score': calculate_balance_metric(...) + } +``` + +**Applications:** +- Balance weapon damage and fire rates +- Validate class roles and counters +- Test different engagement scenarios +- Ensure no dominant strategies + +#### 3. Flag Capture Simulation + +**Objective Flow Testing:** +- Simulate flag running routes +- Test capture timing and scoring +- Validate team balance + +```python +class ObjectiveSimulation: + def simulate_capture_attempt(self, fort_layout, runner_class): + """Simulate flag capture with given fort design""" + runner = create_player(runner_class, has_flag=True) + path = calculate_optimal_path(fort_layout, runner.move_speed) + + # Simulate defenders attempting to intercept + defenders = place_defenders(fort_layout) + interception_probability = calculate_interception_chance( + path, defenders, runner.move_speed + ) + + capture_time = len(path) / runner.move_speed + + return { + 'capture_time': capture_time, + 'interception_chance': interception_probability, + 'path_complexity': analyze_path_difficulty(path) + } +``` + +**Applications:** +- Validate map balance +- Test fort effectiveness +- Determine optimal class for flag running +- Balance capture scoring + +#### 4. Build Phase Simulation + +**Fort Construction Strategies:** +- Simulate different building approaches +- Test block placement algorithms +- Measure construction efficiency + +```python +class BuildPhaseSimulation: + def simulate_fort_construction(self, strategy, time_limit): + """Simulate team building a fort""" + fort = Fort() + time_elapsed = 0 + + while time_elapsed < time_limit: + # AI builder places blocks according to strategy + action = strategy.next_action(fort, time_limit - time_elapsed) + + if action.is_valid(): + fort.add_block(action.block, action.position) + time_elapsed += action.duration + + return { + 'blocks_placed': fort.block_count, + 'coverage_score': fort.calculate_coverage(), + 'choke_points': fort.analyze_choke_points(), + 'defensive_rating': fort.calculate_defensive_value() + } +``` + +**Applications:** +- Test AI bot building strategies +- Validate block limits are sufficient +- Benchmark construction efficiency +- Generate example fort designs + +#### 5. Network Performance Simulation + +**Multiplayer Load Testing:** +- Simulate player counts and actions +- Measure replication bandwidth +- Test server tick rate under load + +```python +class NetworkSimulation: + def simulate_multiplayer_match(self, player_count, match_duration): + """Simulate network load for a full match""" + server = MockServer() + players = [MockPlayer() for _ in range(player_count)] + + # Simulate build phase + build_data = self.simulate_build_phase(players) + server.replicate_blocks(build_data) + + # Simulate combat phase + combat_data = self.simulate_combat_phase(players) + server.replicate_combat_events(combat_data) + + return { + 'peak_bandwidth': server.peak_bandwidth_mbps, + 'average_tick_rate': server.average_tick_rate, + 'replication_bottlenecks': server.identify_bottlenecks(), + 'player_count_limit': server.estimate_player_limit() + } +``` + +**Applications:** +- Determine maximum player counts +- Optimize replication strategies +- Identify performance bottlenecks +- Validate network code before implementation + +--- + +### Python Integration + +**Python Usage in UE5:** + +#### 1. Editor Scripts +- Asset batch processing +- Content validation +- Automated testing +- Build pipeline automation + +**Example Use Cases:** +```python +# Batch generate all block variations +from unreal_engine_toolkit import generate_block_library + +def generate_all_blocks(): + """Generate complete block library""" + sizes = ['small', 'medium', 'large'] + types = ['cube', 'panel', 'beam'] + + for size in sizes: + for block_type in types: + generate_block( + type=block_type, + size=size, + output_path=f'/Game/Blocks/{size}_{block_type}' + ) +``` + +#### 2. Content Pipeline +- Import processing +- Texture generation +- Material setup automation +- LOD generation + +#### 3. Testing Infrastructure +- Unit tests for procedural systems +- Integration tests for game mechanics +- Performance benchmarks +- Regression testing + +**Test Framework:** +```python +import unittest +from unreal_fort_tests import BlockGenerator, MapGenerator + +class TestBlockGeneration(unittest.TestCase): + def setUp(self): + self.generator = BlockGenerator() + + def test_cube_generation(self): + """Verify cube blocks generate correctly""" + block = self.generator.create_cube(size=1.0) + self.assertEqual(block.face_count, 6) + self.assertTrue(block.is_manifold()) + self.assertAlmostEqual(block.volume, 1.0, places=2) + + def test_team_material_application(self): + """Verify team colors apply correctly""" + block = self.generator.create_cube(size=1.0) + block.apply_team_material(team='alpha') + self.assertEqual(block.material.team_color, TEAM_ALPHA_COLOR) + +class TestMapGeneration(unittest.TestCase): + def test_symmetrical_layout(self): + """Verify maps generate with symmetry""" + map_gen = MapGenerator(symmetry='x_axis') + layout = map_gen.generate() + self.assertTrue(layout.is_symmetric(tolerance=0.1)) +``` + +#### 4. Data Generation +- Configuration file generation +- Balance tables +- Localization strings +- Documentation generation + +--- + +### Testing Strategy + +#### Unit Tests + +**Coverage Areas:** +1. **Procedural Generation** + - Mesh generation produces valid geometry + - Materials apply correctly + - LODs generate properly + - Collision is accurate + +2. **Game Logic** + - Damage calculations + - Scoring systems + - Phase transitions + - Flag mechanics + +3. **Physics Systems** + - Block stability + - Collision detection + - Freeze/unfreeze states + - Destruction propagation + +**Example Test Suite Structure:** +``` +tests/ +├── unit/ +│ ├── test_block_generation.py +│ ├── test_weapon_stats.py +│ ├── test_damage_calculation.py +│ └── test_physics_stability.py +├── integration/ +│ ├── test_build_phase.py +│ ├── test_combat_phase.py +│ └── test_flag_capture.py +├── simulation/ +│ ├── test_balance_scenarios.py +│ ├── test_map_flow.py +│ └── test_network_load.py +└── performance/ + ├── test_block_limits.py + ├── test_player_counts.py + └── test_rendering_performance.py +``` + +#### Integration Tests + +- Full gameplay cycle tests +- Networked multiplayer scenarios +- Build-to-combat transitions +- Complete match simulations + +#### Performance Tests + +- Frame rate benchmarks with various block counts +- Network bandwidth under load +- Memory usage profiling +- Load time measurements + +#### Continuous Integration + +**Automated Testing Pipeline:** +1. Code commit triggers tests +2. Run unit tests (fast, < 1 minute) +3. Run integration tests (medium, 5-10 minutes) +4. Run simulation tests (slower, 15-30 minutes) +5. Generate test report +6. Block merge if tests fail + +**Benefits:** +- Catch regressions early +- Validate balance changes +- Ensure performance targets +- Document expected behavior + +--- + +### Benefits Summary + +**Procedural Generation + Testing Advantages:** + +1. **Rapid Iteration**: Change parameters, regenerate, test automatically +2. **Consistency**: Algorithmic generation ensures uniform quality +3. **Scalability**: Easy to expand content library +4. **Validation**: Automated testing catches issues early +5. **Documentation**: Tests serve as executable specifications +6. **Balance**: Simulation validates gameplay before implementation +7. **Performance**: Profile generated content before runtime +8. **Maintainability**: Fewer manual assets to maintain +9. **Collaboration**: Designers adjust parameters, not assets +10. **Quality Assurance**: Unit tests prevent regressions + +**Development Workflow:** +``` +1. Define parameters (data-driven design) +2. Write generation algorithm +3. Write unit tests for validation +4. Generate content programmatically +5. Run automated tests +6. Iterate on parameters based on test results +7. Simulate gameplay scenarios +8. Refine based on simulation data +9. Deploy to engine for playtesting +10. Repeat cycle +``` + +This procedural-first approach ensures UnrealForts is built on a solid, testable foundation that can evolve and scale efficiently. + +--- + +## CI/CD Pipeline + +### Overview + +A robust CI/CD (Continuous Integration/Continuous Deployment) pipeline is essential for UnrealForts development, ensuring code quality, catching regressions early, and automating the build and deployment process. The pipeline will handle code validation, automated testing, builds, and deployment to various environments. + +### Pipeline Architecture + +**CI/CD Platform Options:** +- **GitHub Actions**: Primary choice for repository-integrated CI/CD +- **Jenkins**: Alternative for self-hosted solution with more control +- **TeamCity**: Option for Unreal Engine specific optimizations +- **GitLab CI/CD**: If using GitLab for repository hosting + +**Recommended: GitHub Actions** +- Native GitHub integration +- Free for public repositories +- Good Windows support (important for UE5) +- Large ecosystem of actions +- Self-hosted runner support for heavy builds + +--- + +### Pipeline Stages + +#### Stage 1: Code Quality Checks (Fast - 2-5 minutes) + +**Triggered on:** Every push, every pull request + +**Jobs:** +1. **Linting and Code Style** + ```yaml + - name: Lint C++ Code + run: | + clang-format --dry-run --Werror **/*.cpp **/*.h + + - name: Lint Python Code + run: | + pylint scripts/ tests/ + black --check scripts/ tests/ + flake8 scripts/ tests/ + + - name: Lint Blueprints + run: | + python scripts/validate_blueprints.py + ``` + +2. **Static Analysis** + ```yaml + - name: C++ Static Analysis + run: | + clang-tidy Source/**/*.cpp + + - name: Check for Common Issues + run: | + python scripts/check_common_issues.py + # Check for: TODO comments, debug code, hardcoded paths + ``` + +3. **Documentation Check** + ```yaml + - name: Verify Documentation + run: | + python scripts/verify_docs.py + # Ensure public APIs are documented + # Check for broken links in markdown + ``` + +**Success Criteria:** +- All linters pass +- No critical static analysis warnings +- Documentation is complete + +#### Stage 2: Unit Tests (Medium - 5-10 minutes) + +**Triggered on:** After Stage 1 passes + +**Jobs:** +1. **Python Unit Tests** + ```yaml + - name: Run Python Tests + run: | + pytest tests/unit/ --cov=scripts --cov-report=xml + + - name: Upload Coverage + uses: codecov/codecov-action@v3 + with: + files: ./coverage.xml + ``` + +2. **C++ Unit Tests** + ```yaml + - name: Build Test Binaries + run: | + cmake --build build --target UnrealFortsTests + + - name: Run C++ Tests + run: | + ./build/UnrealFortsTests --gtest_output=xml:test-results.xml + ``` + +3. **Procedural Generation Tests** + ```yaml + - name: Test Block Generation + run: | + pytest tests/unit/test_block_generation.py -v + + - name: Test Map Generation + run: | + pytest tests/unit/test_map_generation.py -v + + - name: Validate Generated Assets + run: | + python scripts/validate_generated_assets.py + ``` + +**Success Criteria:** +- All unit tests pass +- Code coverage >= 70% +- No memory leaks detected + +#### Stage 3: Integration Tests (Slower - 15-30 minutes) + +**Triggered on:** After Stage 2 passes (only on main branch and PRs) + +**Jobs:** +1. **Gameplay Simulation Tests** + ```yaml + - name: Run Combat Simulations + run: | + pytest tests/simulation/test_combat_balance.py -v + + - name: Run Physics Simulations + run: | + pytest tests/simulation/test_block_physics.py -v + + - name: Run Network Simulations + run: | + pytest tests/simulation/test_network_load.py -v + ``` + +2. **Integration Test Suite** + ```yaml + - name: Build Phase Integration Tests + run: | + pytest tests/integration/test_build_phase.py -v + + - name: Combat Phase Integration Tests + run: | + pytest tests/integration/test_combat_phase.py -v + + - name: Full Match Simulation + run: | + pytest tests/integration/test_full_match.py -v + ``` + +**Success Criteria:** +- All integration tests pass +- Simulation results within expected parameters +- Balance metrics meet targets + +#### Stage 4: Unreal Engine Build (Heavy - 30-60 minutes) + +**Triggered on:** After Stage 3 passes (main branch, release branches, and tagged releases) + +**Jobs:** +1. **Editor Build** + ```yaml + - name: Setup Unreal Engine + uses: game-ci/setup-unreal@v1 + with: + unreal-version: '5.3' + + - name: Build Editor + run: | + RunUAT BuildEditor -project=UnrealForts.uproject -platform=Win64 + + - name: Verify Editor Starts + run: | + UnrealEditor.exe UnrealForts.uproject -ExecCmds="Automation RunTests System.Core;Quit" -unattended + ``` + +2. **Procedural Content Generation** + ```yaml + - name: Generate Game Content + run: | + UnrealEditor.exe UnrealForts.uproject -run=PythonScript -script=generate_all_content.py -unattended + + - name: Validate Generated Content + run: | + python scripts/validate_ue_content.py + ``` + +3. **Package Game Builds** + ```yaml + - name: Package Windows Client + run: | + RunUAT BuildCookRun -project=UnrealForts.uproject -platform=Win64 -clientconfig=Development -cook -stage -pak -archive -archivedirectory=builds/Windows + + - name: Package Windows Server + run: | + RunUAT BuildCookRun -project=UnrealForts.uproject -platform=Win64 -clientconfig=Development -server -serverconfig=Development -cook -stage -pak -archive -archivedirectory=builds/WindowsServer + + - name: Package Linux Server (Optional) + run: | + RunUAT BuildCookRun -project=UnrealForts.uproject -platform=Linux -server -serverconfig=Development -cook -stage -pak -archive -archivedirectory=builds/LinuxServer + ``` + +**Success Criteria:** +- Editor builds successfully +- All content generates without errors +- Game packages successfully +- Package size within limits + +#### Stage 5: Automated Gameplay Tests (Heavy - 20-40 minutes) + +**Triggered on:** After Stage 4 passes (main branch and release candidates) + +**Jobs:** +1. **Automated Playtesting** + ```yaml + - name: Run Bot Match Tests + run: | + UnrealEditor.exe UnrealForts.uproject -ExecCmds="Automation RunTests Project.BotMatch;Quit" -unattended -ReportOutputPath=test-reports/ + + - name: Analyze Test Results + run: | + python scripts/analyze_bot_match_results.py test-reports/ + ``` + +2. **Performance Benchmarks** + ```yaml + - name: Run Performance Tests + run: | + UnrealEditor.exe UnrealForts.uproject -ExecCmds="Automation RunTests Project.Performance;Quit" -unattended + + - name: Profile Frame Rate + run: | + python scripts/profile_performance.py + + - name: Check Performance Regression + run: | + python scripts/compare_performance.py --baseline=main --current=HEAD + ``` + +3. **Network Load Testing** + ```yaml + - name: Start Test Server + run: | + UnrealFortsServer.exe -log -unattended & + + - name: Simulate Player Load + run: | + python scripts/simulate_multiplayer_load.py --players=32 --duration=300 + + - name: Analyze Network Stats + run: | + python scripts/analyze_network_performance.py + ``` + +**Success Criteria:** +- Bot matches complete without crashes +- Frame rate meets targets (60+ FPS) +- Network performance within acceptable limits +- No memory leaks over extended play + +#### Stage 6: Deployment (Variable time) + +**Triggered on:** Manual approval after Stage 5 passes, or automatically on tagged releases + +**Deployment Targets:** + +1. **Development Builds (Automatic)** + ```yaml + - name: Upload to Development Server + run: | + aws s3 sync builds/ s3://unrealforts-dev/builds/${{ github.sha }}/ --delete + + - name: Update Development Server + run: | + ssh dev-server "cd /opt/unrealforts && ./update.sh ${{ github.sha }}" + + - name: Notify Team + uses: 8398a7/action-slack@v3 + with: + status: custom + custom_payload: | + { + text: "New development build available: ${{ github.sha }}" + } + ``` + +2. **Staging Environment (Automatic on main branch)** + ```yaml + - name: Deploy to Staging + run: | + aws s3 sync builds/ s3://unrealforts-staging/builds/${{ github.sha }}/ + kubectl apply -f k8s/staging/ + kubectl set image deployment/unrealforts-server unrealforts-server=unrealforts:${{ github.sha }} + ``` + +3. **Production (Manual approval required)** + ```yaml + - name: Deploy to Production + if: startsWith(github.ref, 'refs/tags/v') + run: | + aws s3 sync builds/ s3://unrealforts-prod/releases/${{ github.ref_name }}/ + kubectl apply -f k8s/production/ + + - name: Create Release Notes + run: | + python scripts/generate_release_notes.py --version=${{ github.ref_name }} + + - name: Publish to Steam (Future) + run: | + steamcmd +login $STEAM_USER +run_app_build ../scripts/steam_build.vdf +quit + ``` + +--- + +### Self-Hosted Runners + +**Why Self-Hosted Runners:** +- Unreal Engine builds are resource-intensive +- Require Windows machines with specific hardware +- GitHub Actions free tier has limited Windows minutes +- Better control over build environment +- Can leverage powerful hardware (32GB+ RAM, SSD storage) + +**Setup:** +```yaml +# .github/workflows/build.yml +jobs: + unreal-build: + runs-on: [self-hosted, windows, unreal-engine] + steps: + # Build steps here +``` + +**Hardware Requirements:** +- CPU: 8+ cores (Ryzen 9 / Intel i9 or better) +- RAM: 32GB minimum, 64GB recommended +- Storage: 500GB+ SSD for Unreal Engine and build artifacts +- GPU: Not strictly required but helpful for automated testing +- OS: Windows 10/11 or Windows Server 2019+ + +**Runner Configuration:** +```bash +# Install runner as a service +./config.cmd --url https://github.com/yourorg/UnrealForts --token YOUR_TOKEN --labels windows,unreal-engine --unattended +./run.cmd +``` + +--- + +### Caching Strategy + +**Cache Key Elements:** +To speed up builds, cache frequently used but slowly changing data. + +**Caching Unreal Engine:** +```yaml +- name: Cache Unreal Engine + uses: actions/cache@v3 + with: + path: | + C:/UnrealEngine + ~/UnrealEngine + key: ue-5.3-${{ runner.os }} +``` + +**Caching Build Artifacts:** +```yaml +- name: Cache Build Intermediates + uses: actions/cache@v3 + with: + path: | + Intermediate/ + Saved/ + .vs/ + key: build-cache-${{ runner.os }}-${{ hashFiles('Source/**/*.cpp', 'Source/**/*.h') }} + restore-keys: | + build-cache-${{ runner.os }}- +``` + +**Caching Python Dependencies:** +```yaml +- name: Cache Python Dependencies + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: pip-${{ hashFiles('requirements.txt') }} +``` + +**Caching Generated Content:** +```yaml +- name: Cache Generated Assets + uses: actions/cache@v3 + with: + path: Content/Generated/ + key: generated-content-${{ hashFiles('scripts/generate_content.py') }} +``` + +--- + +### Continuous Monitoring + +**Build Metrics to Track:** +1. **Build Times**: Track how long each stage takes +2. **Test Pass Rate**: Percentage of tests passing over time +3. **Code Coverage**: Ensure coverage doesn't decrease +4. **Performance Metrics**: Frame rate, memory usage, network latency +5. **Build Size**: Track package size over time +6. **Failure Rate**: Monitor how often builds fail + +**Monitoring Tools:** +- **GitHub Insights**: Built-in analytics +- **Codecov**: Code coverage tracking +- **Grafana + Prometheus**: Custom metrics dashboards +- **Sentry**: Error tracking and monitoring + +**Alerts:** +```yaml +- name: Notify on Failure + if: failure() + uses: 8398a7/action-slack@v3 + with: + status: ${{ job.status }} + text: 'Build failed on ${{ github.ref }}' + webhook_url: ${{ secrets.SLACK_WEBHOOK }} +``` + +--- + +### Branch Strategy + +**Branch Protection Rules:** + +**Main Branch:** +- Require pull request reviews (1+ approvals) +- Require status checks to pass: + - Code quality checks + - Unit tests + - Integration tests +- Require branches to be up to date +- Require linear history (no merge commits) +- Require signed commits (optional but recommended) + +**Development Branch:** +- Less strict, but still require tests to pass +- Automatic deployment to dev environment + +**Feature Branches:** +- Run code quality and unit tests only (faster feedback) +- Full integration tests only when merging to main + +**Release Branches:** +- Full test suite +- Additional release candidate testing +- Manual deployment approval + +**Workflow:** +``` +feature/new-weapon → PR → development → PR → main → tag → production + ↓ ↓ ↓ + Tests Full CI Release +``` + +--- + +### Example GitHub Actions Workflow + +**Complete workflow file:** + +```yaml +# .github/workflows/ci.yml +name: UnrealForts CI/CD + +on: + push: + branches: [ main, development ] + tags: [ 'v*' ] + pull_request: + branches: [ main, development ] + +env: + UE_VERSION: '5.3' + PROJECT_NAME: 'UnrealForts' + +jobs: + code-quality: + name: Code Quality Checks + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install Python dependencies + run: | + pip install -r requirements-dev.txt + + - name: Lint Python + run: | + black --check scripts/ tests/ + flake8 scripts/ tests/ + pylint scripts/ tests/ + + - name: Check C++ formatting + run: | + python scripts/check_cpp_format.py + + - name: Static analysis + run: | + python scripts/static_analysis.py + + unit-tests: + name: Unit Tests + needs: code-quality + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + pip install -r requirements.txt + pip install -r requirements-test.txt + + - name: Run Python unit tests + run: | + pytest tests/unit/ --cov=scripts --cov-report=xml -v + + - name: Upload coverage + uses: codecov/codecov-action@v3 + with: + files: ./coverage.xml + + - name: Test procedural generation + run: | + pytest tests/unit/test_block_generation.py -v + pytest tests/unit/test_map_generation.py -v + + integration-tests: + name: Integration Tests + needs: unit-tests + runs-on: ubuntu-latest + if: github.event_name == 'push' || github.base_ref == 'main' + steps: + - uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + pip install -r requirements.txt + pip install -r requirements-test.txt + + - name: Run simulations + run: | + pytest tests/simulation/ -v + + - name: Run integration tests + run: | + pytest tests/integration/ -v + + unreal-build: + name: Build Unreal Engine Project + needs: integration-tests + runs-on: [self-hosted, windows, unreal-engine] + if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') + steps: + - uses: actions/checkout@v3 + + - name: Generate procedural content + run: | + python scripts/generate_all_content.py + + - name: Build Editor + run: | + & "C:/UnrealEngine/Engine/Build/BatchFiles/RunUAT.bat" BuildEditor -project="${{ github.workspace }}/${{ env.PROJECT_NAME }}.uproject" -platform=Win64 + + - name: Run Unreal automation tests + run: | + & "C:/UnrealEngine/Engine/Binaries/Win64/UnrealEditor.exe" "${{ github.workspace }}/${{ env.PROJECT_NAME }}.uproject" -ExecCmds="Automation RunTests System;Quit" -unattended -nopause -NullRHI -log + + - name: Package game + run: | + & "C:/UnrealEngine/Engine/Build/BatchFiles/RunUAT.bat" BuildCookRun -project="${{ github.workspace }}/${{ env.PROJECT_NAME }}.uproject" -platform=Win64 -clientconfig=Development -cook -stage -pak -archive -archivedirectory="${{ github.workspace }}/builds/Windows" + + - name: Upload build artifacts + uses: actions/upload-artifact@v3 + with: + name: windows-build-${{ github.sha }} + path: builds/Windows/ + retention-days: 30 + + deploy-dev: + name: Deploy to Development + needs: unreal-build + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + steps: + - name: Download build artifacts + uses: actions/download-artifact@v3 + with: + name: windows-build-${{ github.sha }} + + - name: Deploy to dev server + run: | + aws s3 sync . s3://unrealforts-dev/builds/${{ github.sha }}/ --delete + + - name: Notify team + uses: 8398a7/action-slack@v3 + with: + status: custom + custom_payload: | + { + text: "New development build deployed: ${{ github.sha }}" + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }} + + deploy-production: + name: Deploy to Production + needs: unreal-build + runs-on: ubuntu-latest + if: startsWith(github.ref, 'refs/tags/v') + environment: + name: production + url: https://play.unrealforts.com + steps: + - name: Download build artifacts + uses: actions/download-artifact@v3 + with: + name: windows-build-${{ github.sha }} + + - name: Deploy to production + run: | + aws s3 sync . s3://unrealforts-prod/releases/${{ github.ref_name }}/ --delete + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + with: + files: | + builds/Windows/**/* + generate_release_notes: true +``` + +--- + +### Benefits of CI/CD for UnrealForts + +1. **Automated Testing**: Catch bugs before they reach players +2. **Consistent Builds**: Every build is reproducible +3. **Fast Iteration**: Developers get quick feedback +4. **Quality Assurance**: Enforced code standards +5. **Confidence**: Deploy with confidence knowing tests pass +6. **Transparency**: Team visibility into build status +7. **Procedural Validation**: Automated testing of generated content +8. **Performance Tracking**: Monitor performance regressions +9. **Balance Validation**: Simulate gameplay to ensure balance +10. **Documentation**: CI output serves as project documentation + +The CI/CD pipeline is critical for maintaining code quality and rapid iteration in UnrealForts development, especially given the procedural generation approach that enables comprehensive automated testing. + +--- + +## Development Roadmap + +### Phase 1: Core Prototype +- Basic build and combat phase system +- Simple block types and physics manipulation +- Basic flag capture mechanics +- Single test map +- Basic networking + +### Phase 2: Gameplay Expansion +- Multiple block types and sizes +- Full class system with weapons +- Destructible blocks +- Phase transition polish +- Multiple maps + +### Phase 3: Polish and Balance +- UI/UX refinement +- Visual and audio polish +- Gameplay balancing +- Performance optimization +- Tutorial system + +### Phase 4: Community Features +- Server browser +- Custom server settings +- Workshop integration +- Replay system +- Statistics tracking + +--- + +## Success Metrics + +### Player Engagement +- Average match duration +- Player retention rate +- Matches per player session + +### Balance Indicators +- Win rate parity between teams +- Class selection distribution +- Average fort complexity and effectiveness + +### Technical Performance +- Server tick rate stability +- Client frame rate (target: 60+ FPS) +- Network latency tolerance +- Block count limits without performance degradation + +--- + +## Conclusion + +UnrealForts aims to bring innovative build-and-combat gameplay to a modern audience using Unreal Engine 5. By implementing the core build-combat cycle while leveraging UE5's advanced capabilities, the project will deliver a fresh take on the fusion of construction and competitive FPS action. The original implementation ensures a unique experience while staying true to the spirit of tactical creativity and team-based action. + +This design brief serves as the foundation for development, providing clear direction on mechanics, technical implementation, and player experience goals. Success will be measured by creating an engaging, balanced, and performant multiplayer experience that captures the magic of building forts and then battling over them.