@openfluke/isocard/README.md

Isomorphic Three.js + Jolt Physics JSON scene runner for browser and server (Node/Bun).

# Isocard

**Isocard** is a versatile, isomorphic scene management library built on top of [Three.js](https://threejs.org/) and [Jolt Physics](https://github.com/jrouwe/JoltPhysics). It provides a unified interface for creating, managing, and simulating 3D scenes with physics and optional AI-driven behaviors, seamlessly supporting both client-side (browser) and server-side (Node.js/Bun) environments. With a JSON-driven configuration, Isocard enables developers to define complex scenes, run physics simulations, and integrate automation or AI policies with ease.

---

## ✨ Features

- **Isomorphic Runtime**: Run the same code in the browser or on a server, enabling consistent behavior across environments.
- **Three.js & Jolt Physics Integration**: Combines powerful 3D rendering with robust physics simulations out of the box.
- **JSON-Driven Scenes**: Define scenes using a simple, serializable JSON format for easy creation, sharing, and replaying of experiments.
- **Deterministic Simulations**: Record inputs and replay simulations with consistent results for reliable testing and experimentation.
- **Headless Mode**: Execute physics simulations without rendering, ideal for server-side computations or AI training.
- **Extensible Architecture**: Integrate custom controllers, automation scripts, or AI policies to enhance scene behavior.
- **Dynamic Object Management**: Add, update, or remove objects with physics properties in real-time.
- **Camera & Layer Control**: Fine-tune camera settings and manage object layers for visibility and rendering control.

## 📦 Installation

Install Isocard using your preferred package manager:

```bash
# Using Bun
bun add @openfluke/isocard

# Using npm
npm install @openfluke/isocard
```

Ensure you have the required dependencies installed:

```bash
bun add three jolt-physics
# or
npm install three jolt-physics
```

## 🛠 Usage

### Basic Example

```ts
import * as THREE from "three";
import { IsoCard } from "isocard";

// dependencies passed into IsoCard
const deps = {
  THREE,
  // optional: lets IsoCard load Jolt if not available on `window`
  loadJolt: async () => (await import("jolt-physics")).default,
};

// create IsoCard instance
const iso = new IsoCard(
  { clientWidth: 800, clientHeight: 600, appendChild() {}, addEventListener() {} } as any,
  deps,
  { isPreview: true, isServer: true }
);

// setup physics
await iso.setupJOLT();
iso.loadSceneWithConstraints(JSON.stringify({
  objects: [
    { name: "box", shape: "box", size: [1, 1, 1], position: [0, 5, 0], physics: { motionType: "dynamic" } }
  ]
}));

iso.startPhysics();
iso.startAnimate();

console.log("Simulation running with", iso.dynamicObjects.length, "dynamic objects");
```

---

## 📂 Project Structure

```
├── src/
│   ├── isocard.ts    # Core Isocard class implementation
│   ├── index.ts      # Package entrypoint
├── dist/             # Compiled output (published to npm)
├── package.json      # Project metadata and scripts
├── README.md         # Project documentation
```

---

## 🧪 Getting Started with Development

To develop or contribute to Isocard, follow these steps:

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/openfluke/isocard
   cd isocard
   ```

2. **Install Dependencies**:
   ```bash
   bun install
   ```

3. **Build the Project**:
   ```bash
   bun run build
   ```

4. **Link Locally for Testing**:
   ```bash
   bun link
   ```
   In your test project:
   ```bash
   bun link @openfluke/isocard
   ```

5. **Run a Development Server** (for frontend testing):
   ```bash
   bun run dev
   ```

---

## 🌐 Resources

- [Three.js Documentation](https://threejs.org/docs/)
- [Jolt Physics GitHub](https://github.com/jrouwe/JoltPhysics)
- [Example Frontend Implementation](https://github.com/openfluke/icfront)
- [Example Backend Implementation](https://github.com/openfluke/icback)




## IsoCard vs Existing Tools

| Feature / Focus | Three.js (core) | Jolt (engine) | Wrappers (Ammo.js, Cannon-es, Rapier, Enable3D) | IsoCard (@openfluke/isocard) |
|-----------------|-----------------|---------------|-----------------------------------------------|------------------------------|
| Rendering       | ✅ (WebGL)      | ❌            | ✅ (via Three.js)                             | ✅ (via injected Three.js)   |
| Physics         | ❌              | ✅ (C++)      | ✅ (JS/WASM bindings)                         | ✅ (Jolt via JS/WASM + DI)  |
| Browser support | ✅              | WASM ports    | ✅                                            | ✅ (React/Vite/Ionic ready)  |
| Server/Headless mode | ❌        | Native only   | Rare / gluey                                 | ✅ (Node/Bun headless physics) |
| Isomorphic parity | ❌          | ❌            | ❌                                            | ✅ (same JSON runs front & back) |
| Scene definition | Manual code  | Manual code   | Sometimes entity configs                     | ✅ JSON schema (interpretJSON) |
| Play/Stop physics | ❌         | Engine-level  | Possible but not first-class                  | ✅ One-liner API (startPhysics) |
| Camera & controls | Manual setup | ❌           | Manual                                       | ✅ JSON + API (setCameraConfig) |
| AI hooks / recording | ❌       | ❌            | ❌                                            | ✅ (player data → AI controller) |
| Remix/share loop | ❌         | ❌            | ❌                                            | ✅ Built-in (JSON scenes sharable) |
| Multi-server watching | ❌     | ❌            | ❌                                            | ✅ Overlay & opacity controls |
| Target users    | Graphics devs   | Engine/game devs | Hobby/game devs                           | Web devs, AI/robotics, educators |

## Key Takeaway

IsoCard isn’t “just another wrapper.” It’s the isomorphic runtime:

- Load a scene from JSON.
- Run it in browser or headless server.
- Toggle physics, camera, and AI controllers with simple APIs.
- Record, replay, remix, and share without touching engine internals.



## 📜 License

Apache License 2.0 © 2025 Samuel Watson