DungeonsOfKharadum/README.md

# Multiplayer Coop Top-Down Action RPG

A Godot 4.6 multiplayer cooperative game supporting both local and online multiplayer with physics-based interactions.

Start with arguments:

--host or --join # instantly hosts or joins a game

--room-debug # shows information above each room what types of puzzles it has, and if player entered the room or not...

--webrtc # this selects webrtc network mode directly. if combined with --join it will try to find room and join that.

## Features

### Multiplayer Support
- **Host or Join**: Any player can host a game or join an existing one

- **Local Multiplayer**: Each machine can have multiple local players (up to 4)

  - First local player uses keyboard controls

  - Additional local players use gamepads

- **Online Multiplayer**: Players can join from different machines

- **Drop-in/Drop-out**: Players can join at any time during gameplay

### Gameplay Mechanics
- **Top-Down Action RPG**: Classic top-down perspective with smooth character movement

- **Physics-Based Interactions**:

  - **Lift (Tap Grab)**: Pick up objects above your head and carry them

  - **Push/Pull (Hold Grab)**: Hold the grab button to push or pull objects

  - **Throw**: While lifting, tap grab again to throw in movement direction

  - **Arc Physics**: Thrown objects and players fly in realistic arcs with Z-axis simulation

  - **Dynamic Shadows**: Shadows scale and fade based on height

  - **Box Breaking**: Boxes shatter into 4 pieces when hitting players or other boxes

  - **Damage System**: Players take damage and knockback from thrown boxes

### Camera System
- Dynamic camera that follows all local players

- Automatically adjusts zoom based on player spread

- Smooth camera movement for comfortable gameplay

## Controls

### Player 1 (Keyboard)

- **WASD** or **Arrow Keys**: Move

- **E (Tap)**: Lift object above head
- **E (Hold)**: Push/Pull object
- **E (While Lifting + Moving)**: Throw object
- **E (While Lifting + Still)**: Place down object

### Player 2+ (Gamepad)
- **Left Stick**: Move
- **A Button (Tap)**: Lift object above head
- **A Button (Hold)**: Push/Pull object
- **A Button (While Lifting + Moving)**: Throw object
- **A Button (While Lifting + Still)**: Place down object

## How to Play

### Starting a Game

1. **Host a Game**:

   - Set the number of local players (1-4)

   - Click "Host Game"

   - Share your IP address with friends who want to join

2. **Join a Game**:
   - Set the number of local players (1-4)

   - Enter the host's IP address
   
   - Click "Join Game"

### Command-Line Testing (Easy Multiplayer Testing)

You can launch the game with command-line arguments to automatically host or join, making it easy to test multiplayer with multiple instances:

**Host Instance:**
```bash
# Windows
godot.exe --path "C:\dev\godot\multiplayer-coop" -- --host

# Or with custom player count
godot.exe --path "C:\dev\godot\multiplayer-coop" -- --host --players=2
```

**Join Instance:**
```bash
# Windows
godot.exe --path "C:\dev\godot\multiplayer-coop" -- --join

# Or with custom address and player count
godot.exe --path "C:\dev\godot\multiplayer-coop" -- --join --address=127.0.0.1 --players=2
```

**Quick Test Setup:**
1. Open 3 terminals
2. Terminal 1: `godot.exe --path "path/to/project" -- --host`
3. Terminal 2: `godot.exe --path "path/to/project" -- --join`
4. Terminal 3: `godot.exe --path "path/to/project" -- --join`

All instances will automatically start and connect - no clicking required!

**Available Arguments:**
- `--host` - Automatically host a game
- `--join` - Automatically join a game
- `--address=IP` - Server address to join (default: 127.0.0.1)
- `--players=N` - Number of local players (default: 1, max: 4)

### Gameplay

**Lifting Objects:**
1. Get close to an object (box)
2. **Tap** the grab button (E or A)
3. Object appears above your head
4. **Move + Tap** grab to throw it
5. **Stand still + Tap** grab to place it down

**Pushing/Pulling Objects:**
1. Get close to an object
2. **Hold** the grab button (E or A)
3. Move with WASD/stick to push/pull
4. **Release** button to let go

**Other Interactions:**
- Walk into objects to push them naturally
- Grab other players the same way as objects
- Throw players for fun chaos! They fly in arcs just like boxes
- Throw boxes at players to damage and knock them back
- Boxes break into 4 pieces when hitting players or other boxes
- Work together to move heavy objects

## Technical Details

### Network Architecture
- Uses Godot's built-in ENet multiplayer system
- Server-authoritative architecture for consistency
- Supports up to 8 concurrent connections
- Default port: 7777

### Project Structure
```
multiplayer-coop/
├── scenes/
│   ├── main.tscn              # Entry point
│   ├── main_menu.tscn         # Main menu UI
│   ├── game_world.tscn        # Game arena
│   ├── player.tscn            # Player character
│   └── interactable_object.tscn # Grabbable objects
├── scripts/
│   ├── network_manager.gd     # Network handling (autoload)
│   ├── player_manager.gd      # Player spawning
│   ├── game_world.gd          # Game logic
│   ├── player.gd              # Player controller
│   ├── interactable_object.gd # Object physics
│   └── game_ui.gd             # UI logic
└── project.godot
```

### Key Systems

#### Network Manager (Autoload)
- Handles hosting and joining games
- Manages player registration and synchronization
- Tracks all connected players and their local player counts

#### Player Manager
- Spawns players for each peer
- Manages player lifecycle (spawn/despawn)
- Handles local vs remote player distinction

#### Player Controller
- Input handling for keyboard and multiple gamepads
- Physics-based movement
- Interaction system (grab/throw)
- Network synchronization

#### Interactable Objects
- RigidBody2D-based physics
- Can be grabbed, pushed, and thrown
- Weight affects throw distance

## Development Notes

### Adding New Features

**New Interactable Objects**:
1. Create a scene inheriting from `interactable_object.tscn`
2. Adjust the sprite, collision shape, and mass
3. Optionally override interaction methods

**Custom Player Abilities**:
1. Add new input actions in Project Settings
2. Implement ability logic in `player.gd`
3. Add network synchronization if needed

**New Game Modes**:
1. Create a new scene inheriting from `game_world.tscn`
2. Add game mode logic in a new script
3. Update the main menu to select game modes

### Testing Multiplayer

**Local Testing**:
1. Run the game from Godot editor
2. Click "Host Game"
3. Run a second instance from the exported build
4. Enter "127.0.0.1" and click "Join Game"

**Network Testing**:
1. Host on one machine
2. Find the host's local IP address (ipconfig/ifconfig)
3. Join from another machine on the same network
4. For internet play, configure port forwarding on port 7777

## Troubleshooting

**Connection Failed**:
- Verify the IP address is correct
- Check firewall settings (allow port 7777)
- Ensure both machines are on the same network (for LAN play)

**Players Not Spawning**:
- Check the console for errors
- Verify the player scene is assigned in PlayerManager
- Ensure NetworkManager is loaded as an autoload

**Gamepad Not Working**:
- Connect gamepad before starting the game
- Check gamepad is recognized in Godot's input settings
- Verify you have more than 1 local player selected

**Objects Not Grabbable**:
- Ensure object has `can_be_grabbed()` method
- Check GrabArea collision layers/masks
- Verify object is within grab range (80 units)

## Future Enhancements

- [ ] Combat system with health and damage
- [ ] Enemy AI
- [ ] Level progression and multiple maps
- [ ] Character customization
- [ ] Inventory system
- [ ] Cooperative puzzles
- [ ] Voice chat integration
- [ ] Dedicated server support

## License

This project is open source and available for modification and distribution.

## Credits

Built with Godot Engine 4.6