@bloomengine/engine 0.3.1

package/src/text/index.ts

@@ -0,0 +1,48 @@
+import { Color, Font, Vec2 } from '../core/types';
+
+// FFI declarations
+declare function bloom_draw_text(text: number, x: number, y: number, size: number, r: number, g: number, b: number, a: number): void;
+declare function bloom_measure_text(text: number, size: number): number;
+declare function bloom_load_font(path: number, size: number): number;
+declare function bloom_draw_text_ex(font: number, text: number, x: number, y: number, size: number, spacing: number, r: number, g: number, b: number, a: number): void;
+declare function bloom_measure_text_ex(font: number, text: number, size: number, spacing: number): number;
+declare function bloom_unload_font(font: number): void;
+
+export function drawText(text: string, x: number, y: number, size: number, color: Color): void {
+  bloom_draw_text(text as any, x, y, size, color.r, color.g, color.b, color.a);
+}
+
+/// RGBA variant of `drawText`. Prefer this over passing a `Color` object on
+/// Android (aarch64): Perry 0.5.x miscompiles `color.r` field reads that feed
+/// straight into an f64 FFI slot, producing NaN for all color components and
+/// dropping the glyph quads. Passing raw numbers bypasses the object read.
+export function drawTextRgba(text: string, x: number, y: number, size: number, r: number, g: number, b: number, a: number): void {
+  bloom_draw_text(text as any, x, y, size, r, g, b, a);
+}
+
+export function measureText(text: string, size: number): number {
+  return bloom_measure_text(text as any, size);
+}
+
+export function loadFont(path: string, size: number): Font {
+  const handle = bloom_load_font(path as any, size);
+  return { handle, size };
+}
+
+export function loadFontEx(path: string, size: number): Font {
+  const handle = bloom_load_font(path as any, size);
+  return { handle, size };
+}
+
+export function unloadFont(font: Font): void {
+  bloom_unload_font(font.handle);
+}
+
+export function drawTextEx(font: Font, text: string, pos: Vec2, size: number, spacing: number, color: Color): void {
+  bloom_draw_text_ex(font.handle, text as any, pos.x, pos.y, size, spacing, color.r, color.g, color.b, color.a);
+}
+
+export function measureTextEx(font: Font, text: string, size: number, spacing: number): Vec2 {
+  const width = bloom_measure_text_ex(font.handle, text as any, size, spacing);
+  return { x: width, y: size };
+}

package/src/textures/index.ts

@@ -0,0 +1,173 @@
+import { spawn, parallelMap } from 'perry/thread';
+import { Color, Rect, Texture } from '../core/types';
+
+// FFI declarations
+declare function bloom_load_texture(path: number): number;
+declare function bloom_unload_texture(handle: number): void;
+declare function bloom_draw_texture(handle: number, x: number, y: number, r: number, g: number, b: number, a: number): void;
+declare function bloom_draw_texture_rec(handle: number, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, r: number, g: number, b: number, a: number): void;
+declare function bloom_draw_texture_pro(handle: number, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number, ox: number, oy: number, rot: number, r: number, g: number, b: number, a: number): void;
+declare function bloom_get_texture_width(handle: number): number;
+declare function bloom_get_texture_height(handle: number): number;
+declare function bloom_load_image(path: number): number;
+declare function bloom_image_resize(handle: number, w: number, h: number): void;
+declare function bloom_image_crop(handle: number, x: number, y: number, w: number, h: number): void;
+declare function bloom_image_flip_h(handle: number): void;
+declare function bloom_image_flip_v(handle: number): void;
+declare function bloom_load_texture_from_image(handle: number): number;
+declare function bloom_gen_texture_mipmaps(handle: number): void;
+declare function bloom_set_texture_filter(handle: number, mode: number): void;
+
+export const FILTER_LINEAR = 0;
+export const FILTER_NEAREST = 1;
+
+export function setTextureFilter(texture: Texture, mode: number): void {
+  bloom_set_texture_filter(texture.id, mode);
+}
+
+export function loadTexture(path: string): Texture {
+  const id = bloom_load_texture(path as any);
+  const width = bloom_get_texture_width(id);
+  const height = bloom_get_texture_height(id);
+  return { id, width, height };
+}
+
+export function unloadTexture(texture: Texture): void {
+  bloom_unload_texture(texture.id);
+}
+
+export function drawTexture(texture: Texture, x: number, y: number, tint: Color): void {
+  bloom_draw_texture(texture.id, x, y, tint.r, tint.g, tint.b, tint.a);
+}
+
+export function drawTextureRec(texture: Texture, source: Rect, position: { x: number; y: number }, tint: Color): void {
+  bloom_draw_texture_rec(texture.id, source.x, source.y, source.width, source.height, position.x, position.y, tint.r, tint.g, tint.b, tint.a);
+}
+
+export function drawTexturePro(
+  texture: Texture, source: Rect, dest: Rect,
+  origin: { x: number; y: number }, rotation: number, tint: Color,
+): void {
+  bloom_draw_texture_pro(
+    texture.id,
+    source.x, source.y, source.width, source.height,
+    dest.x, dest.y, dest.width, dest.height,
+    origin.x, origin.y, rotation,
+    tint.r, tint.g, tint.b, tint.a,
+  );
+}
+
+// Raw variant: takes primitives directly. Workaround for aarch64 Android
+// Perry miscompilation where obj.field reads feeding f64 FFI args arrive as NaN.
+export function drawTextureProRaw(
+  textureId: number,
+  sx: number, sy: number, sw: number, sh: number,
+  dx: number, dy: number, dw: number, dh: number,
+  ox: number, oy: number, rotation: number,
+  r: number, g: number, b: number, a: number,
+): void {
+  bloom_draw_texture_pro(textureId, sx, sy, sw, sh, dx, dy, dw, dh, ox, oy, rotation, r, g, b, a);
+}
+
+export function getTextureWidth(texture: Texture): number {
+  return texture.width;
+}
+
+export function getTextureHeight(texture: Texture): number {
+  return texture.height;
+}
+
+export function loadImage(path: string): number {
+  return bloom_load_image(path as any);
+}
+
+export function imageResize(imageHandle: number, width: number, height: number): void {
+  bloom_image_resize(imageHandle, width, height);
+}
+
+export function imageCrop(imageHandle: number, x: number, y: number, width: number, height: number): void {
+  bloom_image_crop(imageHandle, x, y, width, height);
+}
+
+export function imageFlipH(imageHandle: number): void {
+  bloom_image_flip_h(imageHandle);
+}
+
+export function imageFlipV(imageHandle: number): void {
+  bloom_image_flip_v(imageHandle);
+}
+
+export function loadTextureFromImage(imageHandle: number): Texture {
+  const id = bloom_load_texture_from_image(imageHandle);
+  const width = bloom_get_texture_width(id);
+  const height = bloom_get_texture_height(id);
+  return { id, width, height };
+}
+
+export function genTextureMipmaps(texture: Texture): void {
+  bloom_gen_texture_mipmaps(texture.id);
+}
+
+// Async / threaded loading
+
+declare function bloom_stage_texture(path: number): number;
+declare function bloom_commit_texture(handle: number): number;
+declare function bloom_load_render_texture(width: number, height: number): number;
+declare function bloom_unload_render_texture(handle: number): void;
+declare function bloom_begin_texture_mode(handle: number): void;
+declare function bloom_end_texture_mode(): void;
+declare function bloom_get_render_texture_texture(handle: number): number;
+
+export async function loadTextureAsync(path: string): Promise<Texture> {
+  const stagingHandle = await spawn(() => bloom_stage_texture(path as any));
+  const id = bloom_commit_texture(stagingHandle);
+  const width = bloom_get_texture_width(id);
+  const height = bloom_get_texture_height(id);
+  return { id, width, height };
+}
+
+export function stageTextures(paths: string[]): number[] {
+  return parallelMap(paths, (path: string) => bloom_stage_texture(path as any));
+}
+
+export function commitTexture(stagingHandle: number): Texture {
+  const id = bloom_commit_texture(stagingHandle);
+  const width = bloom_get_texture_width(id);
+  const height = bloom_get_texture_height(id);
+  return { id, width, height };
+}
+
+// ============================================================
+// Q1: Offscreen Render Targets
+// ============================================================
+
+/**
+ * Create an offscreen render texture. Rendering commands between
+ * beginTextureMode and endTextureMode draw into this texture instead
+ * of the screen. Use getRenderTextureTexture to get a Texture for
+ * drawing the result via drawTexture.
+ *
+ * NOTE: GPU implementation is a stub in this version. The FFI surface
+ * is stable; the actual render-to-texture plumbing will land in a
+ * focused GPU session.
+ */
+export function loadRenderTexture(width: number, height: number): number {
+  return bloom_load_render_texture(width, height);
+}
+
+export function unloadRenderTexture(handle: number): void {
+  bloom_unload_render_texture(handle);
+}
+
+export function beginTextureMode(handle: number): void {
+  bloom_begin_texture_mode(handle);
+}
+
+export function endTextureMode(): void {
+  bloom_end_texture_mode();
+}
+
+export function getRenderTextureTexture(handle: number): Texture {
+  const id = bloom_get_render_texture_texture(handle);
+  return { id, width: 0, height: 0 };
+}

package/src/world/index.ts

@@ -0,0 +1,22 @@
+// Bloom shared world module.
+//
+// Defines the on-disk world/prefab schema that the Bloom world editor writes
+// and every Bloom game reads. Games and the editor both import from this
+// module via `import { ... } from 'bloom/world'`.
+//
+// Files:
+//   - types.ts      schema interfaces (WorldData, PrefabData, ...)
+//   - version.ts    schema version + migration
+//   - validate.ts   runtime schema validation
+//   - loader.ts     loadWorld / instantiateWorld (reads JSON, spawns scene nodes)
+//   - saver.ts      saveWorld / savePrefab (writes JSON)
+//   - prefab.ts     loadPrefab / expandPrefab / cycle detection
+//   - terrain.ts    buildHeightmapMesh / sampleHeight / raycastTerrain / defaultTerrain
+
+export * from './types';
+export * from './version';
+export * from './validate';
+export * from './loader';
+export * from './saver';
+export * from './prefab';
+export * from './terrain';

package/src/world/loader.ts

@@ -0,0 +1,385 @@
+// World loader — reads a `*.world.json` file from disk, validates it, and
+// spawns scene nodes. Consumed by both the editor (to display the world) and
+// by every Bloom game (to load its level at runtime).
+//
+// The loader has two entry points:
+//
+//   loadWorld(path)          — pure: reads + parses + migrates + validates.
+//                              Returns a WorldData object. No scene side-effects.
+//
+//   instantiateWorld(w, ctx) — creates scene nodes, applies lighting, and
+//                              returns a map of entity id -> scene node handle.
+//                              The caller provides a context that resolves
+//                              model references to loaded model handles.
+//
+// Splitting parse from instantiate lets the editor hold a `WorldData` in memory
+// and re-sync scene nodes on edits, without re-reading the file every frame.
+
+import { readFile } from '../core/index';
+import {
+  createSceneNode,
+  attachModelToNode,
+  setSceneNodeTransform,
+  setSceneNodeColor,
+  setSceneNodeVisible,
+  setSceneNodeParent,
+  updateSceneNodeGeometry,
+  SceneNodeHandle,
+  enableShadows,
+  disableShadows,
+  addDirectionalLight,
+} from '../scene/index';
+import {
+  mat4Identity,
+  mat4Translate,
+  mat4RotateX,
+  mat4RotateY,
+  mat4RotateZ,
+  mat4Scale,
+} from '../math/index';
+import { Mat4, Vec3 } from '../core/types';
+import {
+  WorldData,
+  EntityData,
+  TransformData,
+  Vec3Lit,
+  Vec4Lit,
+} from './types';
+import { migrateWorldData } from './version';
+import { validateWorld, formatValidationErrors } from './validate';
+import {
+  PrefabRegistry,
+  PrefabLeaf,
+  expandPrefab,
+} from './prefab';
+import { buildHeightmapMesh } from './terrain';
+
+// Context passed to `instantiateWorld`. The caller is responsible for loading
+// GLB models and supplying handles via `getModelHandle`. This inverts the
+// dependency so games and the editor can use their own asset-caching policy.
+export interface InstantiateContext {
+  // Resolve a `modelRef` (e.g. "models/tree_oak.glb") to a loaded model handle.
+  // Return 0 if the model is unavailable — the entity is then skipped and a
+  // warning is appended to `result.warnings`.
+  getModelHandle: (modelRef: string) => number;
+
+  // Prefab registry for expanding prefab entities. Passing null causes prefab
+  // entities to be skipped (with a warning).
+  prefabRegistry: PrefabRegistry | null;
+
+  // Called once per successfully spawned entity. The editor uses this hook to
+  // populate its `HandleMap` (EntityId <-> SceneNodeHandle bi-map).
+  onEntitySpawned?: (entityId: string, handle: SceneNodeHandle) => void;
+
+  // Called once for the terrain scene node, if the world has a terrain.
+  // The editor uses this to track the terrain handle for brush updates.
+  onTerrainSpawned?: (handle: SceneNodeHandle) => void;
+}
+
+export interface InstantiateResult {
+  // One handle per spawned world entity. Prefab entities yield a root group
+  // node whose children are the expanded prefab leaves.
+  entityHandles: Map<string, SceneNodeHandle>;
+
+  // Scene node handle for the terrain mesh, or 0 if the world has no terrain.
+  terrainHandle: SceneNodeHandle;
+
+  // Non-fatal problems encountered during instantiation: missing models,
+  // unresolved prefab references, cycles. The world still instantiates,
+  // with the offending entities skipped.
+  warnings: string[];
+}
+
+// Read, parse, migrate, and validate a world file. Throws on parse error or
+// validation failure — the caller can catch and present the error message.
+export function loadWorld(path: string): WorldData {
+  const text = readFile(path);
+  if (!text || text.length === 0) {
+    throw new Error('loadWorld: file is empty or missing: ' + path);
+  }
+
+  let raw: WorldData;
+  try {
+    raw = JSON.parse(text) as WorldData;
+  } catch (e) {
+    throw new Error('loadWorld: invalid JSON in ' + path + ': ' + (e as Error).message);
+  }
+
+  const migrated = migrateWorldData(raw);
+  const check = validateWorld(migrated);
+  if (!check.ok) {
+    throw new Error('loadWorld: ' + path + '\n' + formatValidationErrors(check.errors));
+  }
+
+  return migrated;
+}
+
+// Spawn scene nodes for every entity in the world and apply environment
+// settings (lighting, shadows). Terrain, water, and rivers are also spawned
+// when present. Water and river rendering depend on engine additions that
+// land in later tasks; for now they are no-ops with TODO warnings.
+export function instantiateWorld(world: WorldData, ctx: InstantiateContext): InstantiateResult {
+  const result: InstantiateResult = {
+    entityHandles: new Map<string, SceneNodeHandle>(),
+    terrainHandle: 0,
+    warnings: [],
+  };
+
+  // Apply environment first so the first frame renders with correct lighting.
+  applyEnvironment(world);
+
+  // Terrain before entities so entities can drop onto it visually.
+  if (world.terrain) {
+    result.terrainHandle = spawnTerrain(world);
+    if (result.terrainHandle !== 0 && ctx.onTerrainSpawned) {
+      ctx.onTerrainSpawned(result.terrainHandle);
+    }
+  }
+
+  // Spawn each entity. Prefab entities are expanded into a root group node
+  // with one child per leaf glb.
+  for (let i = 0; i < world.entities.length; i++) {
+    const entity = world.entities[i];
+    const handle = spawnEntity(entity, ctx, result.warnings);
+    if (handle !== 0) {
+      result.entityHandles.set(entity.id, handle);
+      if (ctx.onEntitySpawned) {
+        ctx.onEntitySpawned(entity.id, handle);
+      }
+    }
+  }
+
+  if (world.water.length > 0) {
+    result.warnings.push(
+      'world has ' + world.water.length + ' water volume(s) — water rendering pending engine Q8 shader',
+    );
+  }
+  if (world.rivers.length > 0) {
+    result.warnings.push(
+      'world has ' + world.rivers.length + ' river(s) — river rendering pending engine Q9 spline ribbon helper',
+    );
+  }
+
+  return result;
+}
+
+// Build the terrain mesh from the heightmap grid and upload it to a dedicated
+// scene node. Called once per world load; the editor's brush tool re-uploads
+// the mesh on each stroke via `updateSceneNodeGeometry` directly.
+function spawnTerrain(world: WorldData): SceneNodeHandle {
+  if (!world.terrain) return 0;
+  const mesh = buildHeightmapMesh(world.terrain);
+  const node = createSceneNode();
+  updateSceneNodeGeometry(node, mesh.vertices, mesh.indices);
+  setSceneNodeTransform(node, mat4Identity());
+  setSceneNodeVisible(node, true);
+  return node;
+}
+
+// ---- entity spawning -------------------------------------------------------
+
+function spawnEntity(
+  entity: EntityData,
+  ctx: InstantiateContext,
+  warnings: string[],
+): SceneNodeHandle {
+  if (entity.modelRef !== null && entity.modelRef.length > 0) {
+    return spawnModelEntity(entity, ctx, warnings);
+  }
+
+  if (entity.prefabRef !== null && entity.prefabRef.length > 0) {
+    return spawnPrefabEntity(entity, ctx, warnings);
+  }
+
+  warnings.push('entity ' + entity.id + ' has neither modelRef nor prefabRef — skipped');
+  return 0;
+}
+
+function spawnModelEntity(
+  entity: EntityData,
+  ctx: InstantiateContext,
+  warnings: string[],
+): SceneNodeHandle {
+  const modelRef = entity.modelRef as string;
+  const modelHandle = ctx.getModelHandle(modelRef);
+  if (modelHandle === 0) {
+    warnings.push('entity ' + entity.id + ' references unknown model "' + modelRef + '" — skipped');
+    return 0;
+  }
+
+  const node = createSceneNode();
+  attachModelToNode(node, modelHandle, 0);
+  setSceneNodeTransform(node, trsToMat4(entity.transform));
+
+  if (entity.tint !== null) {
+    applyTint(node, entity.tint);
+  }
+
+  setSceneNodeVisible(node, true);
+  return node;
+}
+
+function spawnPrefabEntity(
+  entity: EntityData,
+  ctx: InstantiateContext,
+  warnings: string[],
+): SceneNodeHandle {
+  if (!ctx.prefabRegistry) {
+    warnings.push(
+      'entity ' + entity.id + ' references prefab "' + entity.prefabRef + '" but no PrefabRegistry was provided — skipped',
+    );
+    return 0;
+  }
+
+  // Create a root group node at the entity's transform. Expanded leaves are
+  // parented to this root so the editor gizmo can move the whole prefab as
+  // one unit.
+  const root = createSceneNode();
+  const rootMatrix = trsToMat4(entity.transform);
+  setSceneNodeTransform(root, rootMatrix);
+  setSceneNodeVisible(root, true);
+
+  // Expand the prefab into its leaf glbs and spawn one scene node per leaf.
+  // `expandPrefab` accumulates leaves into `leaves` and any errors into a
+  // local list which we fold into the top-level warnings.
+  const leaves: PrefabLeaf[] = [];
+  const expandErrors: string[] = [];
+  const visited = new Set<string>();
+  expandPrefab(
+    ctx.prefabRegistry,
+    entity.prefabRef as string,
+    mat4Identity(),
+    entity.tint,
+    entity.tags,
+    leaves,
+    expandErrors,
+    visited,
+    'world.entities[' + entity.id + ']',
+  );
+
+  for (let i = 0; i < expandErrors.length; i++) warnings.push(expandErrors[i]);
+
+  for (let i = 0; i < leaves.length; i++) {
+    const leaf = leaves[i];
+    const modelHandle = ctx.getModelHandle(leaf.modelRef);
+    if (modelHandle === 0) {
+      warnings.push(
+        'prefab leaf ' + leaf.sourcePath + ' references unknown model "' + leaf.modelRef + '" — skipped',
+      );
+      continue;
+    }
+    const leafNode = createSceneNode();
+    attachModelToNode(leafNode, modelHandle, 0);
+    setSceneNodeTransform(leafNode, leaf.worldMatrix);
+    if (leaf.tint !== null) applyTint(leafNode, leaf.tint);
+    setSceneNodeParent(leafNode, root);
+    setSceneNodeVisible(leafNode, true);
+  }
+
+  return root;
+}
+
+// ---- environment -----------------------------------------------------------
+
+function applyEnvironment(world: WorldData): void {
+  const env = world.environment;
+  if (!env) return;
+
+  // Primary directional light (sun). Additional lights can be added by the
+  // game/editor through `addDirectionalLight` / `addPointLight` directly.
+  addDirectionalLight(
+    env.sunDirection[0], env.sunDirection[1], env.sunDirection[2],
+    env.sunColor[0] * env.sunIntensity,
+    env.sunColor[1] * env.sunIntensity,
+    env.sunColor[2] * env.sunIntensity,
+    env.sunIntensity,
+  );
+
+  if (env.shadowsEnabled) {
+    enableShadows();
+  } else {
+    disableShadows();
+  }
+}
+
+// ---- TRS -> column-major 4x4 -----------------------------------------------
+
+// Build a column-major 4x4 matrix from TRS: M = T * Rz * Ry * Rx * S.
+// The rotation order matches glTF / Blender / most game engines (XYZ Euler,
+// applied right-to-left so X spin happens first in object space).
+export function trsToMat4(t: TransformData): Mat4 {
+  const pos: Vec3 = { x: t.position[0], y: t.position[1], z: t.position[2] };
+  const scl: Vec3 = { x: t.scale[0], y: t.scale[1], z: t.scale[2] };
+
+  let m = mat4Identity();
+  m = mat4Translate(m, pos);
+  m = mat4RotateZ(m, t.rotation[2]);
+  m = mat4RotateY(m, t.rotation[1]);
+  m = mat4RotateX(m, t.rotation[0]);
+  m = mat4Scale(m, scl);
+  return m;
+}
+
+// Apply an RGBA tint to a scene node. Pulled into a helper so it can be reused
+// by prefab expansion (where children inherit the parent entity's tint unless
+// they override it).
+function applyTint(node: SceneNodeHandle, tint: Vec4Lit): void {
+  setSceneNodeColor(node, tint[0], tint[1], tint[2], tint[3]);
+}
+
+// ---- factory helpers used by the editor to create new data ----------------
+
+// Build an empty world with sensible defaults. The editor calls this from
+// File -> New. Games should prefer `loadWorld` from a file on disk.
+export function createEmptyWorld(id: string, name: string): WorldData {
+  return {
+    schemaVersion: 1,
+    name: name,
+    id: id,
+    bounds: { min: [-50, -10, -50], max: [50, 50, 50] },
+    environment: {
+      skyColor: [0.53, 0.81, 0.92],
+      ambientColor: [1.0, 1.0, 1.0],
+      ambientIntensity: 0.35,
+      sunDirection: [-0.5, -1.0, -0.3],
+      sunColor: [1.0, 0.95, 0.85],
+      sunIntensity: 1.0,
+      fogStart: 40,
+      fogEnd: 120,
+      fogColor: [0.7, 0.8, 0.9],
+      shadowsEnabled: true,
+    },
+    terrain: null,
+    entities: [],
+    water: [],
+    rivers: [],
+    metadata: {},
+  };
+}
+
+// Build an empty entity with default transform. The editor calls this when
+// the place tool drops a model at a hit point.
+export function createEntity(id: string, modelRef: string, position: Vec3Lit): EntityData {
+  return {
+    id: id,
+    name: basename(modelRef),
+    modelRef: modelRef,
+    prefabRef: null,
+    transform: {
+      position: position,
+      rotation: [0, 0, 0],
+      scale: [1, 1, 1],
+    },
+    tint: null,
+    tags: [],
+    userData: {},
+  };
+}
+
+function basename(path: string): string {
+  const slash = path.lastIndexOf('/');
+  const dot = path.lastIndexOf('.');
+  const start = slash < 0 ? 0 : slash + 1;
+  const end = dot < start ? path.length : dot;
+  return path.substring(start, end);
+}