🌌 @trap_stevo/morphal

The flagship entity framework for building scalable, reusable, and visually stunning entities.
Compose entities from parts, drive them with behaviors, style them with flexible materials, and scale with instancing and performance primitives.

🚀 Features

• 🧩 Declarative Entities – JSON-like specs for parts, transforms, collisions, and behaviors
• 🎨 Material Factories – Presets like basic, emissive, pbr-normal, sprite, etc., with unlimited extra options
• 🎭 Behavior System – Lifecycle-driven behaviors (fadeIn, fadeOut, float, rotate, pulseEmissive, …)
• 📦 Instancing Pools – Massive scenes via InstancedSpritePool and InstancedMeshPool
• 🧭 Performance Toolkit – Distance culling, impostor swapping, and entity pooling
• 🧰 Anchors & Metadata – Built-in anchors (tip, center, …) and collision accessors
• 🌍 2D & 3D Unified – Mix HUD overlays (orthographic) with world-space entities (perspective)

⚙️ System Requirements

🧩 Spec Reference

Entity Spec (Morphal.create(spec, ctx)) — Core Fields

transform structure:

• position: { x, y, z }
• rotation: { x, y, z } (radians)
• scale: number or { x, y, z }

Part Spec — Common Fields

Behavior Config — Common Fields

Included behaviors (examples):

• fadeIn({ duration, fromScale })
• fadeOut({ duration, scaleTo })
• float({ axis, speed, amplitude })
• rotate({ axis, speed })
• pulseEmissive({ frequency, intensity })

📚 Methods Overview

Morphal (Core) — Methods

Entity — Methods

Collision Accessors (per-part)

part.userData.morphal.collision (if enabled in the part spec):

Performance Toolkit

Instancing Pools

🧱 Part Catalog (Built-ins)

vectorShape

billboardPlane

tentacle

sprite

rippleRing

energyBlob

gltf

🎨 Materials (Built-ins)

basic

emissive

pbr-normal

📦 Installation

npm install @trap_stevo/morphal

---

## 🏗️ Quick Start (HTML)

```js
import { Morphal } from "@trap_stevo/morphal";

// Renderer bootstrap
const appEl = document.getElementById("app");
const renderer = new WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.outputColorSpace = SRGBColorSpace;
appEl.appendChild(renderer.domElement);

// 3D scene & camera
const scene = new Scene();
scene.background = new Color("#0b0b12");
const camera = new PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.1, 500);
camera.position.set(0, 0.8, 3);
scene.add(camera);
scene.add(new HemisphereLight(0xffffff, 0x334466, 0.35));

// 2D HUD scene (orthographic)
const scene2D = new Scene();
const ortho = new OrthographicCamera();
scene2D.add(ortho);
function resizeOrtho() {
  const w = window.innerWidth, h = window.innerHeight;
  ortho.left = -w / 2;
  ortho.right = w / 2;
  ortho.top = h / 2;
  ortho.bottom = -h / 2;
  ortho.near = -1000;
  ortho.far = 1000;
  ortho.updateProjectionMatrix();
}
resizeOrtho();

// Responsive resize
window.addEventListener("resize", () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
  resizeOrtho();
});

// Minimal entity
const entity = Morphal.create({
  name: "demo",
  orient: "view",
  parts: [
    { type: "billboardPlane", src: "/flare.png", scale: 2 },
    { type: "tentacle", color: "#C655FF", segments: 12 }
  ],
  behaviors: [
    { type: "fadeIn", duration: 1.5 },
    { type: "float", axis: "y", speed: 0.4 }
  ]
}, { parent: scene, camera });

// Basic loop
let last = performance.now() / 1000;
(function tick() {
  const now = performance.now() / 1000;
  const delta = now - last;
  last = now;
  entity.update(now, delta);
  renderer.render(scene, camera);
  requestAnimationFrame(tick);
})();

🧪 Examples

1) Vector Shapes (SVG)

Morphal.create({
  parts: [
    {
      type: "vectorShape",
      svg: "<svg><circle cx='0' cy='0' r='0.6'/></svg>",
      material: "basic",
      color: "#a6b2ff",
      opacity: 0.9,
      transform: { scale: { x: 1.2, y: 1.2, z: 1 } },
      zOffset: -1,
      behaviors: [{ type: "pulseEmissive", frequency: 1.25, intensity: 0.25 }],
      materialProps: { transparent: true, opacity: 0.9 },
      collision: { dim: 3, tags: ["eye", "sclera"] }
    }
  ]
}, { parent: scene, camera });

2) Image Billboards

Morphal.create({
  parts: [
    {
      type: "billboardPlane",
      src: "/textures/flare.png",
      scale: 1.25,
      tint: "#9f67ff",
      emissiveIntensity: 2.0,
      zOffset: 2
    }
  ]
}, { parent: scene, camera });

3) Procedural Mesh Part

Morphal.registerPart("energyBlob", (cfg = {}, ctx) => {
  const geometry = new SphereGeometry(cfg.radius ?? 0.32, 48, 48);
  const material = Morphal.makeMaterial(
    cfg.material || "emissive",
    { color: cfg.color || "#b38cff", opacity: 0.2, transparent: true }
  );
  const mesh = new Mesh(geometry, material);
  mesh.userData.anchors = { center: mesh };
  return mesh;
});

4) 2D HUD Overlay (Orthographic)

const hudEntity = Morphal.create(
  { name: "hud", orient: "view", parts: [ /* vector parts… */ ] },
  { parent: scene2D, camera: ortho }
);

5) Collision Export

function gatherCollidable(root) {
  const out = [];
  root.traverse(o => {
    const c = o.userData?.morphal?.collision;
    if (c?.snapshotMatrix) out.push(o);
  });
  return out;
}
const collidables = gatherCollidable(entity.group);
for (const part of collidables) {
  const c = part.userData.morphal.collision;
  c.snapshotMatrix();
  const matrix = new Float32Array(c.getMatrixRef());
  const obb = c.getWorldOBB();
  const tris = [];
  c.forEachWorldTriangle((ax, ay, az, bx, by, bz, cx, cy, cz) => {
    tris.push(ax, ay, az, bx, by, bz, cx, cy, cz);
  });
}

📜 License

See License in LICENSE.md

✨ Morph, Render, Scale

From SVG paths to billboards to procedural meshes, Morphal gives you one unified way to define, manage, and optimize entities at any scale — in both 2D and 3D contexts.