diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2e5ccea
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+# Ultcraft
+
+A Minecraft Fabric mod that adds an **Ultimate Ability** system inspired by Overwatch. Build up charge through combat and time, then unleash powerful abilities!
+
+## Features
+
+### Ultimate Charge System
+- **Passive Charging**: Gain 100% charge over 15 minutes (6.67% per minute)
+- **Combat Charging**: Gain 3% charge per 6 damage points (3 hearts) dealt to enemies
+- Charge caps at 100%
+
+### Available Ultimates
+
+#### Armed and Dangerous (Default)
+Grants powerful combat buffs for close-quarters fighting:
+- **Strength II** for 10 seconds
+- **Regeneration II** for 10 seconds
+
+#### Like a Rabbit
+Grants enhanced mobility for rapid repositioning:
+- **Speed II** for 15 seconds
+- **Jump Boost II** for 15 seconds
+
+### Visual Feedback
+- **Circular HUD**: Displays charge percentage in the bottom-left corner
+- **Progress Ring**: Gold ring fills as you charge
+- **Ready Indicator**: Ring turns green and displays "READY!" when at 100%
+- **Smooth Animations**: Animated charge depletion on activation
+
+### Ultimate Selection
+- Press the ultimate menu key to switch between ultimate types
+- **Switch Penalty**: Charge is capped at 15% when changing ultimates
+- Visual selection screen shows all available ultimates
+
+## Requirements
+
+- **Minecraft**: 1.21.11
+- **Fabric Loader**: 0.18.4 or higher
+- **Fabric API**: 0.141.1+1.21.11 or higher
+- **Java**: 21 or higher
+
+## Installation
+
+1. Install [Fabric Loader](https://fabricmc.net/use/) for Minecraft 1.21.11
+2. Download [Fabric API](https://modrinth.com/mod/fabric-api) 0.141.1+1.21.11
+3. Download the latest Ultcraft release
+4. Place both JAR files in your `.minecraft/mods` folder
+5. Launch Minecraft with the Fabric profile
+
+## Keybindings
+
+Configure in Options → Controls → Key Binds:
+- **Activate Ultimate**: Trigger your charged ultimate ability
+- **Ultimate Selection Menu**: Open the ultimate selection screen
+
+## Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd ultcraft
+
+# Build the mod
+./gradlew build
+
+# The compiled JAR will be in build/libs/
+```
+
+### Development Environment Setup
+
+```bash
+# Generate IDE run configurations
+./gradlew genSources
+
+# For IntelliJ IDEA
+./gradlew idea
+
+# For Eclipse
+./gradlew eclipse
+
+# For VSCode
+./gradlew vscode
+```
+
+### Project Structure
+
+```
+src/
+├── main/                          # Server-side and shared code
+│   ├── java/com/ottohg/ultcraft/
+│   │   ├── Ultcraft.java         # Main mod initializer
+│   │   ├── UltimateData.java     # Core charge management
+│   │   ├── UltimateType.java     # Ultimate ability definitions
+│   │   ├── mixin/                # Server-side mixins
+│   │   └── network/              # Network packet handling
+│   └── resources/
+│       ├── fabric.mod.json       # Mod metadata
+│       └── ultcraft.mixins.json  # Mixin configuration
+└── client/                        # Client-side only code
+    ├── java/com/ottohg/ultcraft/
+    │   ├── UltcraftClient.java   # Client initializer
+    │   └── client/
+    │       ├── ClientUltimateData.java      # Client charge tracking
+    │       ├── UltimateHudRenderer.java     # HUD rendering
+    │       ├── UltimateKeybinding.java      # Keybind registration
+    │       └── UltimateSelectionScreen.java # Selection UI
+    └── resources/
+        └── ultcraft.client.mixins.json
+```
+
+### Technical Implementation
+
+- **Mixin Framework**: Injects into Minecraft's damage system to track combat damage
+- **Network Packets**: Custom packets for client-server charge synchronization
+- **Server Authoritative**: All charge calculations happen server-side to prevent cheating
+- **Thread-Safe**: UUID-based player data storage with proper synchronization
+
+## License
+
+This mod is available under the CC0 license. Feel free to learn from it and incorporate it in your own projects.
+
+## Contributing
+
+Contributions are welcome! Feel free to submit issues or pull requests.
+
+## Credits
+
+Developed by ottohg
+
+---
+
+*Inspired by the ultimate ability system from Overwatch*