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
```

🌐 Resources

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.

Package detail

@openfluke/isocard

readme