From 25d58a0e1fef7f424e638c563d93e0089dec46e8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 24 Dec 2025 13:18:18 +0000 Subject: [PATCH] Add comprehensive documentation (CONTRIBUTING, QUICKSTART guides) Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- CONTRIBUTING.md | 215 ++++++++++++++++++++++++++++++++++++++++++++++++ QUICKSTART.md | 179 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 394 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 QUICKSTART.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..79803816 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,215 @@ +# Contributing to Unreal3Arena + +Thank you for your interest in contributing to Unreal3Arena! This document provides guidelines and instructions for contributing to the project. + +## Getting Started + +1. **Fork the repository** +2. **Clone your fork** + ```bash + git clone https://github.com/YOUR_USERNAME/Unreal3Arena.git + cd Unreal3Arena + ``` + +3. **Run setup script** + ```bash + ./setup.sh + ``` + +4. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +## Development Workflow + +### Prerequisites + +- **Unreal Engine 5.7** installed +- **Python 3.11+** with pip +- **Git** for version control +- Text editor or IDE (VS Code, Visual Studio, Rider, etc.) + +### Project Structure + +``` +Unreal3Arena/ +├── Plugins/GameFeatures/Quake3Arena/ # Game mode plugin +│ ├── Source/ # C++ source code +│ ├── Content/ # Blueprints and assets +│ └── README.md # Plugin documentation +├── Tools/ProceduralGeneration/ # Python generators +│ ├── arena_generator.py +│ ├── weapon_generator.py +│ └── test_*.py # Unit tests +└── .github/workflows/ # CI/CD pipelines +``` + +### Making Changes + +#### C++ Code Changes + +1. Make your changes in the appropriate source files +2. Follow Unreal Engine coding standards +3. Build the project in Unreal Editor +4. Test your changes + +#### Python Code Changes + +1. Make changes to generator scripts +2. Add/update unit tests +3. Run tests locally: + ```bash + cd Tools/ProceduralGeneration + python -m pytest test_*.py -v + ``` +4. Generate assets to verify: + ```bash + python generate_all.py + ``` + +### Testing + +#### Python Tests + +Run all tests: +```bash +cd Tools/ProceduralGeneration +python -m pytest -v +``` + +Run specific test file: +```bash +python test_arena_generator.py +``` + +#### Unreal Engine Tests + +1. Open project in Unreal Editor +2. Run any existing automation tests +3. Manually test gameplay changes + +### Code Quality + +#### Python + +- Follow PEP 8 style guide +- Add docstrings to functions and classes +- Keep functions focused and testable +- Add type hints where appropriate + +#### C++ + +- Follow Unreal Engine coding standards +- Use appropriate Unreal macros (UCLASS, UFUNCTION, UPROPERTY) +- Add comments for complex logic +- Keep header files clean and minimal + +### Commit Messages + +Follow conventional commits format: + +``` +(): + +[optional body] + +[optional footer] +``` + +Types: +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks + +Examples: +``` +feat(bot): Add advanced pathfinding for bots +fix(arena): Correct platform height calculation +docs(readme): Update installation instructions +test(generator): Add tests for weapon generation +``` + +## Pull Request Process + +1. **Update documentation** if needed +2. **Add tests** for new features +3. **Ensure all tests pass** + ```bash + cd Tools/ProceduralGeneration + python -m pytest -v + ``` +4. **Push to your fork** + ```bash + git push origin feature/your-feature-name + ``` +5. **Open a Pull Request** on GitHub +6. **Describe your changes** in the PR description +7. **Wait for review** and address any feedback + +### PR Checklist + +- [ ] Tests added for new features +- [ ] All tests passing +- [ ] Documentation updated +- [ ] Code follows project style guidelines +- [ ] Commits follow conventional commit format +- [ ] No merge conflicts + +## Areas for Contribution + +### High Priority + +- **Weapon System**: Implement Q3A weapons (Rocket Launcher, Railgun, etc.) +- **Pickup System**: Health and armor pickups +- **Movement System**: Strafe jumping and bunny hopping +- **HUD**: Score display, health/armor indicators + +### Medium Priority + +- **Bot Improvements**: Better pathfinding, difficulty levels +- **Game Modes**: Team Deathmatch, Capture the Flag +- **Maps**: More procedural map templates +- **Effects**: Particle effects for weapons + +### Low Priority + +- **Powerups**: Quad Damage, Haste, etc. +- **Spectator Mode**: Watch other players +- **Demo Recording**: Record and replay matches +- **Modding Support**: Plugin system for custom content + +## Code Review Process + +All submissions require review before merging: + +1. **Automated checks** must pass (CI/CD) +2. **Code review** by maintainers +3. **Testing** in development environment +4. **Documentation** review if applicable + +## Community Guidelines + +- Be respectful and constructive +- Help others learn and improve +- Focus on the code, not the person +- Accept and provide constructive feedback +- Follow the code of conduct + +## Questions? + +- Open an issue for bugs or feature requests +- Join discussions in existing issues +- Check documentation first (README.md, plugin docs, etc.) + +## License + +By contributing, you agree that your contributions will be licensed under the same license as the project. + +## Thank You! + +Your contributions help make Unreal3Arena better for everyone. We appreciate your time and effort! diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 00000000..bcf5d3c5 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,179 @@ +# Quake3Arena Quick Reference + +## Quick Start + +```bash +# 1. Setup environment +./setup.sh + +# 2. Generate all assets +cd Tools/ProceduralGeneration +python generate_all.py + +# 3. Open in Unreal Engine +# Open Unreal3Arena.uproject in UE 5.7 +``` + +## Common Commands + +### Procedural Generation + +```bash +# Generate everything +python generate_all.py + +# Generate arena only +python arena_generator.py + +# Generate weapons only +python weapon_generator.py + +# Run tests +python -m pytest test_arena_generator.py -v +``` + +### Git Workflow + +```bash +# Create feature branch +git checkout -b feature/my-feature + +# Make changes, then commit +git add . +git commit -m "feat: description" + +# Push to fork +git push origin feature/my-feature +``` + +## File Locations + +| What | Where | +|------|-------| +| Game Mode | `Plugins/GameFeatures/Quake3Arena/Source/.../Quake3GameMode.cpp` | +| Bot AI | `Plugins/GameFeatures/Quake3Arena/Source/.../Quake3Bot.cpp` | +| Geometry Importer | `Plugins/GameFeatures/Quake3Arena/Source/.../ArenaGeometryImporter.cpp` | +| Arena Generator | `Tools/ProceduralGeneration/arena_generator.py` | +| Weapon Generator | `Tools/ProceduralGeneration/weapon_generator.py` | +| CI/CD Config | `.github/workflows/` | + +## Key Classes + +### C++ Classes + +| Class | Purpose | +|-------|---------| +| `AQuake3GameMode` | Main game mode with Q3A rules | +| `AQuake3Bot` | Bot AI controller | +| `AArenaGeometryImporter` | Imports JSON geometry to UE5 | + +### Python Classes + +| Class | Purpose | +|-------|---------| +| `ArenaGenerator` | Generates arena geometry | +| `WeaponGenerator` | Generates weapon meshes | +| `PickupGenerator` | Generates pickup items | + +## Game Mode Settings + +In Blueprint or C++: + +```cpp +FragLimit = 25; // Frags to win +TimeLimit = 600.0f; // Time limit (seconds) +NumberOfBots = 3; // Bots to spawn +RespawnDelay = 3.0f; // Respawn delay +``` + +## Bot Settings + +```cpp +SkillLevel = 2; // 0-5 (5 = nightmare) +BotName = "Crash"; // Display name +AccuracyModifier = 0.7f; // Aim accuracy +ReactionTime = 0.3f; // Response time +``` + +## Geometry Import + +In Blueprint: + +``` +1. Add ArenaGeometryImporter actor to level +2. Set JsonFilePath = "path/to/arena_geometry.json" +3. Set DefaultMaterial +4. Play - geometry loads automatically +``` + +Or call from Blueprint: +```cpp +ImportArenaFromJson("/Game/Data/arena_geometry.json"); +``` + +## Arena Customization + +Edit `arena_generator.py`: + +```python +# Change size +generator = ArenaGenerator(size=10000.0, height=2000.0) + +# Modify platforms in generate_platforms() +platform_configs = [ + (x, y, z, width, depth, height), +] +``` + +## Testing Checklist + +- [ ] Python tests pass: `pytest test_*.py -v` +- [ ] Assets generate: `python generate_all.py` +- [ ] Project opens in UE5 +- [ ] Plugin loads without errors +- [ ] Bots spawn in level +- [ ] Game mode functions + +## Troubleshooting + +**Geometry not appearing?** +- Check JsonFilePath is correct +- Verify JSON is valid +- Assign DefaultMaterial + +**Bots not spawning?** +- Add Player Starts to level +- Set NumberOfBots > 0 +- Check console for errors + +**Build errors?** +- Verify UE5.7 is installed +- Check module dependencies in .Build.cs +- Regenerate project files + +## Useful Links + +- [Unreal Engine Documentation](https://docs.unrealengine.com/) +- [Lyra Sample Game](https://docs.unrealengine.com/5.0/en-US/lyra-sample-game-in-unreal-engine/) +- [Python API for UE5](https://docs.unrealengine.com/5.0/en-US/PythonAPI/) + +## Project Status + +✅ Implemented: +- Game mode with Q3A rules +- Bot AI with state machine +- Procedural arena generation +- Weapon/pickup generators +- Geometry importer +- CI/CD pipeline +- Unit tests + +🚧 In Progress: +- Weapon system integration +- Pickup actors +- Enhanced bot behavior + +📋 Planned: +- Movement mechanics +- HUD/Scoreboard +- Additional game modes