Isocard

Isocard is a versatile, isomorphic scene management library built on top of Three.js and Jolt Physics. 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:

# Using Bun
bun add @openfluke/isocard

# Using npm
npm install @openfluke/isocard

Ensure you have the required dependencies installed:

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

🛠 Usage

Basic Example

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:

Clone the Repository:

git clone https://github.com/openfluke/isocard
cd isocard

Install Dependencies:
```
bun install
```
Build the Project:
```
bun run build
```
Link Locally for Testing:
```
bun link
```
In your test project:
```
bun link @openfluke/isocard
```
Run a Development Server (for frontend testing):
```
bun run dev
```

JSPM

@openfluke/isocard

Package Exports

Readme