FL4P_B0X

N3on Fl4ppy Adv3ntur3 - A cyberpunk-themed arcade game with combat mechanics, built in Zig with Raylib.

Overview

FL4P_B0X is an arcade survival game featuring neon aesthetics, dynamic combat, and progressive difficulty scaling. Navigate through procedurally generated pipes while battling AI enemies in a visually stunning cyberpunk environment.

Features

Core Gameplay

Tap-Jump Mechanics - Precise single-tap jump control with hold penalty system
Progressive Difficulty - 4 difficulty tiers with tighter gaps and increased enemy spawns
Score-Based Scaling - Gap sizes, pipe spacing, and enemy stats scale with player progress
3-Life System - Strategic respawn system with gap-aligned positioning

Combat System

Directional Shooting - WASD laser system for 360-degree combat
AI Enemy Swarms - Chasing enemies with score-based spawn rates (1-4 simultaneous)
Enemy Health Scaling - Enemies grow tougher (1-5 HP) as you progress
Health Management - 100 HP system with 25 damage per hit and 5-second recharge delay
Spawn Limiting - Maximum 8 enemies on screen to prevent overwhelming

Visual Design

Neon Cyberpunk Aesthetic - Multi-layer lighting with highlights, midtones, and shadows
Animated Pixel Background - Dynamic monochrome patterns with diagonal waves
Glossy UI Elements - Lit panels with shadows, glows, and border effects
Smooth Animations - Frame-based animations for title glow and button pulses
Color-Coded Entities:
- Player: Neon Cyan
- Pipes: Neon Magenta
- Floor: Neon Red
- Enemies: Indigo
- Lasers: Neon Green

Game States

Main Menu - Interactive buttons with hover effects and animated title
Countdown Tutorial - 7-second keybind display with fade-out (6s visible, 1s fade)
Playing State - Full gameplay with all combat and movement systems
Smart Respawn - Gap-aligned positioning to prevent spawn-death loops

Installation

Prerequisites

Zig 0.16.0 or later
Raylib (automatically fetched via Zig package manager)

Building from Source

# Clone the repository
git clone <repository-url>
cd Fl4p_b0x

# Build the game
zig build

# Run the game
zig build run

Build Targets

# Debug build (default)
zig build

# Release build (optimized)
zig build -Doptimize=ReleaseFast

# Run directly
zig build run

Controls

Gameplay

SPACE - Jump (tap for optimal lift, holding causes fast drop penalty)
W - Shoot laser upward
A - Shoot laser left
S - Shoot laser downward
D - Shoot laser right

Game Mechanics

Movement System

Constant Forward Motion - Player always moves right at 2 px/frame
Gravity System - 2 px/frame downward acceleration
Jump Strength - 60 pixels of upward velocity per tap
Hold Penalty - Holding SPACE > 500ms causes 3x gravity (fast drop)

Difficulty Progression

Score Range	Gap Size	Pipe Spacing	Enemies/Wave	Enemy HP
0-3	220-260	350-450	1	1
4-8	180-220	300-400	2	2
9-15	160-200	280-360	3	3
16-25	140-180	250-320	4	4
26+	140-180	250-320	4	5 (max)

Combat Mechanics

Laser Speed - 15 px/frame
Laser Lifetime - 180 frames (3 seconds)
Laser Cooldown - 10 frames (167ms)
Enemy Speed - 3 px/frame chase movement
Enemy Spawn Interval - 300 frames (5 seconds)
Damage Values - 25 HP per enemy hit, 1 HP damage per laser
Health Recharge - 1 HP/frame after 5-second delay

Respawn System

Position - 200 pixels before collision pipe
Vertical Alignment - Centered in pipe gap for safe passage
Invulnerability - 60 frames (1 second) after respawn
Health Reset - Full 100 HP restoration

Technical Details

Architecture

Language - Zig 0.16.0
Graphics - Raylib 5.6-dev
Target FPS - 60
Window Size - 1000x750 (25% larger than classic 800x600)
World Boundaries - ±750 vertical units
Entity System - Modular design with separate files per entity type

Project Structure

Fl4p_b0x/
├── src/
│   ├── main.zig       # Core game loop, state management, rendering
│   ├── player.zig     # Player entity with health system
│   ├── pipe.zig       # Obstacle pipes with collision detection
│   ├── enemy.zig      # AI enemy with chase behavior
│   ├── laser.zig      # Projectile system
│   ├── util.zig       # Utility functions
│   └── root.zig       # Module exports
├── build.zig          # Build configuration
├── build.zig.zon      # Dependencies
└── README.md          # This file

Color Constants

All colors are configurable via constants in main.zig:

Player colors (5 layers: base, 2 highlights, midtone, shadow)
Pipe colors (5 layers: base, 2 highlights, midtone, shadow)
Floor colors (5 layers: base, 2 highlights, midtone, shadow)
Enemy colors (5 layers: base, 2 highlights, midtone, shadow)
Laser colors (base + glow)
UI colors (lives, score, health bar)
Background pixel colors (3 shades)

Development

Code Style

Explicit Typing - Clear type annotations for readability
Comprehensive Comments - Section headers and inline documentation
Modular Design - Separate entity files with public interfaces
Constant Configuration - All magic numbers defined as named constants

Performance Optimizations

Entity Pooling - Fixed-size arrays (10 pipes, 15 enemies, 30 lasers)
Culling - Inactive entities beyond screen bounds
Efficient Collision - AABB detection with early exits
Frame Limiting - Consistent 60 FPS cap

Future Enhancements

Particle effects for explosions
Power-ups (shields, rapid fire, slow-motion)
Boss encounters at milestone scores
High score persistence
Customizable color themes
Gamepad support
Audio system (music and SFX)
Achievements system

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Development Setup

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is open source and available under the Apache License 2.0.

The Apache 2.0 license provides:

✅ Explicit patent grants for all contributors
✅ Patent retaliation protection
✅ Clear terms for modifications and redistribution
✅ Commercial use allowed

Credits

Game Engine - Raylib by Ramon Santamaria
Language - Zig Programming Language
Raylib Zig Bindings - raylib-zig

Acknowledgments

Special thanks to the Zig and Raylib communities for their excellent documentation and support.

Made with ⚡ and Zig

Dependencies

README