# gamedemo_3d

**Repository Path**: voidvvv/gamedemo_3d

## Basic Information

- **Project Name**: gamedemo_3d
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# game-demo-01

A 3D game demo built with [libGDX](https://libgdx.com/) 1.14.0, featuring Bullet physics, third-person camera, and a component-based entity system.

## Current Status: MVP Prototype

The project has completed its first milestone — a fully functional 3D game world with physics-based player control, NPCs, and third-person camera. The 2D sprite demo has been replaced with a 3D scene.

### Features

- **3D Physics World** — Bullet physics engine integration with gravity, collision, and rigid body dynamics
- **Player Control** — WASD movement relative to camera direction, space to jump
- **Third-Person Camera** — Right-click drag to orbit around the player, with pitch and yaw constraints
- **NPC Entities** — 3 static NPC characters placed in the world
- **Procedural Models** — All 3D models generated at runtime (no asset files needed): player with body+head, ground plane, colored NPCs
- **Rendering Pipeline** — Shader abstraction layer (`GameShader` interface) with batch dispatch via `ShaderManager`, default shader wraps libGDX `ModelBatch`
- **Directional Lighting** — Ambient + directional light for basic 3D shading

### Controls

| Key | Action |
|-----|--------|
| W / A / S / D | Move player (relative to camera) |
| Space | Jump |
| Right-click + drag | Rotate camera |

## Architecture

```
Main.java (entry point, wires all systems)
  └── GameWorld (per-frame coordinator)
        ├── PlayerController  → input handling
        ├── PhysicsWorld      → Bullet dynamics step
        ├── Transform sync    → physics → transform → render
        ├── ThirdPersonCamera → camera update
        └── RenderWorld       → collect entities, dispatch to shaders
```

**Per-frame update loop:** `input → physics → sync transforms → camera → render`

## Code Structure

```
core/src/main/java/com/voidvvv/gamedemo01/
├── Main.java                    # Application entry, creates all entities and systems
├── game/
│   ├── GameWorld.java           # Per-frame update coordinator
│   └── GameSettings.java        # Physics/camera/render constants
├── entity/
│   ├── Entity.java              # Base entity interface (transform + physics + render)
│   ├── Player.java              # Player entity (mass=1, dynamic)
│   ├── Npc.java                 # NPC entity (mass=1, dynamic)
│   └── Ground.java              # Ground entity (mass=0, static)
├── component/
│   ├── TransformComponent.java  # Matrix4 world transform + position cache
│   ├── PhysicsComponent.java    # btRigidBody wrapper + sync method
│   └── RenderComponent.java     # ModelInstance + shader name + visibility
├── physics/
│   ├── PhysicsWorld.java        # Bullet dynamics world lifecycle
│   └── PhysicsFactory.java      # Static factory for rigid bodies
├── render/
│   ├── RenderWorld.java         # Entity iteration + shader dispatch
│   ├── ShaderManager.java       # Batch ModelInstances by shader name
│   ├── ModelFactory.java        # Procedural model creation
│   └── shader/
│       ├── GameShader.java      # Shader interface (queue/begin/render/end)
│       └── DefaultShader.java   # Wraps libGDX ModelBatch
├── camera/
│   └── ThirdPersonCamera.java   # Spherical coords, mouse drag, forward/right vectors
└── input/
    └── PlayerController.java    # WASD + space, movement relative to camera
```

## Tech Stack

| Component | Version |
|-----------|---------|
| libGDX | 1.14.0 |
| LWJGL3 | 3.4.1 |
| Bullet Physics (gdx-bullet) | 1.14.0 |
| Java | 8 |

## Running

```bash
./gradlew lwjgl3:run
```

## Building

```bash
./gradlew lwjgl3:jar    # Runnable JAR at lwjgl3/build/libs/
./gradlew lwjgl3:jarMac # macOS-only JAR (smaller)
```

## Project Layout

- `core/` — Main module with all game logic
- `lwjgl3/` — Desktop launcher using LWJGL3
- `assets/` — Resource files (currently none needed — all models are procedural)
- `gradle/` — Gradle wrapper

## Next Steps

Potential directions for future development:
- Animated character models (replacing procedural boxes)
- NPC AI / pathfinding
- Terrain / level design
- UI overlay (HUD, menus)
- Game state management
- Asset loading system