@ggez/three-runtime 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @ggez/three-runtime
+
+Three.js adapter for Web Hammer runtime content.
+
+`@ggez/three-runtime` no longer owns the runtime format or build pipeline.
+
+Package split:
+
+- `@ggez/runtime-format`: runtime contracts, parsing, validation, migration
+- `@ggez/runtime-build`: `.whmap` compilation, asset externalization, bundle packing
+- `@ggez/three-runtime`: Three object creation and scene instances
+- `@ggez/runtime-streaming`: optional chunk/world orchestration
+- `@ggez/runtime-physics-rapier`: optional Rapier bindings
+
+## Install
+
+```bash
+bun add @ggez/three-runtime three
+```
+
+## Host Ownership
+
+The Three adapter does not own:
+
+- renderer creation
+- main loop
+- camera policy
+- input
+- physics stepping
+- chunk streaming policy
+- gameplay systems
+
+It gives you Three objects and helpers. Your application decides what to do with them.
+
+## Load A Runtime Scene Instance
+
+```ts
+import { Scene } from "three";
+import {
+  createThreeAssetResolver,
+  createThreeRuntimeSceneInstance,
+  parseWebHammerEngineBundleZip
+} from "@ggez/three-runtime";
+
+const response = await fetch("/levels/tutorial.runtime.zip");
+const zipBytes = new Uint8Array(await response.arrayBuffer());
+const bundle = parseWebHammerEngineBundleZip(zipBytes);
+const assetResolver = createThreeAssetResolver(bundle);
+
+const threeScene = new Scene();
+const instance = await createThreeRuntimeSceneInstance(bundle.manifest, {
+  applyToScene: threeScene,
+  lod: {
+    lowDistance: 30,
+    midDistance: 10
+  },
+  resolveAssetUrl: ({ path }) => assetResolver.resolve(path)
+});
+
+threeScene.add(instance.root);
+```
+
+The instance returns:
+
+- `root`
+- `nodesById`
+- `lights`
+- `physicsDescriptors`
+- `entities`
+- `scene`
+- `dispose()`
+
+## Compatibility Loader
+
+If you still want the old convenience surface, `loadWebHammerEngineScene()` remains available and now wraps `createThreeRuntimeSceneInstance()`.
+
+## Lower-Level Object Factory
+
+```ts
+import { createThreeRuntimeObjectFactory } from "@ggez/three-runtime";
+
+const factory = createThreeRuntimeObjectFactory(scene, {
+  lod: {
+    lowDistance: 30,
+    midDistance: 10
+  },
+  resolveAssetUrl: ({ path }) => `/assets/${path}`
+});
+
+const nodeObject = await factory.createNodeObject(scene.nodes[0]);
+const instancingObjects = await factory.createInstancingObjects();
+```
+
+## World Settings
+
+```ts
+import {
+  applyRuntimeWorldSettingsToThreeScene,
+  clearRuntimeWorldSettingsFromThreeScene
+} from "@ggez/three-runtime";
+
+await applyRuntimeWorldSettingsToThreeScene(threeScene, {
+  settings: runtimeScene.settings
+});
+
+clearRuntimeWorldSettingsFromThreeScene(threeScene);
+```
+
+## Bundles Vs Manifests
+
+- `.whmap`: authored editor source
+- `scene.runtime.json`: stable runtime manifest
+- `scene.runtime.zip`: transport bundle for quick validation, handoff, or small levels
+
+For production worlds, prefer unpacked manifests plus normal asset hosting and optional chunk streaming.
+
+## Vanilla Three Integration
+
+Recommended stack:
+
+1. Build runtime artifacts with `@ggez/runtime-build`.
+2. Parse or fetch runtime manifests with `@ggez/runtime-format`.
+3. Instantiate Three content with `@ggez/three-runtime`.
+4. Add physics with `@ggez/runtime-physics-rapier` if needed.
+5. Add streaming with `@ggez/runtime-streaming` if your world is chunked.
+
+## React Three Fiber Integration
+
+The same package split applies in R3F:
+
+1. Load manifests or bundles outside the render tree.
+2. Build a Three runtime scene instance.
+3. Mount `instance.root` into your R3F scene graph or mirror its contents into declarative components.
+4. Keep physics, gameplay, and streaming host-owned.

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { WebHammerEngineNode, WebHammerExportMaterial, WebHammerEngineScene, RuntimeScene, WebHammerEngineBundle, RuntimeBundle } from '@ggez/runtime-format';
+export { RuntimeBundle, RuntimeBundleFile, RuntimeGeometry, RuntimeGeometryLod, RuntimeGeometryNode, RuntimeInstancingNode, RuntimeLodLevel, RuntimeMaterial, RuntimeModelLod, RuntimeModelNode, RuntimeNode, RuntimePrimitive, RuntimeScene, RuntimeSceneMetadata, RuntimeWorldChunk, RuntimeWorldIndex, WebHammerEngineBundle, WebHammerEngineBundleFile, WebHammerEngineGeometryNode, WebHammerEngineInstancingNode, WebHammerEngineModelNode, WebHammerEngineNode, WebHammerEngineScene, WebHammerEngineSceneMetadata, WebHammerExportGeometry, WebHammerExportGeometryLod, WebHammerExportMaterial, WebHammerExportModelLod, WebHammerExportPrimitive, WebHammerLodLevel } from '@ggez/runtime-format';
+import { Asset, SceneSkyboxSettings, PropPhysics, Transform } from '@ggez/shared';
+import * as three from 'three';
+import { Object3D, Group, Scene } from 'three';
+import { createWebHammerEngineBundleZip as createWebHammerEngineBundleZip$1, externalizeWebHammerEngineScene as externalizeWebHammerEngineScene$1, parseWebHammerEngineBundleZip as parseWebHammerEngineBundleZip$1 } from '@ggez/runtime-build';
+export { buildRuntimeBundle, buildRuntimeScene, buildRuntimeWorldIndex, externalizeRuntimeAssets, packRuntimeBundle, unpackRuntimeBundle } from '@ggez/runtime-build';
+
+type TextureSlot = "baseColorTexture" | "metallicRoughnessTexture" | "normalTexture";
+type WebHammerAssetResolverContext = {
+    kind: "model";
+    node: Extract<WebHammerEngineNode, {
+        kind: "model";
+    }>;
+    asset?: Asset;
+    path: string;
+    format: "gltf" | "obj";
+} | {
+    kind: "texture";
+    material: WebHammerExportMaterial;
+    path: string;
+    slot: TextureSlot;
+} | {
+    kind: "skybox";
+    path: string;
+    skybox: SceneSkyboxSettings;
+};
+type WebHammerSceneLoaderOptions = {
+    applyToScene?: Scene;
+    castShadow?: boolean;
+    lod?: WebHammerSceneLodOptions;
+    receiveShadow?: boolean;
+    resolveAssetUrl?: (context: WebHammerAssetResolverContext) => Promise<string> | string;
+};
+type WebHammerSceneLodOptions = {
+    lowDistance: number;
+    midDistance: number;
+};
+type ThreeRuntimeSceneInstance = {
+    dispose: () => void;
+    entities: WebHammerEngineScene["entities"];
+    lights: Object3D[];
+    nodesById: Map<string, Object3D>;
+    physicsDescriptors: Array<{
+        nodeId: string;
+        object: Object3D;
+        physics: PropPhysics;
+    }>;
+    root: Group;
+    scene: WebHammerEngineScene;
+};
+type WebHammerLoadedScene = ThreeRuntimeSceneInstance & {
+    nodes: ThreeRuntimeSceneInstance["nodesById"];
+    physicsNodes: ThreeRuntimeSceneInstance["physicsDescriptors"];
+};
+type ThreeRuntimeAssetResolverContext = WebHammerAssetResolverContext;
+type ThreeRuntimeSceneInstanceOptions = WebHammerSceneLoaderOptions;
+type ThreeRuntimeSceneLodOptions = WebHammerSceneLodOptions;
+declare function isWebHammerEngineScene(value: unknown): value is WebHammerEngineScene;
+declare function isWebHammerEngineBundle(value: unknown): value is WebHammerEngineBundle;
+declare function parseWebHammerEngineScene(text: string): WebHammerEngineScene;
+declare function fetchWebHammerEngineScene(url: string, init?: RequestInit): Promise<WebHammerEngineScene>;
+declare function createThreeRuntimeSceneInstance(input: RuntimeScene | string, options?: WebHammerSceneLoaderOptions): Promise<ThreeRuntimeSceneInstance>;
+declare function loadWebHammerEngineScene(input: WebHammerEngineScene | string, options?: WebHammerSceneLoaderOptions): Promise<WebHammerLoadedScene>;
+declare function loadWebHammerEngineSceneFromUrl(url: string, options?: WebHammerSceneLoaderOptions): Promise<WebHammerLoadedScene>;
+declare function loadThreeRuntimeSceneInstanceFromUrl(url: string, options?: WebHammerSceneLoaderOptions): Promise<ThreeRuntimeSceneInstance>;
+declare function applyWebHammerWorldSettings(target: Scene, engineScene: Pick<WebHammerEngineScene, "settings">, options?: Pick<WebHammerSceneLoaderOptions, "resolveAssetUrl">): Promise<void>;
+declare function clearWebHammerWorldSettings(target: Scene): void;
+declare const applyRuntimeWorldSettingsToThreeScene: typeof applyWebHammerWorldSettings;
+declare const clearRuntimeWorldSettingsFromThreeScene: typeof clearWebHammerWorldSettings;
+
+declare function createThreeAssetResolver(bundle: RuntimeBundle): {
+    dispose(): void;
+    resolve(path: string): string;
+};
+declare function createWebHammerBundleAssetResolver(bundle: WebHammerEngineBundle): {
+    dispose(): void;
+    resolve(path: string): string;
+};
+declare function createWebHammerEngineBundleZip(bundle: WebHammerEngineBundle, options?: Parameters<typeof createWebHammerEngineBundleZip$1>[1]): Uint8Array<ArrayBufferLike>;
+declare function parseWebHammerEngineBundleZip(bundleBytes: Uint8Array, options?: Parameters<typeof parseWebHammerEngineBundleZip$1>[1]): RuntimeBundle;
+declare function externalizeWebHammerEngineScene(scene: WebHammerEngineBundle["manifest"], options?: Parameters<typeof externalizeWebHammerEngineScene$1>[1]): Promise<RuntimeBundle>;
+
+type WebHammerSceneObjectFactoryOptions = Pick<WebHammerSceneLoaderOptions, "castShadow" | "lod" | "receiveShadow" | "resolveAssetUrl">;
+type CreateNodeObjectOverrides = {
+    transform?: Transform;
+};
+type WebHammerSceneObjectFactory = {
+    createInstancingObjects: () => Promise<Object3D[]>;
+    createNodeObject: (node: WebHammerEngineNode, overrides?: CreateNodeObjectOverrides) => Promise<Object3D>;
+};
+declare function createWebHammerSceneObjectFactory(engineScene: Pick<WebHammerEngineScene, "assets" | "nodes">, options?: WebHammerSceneObjectFactoryOptions): WebHammerSceneObjectFactory;
+declare const createThreeRuntimeObjectFactory: typeof createWebHammerSceneObjectFactory;
+declare function extractPhysics(node: WebHammerEngineNode): PropPhysics | undefined;
+declare function findPrimaryLight(object: Object3D): Object3D<three.Object3DEventMap> | undefined;
+
+export { type ThreeRuntimeAssetResolverContext, type ThreeRuntimeSceneInstance, type ThreeRuntimeSceneInstanceOptions, type ThreeRuntimeSceneLodOptions, type WebHammerAssetResolverContext, type WebHammerLoadedScene, type WebHammerSceneLoaderOptions, type WebHammerSceneLodOptions, type WebHammerSceneObjectFactory, applyRuntimeWorldSettingsToThreeScene, applyWebHammerWorldSettings, clearRuntimeWorldSettingsFromThreeScene, clearWebHammerWorldSettings, createThreeAssetResolver, createThreeRuntimeObjectFactory, createThreeRuntimeSceneInstance, createWebHammerBundleAssetResolver, createWebHammerEngineBundleZip, createWebHammerSceneObjectFactory, externalizeWebHammerEngineScene, extractPhysics, fetchWebHammerEngineScene, findPrimaryLight, isWebHammerEngineBundle, isWebHammerEngineScene, loadThreeRuntimeSceneInstanceFromUrl, loadWebHammerEngineScene, loadWebHammerEngineSceneFromUrl, parseWebHammerEngineBundleZip, parseWebHammerEngineScene };