npm package: @kernelplay/three-renderer
Description: A lightweight JavaScript 2D game engine inspired by Unity’s component system.
Author: Soubhik Mukherjee
Latest version: 0.1.0

# @kernelplay/three-renderer

Professional 3D renderer for KernelPlayJS using Three.js.

> **Version:** `0.1.0-alpha` | **Requires:** `kernelplay-js@^0.2.0`, `three@^0.158.0`

---

## 🎮 Why Three.js Renderer?

- **Full 3D Support** - Real 3D game development with WebGL
- **Advanced Lighting** - Point, directional, ambient, spot lights
- **Materials & Shaders** - PBR materials, custom shaders
- **3D Physics** - AABB collision detection in 3D space
- **Scene Helpers** - Cameras, fog, shadows, post-processing
- **Industry Standard** - Battle-tested 3D library

**Use Cases:** First-person games, 3D platformers, racing games, architectural visualization.

---

## 📦 Installation

```bash
npm install @kernelplay/three-renderer three kernelplay-js
```

Or use CDN:
```html
<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.158.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.158.0/examples/jsm/",
    "kernelplay-js": "https://cdn.jsdelivr.net/npm/kernelplay-js/dist/kernelplay.es.js",
    "@kernelplay/three-renderer": "https://cdn.jsdelivr.net/npm/@kernelplay/three-renderer/dist/three-renderer.es.js"
  }
}
</script>
```

---

## 🚀 Quick Start

```javascript
import { Game } from "kernelplay-js";
import { ThreeRenderer } from "@kernelplay/three-renderer";
import { MyScene } from "./scenes/MyScene.js";

const game = new Game({
  renderer: new ThreeRenderer(),
  width: 800,
  height: 600,
  backgroundColor: "#87CEEB"
});

game.sceneManager.addScene(new MyScene("Main"));
game.sceneManager.startScene("Main");
game.start();
```

---

## 🎨 Core Components

### MeshComponent

Add 3D meshes to entities.

```javascript
import { Entity, TransformComponent } from "kernelplay-js";
import { MeshComponent } from "@kernelplay/three-renderer";
import * as THREE from "three";

const cube = new Entity("Cube");

cube.addComponent("transform", new TransformComponent({
  position: { x: 0, y: 1, z: 0 },
  rotation: { x: 0, y: 0, z: 0 },
  scale: { x: 1, y: 1, z: 1 }
}));

// Create Three.js mesh
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({ 
  color: 0x00ff00,
  metalness: 0.5,
  roughness: 0.5
});
const mesh = new THREE.Mesh(geometry, material);

cube.addComponent("mesh", new MeshComponent(mesh));

scene.addEntity(cube);
```

### BoxCollider3D

3D AABB collision detection.

```javascript
import { BoxCollider3D } from "@kernelplay/three-renderer";

entity.addComponent("collider3D", new BoxCollider3D({
  isTrigger: false
}));
```

### Rigidbody3D

3D physics (gravity, velocity, forces).

```javascript
import { RigidbodyComponent } from "kernelplay-js";

entity.addComponent("rigidbody", new RigidbodyComponent({
  mass: 1,
  gravityScale: 1,
  useGravity: true,
  drag: 0.1
}));
```

---

## 🎮 Complete Example

### 3D Player Prefab

```javascript
import { Entity, TransformComponent, Rigidbody3DComponent } from "kernelplay-js";
import { MeshComponent, BoxCollider3D } from "@kernelplay/three-renderer";
import { PlayerController3D } from "../scripts/PlayerController3D.js";
import * as THREE from "three";

export class Player3D extends Entity {
  constructor(x, y, z) {
    super("Player");
    this.tag = "player";

    this.addComponent("transform", new TransformComponent({
      position: { x, y, z },
      scale: { x: 0.5, y: 1, z: 0.5 }
    }));

    // Create capsule-like mesh
    const geometry = new THREE.CylinderGeometry(0.5, 0.5, 1, 8);
    const material = new THREE.MeshStandardMaterial({ 
      color: 0x00ff00 
    });
    const mesh = new THREE.Mesh(geometry, material);
    mesh.castShadow = true;

    this.addComponent("mesh", new MeshComponent(mesh));

    this.addComponent("rigidbody", new RigidbodyComponent({
      mass: 1,
      gravityScale: 2
    }));

    this.addComponent("collider3D", new BoxCollider3D());

    this.addComponent("controller", new PlayerController3D());
  }
}
```

### Player Controller Script

```javascript
import { ScriptComponent, Keyboard } from "kernelplay-js";

export class PlayerController3D extends ScriptComponent {
  onStart() {
    this.speed = 5;
    this.jumpForce = 10;
  }

  update(dt) {
    const rb = this.entity.getComponent("rigidbody");
    
    // Horizontal movement
    rb.velocity.x = 0;
    rb.velocity.z = 0;

    if (Keyboard.isDown("ArrowRight")) rb.velocity.x = this.speed;
    if (Keyboard.isDown("ArrowLeft")) rb.velocity.x = -this.speed;
    if (Keyboard.isDown("ArrowUp")) rb.velocity.z = -this.speed;
    if (Keyboard.isDown("ArrowDown")) rb.velocity.z = this.speed;

    // Jump
    if (Keyboard.wasPressed("Space") && rb.isGrounded) {
      rb.velocity.y = this.jumpForce;
    }
  }

  onCollision(other) {
    if (other.tag === "enemy") {
      console.log("Hit enemy!");
    }
  }
}
```

---


## 📚 Resources

- **Three.js Documentation:** https://threejs.org/docs/
- **Three.js Examples:** https://threejs.org/examples/
- **KernelPlayJS Docs:** https://soubhik-rjs.github.io/kernelplay-js-demo/docs/

---

## 🤝 Contributing

See main [CONTRIBUTING.md](https://github.com/Soubhik1000/kernelplay/blob/main/CONTRIBUTING.md)

---

## 📄 License

MIT License - Same as KernelPlayJS

---

## 🔗 Links

- **GitHub:** https://github.com/Soubhik1000/kernelplay
- **NPM:** https://www.npmjs.com/package/@kernelplay/three-renderer
- **Main Package:** https://www.npmjs.com/package/kernelplay-js

---

**@kernelplay/three-renderer** - Professional 3D game development with Three.js 🎮