mirror of
https://github.com/johndoe6345789/ArenaFPS.git
synced 2026-04-26 06:34:58 +00:00
Add comprehensive documentation (CONTRIBUTING, QUICKSTART guides)
Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
215
CONTRIBUTING.md
Normal file
215
CONTRIBUTING.md
Normal file
@@ -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:
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[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!
|
||||
179
QUICKSTART.md
Normal file
179
QUICKSTART.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user